Genolini ConstruireUnPackage

Construire un Package
Classic et S4
Christophe Genolini
Table des mati` eres

1 Cr eation dun package classique 1.1 Conguration de votre ordinateur . . . . . . . . . . . . . . . 1.1.1 Installation de programmes . . . . . . . . . . . . . . 1.1.2 Modication du PATH . . . . . . . . . . . . . . . . . 1.1.3 R epertoire TMPDIR . . . . . . . . . . . . . . . . . . . 1.1.4 Ajustements pour MiKTeX . . . . . . . . . . . . . . 1.2 Cr eation dun programme... qui fonctionne ! . . . . . . . . . 1.2.1 Quelques r` egles . . . . . . . . . . . . . . . . . . . . 1.2.2 Les tests . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.3 Le programme . . . . . . . . . . . . . . . . . . . . . 1.3 Cr eation de larborescence et des chiers . . . . . . . . . . . 1.3.1 package.skeleton . . . . . . . . . . . . . . . . . . . 1.3.2 Cr eation des aides pour les donn ees . . . . . . . . . 1.3.3 DESCRIPTION . . . . . . . . . . . . . . . . . . . . 1.4 Visibilit e des fonctions : NAMESPACE . . . . . . . . . . . . . . 1.4.1 export . . . . . . . . . . . . . . . . . . . . . . . . . 1.4.2 import . . . . . . . . . . . . . . . . . . . . . . . . . 1.4.3 Bilan . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5 Pr eparation de la documentation . . . . . . . . . . . . . . . 1.5.1 Cest long, cest fastidieux, c a nest pas le moment... 1.5.2 Que faut-il documenter ? . . . . . . . . . . . . . . . . 1.5.3 Les alias . . . . . . . . . . . . . . . . . . . . . . . . . 1.5.4 Lalias modi es . . . . . . . . . . . . . . . . . . . . . 1.5.5 Les alias multiples . . . . . . . . . . . . . . . . . . . 1.5.6 Les extra . . . . . . . . . . . . . . . . . . . . . . . . 1.5.7 \alias{nomDuPackage} . . . . . . . . . . . . . . . . 1.5.8 Internal . . . . . . . . . . . . . . . . . . . . . . . . . 1.5.9 Eacer les docs des priv es . . . . . . . . . . . . . . . 1.5.10 Bilan . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6 R edaction des documentations . . . . . . . . . . . . . . . . 1.6.1 Syntaxe g en erale . . . . . . . . . . . . . . . . . . . . 1.6.2 G en eralit es pour toutes les documentations . . . . . 1.6.3 Pr esentation g en erale du package . . . . . . . . . . . 3 5 5 5 6 6 6 7 7 7 9 12 12 14 14 16 16 18 18 18 19 20 20 21 21 21 22 22 22 22 23 23 24 25
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4 1.6.4 Fonctions . . . . . . . . . . . . 1.6.5 Donn ees . . . . . . . . . . . . . Finalisation et cr eation . . . . . . . . . 1.7.1 V erication . . . . . . . . . . . 1.7.2 Construction (ou compilation) 1.7.3 Documentation . . . . . . . . . 1.7.4 upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
` TABLE DES MATIERES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 27 28 28 28 29 30 31 31 31 31 33 33 35 35 36 36 37 37 38 38 38 38 39 41 42 44 46 46
1.7
2 Cr eation dun package en S4 2.1 Conguration de votre ordinateur . . . . . . . . . . . . 2.2 Cr eation dun programme... fonctionne ! . . . . . . . . 2.2.1 Quelques r` egles de plus . . . . . . . . . . . . . 2.2.2 Les tests . . . . . . . . . . . . . . . . . . . . . . 2.2.3 Toy exemple S4 . . . . . . . . . . . . . . . . . . 2.3 Cr eation de larborescence et des chiers . . . . . . . . 2.3.1 package.skeleton . . . . . . . . . . . . . . . . 2.3.2 Aides pour les donn ees . . . . . . . . . . . . . . 2.3.3 DESCRIPTION . . . . . . . . . . . . . . . . . . . 2.4 Visibilit e des classes et des m ethodes (NAMESPACE) 2.4.1 export . . . . . . . . . . . . . . . . . . . . . . 2.4.2 import . . . . . . . . . . . . . . . . . . . . . . 2.4.3 Bilan . . . . . . . . . . . . . . . . . . . . . . . . 2.5 Pr eparation de la documentation . . . . . . . . . . . . 2.5.1 Aide en S4 . . . . . . . . . . . . . . . . . . . . 2.5.2 Fichiers et alias cr e ees par package.skeleton . . 2.5.3 Intuitivement : de quoi a-t-on besoin ? . . . . . 2.5.4 Les alias en double . . . . . . . . . . . . . . . . 2.5.5 Bilan . . . . . . . . . . . . . . . . . . . . . . . . 2.6 R edaction des documentations . . . . . . . . . . . . . 2.7 Finalisation et cr eation . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
A Remerciements 47 A.1 Nous vivons une epoque formidable . . . . . . . . . . . . . . . . . . . . . . 47 A.2 Ceux par qui ce tutorial existe... . . . . . . . . . . . . . . . . . . . . . . . 47 Bibliographie Index 49 50
Chapitre 1
Cr eation dun package classique

1.1
1.1.1
Conguration de votre ordinateur 1

Installation de programmes
Pour cr eer un package, il vous faut installer sur votre ordinateur un certain nombre de logiciels (tous disponibles gratuitement sur le web), puis les congurer. Perl : Perl est un langage optimis e pour lextraction dinformations de chiers textes et la g en eration de rapports. http://www.activestate.com/Products/ActivePerl/Download.html Rtools : Les Rtools sont des outils Unix qui fournissent une couche d emulation pour le syst` eme Windows. Ils rendent possible lex ecution de programmes Unix sous Windows. http://www.murdoch-sutherland.com/Rtools/tools.zip MinGW : MinGW permet de compiler du code C, C++ et FORTRAN. Si vous nincluez pas de langage autre dans votre code, vous navez pas besoin de MinGW. Sinon : http://prdownloads.sourceforge.net/mingw/MinGW-5.0.0.exe HTML Help Workshop : Ce logiciel permet de produire des aides au format .chm, le format daide propri etaire de Windows. http://msdn.microsoft.com/library/en-us/htmlhelp/html/ /hwmicrosofthtmlhelpdownloads.asp Un compilateur LaTeX : LaTeX permet de produire une aide au format pdf. Plusieurs compilateurs sont disponibles, MiKTeX est assez stable. http://www.miktex.org/ FTP : quand vous aurez termin e votre package, il vous faudra le poster sur le site du CRAN. Cela se fait gr ace ` a un logiciel g erant le FTP (File Transfert Protocol). L` a encore, plusieurs choix sont possibles.
1. Les sections 1.1 et 1.7 sont fortement inspir ees (avec laimable autorisation de lauteur) de lexcellent travail de Sophie Baillargeon. Pour des informations plus compl` etes, nous vous recommandons chaudement de lire son tutorial [1] ou le diaporama qui laccompagne [2].
CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE http://filezilla-project.org/
1.1.2
Modication du PATH
La cr eation dun package se fait via une fen etre de commande DOS ou une fen etre terminal sous Linux. Tous les nouveaux programmes qui viennent d etre install es doivent etre accessibles depuis cette fen etre. Pour cela, il faut pr eciser lendroit o` u ils ont et e install es sur votre ordinateur. Cela se fait en modiant la variable PATH. Le plus simple est de cr eer un chier Rpath.bat contenant la d enition de la variable PATH. A noter que les espaces ne sont pas accept es dans les noms de chier. Sous Windows, Programme File doit donc etre abr eg e en Progra~1. La s eparation des di erents chemins peut se faire gr ace ` a ;. Pour plus de lisibilit e, il est possible de d enir le PATH sur plusieurs lignes :
SET SET SET SET SET SET SET SET SET PATH = C :\ Rtools \ bin PATH =% PATH %; C :\ Perl \ bin PATH =% PATH %; C :\ Rtools \ MinGW \ bin PATH =% PATH %; C :\ PROGRA ~ 1\ R \R -2.9.1\ bin PATH =% PATH %; C :\ PROGRA ~ 1\ R \R -2.9.1\ include PATH =% PATH %; C :\ PROGRA ~ 1\ MIKTEX ~ 1.6\ miktex \ bin PATH =% PATH %; C :\ PROGRA ~ 1\ HTMLHE ~ 1 PATH =% PATH %; C :\ WINDOWS PATH =% PATH %; C :\ WINDOWS \ system32
Si vous sauvegardez Rpath.bat dans le r epertoire racine C:/, il vous sut ensuite de taper C:/Rpath dans la fen etre syst` eme que vous venez douvrir et votre variable PATH est modi ee comme il convient. Nous reviendrons sur lutilisation de ce chier dans la section sur la compilation nale 1.7. Il est egalement possible de modier la variable PATH en allant explorer les variables denvironnement. Mais ces modications sont permanentes (jusqu` a ce quelles soient recti ees). Cela veut dire qu` a chaque fois que vous allumerez votre ordinateur, le PATH sera modi e m eme si vous navez pas de package ` a compiler ce jour-l` a. Votre ordinateur sera un zeste moins rapide. Aussi, il est plus int eressant de cr eer un chier Rpath.bat que lon ex ecutera les jours o` u cest n ecessaire.
1.1.3
R epertoire TMPDIR
La construction dun package n ecessite lexistence dun r epertoire temporaire. Le plus simple est de cr eer le r epertoire C:/temp. Il est egalement possible de modier la variable TMPDIR (voir [1] pour plus de d etail sur cette option.)
1.1.4
Ajustements pour MiKTeX
Si on utilise MiKTeX comme compilateur LaTeX, il y a une derni` ere manipulation ` a eectuer pour le rendre compatible. Il faut :
1.2. CREATION DUN PROGRAMME... QUI FONCTIONNE !
Cr eer un sous r epertoire nomm e /tex/ dans le r epertoire C:/localtexmf/ Copier tous les dossiers du r epertoire C:/Program Files/R/R-2.2.1/ /share/texmf/ dans le r epertoire C:/localtexmf/tex/ Pour sassurer que tout fonctionne, aller dans : Menu d emarrer Programmes MiKTeX MiKTeX Options General et cliquer sur Refresh Now et Update Now.
1.2
Cr eation dun programme... qui fonctionne !
Votre ordinateur est pr et, il faut maintenant v erier que votre programme lest aussi.
1.2.1
Quelques r` egles
Votre programme doit fonctionner dans un environnement vierge, sans aucun pr ealable. Ouvrez R (sans restauration dune session pr ec edente), lancez votre programme, il doit sex ecuter. Votre programme doit etre propre. En particulier, il ne doit contenir QUE les variables et les fonctions que vous souhaitez voir apparaitre dans la version nale de votre package. Si vous avez utilis e des fonctions auxiliaires ou des variables qui vous ont servi ` a faire des tests, prenez soin de les eacer en n de programme. Votre programme doit fonctionner... Or, la programmation est une t ache particuli` erement ardue, les programmes sont buggu es. Il faut les d ebuguer. Pour cela, il faut v erier que les fonctions se comportent bien comme vous le souhaitez. Cela passe par des tests 2 . Beaucoup de tests. Ou plus pr ecis ement, des tests bien choisis et le plus exhaustifs possibles. Il est pr ef erable de s eparer la cr eation des fonctions et les tests que vous eectuez dans deux chiers di erents. Les noms de chiers ou de r epertoires ne doivent pas comporter daccent ni despace (les caract` eres sp eciaux ne sont pas g er es de la m eme mani` ere sous Linux et sous Windows, les transferts de lun vers lautre posent probl` emes).
1.2.2
Les tests
Quest-ce que tester ? Tester, cest v erier que ce que vous avez programm e se comporte bien comme vous le voulez. Par exemple, si vous programmez la fonction carre qui calcule le carr e dun nombre, vous vous attendez ` a ce que carre(2) donne 4 et carre(-3) donne 9. Si carre(3) donne -9, cest quil y a une erreur dans votre programme. Les tests sont l` a pour d ebusquer ce genre derreur. Les tests en pratique
2. Notez que le test informatique est un concept compl` etement di erent du test statistique...
CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE
D enir un test pour une fonction, cest donner le r esultat attendu relativement ` a une certaine entr ee. La conception dun test est donc compl` etement ind ependante de la programmation de la fonction. En th eorie, les tests se construisent avant l ecriture du programme. Exemple : la fonction impute du package kml a pour mission de remplacer une valeur manquante au esentes. Consid erons les moyenne des autres mesures pr temps i par la 3 12 23 trajectoires 4 N A N A. N A N A 25 La valeur manquante de la premi` ere colonne devrait etre remplac ee par la moyenne de {3, 4} cest ` a dire 3.5 Les valeurs manquantes de la deuxi` eme colonnes devraient etre remplac ees par 12. La valeur manquante de la troisi` eme colonne devrait etre remplac ee par la moyenne de {23, 25} cest-` a-dire 24 3 12 23 Au nal, apr` es imputation, nos trajectoires devraient etre 4 12 24. 3.5 12 25 Nous venons de d enir un test informatique. Notez quil est ind ependant de la fonction impl ement ee. Le test est lexpression de ce que lon souhaite, pas de ce qui existe. Une fois le test con cu, on peut v erier que ce que lon a programm e est bien conforme ` a ce que lon veut programmer. Dans notre cas, il sagit de v erier que la fonction impute r eagit bien comme elle devrait. Naturellement, un unique test est tr` es insusant, il en faut bien dautres. Combien de tests ? Quoi tester ? Les tests doivent vous permettre de v erier que votre programme fonctionne correctement et cela dans tous les cas m eme ceux auxquels vous ne pensez pas mais qui se pr esenteront s urement un jour ! Dicile de pr evoir m eme ce ` a quoi il nous est impossible de penser. Pour palier ` a ce manque dimagination, il est important de bien choisir ses tests : en pr evoir un grand nombre mais surtout, pr evoir des tests les plus vari es possibles. ce sujet, une petite anecdote : mon bin A ome et moi avions 16 ans ; c etait l epoque des premiers compatibles PC. Nous avions cours dinformatique (turbo pascal). Le probl` eme du jour etait de construire la fonction f (x, y ) = xy . Apr` es avoir fait au moins 50 tests, nous appelons lenseignant. Ex prof de math, un pince sans rire. Il arrive sans un mot, il tape 20 et crack, notre programme plante. Il repart, toujours sans un mot... Nous navions pas pens e` a la puissance z ero. Rageurs, nous reprenons notre code, nous corrigeons, nous eectuons au moins 200 tests (parce quappeler le prof quand c a ne marche pas, ` a cet age-l` a, cest un peu la honte) et nous rappelons le prof. Il tape 02 , ca marche. Victoire ! De courte dur ee : il essaie 00 et crack, ca replante... Une demi-heure plus tard, il nous fait boire notre calice jusqu` a sa lie avec 22 ... Cette petite anecdote illustre bien le fait quil est plus important de bien choisir ses tests que de les multiplier. Faire 50 tests comme 23 , 34 , 82 , ... a bien moins dint er et que les 9 petits tests 23 , 03 , 43 , 20 , 00 ,40 , 25 , 05 et 45
Au nal, pour tester une fonction, il faut essayer de trouver tous les types dentr ees quun utilisateur pourrait avoir ` a saisir (dans la mesure o` u il respecte les sp ecications de la fonction : nous naurions pas ` a nous occuper dun utilisateur qui essaierait carre("bonjour")) et de v erier que le r esultat est bien conforme ` a ce quon attend. Des tests compatibles R Core team... ou pas ? La R Core Team a mis au point un syst` eme de gestion de tests automatiques tr` es performant mais un peu dicile ` a utiliser pour le programmeur non expert. Il n ecessite en particulier davoir un package compilable (selon les conditions que nous verrons section 1.7.2 page 28) m eme pendant sa construction. Lexpert d eveloppe son package en sassurant quil est compilable et ecrit en parall` ele un chier de test qui commence par linstruction library(monPackage). Quand il veut faire ses tests, il compile son package, puis ex ecute son chier test. La premi` ere instruction, le chargement du package, lui assure que toutes les fonctions quil a d enies sont eectivement charg ees en m emoire en conditions r eelles. Ainsi fait lexpert. notre niveau, une telle d A emarche est impossible. En eet, la compilation dun package pr esente en elle-m eme des dicult es, m elanger ces dicult es avec celles de la cr eation dun programme serait informatiquement suicidaire. Autre probl` eme, les tests automatiques ne permettent de tester que les fonctions qui seront au nal accessibles ` a lutilisateur mais pas les fonctions interm ediaires qui seraient utilis ees en interne dans le pacakge (les concepts de fonctions internes et accessibles ` a lutilisateur seront abord es section 1.4.1 page 16). Dans ce livre, nous allons donc laisser de c ot e la gestion des tests automatiques pour experts et proposer une gestion alternative, certes manuelle, mais plus accessible.
1.2.3
Le programme
Notre package classique sappelle packClassic. Cest ce quon appelle un toy example, il na dint er et que sa simplicit e... Il est constitu e dune base de donn ees appel ee dataAges.Rda et de deux chiers progClassic.R et testsProgClassic.R. 1. Notre base de donn ees dataAges.Rda est situ ee dans le r epertoire /packClassic/data/. En th eorie, cest une gigantesque base de donn ees dune valeur incalculable dont la collecte vous a demand e des ann ees. Dans notre exemple, cest simplement la sauvegarde dun data.frame obtenu par le code :
# ######################################################################## # ## donnees ### # ######################################################################## dataAges <- data . frame ( sex = c ( " H " ," H " ," F " ," H " ," F " ) , age = c (5 ,6 ,5 ,4 ,8) ) save ( dataAges , file = " packClassic / data / dataAges . rda " )
10
Il est egalement possible de sauvegarder directement des donn ees aux formats .csv, .txt ou .tab. Enn, nous aurions pu placer dans le r epertoire /data/ un chier R fabriquant les donn ees. 2. progClassic.R est situ e dans le r epertoire /packClassic/R/. Il contient le code source du programme, la d enition de 6 fonctions.
# ######################################################################## # ## progClassic . R ### # ######################################################################## publicA privateA . publicB . privateB publicC privateC <<<<<<function ( x ){ plot ( x +1)} function ( x ){ x +2} function ( x ){ x +10} function ( x ){ x +20} function ( x ){ publicA ( privateA ( x ))} function ( x ){. publicB (. privateB ( x ))}
3. testsProgClassic.R est situ e dans le r epertoire /packClassic/testsDev/. Il contient les tests pour chaque fonction du code source.
# ######################################################################## # ## testsProgClassique . R ### # ######################################################################## load ( " .. / data / dataAges . rda " ) source ( " .. / R / progClassic . R " ) publicA (1) privateA (2) . publicB (3) . privateB (4) publicC (5) publicC ( dataAges $ age ) privateC (6)
Au nal, on obtient larborescence suivante :
11
Note : nous venons de pr esenter ici une version termin ee de nombre programme. Mais la structure que nous sommes en train de mettre en place est egalement utilisable pendant la phase d eveloppement. Ainsi, apr` es avoir d evelopp e la fonction publicA et privateA, l etat des chiers aurait et e:
# ######################################################################## # ## progClassic . R ### # ######################################################################## publicA privateA <- function ( x ){ plot ( x +1)} <- function ( x ){ x +2}
et
# ######################################################################## # ## testsProgClassique . R ### # ######################################################################## load ( " .. / data / dataAges . rda " ) source ( " .. / R / progClassic . R " ) publicA (1) privateA (2)
Pour v erier que notre programme fonctionne (quand il est nalis e comme pendant la phase d eveloppement), il faut d enir le r epertoire /packClassic/ /testsDev/ comme etant le r epertoire courant de R, copier les tests puis les coller dans la console de R. Si on veut faire simplement le programme sans les tests, il faut se placer dans le repertoire /packClassic/R/ puis ex ecuter source("progClassic.R"). Note : pour utiliser la gestion des tests automatiques de la R Core team, il faudrait placer le chier tests testsProgClassic.R dans le r epertoire /packClassic/ /tests/ et le modier de la mani` ere suivante :
# ########################################################################
12
# ## testsProgClassique . R ### # ######################################################################## library ( packClassic ) data ( dataAges ) publicA (1) . publicB (3) publicC (5) publicC ( dataAges $ age )
1.3
Cr eation de larborescence et des chiers
Un package est un ensemble de plusieurs chiers et r epertoires, tous r eunis dans un r epertoire racine. Le r epertoire racine a pour nom le futur nom du package (packClassic dans notre exemple). Il contient un chier nomm e DESCRIPTION, un chier nomm e NAMESPACE (optionnel) plus les r epertoires /R/, /man/, /data/ (optionnel) et /tests/ (optionnel). Le r epertoire /R/ contient le code des programmes (dans notre cas progClassic.R). /man/ contient les chiers daide. /data/ contient les jeux de donn ees que nous avons d ecid e dinclure dans notre package (pr esentement dataAges.Rda). /tests/ contient les chiers permettant de tester notre programme (tests selon la R Core Team). Comme nous avons pris loption tests simpli es non compatibles, nous le remplacerons par /testsDev/ pour d enir des tests utilisables pendant le d eveloppement. Dans notre exemple, nous supposerons de plus que le repertoire racine est lui-m eme situ e dans le repertoire /TousMesPackages/.
1.3.1
package.skeleton
package.skeleton est une fonction qui cr ee pour vous larborescence des chiers (r epertoire racine, r epertoires /R/, /man/ et /data/). Elle cr ee aussi les chiers daide (dans /man/), les chiers codes (dans /R/), eventuellement les donn ees (dans /data/), le chier DESCRIPTION et eventuellement le chier NAMESPACE. Lid ee est dutiliser package.skeleton pour la cr eation initiale de votre package, puis de modier ensuite ` a la main les chiers quil a cr e es. Pour m emoire, nous voulons cr eer un package packClassic ` a partir du programme progClassic.R qui se trouve d ej` a dans le r epertoire /packClassic/R/ lui m eme situ e de /TousMesPackages/. Le plus simple est de se placer dans le r epertoire /TousMesPackages/ puis de taper :
> package . skeleton ( " packClassic " , + code _ file = " packClassic / R / progClassic . R " ,
1.3. CREATION DE LARBORESCENCE ET DES FICHIERS

+ + + ) namespace =TRUE , f o r c e =TRUE
13
Cela a pour eet de : Cr eer chier DESCRIPTION dans le r epertoire /packClassic/. Cr eer le r epertoire /packClassic/R/. Comme nous avons choisi loption force= TRUE, celui qui existe d ej` a est eac e. Copier le chier progClassic.R dans le r epertoire /packClassic/R/. Cr eer le r epertoire /packClassic/man/. Cr eer de nombreux chiers daide dans /packClassic/man/. Cr eer le r epertoire /packClassic/data/. Ce r epertoire nest cr e e que dans le cas o` u le programme progClassic.R contient la d enition de donn ees. Cr eer un chier appel e Read-and-delete-me. Ce chier contient des informations sur la cr eation du package et peut etre eac e sans probl` eme apr` es lecture. Le r epertoire /packClassic/testsDev/ nest pas modi e. namespace=TRUE est une option que lon peut supprimer si on ne compte pas pr eciser laccessibilit e des fonctions. Dans ce livre, nous allons pr eciser... La destruction / recr eation des chiers sources permet ` a R de v erier que les noms donn es ` a nos noms de chiers sont corrects. Sils ne le sont pas, package.skeleton les renomme en ajoutant des ZZZ ou des _ ` a la place des caract` eres non accept es. Au nal, apr` es lex ecution de package.skeleton :
14
1.3.2
Cr eation des aides pour les donn ees
package.skeleton a cr e e plusieurs chiers daide, mais il na pas cr e e un chier pour dataAges. Or, la cr eation dun package n ecessite aussi la documentation des jeux de donn ees. Il faut donc ajouter un chier daide. Cela se fait gr ace ` a linstruction prompt, instruction que lon peut utiliser apr` es s etre assur e que les donn ees sont eectivement en m emoire :
> > > > # ## Charge des donn e es en m e moire load ( " packClassic / data / dataAges . Rda " ) # ## Ajoute le fichier d ' aide ` a / packClassic / man / prompt ( dataAges , filename = " packClassic / man / dataAges . Rd " )
Si, bien plus tard dans la cr eation du package, ` a lheure o` u tout est presque termin e et o` u il devient co uteux dutiliser package.skeleton, on se rend compte quon a oubli e de cr eer une fonction, on peut toujours la cr eer et cr eer son aide gr ace ` a prompt. Il sut de donner ` a prompt le nom de la fonction et de lui pr eciser que cest une fonction (et non des data comme dans le cas pr ec edent). Cela se fait gr ace ` a largument force.function :
> funcDerniereMinute <- function ( x ){ cat ( x )} > prompt ( funcDerniereMinute , f o r c e . function =TRUE)
Cette instruction cr ee le chier daide funcDerniereMinute.Rd dans le r epertoire courant.
1.3.3
DESCRIPTION
Le chier DESCRIPTION contient, vous laurez devin e, une description du package. Voil` a celui que package.skeleton vient de cr eer pour nous :
Package : packClassic Type : Package Title : What the package does ( short line ) Version : 1.0 Date : 2009 -05 -23 Author : Who wrote it Maintainer : Who to complain to < yourfault@somewhere . net > Description : More about what it does ( maybe more than one line ) License : What license is it under ? LazyLoad : yes
Pour ladapter ` a notre package, il sut de louvrir dans un editeur de texte et de le modier. Cest assez rapide : Package: packClassic : nom du package. Il est important que le nom du package soit le m eme partout, en particulier le nom du r epertoire racine doit etre le m eme que celui pr esent sur cette premi` ere ligne. Le nom ne doit pas contenir de caract` eres sp eciaux ou despace. Type: Package : pas de modication.
15
Title: Toy Pack Classique : titre du package. Contrairement au nom du package, le titre peut contenir des espaces et des caract` eres sp eciaux. Version: 0.5 : La version 1.0 est la premi` ere version stable (cest-` a-dire utilisable et raisonnablement peu buggu ee). Les versions 0.x sont les versions pr etes ` a x%. Si nous estimons notre package pr et ` a 50%, nous pouvons choisir Version: 0.5. Si nous ajoutons une petite am elioration, elle sera publi ee dans la version 0.5.1. Quand tout sera nalis e, nous publierons une version 0.9 pour que dautres la testent. Quand les testeurs auront rapport e les bugs les plus importants et que nous aurons corrig e, il sera alors temps de publier la Version 1.0. Pour linstant, 0.5 semble raisonnable. noter, la date est au format interna Date: 2008-07-22 : Pas de modication. A tional : ann ee puis mois puis jour. Author: Christophe Genolini (and some helpfull readers...) : les auteurs. Maintainer: <genolini@u-paris10.fr>: Un package est un programme qui a pour vocation d etre utilis e par dautres. Ces autres vont trouver des bugs ou exprimer des besoins. Ladresse mail est ladresse de la personne ` a qui ils doivent ecrire. Description: This package comes to illustrate the book "Petit manuel de Programmation Orient ee Objet sous R" : La description permet de pr eciser de mani` ere un peu plus d etaill ee ce que fait le package. License: GPL (>=2.0) R est un logiciel libre. Votre package doit egalement etre d eni comme libre, cest ` a dire sous licence GPL (Gnu Public Licence). Pour les non experts, la GPL 2 et suivantes semble assez classique. LazyLoad: yes, pas de modication. Les lignes suivantes sont optionnelles et ne sont pas dans le chier par d efaut : Depends:graphics : Si votre package fait appel ` a dautres packages, vous devez ajouter une ligne Depends:nomAutrePackageA nomAutrePackageB. De mani` ere plus pr ecise, toutes les fonctions de R appartiennent ` a un package 3 : ls est dans le package base, plot est dans graphics, anova est dans stats... Tous les packages auquel notre programme fait appel doivent etre list es. Seule exception a la r` ` egle, le package base est automatiquement inclus, il na pas besoin d etre d eclar e. Dans le cas pr esent, nous utilisons plot, il faut donc pr eciser que nous avons besoin du package graphics. URL:www.r-project.org,christophe.genolini.free.fr/webTutorial : le but de faire un package est ensuite de le distribuer. URL permet de pr eciser les sites sur lesquels votre package est disponible. Classiquement, on devrait pouvoir le trouver au moins sur le site du CRAN plus eventuellement sur un site d edi e. Encoding : si votre chier DESCRIPTION contient des caract` eres non internationaux (par exemple e, ` e, ` a, c ...), il faut ajouter la ligne Encoding: latin1. Mais
3. Pour connaitre le package auquel une fonction appartient, il sut de consulter laide de la fonction. Sur la premier ligne en haut a ` gauche, le nom du package est donn e entre parenth` eses, juste a ` c ot e du nom de la fonction.
16
CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE le package est alors moins portable, il vaut mieux eviter dutiliser cette option. Collate : Si votre programme se d ecompose en plusieurs chiers et que ceux-ci doivent etre ex ecut es dans un ordre pr ecis, alors cet ordre doit etre pr ecis e` a laide de Collate (pour nous, la question de lodre ne se pose pas dans le cas de notre package classique mais nous en aurons besoin lors de la cr eation de notre package S4). Au nal, voila notre chier DESCRIPTION :
Package : packClassic Type : Package Title : Toy Pack Classic Version : 0.5 Date : 2009 -05 -25 Author : Author : Christophe Genolini ( and some helpfull readers ...) Maintainer : < genolini@u - paris10 . fr > Description : This package comes to illustrate the book " Petit Manuel de Programmation Orientee Objet sous R " License : GPL ( >=2.0) LazyLoad : yes Depends : graphics URL : www .r - project . org , christophe . genolini . free . fr / webTutorial
1.4
Visibilit e des fonctions : NAMESPACE
Le chier NAMESPACE sert ` a d enir la visibilit e de nos fonctions et des fonctions des autres packages, via import et export. Contrairement ` a ce qui est pr esent e dans de nombreux tutoriaux, import et export cachent deux concepts di erents. En particulier, on peut avoir besoin de d enir export mais pas import (linverse est plus rare).
1.4.1
export
Lorsquon cr ee un package, on peut d enir plusieurs niveaux daccessibilit e des fonctions. Public et priv e On peut choisir que certaines fonctions soient accessibles ` a lutilisateur, que dautres soient r eserv ees au programmeur et ` a son programme. Les fonctions accessibles sont appel ees publiques ), les r eserv ees sont dites priv ees. Le statut public ou priv e se d enit dans le chier NAMESPACE. Les fonctions publiques doivent etre d eclar ees dans export. Les fonctions priv ees doivent simplement ne pas etre d eclar ees. Visible et invisible Parall` element ` a public et priv e, il est possible de d enir des fonctions visibles ou invisibles. Les fonctions invisibles sont simplement des fonctions dont le nom commence
DES FONCTIONS : NAMESPACE 1.4. VISIBILITE
17
par un point . . Ces fonctions ne sont pas ach ees lorsque lutilisateur demande un achage g en eral ls(). Par contre, elles sont utilisables normalement. A noter que le . ne change pas le statut (public ou priv e) dune fonction, il aecte simplement linstruction ls().
Public, invisible, priv e Th eoriquement, il est donc possible de d enir quatre types de fonctions : publiques visibles, publiques invisibles, priv ees visibles et priv ees invisibles. En pratique, la derni` ere cat egorie ne pr esente aucun int er et. On parlera donc de publiques (pour publiques visibles), dinvisibles (pour publiques invisibles) et de priv ees (pour priv ees visibles et priv ees invisibles). Publique visible Publique invisible Priv ee visible Priv ee invisible Publique Invisible Priv ee Priv ee
D enition de export Un petit exemple va permettre de xer les choses. On souhaite que les fonctions publicA et publicC soient publiques ; que .publicB soit invisible ; que privateA, .privateB et privateC soient priv ees. Pour cela, on ecrit dans le chier NAMESPACE :
> export ( " publicA " , + " . publicB " , + " publicC " + )
Ainsi, lutilisateur peut utiliser publicA (publique), .publicB (invisible) et publicC (publique) mais pas privateA, .privateB et privateC (priv ees). A noter que tout cela concerne lutilisateur et non pas les fonctions : publicC, une fonction faite par le programmeur (d enie dans le package), peut sans probl` eme utiliser privateA. Par contre, les fonctions programm ees par lutilisateur ne pourront pas lutiliser. export par d efaut Petite digression informatique : une expression r eguli` ere est la repr esentation synth etique dun ensemble de cha nes de caract` eres ayant des caract eristiques communes. Par exemple, si on consid` ere les dix cha nes Ind0, Ind1, Ind2, ... Ind9, il est assez p enible de les noter une par une. Une expression r eguli` ere r esumant ces dix cha nes sera Ind + un chire. Naturellement, nous donnons ici un exemple illustratif, les vraies expressions r eguli` eres utilisent des codications plus pr ecises. R et NAMESPACE permettent ` a lutilisateur de travailler avec des expressions r eguli` eres. Cela permet de raccourcir la liste des export. Par d efaut, package.skeleton cr ee un
18
export utilisant une expression r eguli` ere signiant : exporte toutes les variables et fonctions qui NE commencent PAS par un point, autrement dit nexporte pas les invisibles. Pour plus dinformation sur les expressions r eguli` eres, vous pouvez consulter laide en ligne ?regex.
1.4.2
import
En parall` ele avec le m ecanisme cachant ou d evoilant lintimit e de notre programme, il existe un principe permettant daller explorer les cuisines des autres. Cela se fait via linstruction import, situ ee dans le chier NAMESPACE. import vient en compl ement de la ligne Depends du chier DESCRIPTION. Plus pr ecis ement, toutes les fonctions d enies dans dautres packages doivent etre import ees. Pour cela, on peut soit importer le package d enissant les fonctions dont on a besoin int egralement, soit importer juste une fonction. Limport int egral dun package se fait gr ace ` a linstruction import :
# ## Pour le package integralement import ( graphics )
Limport dune fonction particuli` ere se fait avec importFrom en lui pr ecisant le nom du package puis celui de la fonction :
# ## Pour une unique fonction importFrom ( graphics , plot )
1.4.3
Bilan
Au nal, voila notre chier NAMESPACE :

export ( " publicA " , " . publicB " , " publicC " ) importFrom ( graphics , plot )
1.5
Pr eparation de la documentation
Lordinateur est congur e, le programme tourne, larborescence est faite, les chiers DESCRIPTION et NAMESPACE sont modi es. Nous touchons au but, il ne reste plus que les docs... Erreur, grave erreur... car sous le plus que se dissimulent deux monstres terriblement chronophages : la p edagogie et la lisibilit e...
1.5. PREPARATION DE LA DOCUMENTATION
19
1.5.1
Cest long, cest fastidieux, ca nest pas le moment...
Il y a trois grosses dicult es lorsquon aborde la r edaction de la documentation : Cest long, Cest long... Cest long et c a tombe au mauvais moment ! Plus pr ecis ement, examinons ensemble le cheminement qui aboutit ` a la cr eation dun package. Dabord, on a une id ee. On commence ` a la programmer. Lid ee evolue, le programme aussi. Il se complexie. On sy perd, on le retravaille, on change tout. Il murit. Finalement, apr` es un epuisant travail, il est quasi termin e. On supprime les derniers bugs, on met la petite touche nale. On sent que la n est proche. On cr ee les chiers DESCRIPTION, le NAMESPACE, larborescence. On pense que lessentiel du travail est derri` ere nous. On a r esolu toutes les dicult es techniques, tout ce qui est intellectuellement stimulant. Reste... la documentation. A ce stade, sa r edaction apparait comme un petit extra, une partie annexe, un bonus. De plus, notre programme marchera, avec ou sans. Erreur fatale, la documentation est fondamentale. Elle est fondamentale ` a au moins deux titres : Une documentation est faite pour expliquer aux autres. Elle doit donc etre p edagogique. La p edagogie, ca se travaille, ca se pense, ca se relit et ca se fait relire. Et si personne ne comprend rien ` a ce que vous avez ecrit, c a nest pas parce que les autres sont des tirs au anc qui ne prennent pas le temps de lire, cest parce que vous n etes pas aussi clair que vous le pensez... Si vous faites un package, ca nest pas pour le plaisir de torturer votre code, cest pour donner votre travail ` a la communaut e (puis pour avoir la joie de savoir que dautres utilisent votre travail ce qui en montre la qualit e). Hors, il y a assez peu de chance pour que votre package soit unique : il existe des solutions alternatives plus ou moins proches. Si, au d etour dun forum, votre package est cit e parmi ceux susceptibles daider un utilisateur mais quil narrive pas ` a le comprendre, il se tournera vers les autres 4 . Votre package tombera en d esu etude, toute votre programmation (qui est peut- etre de grande qualit e par ailleurs, l` a nest pas la question) naura servi ` a rien. Bilan, une programmeur averti en valant deux, il faut le savoir : r ediger la documentation est une partie longue, fastidieuse, qui arrive au moment o` u lon pense avoir enn ni... mais INDISPENSABLE. Pour vous-m eme quand vous aurez oubli e les d etails de votre package ; pour les autres qui aimeraient utiliser votre travail ; pour la qualit e des logiciels libres.
4. Si besoin est, les statisticiens changent m eme de logiciel : par exemple les gens de SAS viennent faire leurs imputations multiples sous R et les gens de R vont faire leur r egression polytomique sous SAS ou sous STATA et cela simplement parce que les r esultats dune r egression polytomique sous R ne sont pas tr` es clairs... En tout etat de cause, il est important de ne pas h esiter a ` utiliser un autre logiciel si on a des doutes sur une fonction R, m eme si cest simplement a ` titre conrmatoire.
20
1.5.2
Que faut-il documenter ?
L egitime question : Que faut-il documenter ? R eponse simple : TOUT ! Et plut ot deux fois quune... Cela r esume assez bien la pens ee de ceux qui ont programm e votre pire ennemi et votre th eorique alli e, jai nomm e R CMD check et package.skeleton (lequel est lequel ? Il faut avouer que parfois, il est dicile de savoir...). Plus pr ecis ement, il faut documenter le package dans sa globalit e, tous les chiers de donn ees, toutes les fonctions publiques et toutes les invisibles (G en eralement, toutes les invisibles sont document ees dans le m eme chier qui a pour titre et pour unique texte For internal use only...) Seules les priv ees sont exempt ees. La documentation doit etre r edig ee sous forme de chiers daides au format .Rd. Les chiers doivent etre enregistr es dans le r epertoire /man/. Ca permet ensuite ` a lutilisateur qui se sert de notre package de faire acher les di erents chiers daide gr ace ` a la commande help.
1.5.3
Les alias
Quand lutilisateur veut de laide sur une fonction, il tape g en eralement help(fonctionMystere). Dans notre cas, il peut vouloir en savoir plus sur publicA. Il lui sut de taper help(publicA) (ou ?publicA) et le chier daide publicA.Rd souvre. Petite v erication du travail quavaient eectu e package.skeleton et prompt quelques paragraphes plus t ot: dans le r epertoire /packClassic/man/, on trouve 6 chiers : dataAge.Rd packClassic-package.Rd privateA.Rd privateC.Rd publicA.Rd publicC.Rd Les quatre derniers portent les noms de fonctions que nous avons d enies. Vous laurez compris, des chiers ont et e cr e es pour toutes les fonctions sauf les invisibles. Lier un chier daide ` a une demande daide ne se fait pas gr ace au nom du chier mais ` a laide de linstruction alias. La r` egle est simple : Le chier qui doit souvrir lorsque lutilisateur tape help(fonctionMystere) doit contenir linstruction \alias(fonctionMystere) Ainsi, comme on veut que publicA.Rd souvre lorsque lutilisateur tape help(publicA), le chier publicA.Rd doit contenir \alias(publicA). Pour v erier, ouvrons le chier publicA.Rd. Voil` a les trois premi` eres lignes :
\ name { publicA } \ Rdversion {1.1} \ alias { publicA } ...
21
Cette aide souvrira donc ` a lappel de help(publicA).
Remarque : alias est le seul lien entre un chier et la commande help. En particulier, si lon renomme un chier daide sans changer son alias, cela ne modiera pas le comportement du package.
1.5.4
Lalias modi es
Il est possible daner un peu le processus : etant donn e un chier daide aide.Rd, on peut sp ecier le mot que lutilisateur doit taper pour louvrir. Cela se fait gr ace a la commande alias. Si dans le chier publicA.Rd on remplace \alias(publicA) ` par \alias(superPublicA), linstruction help(publicA) produira une erreur alors que help(superPublicA) ouvrira le chier. Cela semble etrange de vouloir faire ce genre de modication. Ca lest sans doute dans un package classique, ca le sera beaucoup moins dans un package S4.
1.5.5
Les alias multiples
Un chier peut contenir plusieurs alias. Ainsi, si le chier publicA.Rd contient les alias publicA et publicC, lutilisateur pourra le visualiser soit en tapant help(publicA), soit help(publicC). Ceci est en particulier utile pour documenter des fonctions qui traitent de sujets proches (comme numeric, as.numeric et is.numeric). Par contre, il pourra etre souhaitable de renommer le chier publicA.Rd en publicAC.Rd pour bien indiquer quil ne correspond plus ` a une aide unique. Ainsi, nous pouvons : Renommer publicA.R en publicAC.R Supprimer publicC.R Ajouter \alias(publicC.R) au chier publicAC.R. Notez que r eciproquement, un chier daide sans alias ne serait plus accessible (du moins, plus par la fonction help).
1.5.6
Les extra
Nous venons de le voir, une aide est li ee ` a un chier gr ace ` a un alias. Il est donc possible dajouter des chiers daide non pr evus par package.skeleton. Pour cela, il sut de cr eer un nouveau chier .Rd et de lui ajouter lalias d esir e. Cest en particulier utile si plusieurs fonctions gravitent autour dun concept central sans quaucune ne lenglobe totalement. On peut alors ajouter une aide conceptCentral.Rd qui sera accessible par help(conceptCentral).
22
1.5.7
\alias{nomDuPackage}
R nimpose pas lexistence de \alias(nomDuPackage) 5 . Or, quand un utilisateur vient dinstaller un package tout beau tout neuf quil ne connait pas, son premier r eexe est de taper help(nomDuPackage). Si cet alias nexiste pas, lutilisateur ne sait pas par o` u commencer pour avoir une aide. Cest un peu d eroutant. Cet alias a assez naturellement sa place dans le chier nomDuPackage-package. En eet, ce chier daide a un r ole un peu particulier : il sert ` a donner une vue globale du package. Linstruction help(nomDuPackage) ouvrira donc directement la description g en erale gr ace ` a cet alias. Notez que ca nest pas une obligation, rien ne vous emp eche de cr eer un autre chier daide (un extra) et de lui aecter \alias(nomDuPackage). Mais dans un chier ou dans lautre, cet alias doit exister parce quil est vraiment d esagr eable, lorsquon vient de t el echarger nouveauSuperPackage et quon sattelle ` a la lourde t ache de comprendre comment il fonctionne, de ne pas recevoir daide apr` es avoir tap e help(nouveauSuperPackage).
1.5.8
Internal
Pour nir, package.skeleton g en` ere le chier packClassic-internal.Rd seulement si loption namespace=FALSE. Ce chier est l` a pour opposer une n de non recevoir aux curieux qui voudraient des informations sur les fonctions invisibles. Il est poli, mais ferme : These are not to be called by the public... En fait, il fait un peu double emploi avec NAMESPACE : Soit le programmeur cache ses fonctions en les rendant invisibles (avec des noms commen cant par des points) : dans ce cas, R exige des documentations pour les invisibles, mais comme le programmeur estime que lutilisateur nen a pas besoin, il redirige les demandes daide vers packClassic-internal.Rd (en ajoutant dans ce chier les alias de toutes les fonctions invisibles). Soit le programmeur cache ses fonctions en les rendant priv ees (gr ace ` a NAMESPACE) auquel cas il na plus besoin de les documenter.
1.5.9
Eacer les docs des priv es
package.skeleton ne sait pas que les fonctions private sont priv ees, il a donc cr e e des chiers daide pour chacune dentres elles. Ces chiers sont inutiles, les priv es nont pas besoin d etre document es. Nous pouvons donc supprimer privateA.Rd et privateC.Rd.
1.5.10
Bilan
Au nal, laide se construit de la mani` ere suivante : Ajouter dans NAMESPACE le nom des fonctions publiques et invisibles.
5. Depuis, la version R 2.9.0, cet alias est ins er e dans nomDuPackage-package, mais il nest toujours pas obligatoire.
1.6. REDACTION DES DOCUMENTATIONS
23
Documenter les publiques, eventuellement en regroupant certaines dans un m eme chier. Documenter les chiers de donn ees. Documenter le package dans son ensemble. Le cas ech eant, documenter les invisibles dans un unique chier qui ne donnera pas dinformation.
Appliqu e` a notre package packClassic, cela donne :
1.6
R edaction des documentations
Il est maintenant temps d editer les chiers daide et dadapter les chiers cr e es par package.skeleton ` a nos besoins. La r edaction des documentations se fait dans un langage interpr et e (assez proche de LaTeX). Le texte est tap e tel quel et est egay e instructions sp eciales pr ec ed ees de \ et permettant la mise en forme du document. Les textes saisis doivent obligatoirement gurer dans une rubrique (dans \detail{ }, dans \author{ },...) Le texte %% ~Make other sections like Warning with \section{Warning }{....} ~ est une entorse ` a cette r` egle, il faut donc le supprimer, sinon le chier ne sera pas syntaxiquement correct. Avant de pr esenter les di erentes rubriques que doivent comprendre les chiers daides, quelques remarques sur la syntaxe g en erale.
1.6.1
Syntaxe g en erale
Connaitre la syntaxe de trois ou quatre instructions sut pour la majorit e des aides : Pour mettre du code informatique en valeur, il faut utiliser \code{mon code}
24
CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE Linstruction \link permet de rendre un mot cliquable, pour que lutilisateur puisse aller sur une autre page daide. \link{AutreAide} ache le mot AutreAide et redirige vers le chier AutreAide.Rd. Linstruction \link[=fichierAide]{motClef} ache motClef et redirige vers le chier fichierAide.Rd, ` a condition toutefois que celui-ci fasse partie du package. Pour une aide dans un autre package, il faut utiliser linstruction \link[nomAutrePackage]{motClef} pour acher motClef et ouvrir le chier motClef.Rd ; \link[nomAutrePackage:fichierAide]{motClef} pour acher motClef et ouvrir le chier fichierAide.Rd. Pour faire une liste ` a puce, il faut utiliser la structure \itemize{ pour commencer la liste. Puis pour chaque puce, on ajoute \item texte associ e. Enn, } cloture la liste. Pour faire une liste num erot ee, on remplace \itemize{ par \enumerate{. Pour faire une liste avec des items nom es, il faut utiliser la structure \describe{ pour commencer la liste. Puis pour chaque item, on ajoute \item{item 1}{texte associ e}, \item{item 2}{texte associ e 2}... Enn, comme dans les cas pr ec edents, } cloture la liste. De nombreux exemples illustratifs sont pr esent es dans les pages suivantes.
1.6.2
G en eralit es pour toutes les documentations
Pour etre correcte, une aide doit obligatoirement comporter un certain nombre de rubriques. Voil` a les rubriques communes ` a toutes les aides : L\alias, nous en avons d ej` a longuement parl e, d enit linstruction qui permet douvrir le chier daide. Le \title sert ` a d ecrire laide. Autre utilit e, lorsquun utilisateur fait une recherche avec help.search sur un mot clef, la liste des packages et fonctions qui se rapportent ` a son mot clef est ach ee. Chaque fonction est assortie dun court descriptif. Ce descriptif, le programmeur le sp ecie via \title de laide associ e` a la fonction. Les \references servent ` a citer des articles ou des livres qui ont servi de support a la cr ` eation du package. \seealso permet de rediriger vers dautres aides qui eventuellement compl` etent celle que nous sommes en train d ecrire. \examples contient un mini programme R illustrant laide que lon est en train d ecrire. Il est appel e lorsque lutilisateur utilise linstruction example Ce code doit etre directement ex ecutable sans modication. Dans le cas de la pr esentation globale du package, il doit reprendre les fonctions les plus importantes. Dans le cas de fonctions, il doit pr esenter di erentes mani` eres dutiliser la fonction. \keyword permet de d enir des mots clefs. Quand un utilisateur qui ne connait pas lexistence de votre package fait une recherche sur un concept, il le fait en saisissant un mot. Si le mot correspond ` a un de vos mots clef, votre package sera signal e ` a lutilisateur comme etant potentiellement int eressant pour lui. La liste des mots clefs autoris es est donn ee en annexe ?? page ??.
25
1.6.3
Pr esentation g en erale du package
La pr esentation g en erale de notre package se fait dans le chier daide packClassicpackage.Rd. Par rapport ` a ce qui pr ec` ede, on doit ajouter \details. \details reprend les informations du chier DESCRIPTION. On obtient le chier :
\ name { packClassic - package } \ Rdversion {1.1} \ alias { packClassic - package } \ alias { packClassic } \ docType { package } \ title { Toy example of a classic package } \ description { This package is a toy example build to illustrate the construction of a package as explain in the tutorial \ emph { Petit Manuel de Programmation Orientee Objet en R }. } \ details { \ tabular { ll }{ Package : \ tab packClassic \ cr Type : \ tab Package \ cr Version : \ tab 0.5\ cr Date : \ tab 2009 -05 -23\ cr License : \ tab GPL ( >=2.0)\ cr LazyLoad : \ tab yes \ cr } This package is a toy example build to illustrate the construction of a package as explain in the tutorial \ emph { Petit Manuel de Programmation Orientee Objet en R }. There is mainly two functions . There are documented in \ link [ packClassic ]{ publicAC }. May be there is another one , but it is a secret ... } \ author { Christophe Genolini < genolini@u - paris10 . fr >} \ references { Book : " Petit Manuel de Programmation Orientee Objet sous R " } \ seealso { \ code {\ link [ packS4 : packS4 - package ]{ packS4 }} is another toy example build to illustrate the construction of an S4 package . } \ examples { # ## PublicC is the main fonction of this package publicC (3) }
26
\ keyword { package }
1.6.4
Fonctions
Dans les chiers daide expliquant les fonctions, il faut egalement d etailler lutilisation de la fonction et les arguments utilis es : \usage pr esente la mani` ere dappeler la fonction, en particulier la liste des arguments et eventuellement les valeurs par d efaut de certains dentre eux. La liste des arguments doit etre rigoureusement identique ` a celle de la d enition de la fonction. \arguments d etaille la liste des arguments en pr ecisant les valeurs quils doivent prendre et leur utilit e. \value pr ecise le type de ce qui est retourn e par la fonction (un numeric, un character, une list...) Pour le chier publicAC.Rd, on obtient :
\ name { publicAC } \ Rdversion {1.1} \ alias { publicA } \ alias { publicC } \ title { publicA and publicC } \ description { Two great function that do very simple mathematical operation . } \ usage { publicA ( x ) publicC ( x ) } \ arguments { \ item { x }{\ code { x } is a numeric } } \ details { So simple , no details are needed . } \ value { A numeric } \ references { Book : " Petit Manuel de Programmation Orientee Objet sous R " } \ author { Christophe Genolini < genolini@u - paris10 . fr >} \ examples { publicA (3)

publicC (4) } \ keyword { documentation }
27
1.6.5
Donn ees
Enn, dans les chiers daide pour les donn ees, il faut ajouter \format. \format d etaille chaque colonne. Pour le chier dataAges.Rd, on obtient :
\ name { dataAges } \ Rdversion {1.1} \ alias { dataAges } \ docType { data } \ title { Toy data frame for packClassic } \ description { This data . frame is a fake toy example made up to illustrate the inclusion of data in a package . } \ usage { data ( dataAges )} \ format { A data frame with 5 observations on the following 2 variables . \ describe { \ item {\ code { sex }}{ a factor with levels \ code { F } \ code { H } , which denote the gender of the subject } \ item {\ code { age }}{ a numeric vector for teh age .} } } \ details { So simple , no detail are needed . } \ source { Fake data .} \ references { Book : " Petit Manuel de Programmation Orientee Objet sous R " } \ examples { data ( dataAges ) str ( dataAges ) } \ keyword { datasets }
28
1.7
Finalisation et cr eation
Lorsque les chiers sources (programme, aides et donn ees) sont pr ets, il reste ` a les v erier, ` a construire le package et eventuellement ` a construire des documentations au format pdf. Ces trois etapes se font dans une fen etre de commandes DOS sur Windows ou une fen etre terminal sur Linux.
1.7.1
V erication
Pour v erier le package, il faut ouvrir une fen etre de commande DOS ou une fen etre terminale Linux, se placer dans le r epertoire contenant le r epertoire du package (pas dans le r epertoire portant le nom package, mais un niveau au dessus ; dans notre cas, il sagit du r epertoire /TousMesPackages/). Si vous avez cr e e un cher Rpath.bat comme conseill e section 1.1 page 5, il vous faut taper la commande C:/Rpath pour modier le path. Ensuite, la v erication de votre package se fait avec linstruction : R CMD check monPackage R CMD check classe les probl` emes en deux cat egories : les erreurs et les avertissements (warnings). Les erreurs sont fatales, elles indiquent quun probl` eme emp echera la construction future de votre package. Entrent dans cette cat egorie les erreurs de programmation, les erreurs de syntaxe dans les chiers DESCRIPTION, NAMESPACE ou dans les aides et bien dautres encore. Quand il d etecte une erreur, R CMD check la signale puis sarr` ete. Les avertissements sont moins graves : ils signalent des probl` emes qui nemp echeront pas la construction du package mais plut ot sa bonne utilisation. Par exemple, si les chiers daide ne sont pas tous pr esents, si des alias existent en double, si des attributs obligatoires manquent, cela donnera lieu ` a des avertissements. Il sera donc possible de construire votre package. Par contre, un tel package sera refus e sur le site du CRAN. La R Core Team naccepte en eet que les packages sans erreur ni avertissement. Pour la petite histoire, il existe des packages dissidents de personnes estimant quelles nont pas ` a corriger les avertissements et qui diusent leur package via des sites personnels... Mais cela est un peu excessif, la correction des avertissements se fait assez rapidement. Enn, il peut arriver que la v erication dun package g en` ere des avertissements sur un syst` eme dexploitation mais pas sur lautre. Si vous travaillez sur Linux, vous navez pas ` a vous en soucier puisque la R Core Team v erie les package ` a partir de Linux et g` erera elle-m eme lexport vers windows. Linverse est plus probl ematique, mais est heureusement tr` es rare. Si vous voulez en savoir plus sur les options, une aide en ligne est disponible via R CMD check -help.
1.7.2
Construction (ou compilation)
Apr` es la v erication dun package, on peut passer ` a sa construction proprement dite. Cette derni` ere etape se fait ` a laide de la commande R CMD build <option> monPackage. Les options d ependent de la plateforme informatique sur laquelle on travaille et
1.7. FINALISATION ET CREATION
29
de la plateforme ` a laquelle est destin e le package. Pour ce qui est dune soumission dun package au CRAN, la R Core Team naccepte que les packages Linux et se charge de les compiler sous windows. Trois types de compilations sont donc n ecessaires : Windows Windows : vous travaillez sous Windows et vous voulez compiler votre package pour vous m eme. Windows Linux : vous travaillez sous Windows et vous voulez compiler votre package pour soumission ` a la R Core Team. Linux Linux : vous travaillez sous Linux et vous voulez compiler votre package pour vous m eme ou pour soumission ` a la R Core Team. Sur Windows pour Windows : R CMD build -binary monPackage Cette commande cr ee un package binaire pr ecompil e (pre-compiled binary package) zipp e. Ce chier se nomme monPackage_version.gz o` u version est le num ero de la version inscrit dans le chier DESCRIPTION. Il permet linstallation du package sous Windows. Sur Windows pour Linux : R CMD build monPackage Cette commande cr ee un chier nomm e monPackage_version.tar.gz comprenant les chiers sources (cest ` a dire les chiers originaux) du package. Au passage, le fait que les sources soient inclues permet ` a celui qui re coit votre chier de le recompiler, y compris de le recompiler pour un autre syst` eme que Linux. Cest en particulier ce que fait la R Core Team : ` a partir de vos sources, ils compilent un chier pour Windows, un chier pour Linux et un chier pour Mac. Sur Linux pour Linux : R CMD build monPackage Cest la m eme commande que Windows pour Linux. Elle cr ee un chier nomm e monPackage_version.tar.gz comprenant egalement les chiers sources du package. Sur Linux pour Windows Il sagit de la construction la plus compliqu ee ` a eectuer. Heureusement, rares sont ceux qui en ont besoin puisque la cr eation dun package pour Windows ` a partir de Linux est assur ee par la R Core Team ` a partir des sources. Pour ceux qui voudraient quand m eme faire la conversion, nous vous renvoyons encore une fois ` a lincontournable tutorial de Sophie Baillargeon [1]. Si vous voulez en savoir plus sur les options, une aide en ligne est disponible via R CMD build -help.
1.7.3
Documentation
Enn, on peut cr eer un chier documentation au format pdf avec la commande : R CMD Rd2dvi --pdf monPackage. Sur Windows, le document Rd2.pdf est alors cr e e
30
dans le r epertoire ./Rd2dv/. Sur Linux, le document monPackage.pdf est cr e e dans le r epertoire du package.
1.7.4
upload
Quand tout est termin e, il vous faut soumettre votre package. Cela se fait gr ace ` a un d ep ot (un upload, cest ` a dire linverse dun t el echargement ou download) sur le site du CRAN. Pour cela, il vous faut ouvrir une connexion ftp vers ladresse ftp://cran.rproject.org/incoming/ puis d eposer votre package compil e pour Linux (cest ` a dire le chier monPackage_version.tar.gz) dans le r epertoire incoming. Le lendemain, vous recevrez un petit mail disant :
Dear package maintainer , this notification has been generated automatically . Your package packClassic _ 0.5. tar . gz has been built for Windows and will be published within 24 hours in the corresponding CRAN directory ( CRAN / bin / windows / contrib / 2.9 / ). R version 2.9.0 Patched (2009 -04 -27 r48414 ) All the best , Uwe Ligges ( Maintainer of binary packages for Windows )
Fini ! Merci Uwe ! Enn, c a, cest dans le meilleur des mondes. Dans la r ealit e, vous allez probablement recevoir un message vous informant que vous avez oubli e de corriger tel et tel warnings, que vous avez une version de R un peu vieillote, que tel chier daide est mal fait... Il vous faudra donc reprendre, corriger, modier et ressoumettre. Et recommencer jusqu` a recevoir le tant attendu message. Et l` a, c a sera vraiment ni. Au moins pour le cas dun package classique. Reste le passage ` a la S4...
Chapitre 2
Cr eation dun package en S4

Les six etapes de la cr eation sont les m emes que pour un package classique.
2.1
Conguration de votre ordinateur
Rigoureusement identique ` a la cr eation dun package classique.
2.2
Cr eation dun programme... fonctionne !
Les r` egles d enies section 1.2.1 sappliquent toujours mais le d ecoupage du programme est un peu plus complexe.
2.2.1
Quelques r` egles de plus
Nous lavons bri` evement evoqu e dans lintroduction, lencapsulation est le fait de rassembler ` a un seul endroit le code d enissant un objet, ce qui permet de ne plus avoir a soccuper de ses m ` eandres internes lorsquil est termin e. R ne force pas le programmeur a encapsuler ses objets, mais il est possible dencapsuler malgr ` e tout. Pour cela, il sut de suivre une r` egle toute simple : chaque objet son chier A De m eme, chaque objet doit etre test e. Do` u une deuxi` eme r` egle tout aussi simple que la premi` ere : chaque chier de code son chier test. A Il va donc nous falloir cr eer un chier et un chier test par objet. En outre, ` a ces chiers vont venir sajouter divers chiers auxiliaires. Prenons un exemple, l` a encore articiel et simple. Son nom est packS4. Il est constitu e de trois classes ClassU, ClassV et ClassW. Pour cela, il nous faut cr eer les chiers suivants : 31
32
CHAPITRE 2. CREATION DUN PACKAGE EN S4 global.R : M eme si notre programme est orient e objet, il arrive que nous fassions appel ` a des fonctions classiques non S4 et nappartenant ` a aucune classe en particulier. Ces fonctions ne peuvent pas etre plac ees dans le chier associ e` a une classe et doivent donc etre d eclar ees dans un chier ` a part. Nous les mettons dans global.R lui-m eme dans /packS4/R/. global.R contient egalement tous les setGeneric (nous avions vu section ?? quil valait mieux les regrouper dans un m eme chier et non les inclure dans une classe particuli` ere). ClassU.R, ClassV.R et ClassW.R : A chaque classe son chier. Les chiers d enissant les classes sont dans le r epertoire /packS4/R/. ClassV-ClassW.R : Exception, il peut arriver quune m ethode d epende de deux classes, ClassV et ClassW. Si cette m ethode appartient ` a la classe ClassV mais quil faut d enir ClassW apr` es ClassV, alors la m ethode mixte ne peut pas etre test ee lors de sa cr eation (car ClassW nexiste pas encore). Dans ce cas, il est pr ef erable de d enir les m ethodes mixtes dans un chier ` a part (petite entorse ` a la r` egle A chaque objet son chier) que lon appellera ClassV-ClassW.R et qui sera ex ecut e apr` es ClassV.R et apr` es ClassW.R. Il sera dans /packS4/R/. testsClassU.R, testsClassV.R, testsClassW.R et testsClassV-ClassW.R : chaque chier de code, son chier test. Pour chaque chier pr A esent dans /packS4/R/, on cr ee un chier test que lon place dans /packS4/testsDev/ 1 . dataAges.rda : pas de changement par rapport au cas classique, les chiers de donn ees sont dans le r epertoire /data/. main.R : enn, un chier main.R appelle tous les chiers tests. Il ne fait pas vraiment partie du package, il permet juste de lex ecuter pendant sa conception. Il ne faut donc pas linclure dans /packS4/R/ puisquil ne d enit pas de fonctionnalit e du langage. On peut le mettre dans le r epertoire /packS4/. On a donc :
1. Comme pour le package classique, ce r epertoire nest a ` utiliser que si vous choisissez de suivre la gestion des tests alternative et manuelle telle que nous lavons d enie section 1.2.2 page 7. Pour la gestion automatique et ocielle de la R Core Team, utilisez le r epertoire /packS4/tests/.
2.2. CREATION DUN PROGRAMME... FONCTIONNE !
33
2.2.2
Les tests
M emes r` egles que dans le cas classique. L` a encore, chaque chier test testsClassU.R doit commencer par linclusion du programme associ e : source("../R/ClasseU.R"). Il est possible de concevoir les chiers tests comme une suite de chiers appel es les uns apr` es les autres. Par exemple, on peut d ecider que testsClassV.R sera toujours ex ecut e apr` es testsClassU.R. Cela permet de consid erer que les objets d enis dans testsClassU.R seront utilisables dans testsClassV.R. Ce genre dimbrication est facilement g erable gr ace au chier main.R. Lint er et est de ne pas avoir ` a reconstruire de but en blanc les jeux de donn ees tests pour chaque chier mais de pouvoir r eutiliser ce qui a et e d eni avant.
2.2.3
Toy exemple S4
Reprenons notre exemple. Il est constitu e de trois classes ClassU, ClassV, ClassW et de donn ees dataAges. ClassW h erite de ClassU. Nous souhaitons que lutilisateur puisse avoir acc` es ` a la classe ClassW int egralement, ` a la classe ClassV partiellement (certaines m ethodes mais pas toutes) et quil nait pas acc` es ` a ClassU. Le code complet (tests 2 inclus) est t el echargeable sur le site web du livre .
# ######################################################################## # ## main . R ### # ######################################################################## load ( " . / data / dataAges . rda " ) 2. http://christophe.genolini.free.fr/webTutorial.
34
CHAPITRE 2. CREATION DUN PACKAGE EN S4
source ( " . / testsDev / testsGlobal . R " ) source ( " . / testsDev / testsClassU . R " ) source ( " . / testsDev / testsClassV . R " ) source ( " . / testsDev / testsClassW . R " ) source ( " . / testsDev / testsClassV - ClassW . R " ) # ######################################################################## # ## global . R ### # ######################################################################## setGeneric ( " privateA " , function ( object ){ standardGeneric ( " privateA " )} ) setGeneric ( " publicA " , function ( object ){ standardGeneric ( " publicA " )} ) setGeneric ( " publicB " , function ( objectV , objectW ){ standardGeneric ( " publicB " )} ) functionClassicA <- function ( age ){ return ( age * 2)} # ######################################################################## # ## ClassU . R ### # ######################################################################## setClass ( " ClassU " , representation ( u1 = " numeric " , u2 = " numeric " )) setMethod ( " privateA " ," ClassU " , function ( object ){ object@u1 ^2}) setMethod ( " plot " ," ClassU " , function (x , y ){ barplot ( c ( x@u1 , x@u2 ))}) # ######################################################################## # ## ClassV . R ### # ######################################################################## setClass ( " ClassV " , representation ( v1 = " numeric " , v2 = " numeric " )) setMethod ( " privateA " ," ClassV " , function ( object ){ object@v1 ^3}) setMethod ( " publicA " ," ClassV " , function ( object ){ sqrt ( object@v2 ^3)}) setMethod ( " plot " ," ClassV " , function (x , y ){ barplot ( c ( x@v1 , x@v2 ^2))}) # ######################################################################## # ## ClassW . R ### # ######################################################################## setClass ( " ClassW " , representation ( w1 = " character " ) , contains = " ClassU " ) classW <- function ( u1 , u2 , w1 ){ new ( " ClassW " , u1 = u1 , u2 = u2 , w1 = w1 )} setMethod ( " publicA " ," ClassW " , function ( object ){ sqrt ( object@u2 ^5)}) setMethod ( " plot " ," ClassW " , function (x , y ){ barplot ( c ( x@u1 , x@u2 ) , main = x@w1 )} )

setMethod ( " [ " ," ClassW " , function (x ,i ,j , drop ){ switch ( EXP =i , " u1 " ={ return ( x@u1 )} , " u2 " ={ return ( x@u2 )} , " w1 " ={ return ( x@w1 )} ) } ) setReplaceMethod ( " [ " ," ClassW " , function (x ,i ,j , value ){ switch ( EXP =i , " u1 " ={ x@u1 <- value } , " u2 " ={ x@u2 <- value } , " w1 " ={ x@w1 <- value } ) validObject ( x ) return ( x ) } )
35
# ######################################################################## # ## ClassV - ClassW . R ### # ######################################################################## setMethod ( " publicB " ,c ( " ClassV " ," ClassW " ) , function ( objectV , objectW ){ objectV@v1 * objectW@u1 } )
2.3
2.3.1
Cr eation de larborescence et des chiers

package.skeleton
Quasi identique ` a ce que nous avons utilis e pour un package classique, il faut n eanmoins donner ` a package.skeleton un peu plus darguments. En eet, le code source a et e s epar e en cinq chiers. Il faut donc les pr eciser dans code_file. Comme dans le cas classique, il faut d enir le r epertoire /TousMesPackage/ comme r epertoire courant de votre console R.
> package . skeleton ( " packS4 " , namespace =TRUE , f o r c e =TRUE , + code _ file = c ( + " packS4 / R / global . R " , + " packS4 / R / ClassU . R " , + " packS4 / R / ClassV . R " , + " packS4 / R / ClassW . R " , + " packS4 / R / ClassV - ClassW . R " + ) + )
36
Par d efaut, package.skeleton a tendance ` a cr eer beaucoup dalias (dont certains en double, comme nous le verrons en d etail section 2.5.4), mais ne cr ee pas daide pour les donn ees.
2.3.2
Aides pour les donn ees
Comme dans la cr eation de package classique, il faut donc les ajouter ` a la main avec prompt. Linstruction est la m eme :
load ( " packS4 / data / dataAges . rda " ) prompt ( dataAges , filename = " packS4 / man / dataAges . Rd " )
ce stade : A
2.3.3
DESCRIPTION
M eme chose que dans le cas classique. Dans le cas pr esent, nous avons besoin de pr eciser lordre dex ecution des di erents chiers : global.R d enit les g en eriques, donc il doit etre lu en premier ; puis la d enition des 3 classes ; et enn, les m ethodes communes a deux classes. Pour m ` emoire, cela se fait gr ace ` a linstruction Collate. Au nal, le chier description est :
DES CLASSES ET DES METHODES 2.4. VISIBILITE (NAMESPACE)
37
Package : packS4 Type : Package Title : Toy example of S4 package Version : 0.5 Date : 2009 -05 -26 Author : Christophe Genolini Maintainer : < genolini@u - paris10 . fr > Description : This package comes to illustrate the book " Petit Manuel de Programmation Orientee Objet sous R " License : GPL ( >=2) LazyLoad : yes Depends : methods , graphics URL : www .r - project . org , christophe . genolini . free . fr / webTutorial Collate : global . R ClassU . R ClassV . R ClassW . R ClassV - ClassW . R
2.4
Visibilit e des classes et des m ethodes (NAMESPACE)
L` a encore, on distingue les export des import.
2.4.1
export
package comporte trois types de d enitions : fonctions classiques, classes, m ethodes.
Notre Les Les Les
Chacune de ces cat egories sexporte en utilisant une instruction sp ecique : Les fonctions classiques sexportent comme dans le cas classique en utilisant export. Les classes sexportent gr ace ` a exportClasses Les m ethodes sexportent, oh ! surprise, via exportMethods Dans notre cas, nous voulons exporter les classes ClassV et ClassW, mais pas ClassU. Do` u:
exportClasses ( " ClassV " , " ClassW " )
De m eme, nous voulons exporter la m ethode publicA de ClassV, les m ethodes publicA, [ et [<- de ClassW.
exportMethods ( "[", " [ <-" , " plot " , " publicA " , " publicB "
38
)
Enn, il nous faut exporter les fonctions classiques non S4 :

" classW " , " functionClassicA " )
noter, plot a un statut un peu particulier : cest ` A a la fois une fonction classique et une fonction S4 (pour des soucis de compatibilit e). Il est donc possible de lexporter soit dans export, soit dans exportMethods.
2.4.2
import
Le fonctionnement est le m eme que dans le cas classique.
2.4.3
Bilan
Au nal, voil` a notre chier NAMESPACE :

export ( " classW " , " functionClassicA " ) exportMethods ( "[", " [ <-" , " plot " , " publicA " , " publicB " ) exportClasses ( " ClassV " , " ClassW " ) import ( graphics )
2.5
Pr eparation de la documentation
Lors de lappel de package.skeleton, un certain nombre de chiers de documentation et dalias ont et e cr e es. Tous ne sont pas n ecessaires, il va falloir faire le tri. Mais avant tout, quelques d etails sur lutilisation de laide en S4.
2.5.1
Aide en S4
Par rapport ` a la programmation classique, la programmation S4 ajoute trois types chaque outil, elle associe doutils (classes, m ethodes g en eriques, m ethodes sp eciques). A
39
un chier daide. Ainsi, on trouve des aides pour les classes, des aides pour les m ethodes g en eriques et des aides pour les m ethodes sp eciques. Acher laide pour une classe se fait en appelant le nom de la classe suivi de -class. Exemple, laide sur ClassU se fait gr ace ` a help(ClassU-class). Laide pour une m ethode g en erique se fait en appelant le nom de la m ethode. Par exemple, pour connaitre le fonctionnement g en eral de publicA, on tape help(publicA) Acher laide de m ethodes sp eciques se fait en appelant le nom de la m ethode suivi de -methods (avec un s). Par exemple, pour connaitre les fonctionnements sp eciques de publicA, on tape help(publicA-methods). Acher laide dune m ethode sp ecique se fait en appelant le nom de la m ethode suivi de la signature de la m ethode puis -method sans s. Par exemple, connaitre le fonctionnement sp ecique de publicA appliqu e` a la signature ClassV,ClassW se fait avec help(publicA,ClassV,ClassW-method).
2.5.2
Fichiers et alias cr e ees par package.skeleton
Lutilisation de pacakge.skeleton cr ee les chiers et les alias suivants : 1. Nom de package : Le chier packS4-package.Rd est cr e e pour lensemble du package (et donc en un seul exemplaire). Il contient \alias(packS4) et \alias(packS4-package). Ce chier est le chier qui est ouvert quand lutilisateur tape help(packS4). Il a pour vocation de d ecrire le package dans sa globalit e. 2. Classes : pour chaque classe, un chier ClassU-class.Rd est cr e e. Il contient deux groupes dalias : un alias pour la classe propre \alias(ClassU-class). Egalement, pour toutes les m ethodes publicA de la classe ClassU, il contient un alias vers la m ethode sp ecique \alias(publicA,ClassU-method), et cela pour toutes les signatures possibles. 3. M ethodes g en eriques : pour chaque g en erique d eni dans notre package, un chier publicA.Rd est cr e e. Il contient \alias(publicA). Les m ethodes g en eriques qui sont utilis eees dans notre package mais qui sont d enies dans dautres packages (comme plot, print, [<-,...) ne donnent pas lieu ` a la cr eation dun chier g en erique. 4. M ethodes sp eciques : pour chaque m ethode utilis ee par une classe, un chier publicA-methods.Rd est cr e e. Il contient un alias vers lensemble des m ethodes sp eciques \alias(publicA-methods) plus un alias pour toutes les signatures possibles de la m ethode publicA,ClassU-methods. 5. Fonctions classiques : enn, un chier functionClassic.Rd est cr e e pour chaque fonction classique (non S4). Il contient \alias(functionClassic) On constate que dans son d esir d etre exhaustif, package.skeleton a cr e e certains alias deux fois : help(publicA,ClassU-method) renvoie vers les aides ClassU-class.Rd et publicA-methods.Rd. Il va nous falloir choisir lequel concerver et lequel supprimer. Pour linstant, voil` a l etat de notre package packS4 :
40
Fichier ClassU-class.Rd
Alias ClassU-class plot,ClassU-method privateA,ClassU-method ClassV-class plot,ClassV-method privateA,ClassV-method publicA,ClassV-method publicB,ClassV,ClassW-method classW ClassW-class [,ClassW-method plot,ClassW-method publicA,ClassW-method publicB,ClassV,ClassW-method dataAge functionClassicA packS4-package packS4 plot-methods plot,ANY-method plot,ClassU-method plot,ClassV-method plot,ClassW-method privateA privateA-methods privateA,ClassU-method privateA,ClassV-method publicA publicA-methods publicA,ClassV-method publicA,ClassW-method publicB publicB-methods publicB,ClassV,ClassW-method [<--methods [<--,ClassW-method [-methods [,ClassW-method
ClassV-class.Rd
classW.Rd
ClassW-class.Rd
dataAges.Rd functionClassicA packS4-package.Rd
plot-methods.Rd
privateA.Rd privateA-methods.Rd publicA.Rd publicA-methods.Rd publicB.Rd publicB-methods.Rd z[_--methods.Rd z[-methods.Rd
Ensuite, comme dans le cas classique, chaque chier doit etre edit e et modi e. Quel travail de titan, seriez-vous en droit de vous exclamer ! Et vous auriez raison... Et encore, il ne sagit l` a que dun toy example, la r ealit e est bien pire ! Vous etes encore l` a? Heureusement, il va etre possible de faire quelques fusions et simplications. Mais ne vous y trompez pas, nous ne le r ep` eterons jamais assez, la r edaction dune documentation claire et compr ehensible est un travail chronophage... totalement indispensable mais chronophage. La section 1.5.1 page 19 d etaille ce point.
41
Avant de poursuivre, deux remarques : en premier lieu, un nom de chier ne peut pas commencer par le symbole [. Le chier [-methods.Rd est donc renomm e en z[_methods.Rd. De m eme, tous les noms de chiers non compatibles selon R sont renomm es : les caract` eres fautifs sont remplac es par _ et le pr exe z est ajout e au nom du chier. Par exemple, le chier daide de la m ethode de remplacement nest pas [<-methods mais z[_--methods.Rd. Deuxi` eme point, method(s) est parfois au singulier, parfois au pluriel. Cela permet de distinguer si on est en train de parler dune m ethode g en erique (methods est alors au pluriel), de plusieurs m ethodes sp eciques (pluriel) ou dune seule m ethode sp ecique (singulier).
2.5.3
Intuitivement : de quoi a-t-on besoin ?
Laissons un instant package.skeleton ; imaginons que vous ayez besoin dun package qui traite de trajectoires et vous ne connaissez rien ` a la S4. Sur un forum, on vous conseille miniKml en particulier sa fonction impute. Vous le t el echargez. Ensuite, vous allez essayer dapprendre ` a vous en servir. Intuitivement, quelles sont les aides que vous allez demander ? Reprenons maintenant nos casquettes de programmeur. Quelles sont les aides que nous allons programmer ? Simple, celles dont nous aurions eu besoin en temps quutilisateur ne connaissant rien ` a la S4... En S4, il existe des m ethodes pr ecises et bien pens ees pour appeler des aides sur des m ethodes ou sur des classes, comme nous lavons vu section 2.5.1 page 38. Mais la majorit e des utilisateurs ne connaissent rien ` a la S4 et ils ne savent m eme pas quils sont en train dutiliser des objets. Le non-initi e` a la S4 ne connait quun seul type daide, la fonction help de base. Cela signie que sil cherche de laide sur la classe Trajectories, il tapera help(Trajectories). Sil cherche de laide sur la m ethode impute, il tapera help(impute). Il ne cherchera pas ` a faire de di erence entre une classe, une m ethode g en erique, une sp ecique et une fonction classique. Dun autre c ot e, il est important de donner aussi une aide ` a lexpert, celui qui sait quil est en train de manipuler de lobjet. Il va donc nous falloir jongler entre ceux qui ne savent pas et pour lesquels il faut fournir des aides intuitives, et ceux qui savent pour lesquels il faut fournir des aides pr evus par la S4... Pour cela, nous conseillons dajouter, en plus des alias pr evu par la R Core Team, des alias plus intuitifs, pour non initi es. Par exemple, en plus de \alias(MaClass-class), on peut ajouter \alias(MaClass). Probl` eme, si MaClass d esigne ` a la fois le constructeur et la classe, help(MaClass) devra faire r ef erence au constructeur. Si on a distingu e les deux en utilisant une majuscule pour la classe et une minuscule pour le constructeur, il ny a plus de probl` eme. laide pour la classe sera appelable via help(MaClass) et help(MaClass-class), celle pour le constructeur sera appelable via help(maClass). Concernant les m ethodes invent ees par le programmeur (celles qui nexistent pas ailleurs et pour lesquelles le programmeur a le contr ole du g en erique), il est conseill e de faire un lien de laide g en erique vers laide sp ecique. Ainsi, si lutilisateur averti
42
cherche une documentation sp ecique, il tapera help(maMethod,MaClass-methods). De son c ot e, lutilisateur non averti tapera simplement help(maMethod). Cette instruction ouvrira laide g en erique de maMethod ; gr ace au lien que nous sugg erons dins erer dans maMethod, lutilisateur non averti pourra se rediriger vers la description sp ecique et trouvera lui aussi linformation quil cherche. Pour les m ethodes g en eriques d enies dans dautres packages (comme plot) pour lesquelles vous ecrivez une d enition sp ecique, ` a moins de gentiment demander ` a la R 3 Core Team un lien vers notre m ethode sp ecique , il ny a pas vraiment de solution : tout au plus pourra-t-on ajouter \alias(plot,MaClass) ce qui est l eg` erement plus simple que \alias(plot,MaClass-methods). Toutefois, depuis la version R 2.9.0, il est possible de d enir des aides pour les fonctions g en eriques existant par ailleurs. Dans ce cas, lappel de laide en question (qui renvoie donc ` a deux chiers di erents) propose ` a lutilisateur de choisir entre les deux chiers. Par exemple, si nous d ecidons de d enir dans notre package un chier daide pour la m ethode g en erique plot, lappel help(plot) d eclenchera la question : plot du package base ou plot du package packS4 lappel dune aide
2.5.4
Les alias en double
Les alias des m ethodes sp eciques existent dans plusieurs chiers : dans les chiers de chaque classe pr esente dans la signature et dans le chier d ecrivant la m ethode sp ecique. Par exemple, \alias(publicA,ClassV-method) est pr esent dans ClassV-class.Rd et dans publicA-methods.Rd Pire, \alias(publicB,ClassV, ClassW-method) est pr esent dans trois chiers... Il va nous falloir d ecider si help(publicA,ClassV-method) ouvre le chier d ecrivant la classe ClassV-class.Rd ou d ecrivant la m ethode publicA-method.Rd. Comment choisir ? Un chier daide contient de nombreuses informations : un titre, des auteurs, des r ef erences, des liens externes... Dun chier daide ` a lautre, ces informations sont redondantes. Aussi, si laide pour publicA,ClassU est courte, il est plus simple de ne pas lui cr eer un chier sp ecique mais de linclure dans le chier d ecrivant la classe. Pour lutilisateur, il est agr eable davoir la description dune classe puis en quelques lignes la description de ses principales m ethodes, m ethodes quil connait probablement d ej` a par ailleurs (comme plot, print ou summary) sans avoir ` a chercher ` a travers plusieurs chiers.
3. M eme pas en r eve...
43
R eciproquement, si les aides sur des m ethodes sont longues, il sera plus agr eable de les trouver dans des chiers s epar es que dans un seul m ega chier. En particulier, des informations sur une m ethode pr ecise seront plus diciles ` a trouver si elles sont noy ees au milieu dautres m ethodes.
Au nal, la taille de laide doit d eterminer la redirection de help(MaMethod, MaClass) : Si laide est courte, elle peut etre laiss ee dans MaClass-class.Rd. Si laide est longue, il vaut mieux lui consacrer une page daide personnelle.
Dans le m eme esprit, si deux m ethodes sp eciques sont tr` es proches, on peut les laisser dans le m eme chier. Par contre, si elles di` erent, il pourra etre plus pertinent de s eparer maMethod-methods.Rd en deux chiers maMethod-ClassUmethod.Rd et maMethodClassV-method.Rd, chacun r ecup erant ses alias (notez la pr esence ou absence des s ` a methode(s) selon le type de chier). Il reste n eanmoins indispensable de conserver le chier maMethod-methods.Rd parce quil sera exig e lors de la compilation du package. Dans le cas pr esent, il pourra servir ` a rediriger vers lun ou lautre des alias sp eciques.
44
2.5.5
Bilan
Au nal, nous supposons que (suppositions faites uniquement pour simuler ce qui peut se passer dans un package r eel) : publicA a un comportement assez di erent avec ClassV et ClassW. Il faut donc deux aides s epar ees publicA-ClassV.Rd et publicA-ClassW.Rd, tout en conservant le chier publicA-Methods.Rd qui servira daiguilleur. Les accesseurs et constructeurs peuvent etre inclus dans la description de la classe (pour pouvoir egalement rediriger les accesseurs g en eriques vers ce chier, il faut etre certain quils ne concernent QUE cette classe). z[-method.Rd, z[_-method.Rd et classZ.Rd peuvent donc etre supprim ees. Les autres m ethodes sp eciques m eritent des chiers s epar es de ceux des classes.
Fort de ces hypoth` eses, et apr` es elimination de ce qui est priv e (ClassU et les m ethodes private), il nous reste (en soulign e ce quil faut ajouter, en gris ce que nous avons supprim e) :
Fichier ClassU-class.Rd ClassV ClassV-class plot,ClassV-method privateA,ClassV-method publicA,ClassV-method publicB,ClassV,ClassW-method ClassW ClassW-class [,ClassW-method [<-,ClassW-method plot,ClassW-method privateA,ClassW-method publicA,ClassW-method publicB,ClassV,ClassW-method classW dataAges functionClassicA packS4 packS4-package plot-methods plot,ClassU-method plot,ClassV-method plot,ClassW-method Alias
ClassV-class.Rd
classW.Rd
ClassW-class.Rd
dataAges.Rd functionClassicA.Rd packS4-package.Rd
plot-methods.Rd privateA.Rd privateA-methods.Rd publicA.Rd
publicA publicA-methods
45
publicA-ClassV-method.Rd publicA-ClassW-method.Rd publicA-methods.Rd publicB.Rd z[_--methods.Rd z[-methods.Rd
publicA,ClassV-method publicA,ClassW-method publicB publicB-methods publicB,ClassV,ClassW-method
noter, la classe ClassU et les m A ethodes private napparaissent plus puisque nous les avons d enies comme priv ees dans la section NAMESPACE. noter A egalement, si une m ethode g en erique (comme plot) existe d ej` a dans R, il nest pas possible de cr eer un \alias(plot) ou \alias(plot-methods). Par contre, il faut ajouter la description sp ecique de plot relativement ` a la classe qui lemploie (\alias(plot,trajPartitioned-methods) et \alias(plot,trajPartitioned)). Au nal, notre package sera compos e des chiers suivants :
46
2.6
R edaction des documentations
Deux petits changements par rapport au package classique : en premier lieu, \linkS4class{maClass} est une nouvelle instruction qui redirige directement vers le chier daide d enissant une classe. Deuxi` eme point, les keyword methods et classes sont ` a ajouter dans les chiers daide d ecrivant des m ethodes et des classes.
2.7
Finalisation et cr eation
Identique au package classique. Dans notre exemple : R CMD check packS4 R CMD build packS4 Puis un upload sur le site du CRAN ftp://cran.r-project.org/incoming/ Fini ! Et cette fois, cest la bonne. Champagne (bien m erit e...)
Annexe A
Remerciements
A.1 Nous vivons une epoque formidable
Quand on vit un moment historique, une r evolution, une date clef, on ne sen rend pas toujours compte. Je pense que la cr eation dInternet sera consid er ee par les historiens futurs comme une avanc ee majeure, quelque chose daussi enorme que linvention de l ecriture ou limprimerie. L ecriture, cest la conservation de linformation. Limprimerie, cest la diusion de linformation ` a une elite, puis ` a tout le monde, mais avec un co ut. Internet, cest linstantan eit e, la gratuit e, le partage global, les connaissances des experts mises ` a la disposition de tous... Les forums, cest la n des questions sans r eponses... Il y a quelque temps, je ne connaissais de la S4 que le nom. En quelques mois, jai pu acqu erir des connaissances s erieuses gr ace ` a des gens que je ne connais pas, mais qui mont aid e. Bien s ur, jai beaucoup lu. Mais d` es que javais une question, je la posais le soir, je dormais du sommeil du juste et le lendemain matin, javais ma r eponse. Cest gratuit, cest de laltruisme, cest tout simplement merveilleux. Nous vivons une epoque formidable...
A.2
Ceux par qui ce tutorial existe...
Un grand merci donc ` a de nombreuses personnes dont certaines que je ne connais pas. Pierre Bady, inestimable relecteur, ma fait des remarques tr` es pertinentes, en particulier sur la structure g en erale du document qui partait un peu dans tous les sens... Martin Morgan, non seulement connait TOUT sur la S4, mais de surcroit d egaine plus vite que son ombre quand il faut r epondre ` a une question sur r-help... Merci aussi ` a l equipe du CIRAD qui anime le forum du Groupe des Utilisateurs de R. Jamais on ne se fait jeter, jamais le moindre RTFM ou GIYF 1 . Cest cool. Bruno Falissard ma donn e (par ordre d ecroissant dimportance) une equipe 2 , son amour de R, un th` eme de recherche, des id ees, des contacts, un bureau, un ordi m ega puissant... Sans lui, je serais sans
1. Read The Fucking Manuel ou Google Is Your Friend, r eponses classiques faites a ` ceux qui posent des questions sans avoir pris le temps de chercher par eux-m emes. 2. La MEILLEEEEUUUURE des equipes !
47
48
ANNEXE A. REMERCIEMENTS
doute encore en train de v eg eter dans une impasse. Merci ` a Scarabette pour ses avis, sa fraicheur et son impertinence. Merci ` a Cathy et Mich` ele, mes deux chasseuses de fautes pr ef er ees. Enn, merci ` a la R Core Team pour the free gift of R...
Bibliographie
[1] S. Baillargeon. Programmation en R: incorporation de code C et cr eation de packages, 2006 http://www.mat.ulaval.ca/leadmin/informatique/LogicielR/ ProgR AppelC Package 210607.pdf. [2] S. Baillargeon. Programmation en R: incorporation de code C et cr eation de packages, 2006 http://www.mat.ulaval.ca/leadmin/informatique/LogicielR/ ProgR AppelC Package Pres.pdf.
49
Index
- Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 ?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22 [<- . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 -Aaide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14, 16 R CMD build . . . . . . . . . . . . . . . . . . . . . . 31 R CMD check . . . . . . . . . . . . . . . . . . . . . . 30 regex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22, 38, 41 en double . . . . . . . . . . . . . . . . . . . . . . . . . . 44 modi e . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 multiples . . . . . . . . . . . . . . . . . . . . . . . . . . 23 alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22, 26 arborescence . . . . . 12, 14, 15, 25, 38, 41, 47 arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 avanc ee majeure . . . . . . . . . . . . . . . . . . . . . . . 51 -Bbase de donn ees . . . . . . . . . . . . . . . . . . . . . . . . 11 bug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9, 10, 17 -Ccaract` eres sp eciaux . . . . . . . . . . . . . . . . . . . . . . 9 carre . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 CIRAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 classe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39, 41 ClassU.R . . . . . . . . . . . . . . . . . . . . . . . . . . 34, 36 ClassV-ClassW.R . . . . . . . . . . . . . . . . . . 34, 37 ClassV.R . . . . . . . . . . . . . . . . . . . . . . . . . . 34, 36 ClassW.R . . . . . . . . . . . . . . . . . . . . . . . . . . 34, 36 code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Collate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18, 38 communaut e . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 compatibles PC . . . . . . . . . . . . . . . . . . . . . . . . 10 compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 conguration dordinateur . . . . . . . . . . . . . . . 7 construction . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 cr eation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 cr eation dun package cheminement . . . . . . . . . . . . . . . . . . . . . . 21 classique . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 S4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 -Dd ebuggage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 d ep ot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 dataAges.Rda . . . . . . . . . . . . . . . . . . . . . . . . . 11 dataAges.rda . . . . . . . . . . . . . . . . . . . . . . . . . 34 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 debuggage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Depends . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17, 20 describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 DESCRIPTION . . . . . . . . 1416, 18, 20, 27, 38 Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Collate . . . . . . . . . . . . . . . . . . . . . . . 18, 38 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Depends . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Description . . . . . . . . . . . . . . . . . . . . . . 17 Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . 17 LazyLoad . . . . . . . . . . . . . . . . . . . . . . . . . . 17 License . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Maintener . . . . . . . . . . . . . . . . . . . . . . . . . 17 Package . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
50
INDEX Version . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Description . . . . . . . . . . . . . . . . . . . . . . . . . . 17 details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 documentation . . . . . . . . . . 20, 31, 40, 43, 44 alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 arguments . . . . . . . . . . . . . . . . . . . . . . . . . 28 code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 describe . . . . . . . . . . . . . . . . . . . . . . . . . . 26 details . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 enumerate . . . . . . . . . . . . . . . . . . . . . . . . . 26 example . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 chier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 itemize . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 m ethode . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 pi` ege . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 r edaction . . . . . . . . . . . . . . . . . . . . . . . . . . 25 r ef erences . . . . . . . . . . . . . . . . . . . . . . . .26 S4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 seealso . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 syntaxe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 donn ees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 chier daide . . . . . . . . . . . . . . . . . . . . . . . 29 DOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8, 30 -EEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 enumerate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 epoque formidable . . . . . . . . . . . . . . . . . . . . . 51 erreur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9, 30 fatale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 exemple. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33 export . . . . . . . . . . . . . . . . . . . . . . . . . 18, 19, 39 exportClasses . . . . . . . . . . . . . . . . . . . . . . . . 39 exportMethods . . . . . . . . . . . . . . . . . . . . . . . . 39 expression r eguli` ere . . . . . . . . . . . . . . . . . . . . 19
51 -Fchier . . . . . . . . . . . . . . . . . . . . . . . . 9, 11, 14, 41 documentation . . . . . . . . . . . . . . . . . . . . . 31 chier daide . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 chier daide voir documentation29 FileZilla. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 nalisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 fonction . . . . . . . . . . . . . . . . . . . . . . . . 10, 28, 39 export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 chier daide . . . . . . . . . . . . . . . . . . . . . . . 28 import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 ftp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 -GGlobal.R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 global.R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 -Hhelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22, 41 HTML Help Workshop . . . . . . . . . . . . . . . . . . 7 -Iimport . . . . . . . . . . . . . . . . . . . . . . . . . 18, 20, 40 importFrom . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 imputation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 impute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 installation de programme . . . . . . . . . . . . . . . 7 invisible. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 itemize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 -Kkeyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 kml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 -LLaTeX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7, 25 LazyLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 linkS4class . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8, 30 -Mm ethode . . . . . . . . . . . . . . . . . . . . . . . . . . . 39, 41
52 g en erique . . . . . . . . . . . . . . . . . . . . . . . . . . 41 sp ecique . . . . . . . . . . . . . . . . . . . . . . . . . . 41 test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 main.R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 main.r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Maintener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 MiKTeX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7, 8 MinGW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 miniKml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 -NNAMESPACE . . . . . . . . . . . . . . 14, 1820, 24, 40 nom de chier. . . . . . . . . . . . . . . . . . . . . . . . . .15 -Pp edagogie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 pacakge nalisation . . . . . . . . . . . . . . . . . . . . . . . . . 30 pacakge.skeleton . . . . . . . . . . . . . . . . . . . . .41 Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 package cr eation . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 package.skeleton . . . . . . . . . . . . . 14, 15, 37 packClassic . . . . . . . . . . . . . . . . . . . . . . . . . . 14 packClassic-internal.Rd . . . . . . . . . . . . 24 packS4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 priv ees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 progClassic.R . . . . . . . . . . . . . . . . . . . . . . . . 11 Progra~1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 programme . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Programme File . . . . . . . . . . . . . . . . . . . . . . . . 8 prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 38 publique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
INDEX R CMD build windows-windows . . . . . . . . . . . . . . . .31 R CMD build . . . . . . . . . . . . . . . . . . . . . . . . . . 30 R CMD check R CMD check aide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 R CMD check . . . . . . . . . . . . . . . . . . . . . . . . . . 30 R CMD Rd2dvi . . . . . . . . . . . . . . . . . . . . . . . . . 31 R Core Team . . . . . . . . . . . . . . . . . . . . . . .11, 52 r ef erences . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 r epertoire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 racine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 r esultat attendu. . . . . . . . . . . . . . . . . . . . . . . .10 r` egle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9, 22, 33 Read-and-delete-me . . . . . . . . . . . . . . . . . . 15 remerciement . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Rpath.bat . . . . . . . . . . . . . . . . . . . . . . . . . . 8, 30 Rtools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 -SS4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 seealso . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
-Ttest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9, 10, 35 choix judicieux. . . . . . . . . . . . . . . . . . . . .10 compatible . . . . . . . . . . . . . . . . . . . . . . . . . 11 conception . . . . . . . . . . . . . . . . . . . . . . . . . 10 gestion automatique . . . . . . . . . . . . 11, 13 gestion manuelle . . . . . . . . . . . . . . . 11, 13 informatique . . . . . . . . . . . . . . . . . . . . . . . 10 testsClassU.R . . . . . . . . . . . . . . . . . . . . . . . . 34 testsClassV-ClassW.R . . . . . . . . . . . . . . . . 34 testsClassV.R . . . . . . . . . . . . . . . . . . . . . . . . 34 testsClassW.R . . . . . . . . . . . . . . . . . . . . . . . . 34 testsProgClassic.R . . . . . . . . . . . . . . . 1113 -Rtextttinternal . . . . . . . . . . . . . . . . . . . . . . . . . . 24 R CMD build textttregex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 R CMD build aide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 R CMD build linux-linux . . . . . . . . . . . . . . . . . . . . 31 TMPDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8 toy example. . . . . . . . . . . . . . . . . . . . . . . . . . . .11 R CMD build windows-linux . . . . . . . . . . . . . . . . . . 31 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
INDEX -Uupload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32, 48 URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 -Vvaleur manquante . . . . . . . . . . . . . . . . . . . . . . 10 variable denvironnement . . . . . . . . . . . . . . . . . . . . 8 Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 visibilit e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 -Wwarnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 -Zz. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 ZZZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
53

Genolini ConstruireUnPackage

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Genolini ConstruireUnPackage

Загружено:

Авторское право:

Доступные форматы

Construire un Package

Table des mati` eres

` TABLE DES MATIERES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 27 28 28 28 29 30 31 31 31 31 33 33 35 35 36 36 37 37 38 38 38 38 39 41 42 44 46 46

Cr eation dun package classique

Conguration de votre ordinateur 1

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE http://filezilla-project.org/

Ajustements pour MiKTeX

1.2. CREATION DUN PROGRAMME... QUI FONCTIONNE !

Cr eation dun programme... qui fonctionne !

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

1.2. CREATION DUN PROGRAMME... QUI FONCTIONNE !

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

Au nal, on obtient larborescence suivante :

1.2. CREATION DUN PROGRAMME... QUI FONCTIONNE !

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

Cr eation de larborescence et des chiers

1.3. CREATION DE LARBORESCENCE ET DES FICHIERS

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

Cr eation des aides pour les donn ees

Cette instruction cr ee le chier daide funcDerniereMinute.Rd dans le r epertoire courant.

1.3. CREATION DE LARBORESCENCE ET DES FICHIERS

Visibilit e des fonctions : NAMESPACE

DES FONCTIONS : NAMESPACE 1.4. VISIBILITE

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

Au nal, voila notre chier NAMESPACE :

1.5. PREPARATION DE LA DOCUMENTATION

Cest long, cest fastidieux, ca nest pas le moment...

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

Que faut-il documenter ?

1.5. PREPARATION DE LA DOCUMENTATION

Cette aide souvrira donc ` a lappel de help(publicA).

Les alias multiples

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

Eacer les docs des priv es

1.6. REDACTION DES DOCUMENTATIONS

Appliqu e` a notre package packClassic, cela donne :

R edaction des documentations

G en eralit es pour toutes les documentations

1.6. REDACTION DES DOCUMENTATIONS

Pr esentation g en erale du package

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

1.6. REDACTION DES DOCUMENTATIONS

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

Construction (ou compilation)

1.7. FINALISATION ET CREATION

CHAPITRE 1. CREATION DUN PACKAGE CLASSIQUE

Cr eation dun package en S4

Conguration de votre ordinateur

Rigoureusement identique ` a la cr eation dun package classique.

Cr eation dun programme... fonctionne !

Quelques r` egles de plus

2.2. CREATION DUN PROGRAMME... FONCTIONNE !

CHAPITRE 2. CREATION DUN PACKAGE EN S4

2.3. CREATION DE LARBORESCENCE ET DES FICHIERS

Cr eation de larborescence et des chiers

CHAPITRE 2. CREATION DUN PACKAGE EN S4

Aides pour les donn ees

DES CLASSES ET DES METHODES 2.4. VISIBILITE (NAMESPACE)

Visibilit e des classes et des m ethodes (NAMESPACE)

L` a encore, on distingue les export des import.

Notre Les Les Les

CHAPITRE 2. CREATION DUN PACKAGE EN S4

Enn, il nous faut exporter les fonctions classiques non S4 :