Programmation en R : incorporation de code C et création de packages 1

Transcription

1 Programmation en R : incorporation de code C et création de packages 1 Table des matières Sophie Baillargeon Université Laval Rédigé en février 2006, révisé en juin Introduction Préalables informatiques Installation de programmes Détermination du PATH Définition de la variable d environnement TMPDIR Incorporation de code C en R Particularités du code C Démarche d incorporation de code C en R Compilation du code C Chargement en R du code C compilé Appel en R des fonctions programmées en C Packages R Installation et utilisation d un package R Création d un package R Élaboration des fichiers sources A - Création du répertoire de base avec la fonction «package.skeleton» B - Ajout de fichiers pour l incorporation de code C, C++ ou FORTRAN C - Modification des fichiers d information sur le package Vérification et construction du package Solution à différents messages d erreur Utilisation de WinEdt comme éditeur de code R Bibliographie Remarque : Le fonctionnement des techniques présentées dans ce document n est pas garanti pour des versions de R antérieures à la version Pour éviter tout problème et perte de temps, assurez-vous d avoir la version de R la plus récente (téléchargeable sur le site internet

2 1 Introduction Pourquoi R et non S-PLUS? S est un langage de programmation flexible de calculs statistiques et de production de graphiques. Pour utiliser ce langage, deux implémentations sont offertes : S-PLUS et R. S-PLUS est un logiciel commercial distribué par la compagnie Insightful et R est un logiciel libre. Bien que R ait une interface moins conviviale que S-PLUS et que la gestion de jeux de données y soit moins intuitive, il possède de nombreux avantages sur S-PLUS (Hornik, 2007). Étant donné que R est gratuit, il assure à un statisticien qui l utilise pour illustrer ses recherches que ses résultats sont reproductibles par quiconque. De plus, R a maintes fois prouvé être plus rapide que S-PLUS pour effectuer certains calculs et il possède plus d options graphiques. De plus en plus de chercheurs en statistique tournent le dos à S-PLUS au dépend de R. La communauté d utilisateurs et de développeurs R est grandissante et très active ( En conséquence, le logiciel est en constante évolution : des mises à jour majeures sont effectuées environ tous les 6 mois, les bugs sont identifiés et corrigés rapidement et plusieurs packages sont disponibles en sus. Ces packages, souvent élaborés par des experts dans leur domaine, permettent de faire les analyses les plus diverses en R. En outre, l aide de R et ses manuels d utilisateur sont très complets et le support à l utilisateur sous la forme de listes courriels est efficace. Bref, R est un logiciel libre bien documenté, stable et sûr. Pour toutes ces raisons, ce document traite de programmation en R et non en S-PLUS. Sachez cependant qu étant donné que R et S-PLUS sont des dialectes du même langage, le langage S, toutes les techniques décrites ici sont aussi réalisables avec S-PLUS à quelques différences près dans la méthodologie. Quel objectif est visé par ce document? Ce document décrit la mise en œuvre de certaines techniques qui exploitent des possibilités avancées de programmation en R. L objectif du document est de rendre le lecteur capable d intégrer du code C dans des programmes R et de créer des packages R. L incorporation de code C en R permet d augmenter la vitesse d exécution de certains programmes et un package regroupe, organise et documente des fonctions R, les rendant ainsi plus facilement utilisables et partageables. Ces techniques sont présentées pour les utilisateurs de R sur Linux et sur Windows. Que contient ce document et comment se structure-t-il? Le document comporte cinq sections, mise à part l introduction. Premièrement, les préalables informatiques sont décrits à la section 2. Dans cette section, les utilisateurs de R sur Windows trouveront des informations concernant la préparation de leur ordinateur afin de pouvoir mettre en oeuvre les techniques présentées. Ensuite, il est décrit point par point, aux sections 3 et 4, comment intégrer du code C en R et comment créer un package R. Ces deux sections forment le cœur du document. À la section 5, vous trouverez une liste de problèmes possibles en cours de travail et leurs solutions. Finalement, une mention à propos de l utilisation du logiciel WinEdt en tant qu éditeur de code R se trouve à la section 6. Notons qu une présentation pdf (Baillargeon, 2006) complète le document en illustrant de façon encore plus concrète les méthodologies détaillées ici. 2

3 2 Préalables informatiques Les ordinateurs Linux du Département de mathématiques et de statistique possèdent tous les logiciels nécessaires à l appel de code C en R et à la création d un package R. Par contre, un ordinateur sur plateforme Windows n a pas, par défaut, tous les programmes requis pour mettre en œuvre ces techniques. Voici comment préparer son ordinateur Windows à la création de packages et à l appel code C en R. 2.1 Installation de programmes En plus du logiciel R, on doit installer les programmes utilitaires suivants si on ne les a pas déjà (R Team, 2007a, annexe E ; : Installations obligatoires : Perl : Rtools : - Le fichier exécutable Rtools.exe téléchargeable à cette adresse installe quelques outils Unix pour R ainsi que les compilateurs C, C++ et FORTRAN de MinGW. Certains des outils R utilisent des DLL de Cygwin. Si vous avec déjà une version de Cygwin installée sur votre ordinateur, veuillez lire le fichier Rtools.txt à l adresse ci-dessus et suivre les instructions. Installations optionnelles : HTML Help Workshop : - Permet de produire de la documentation en format.chm si désiré. Un compilateur LaTeX (un bon compilateur gratuit est MiKTeX téléchargeable sur le site web - Permet de produire de la documentation LaTeX, dvi et pdf si désiré. 2.2 Détermination du PATH Afin que l ordinateur reconnaisse les commandes nécessaires à la création d un package ou l incorporation du code C en R, son PATH doit contenir le répertoire «bin» de Rtools, Perl, MinGW, R et LaTeX ainsi que le répertoire de Html Help Workshop. Il n est pas recommandé de modifier le PATH de son ordinateur de façon permanente car cela pourrait ralentir un peu l ordinateur et même causer le non fonctionnement de certains programmes. Il est plutôt recommandé de modifier le PATH chaque fois que nous ouvrons une fenêtre de commandes dans le but d exécuter des commandes R. Pour ce faire, une façon simple et efficace est de créer un fichier «.bat» contenant la nouvelle définition du PATH. Ce fichier sera appelé à l ouverture d une fenêtre de commandes simplement en tapant le nom complet du fichier incluant son chemin d accès. Par exemple, si le fichier est nommé Rpath.bat et placé dans le répertoire «C:\», à l ouverture d une fenêtre de commande il faudrait taper la commande suivante pour définir le PATH : C:\Rpath.bat 3

4 Pour créer ce fichier, il suffit d utiliser un éditeur de texte ASCII, tel que le Bloc-notes. Le fichier contiendra uniquement la ligne suivante : PATH=C:\Rtools\bin;C:\Perl\bin;C:\Rtools\MinGW\bin;C:\PROGRA~1\R\R-2.5.0\bin; C:\PROGRA~1\MIKTEX~1.6\miktex\bin;C:\PROGRA~1\HTMLHE~1; C:\WINDOWS;C:\ WINDOWS \system32 (à adapter selon l emplacement des répertoires sur son ordinateur). La position de ces répertoires dans le PATH importe peu, à l exception du répertoire de Rtools qu il faut placer au tout début car certains fichiers du Rtools ont des noms usuels qui pourraient entrer en conflit avec d autres fichiers dans le PATH. Il est très important de ne pas laisser traîner d espaces avant et après les pointsvirgules. En fait, il vaut mieux que le PATH ne contienne aucun espace, c est pourquoi dans l exemple ci-dessus les répertoires contenant des espaces, tel «Program Files» ont été remplacé par leur forme courte (trouvée par la commande «dir /x» dans une fenêtre de commandes). Les répertoires de Windows ont été inclus dans le PATH pour s assurer que certaines commandes de base soient toujours accessibles. 2.3 Définition de la variable d environnement TMPDIR Pour certaines versions de Windows, il sera nécessaire de définir la variable d'environnement TMPDIR en fonction de l emplacement du répertoire de fichiers temporaires de son ordinateur. Par exemple, sur Windows XP, il faut aller dans : «Menu démarrer Panneau de configuration Système Avancé» et cliquer sur «Variables d environnement». Dans la section «Variables système», cliquer sur «Nouveau» et entrer les informations suivantes : Nom de la variable = «TMPDIR», Valeur de la variable = «C:\WINDOWS\TEMP»). Remarque : Le problème réglé par cette étape peut aussi être réglé en créant un répertoire «C:\temp» sur son ordinateur. L incorporation de code C en R sur Windows exige seulement l installation de Perl, Rtools et MinGW, ainsi que l ajout des répertoires «bin» de ces logiciels en plus de celui de R au Path de votre ordinateur s ils ne s y trouvent pas déjà. Notez également que pour créer un package ne contenant pas de code en langage C, C++ et FORTRAN, le compilateur MinGW n est pas requis. Mentionnons finalement que si vous avez un compilateur tel Visual C++ ou Borland C++, il est possible de vous en servir afin de créer le fichier.dll dont R a besoin pour incorporer du code C. Pour ce faire, vous devez suivre les instructions présentes dans le fichier README.packages se trouvant dans le répertoire de R de votre ordinateur (ex. : C:\Program Files\R\R-2.5.0). Par contre, il est plus simple d installer MinGW. En outre, pour créer un package R contenant du code C vous avez besoin de MinGW. 4

5 3 Incorporation de code C en R Cette section résume la marche à suivre afin d incorporer du code C dans un programme R. Pour ce faire, on utilise une fonction R qui sert d interface pour du code C compilé préalablement chargé en R. L utilisation de fonctions écrites en C dans un programme R s effectue en trois étapes : 1) Compiler le code C afin de créer un objet partagé (fichier.so) si on travaille sur Linux ou une librairie dynamique (fichier.dll) si on travaille sur Windows ; 2) Charger en R l objet partagé ou la librairie dynamique créé à l étape précédente avec la fonction «dyn.load» ; 3) Appeler en R les fonctions créées dans le code C avec une fonction d interface. Dans ce document, seule la fonction d interface.c est décrite. Il existe deux autres fonctions d interface R/C :.Call et.external. Ces interfaces sont plus puissantes car elles permettent d utiliser des objets R dans le code C, par contre elles sont plus compliquées d utilisation que.c. Si la tâche à programmer en C est assez simple et ne requière aucun appel de code R, il est conseillé d utiliser l interface.c. Notons que du code C++ peut aussi être incorporé avec l interface.c et du code FORTRAN peut être appelé grâce à une autre interface, la fonction.fortran. Pour plus d informations concernant l incorporation de code C, C++ ou FORTRAN en R, la meilleure référence est le manuel Writing R Extensions (R Team, 2007b, chapitre 4). 3.1 Particularités du code C Le code C incorporé en R doit respecter les propriétés suivantes (Peng et Leeuw, 2002) : Les fonctions C appelées en R doivent être de type «void». Elles doivent retourner les résultats des calculs par leurs arguments. Les arguments passés aux fonctions C sont des pointeurs à un nombre ou à un tableau. Il faut donc correctement déréférencer les pointeurs dans le code C afin d obtenir la valeur d un élément dont l adresse est contenue dans le pointeur. On déréférence un pointeur en ajoutant «*» devant ce pointeur. Il est préférable d inclure dans tout fichier contenant du code C à être appelé en R le fichier d entête R.h en ajoutant au début du fichier de code C la ligne : #include <R.h> De plus, il est possible d utiliser en C certaines fonctions mathématiques R en incluant le fichier d en-tête Rmath.h dans votre fichier de code C par la ligne : #include <Rmath.h> Par exemple, on peut utiliser les fonctions de distribution telles dnorm, pnorm, qnorm et rnorm. Le document Writing R Extensions à la section 5.7 (R team, 2007b) liste les fonctions utilisables. Le fichier contenant le code C doit porter l extension «.c». 5

6 Voici un exemple, tiré du document An introduction to the.c Interface to R (Peng et Leeuw, 2002), d un code C très simple qui détient toutes ces propriétés. Ce programme affiche n fois à l écran la chaîne de caractères «Hello, world!». Le fichier hello.c contenant le code C a l allure suivante : #include <R.h> void hellofct(int *n) { int i; } for(i=0; i < *n; i++) { Rprintf("Hello, world!\n"); } 3.2 Démarche d incorporation du code C en R Détaillons maintenant les trois étapes présentées dans l introduction afin d incorporer du code C en R. Notons d abord que la démarche d incorporation de C en R est la même peu importe la plateforme informatique avec laquelle on travaille à la condition que tous les logiciels nécessaires sont installés sur l ordinateur. Afin d illustrer la démarche, l exemple du programme «Hello, world!» sera utilisé à chaque étape. Supposons pour cet exemple que l on travaille sur une plateforme Windows XP et que le fichier hello.c se trouve dans le répertoire «C:\Mes documents» Compilation du code C La première étape consiste à compiler le code C afin de créer un objet partagé (fichier.so) si on travaille sur Linux ou une librairie dynamique (fichier.dll) si on travaille sur Windows. On effectue cette étape dans une fenêtre terminal sur Linux ou dans une fenêtre de commandes sur Windows. On se place d abord dans le répertoire où se trouve le fichier contenant le code C, puis on tape la commande : R CMD SHLIB nomfichier.c L objet partagé ou la librairie dynamique créé par cette commande se nommera nomfichier.so ou nomfichier.dll. Pour en savoir plus sur les options de la fonction «R CMD SHLIB», tapez la commande : R CMD SHLIB --help EXEMPLE : On ouvre une fenêtre de commande (accessible par «Menu démarrer Programmes Accessoires Invite de commandes»). On tape la commande «cd C:\Mes documents» afin de se placer dans le bon répertoire, puis on tape «R CMD SHLIB hello.c» pour compiler le code C. 6

7 3.2.2 Chargement en R du code C compilé Il faut ensuite charger en R l objet partagé ou la librairie dynamique créé à l étape précédente avec la fonction «dyn.load». Pour ce faire, on ouvre R et on se place dans le répertoire courant contenant le fichier de code C compilé.so ou.dll (par le menu «Fichier Changer le répertoire courant» ou par la commande «setwd»). On charge ensuite ce code compilé par la commande suivante (le nom du fichier doit obligatoirement être entre guillemets) : > dyn.load("nomfichier.so") ou > dyn.load("nomfichier.dll") On peut aussi utiliser le nom complet du fichier incluant son chemin d accès pour le charger en R. On évite ainsi de devoir changer le répertoire courant. On peut faire un test pour s assurer que les fonctions C ont été correctement chargées en R. Pour ce faire, on utilise la fonction «is.loaded» avec, en argument, le nom entre guillemet d une fonction C. Si cette commande ne retourne pas «TRUE» le premier point de la section 5 pourrait vous aider à régler le problème. EXEMPLE : On ouvre R puis on tape la commande «dyn.load("c:/mes documents/hello.dll")». Notez qu en R les chemins d accès doivent être fournis en utilisant le symbole «/» ou «\\» entre les répertoires plutôt que «\» Appel en R des fonctions programmées en C On peut finalement appeler en R les fonctions créées dans le code C avec la fonction d interface.c. On utilise cette fonction de la façon suivante : >.C("nomfonction",argument1,argument2,.) Le nom de la fonction doit obligatoirement être entre guillemets. Il est préférable de s assurer que chaque argument passé à la fonction C est du bon type en appliquant aux arguments une fonction telle «as.integer», «as.double», «as.character» ou «as.logical». De plus, pour rendre les appels à la fonction C plus conviviaux, il est conseillé de créer une fonction R qui enveloppe l appel à la fonction C. EXEMPLE : On se crée une fonction R qui appelle la fonction C par le programme R suivant : Hello <- function(n){.c("hellofct",as.integer(n)) } On peut ensuite utiliser cette fonction pour afficher disons 5 fois «Hello, world!» par la commande: > Hello(5) 7

8 D autres exemples simples d incorporation de code C en R sont présentés dans le document An introduction to the.c Interface to R de Peng et Leeuw (2002). 4 Packages R La meilleure façon de partager des fonctions R que l on a programmées consiste à les mettre dans un package. Un package R se présente sous la forme d un fichier compressé qui regroupe des fonctions, les documente et peut contenir des jeux de données servant à illustrer l utilisation des fonctions. Ainsi, tout y est pour faciliter la compréhension de l utilisation les fonctions. On peut rendre un package disponible à tous en le plaçant sur un site web personnel ou, mieux encore, en le mettant sur le CRAN, le réseau officiel de distribution de code et de documentation R ( On retrouve en date d aujourd hui (juin 2007) près de 1068 packages sur le CRAN. La source officielle d information concernant la création de packages R est le manuel Writing R Extensions (R Team, 2007b, chapitre 4). Certaines pages web sont aussi de bonnes références, moins complètes mais plus vulgarisées : Cette section tente de résumer et de présenter simplement les informations provenant de ces différentes sources. 4.1 Installation et utilisation d un package R Avant de savoir comment créer des packages R, il faut savoir comment les utiliser. Voici comment faire en fonction de la plateforme informatique sur laquelle on travaille. Sur Windows : Un package utilisable sur Windows possède l extension «.zip». Il est constitué de fichiers binaires précompilés. Pour l utiliser, il faut effectuer les deux étapes suivantes : 1) Installer le package (en R) : Ouvrir R, aller dans le menu «Packages Installer le(s) package(s) depuis des fichiers zip» puis sélectionner le fichier zip nompackage_version.zip contentant le package. Ce que R fait alors est simplement de dézipper le fichier zip et de placer son contenu dans le répertoire «C:\Program Files\R\R-2.5.0\library». 2) Charger le package (en R) : Aller dans le menu «Packages Charger le package» puis sélectionner le package ou taper la commande : > library(nompackage) 8

9 Sur Linux : Un package utilisable sur Linux possède l extension «.tar.gz». Il est composé des fichiers sources du package. Afin de l utiliser sur un des ordinateurs du département, il faut : 1) Installer le package (dans une fenêtre terminal) : Ouvrir une fenêtre terminal, se placer dans le répertoire contenant le fichier nompackage_version.tar.gz et taper la commande : R CMD INSTALL --library=/mat/usr/sbaillar/.r/library nompackage_version.tar.gz La localisation de la librairie est évidemment à modifier en mettant votre code d utilisateur plutôt que le mien. On peut aussi se créer un répertoire qui constituera la librairie R (ex. : /mat/usr/sbaillar/librairier/). 2) Charger le package (en R) : Ouvrir R et taper la commande : > library(nompackage, lib.loc="/mat/usr/sbaillar/.r/library") 4.2 Création d un package R Pour créer un package R, il faut élaborer les fichiers sources, puis vérifier et construire le package. L élaboration des fichiers sources se décompose en 3 étapes. Il faut d abord créer le répertoire de base du package avec la fonction «package.skeleton», ensuite y ajouter des fichiers si une partie de la programmation du package est en langage C, C++ ou FORTRAN, puis modifier les fichiers dits d information. En outre, l étape de la construction du package dépend de la plateforme informatique sur laquelle on travaille et de la plateforme à laquelle est destinée le package Élaboration des fichiers sources Les fichiers sources d un package doivent respecter une certaine structure. Notamment, ces fichiers doivent être localisés dans un répertoire portant le nom du package. Ce répertoire doit obligatoirement contenir un sous répertoire nommé man pour la documentation et un autre nommé R pour le code R. De plus, il doit contenir un fichier nommé DESCRIPTION contenant des informations bien spécifiques. Si votre package contient des jeux de données, un sous répertoire data est également requis et, finalement, il faut un sous répertoire src si des fonctions sont écrites dans le langage C, C++ ou FORTRAN. Pour simplifier la création des répertoires contenant les fichiers sources, on peut utiliser la fonction «package.skeleton» afin de créer un gabarit de base pour le package, puis ajouter si nécessaire et modifier des fichiers du répertoire. A - Création du répertoire de base du package avec la fonction «package.skeleton» a) Ouvrir R et se positionner dans le répertoire courant qui contiendra la package. b) Créer toutes les fonctions et les jeux de données à inclure dans le package. Il est bien de rédiger un programme (aussi appelé script) R qui crée tous ces objets. Ensuite, on peut lire ce programme avec la commande : 9

10 > source("chemin_d accès_approprié/programme.r") c) Utiliser la fonction «package.skeleton» qui crée les répertoires et les fichiers de base avec la commande : > package.skeleton(list=c("fct1","fct2",.,"data1","data2", ), name="nompackage") où «fct1», «fct2», etc. sont les fonctions à inclure dans le package et «data1», «data2», etc. sont les jeux de données à mettre dans le package. Si on a omis de se positionner dans le répertoire courant qui contiendra la package, on peut aussi spécifier ce répertoire par l argument «path» de la fonction «package.skeleton». Si le package doit contenir un grand nombre d objets, il vaut mieux remplacer la dernière étape par les deux étapes suivantes : c) Laisser dans notre environnement de travail seulement les fonctions et les jeux de données à inclure dans le package. Commandes R utiles à cette étape : > ls() # Pour avoir la liste de tous les objets dans l environnement de travail > rm(nomobject) # Pour enlever l objet «nomobject» de l environnement de travail > rm(list = ls()) # Pour enlever tous les objets de l environnement de travail 2 d) Utiliser la fonction «package.skeleton» sans spécifier la liste des objets à mettre dans le package. Par défaut, tous les objets présents dans l environnement de travail sont inclus. > package.skeleton(name="nompackage") EXEMPLE : On ouvre R puis on va dans «Fichier Changer le répertoire courant» et on inscrit «C:\Mes documents\packager». On crée nos fonctions et nos jeux de données : > f <- function(x,y) x+y > g <- function(x,y) x-y > d <- data.frame(a=1, b=2) > e <- rnorm(1000) On crée le package par la commande : > package.skeleton(list=c("f","g","d","e"), name="monpkg") Ou encore, on crée un fichier nommé programme.r dans le répertoire qui contiendra le package. Ce fichier a l allure suivante : 2 Remarque : Lors de l ouverture d une session en S-Plus, l environnement de travail contient tous les objets créés lors des sessions passées dans le même répertoire. En R c est différent. Lors de l ouverture d une nouvelle session, l environnement de travail est vide. Par contre, on peut conserver des objets créés lors d une session en sauvant une image de la session. On peut ensuite retrouver ces objets lors d une nouvelle session R en chargeant l environnement de travail de l image sauvée («Fichier Charger l environnement de travail» ou avec la fonction «load»). 10

11 Puis, on exécute les commandes R suivantes : > rm(list = ls()) > source("programme.r") > package.skeleton(name="monpkg") f <- function(x,y) x+y g <- function(x,y) x-y d <- data.frame(a=1, b=2) e <- rnorm(1000) On peut vérifier dans un gestionnaire de fichiers que la fonction «package.skeleton» a créé les répertoires et les fichiers suivants :.\nompackage.\nompackage\data.\nompackage\data\data1.rda.\nompackage\data\data2.rda.\nompackage\man.\nompackage\man\nompackage-package.rd.\nompackage\man\fct1.rd.\nompackage\man\fct2.rd.\nompackage\man\data1.rd.\nompackage\man\data2.rd.\nompackage\r.\nompackage\r\fct1.r.\nompackage\r\fct2.r.\nompackage\read-and-delete-me.\nompackage\description Chaque fichier du sous répertoire.\nompackage\data est un jeu de données et les fichiers du sous répertoire.\nompackage\r contiennent les programmes R pour créer les fonctions. Dans le sous répertoire.\nompackage\man, on retrouve des fichiers qui serviront à construire la documentation. B - Ajout de fichiers pour l incorporation de code C, C++ ou FORTRAN : Pour inclure du code C, C++ ou FORTRAN dans un package, il faut ajouter aux fichiers du package le répertoire.\nompackage\src et y sauver un fichier «.c» ou «.f» contenant le code. De plus, il faut ajouter un fichier dans le répertoire.\nompackage\r contenant la fonction suivante :.First.lib <-function (lib, pkg) { library.dynam("nompackage", pkg, lib) } Ce fichier est souvent nommé zzz.r, mais le nom du fichier importe peu tant qu il porte l extension «.R». Grâce au code dans ce fichier, le fichier dll du code C, C++ ou FORTRAN compilé est chargé en R en même temps que le package. L utilisateur du package n a donc pas besoin de charger le fichier dll avec la fonction «dyn.load». D ailleurs aucune commande «dyn.load» ne doit apparaître dans le code R du package. De plus, dans le code R, il faut modifier tous les appels des 11

12 fonctions.c,.fortran,.call ou.external en y ajoutant l argument «PACKAGE="nompackage"» (ex. : l appel «.C("fctC",as.integer(a))» devient «.C("fctC",as.integer(a),PACKAGE="nompackage")»). Remarque : Si le package contient un espace de nommage (un fichier NAMESPACE), le fichier zzz.r ne doit pas être celui définit ci-dessus. Il doit plutôt être le suivant :.onload <-function (lib, pkg) { library.dynam("nompackage", pkg, lib) } C - Modification des fichiers d information sur le package : Afin de finaliser les fichiers sources du package, il faut aller modifier l information dans le fichier.\nompackage\description et les fichiers.rd du sous répertoire.\nompackage\man. La fonction «package.skeleton» a créé des gabarits pour ces fichiers. Ils ont donc déjà la bonne structure. La modification de ces fichiers est une étape longue, mais nécessaire a) Modifier les informations du fichier.\nompackage\description. Les champs obligatoires sont ceux intitulés Package, Version, License, Description, Title, Author et Maintainer. Le manuel Writing R Extensions (R Team, 2007b) décrit ces champs, ainsi que tous ceux qui sont optionnels. Si le package créé utilise des fonctions provenant d autres packages, ceux-ci doivent être mentionnés dans le champ Depends du fichier DESCRIPTION. Les package inscrits dans le champ Depends seront automatiquement chargés en R lors du chargement du package créé. b) Modifier les informations des fichiers.rd dans le sous répertoire.\nompackage\man. Ces fichiers vont permettre de générer la documentation des fonctions et des jeux de données du package. Le langage dans lequel sont écrits les fichiers.rd ressemble à LaTeX. Le chapitre 2 du manuel Writing R Extensions (R Team, 2007b) contient toutes les informations à connaître pour rédiger de la documentation en format.rd. EXEMPLE : Attention : Il est important que le nom du package soit le même partout. Particulièrement, si le nom du répertoire du package ne correspond pas à la chaîne de caractères après «Package:» dans le fichier.\nompackage\description, il y a une erreur lors de la construction du package Vérification et construction du package Lorsque les fichiers sources sont prêts, il ne reste plus qu à les vérifier, puis à construire le package. Ces deux étapes se font dans une fenêtre de commandes sur Windows ou une fenêtre terminal sur Linux. On peut aussi en profiter alors pour générer un document dvi, ps ou pdf documentant le package en regroupant les fiches d aide de toutes les fonctions et tous les jeux de données. 12

13 VÉRIFICATION : Pour vérifier le package, il faut ouvrir une fenêtre de commande ou une fenêtre terminal, se placer dans le répertoire contenant le répertoire du package (pas dans le répertoire portant le nom package, mais un niveau au dessus). Ensuite, on tape la commande : R CMD check nompackage S il y a des erreurs, il vaut mieux ne pas les ignorer, car le package pourrait être mal construit ou ne pas être construit du tout à la prochaine étape. Les avertissements sont moins graves et leur présence ne signale pas nécessairement des problèmes futurs. Pour vérifier un package qui contient du code C, C++ ou FORTRAN, vous devrez peut-être construire le package et l installer avant de faire la vérification. DOCUMENTATION : On crée un fichier pdf documentant le package par la commande : R CMD Rd2dvi --pdf nompackage Sur Windows, le document Rd2.pdf sera alors créé dans le répertoire.\rd2dvi et sur Linux, le document nompackage.pdf sera créé dans le répertoire du package. CONSTRUCTION : Après la vérification d un package, on peut passer à sa construction. Cette dernière étape dépend de la plateforme informatique sur laquelle on travaille et de la plateforme à laquelle est destinée le package. Sur Windows pour Windows : Taper la commande : R CMD build --binary nompackage Un package binaire précompilé (pre-compiled binary package) zippé est ainsi créé. Ce fichier se nomme nompackage_version.gz où version est le numéro de la version inscrit dans le fichier DESCRIPTION. C est de ce fichier que R sous Windows a besoin pour installer un package. Pour en savoir plus sur les options de la fonction «R CMD build» (ou «R CMD check»), tapez la commande «R CMD build --help». Sur Windows pour Linux : R sur Linux a besoin des fichiers sources du package pour l installer et non d un package binaire précompilé. La construction du package se fait donc par la commande : R CMD build nompackage 13

14 qui crée un fichier nommé «nompackage_version.tar.gz» comprenant les fichiers sources du package. Ainsi, comparativement à la commande sur Windows pour Windows, il faut omettre l option «--binary». Sur Linux pour Linux : Il faut utiliser exactement la même commande que Windows pour Linux. Sur Linux pour Windows : Il s agit de la construction la plus compliquée à effectuer. Si vous avez accès à un ordinateur sur Windows, il est vraiment plus simple de créer un package R pour Windows sur Windows. Sinon, voici comment faire. 1) Créer le package pour Linux (avec la commande «R CMD build nompackage»). 2) Installer les «cross-building tools» : (documentés par Yan et Rossini, 2005). : a) Créer le répertoire./rcrossbuild. b) Placer dans ce répertoire le fichier en le nommant Makefile. c) Modifier le Makefile : Remplacer R = R par la version de R qu on utilise (ex. : R = R-2.5.0) ; Remplacer MINGW_CROSS = mingw-cross4 par la version se trouvant sur le site web (exemple : (février 2006) MINGW_CROSS = mingw-cross5). d) Dans une fenêtre terminal, se placer dans le répertoire courant./rcrossbuild et soumette les commandes : make down make xtools make prepsrc make linuxr make LinuxFresh=Yes mkrules make R Remarque : Les commandes «make linuxr» et «make R» sont longues à exécuter (environ 30 min et 15 min respectivement). 3) Créer les sous répertoire./rcrossbuild/pkgsrc et./rcrossbuild/winlibs. 4) Placer le package Linux (.tar.gz) dans le sous répertoire./rcrossbuild/pkgsrc. 5) Dans une fenêtre terminal (toujours dans répertoire courant./rcrossbuild ) soumettre la commande : 14

15 make pkg-nompackage_version 6) Le package R pour Windows a été créé et se trouve dans le répertoire./rcrossbuild/winlibs. 5 Solution à différents messages d erreur Voici certains problèmes que vous pouvez rencontrer en cours de travail et leurs solutions. Message d erreur en R lors de l appel d une fonction C avec.c : C entry point "fctc" not in load table Solution : Vous avez peut-être oublié de charger le fichier dll contenant la function "fctc". Si votre fichier dll est bien chargé et que vous aviez bien nommé votre fonction "fctc" dans votre code C, alors c est peut-être que votre compilateur a modifié le nom de votre fonction. Pour connaître le nom des fonctions exportées par un dll, suivez les étapes suivantes : - Ouvrez vous une fenêtre de commandes ; - Placez vous dans le répertoire contenant le fichier dll ; - Tapez la commande : objdump -p nomfichier.dll Le nom des fonctions se trouvent dans la section intitulée : «[Ordinal/Name Pointer] Table». Pour appeler les fonctions de ce dll en R, vous devez utiliser les noms dans le dll. (source d information : Message d erreur (de toute commande R CMD ) : R n est pas reconnu en tant que commande interne ou externe, un programme exécutable ou un fichier de commandes Solution : Ajouter le répertoire bin de R au PATH (voir section 2.2). Message d erreur (de R CMD build) : Please set TMPDIR to a valid temporary directory Solution : Définir la variable d environnement TMPDIR (voir section 2.3). Message d erreur (de R CMD build ou R CMD check) : perl n est pas reconnu en tant que commande interne ou externe, un programme exécutable ou un fichier de commandes Solution : Installer Perl et ajouter son répertoire bin au PATH (voir sections 2.1 et 2.2). 15

16 Message d erreur (de R CMD build ou R CMD check) : sh n est pas reconnu en tant que commande interne ou externe, un programme exécutable ou un fichier de commandes Solution : Installer Rtools et ajouter son répertoire bin au PATH (voir sections 2.1 et 2.2). Message d erreur (de R CMD check) : hhc : not found Solution : Installer HTML Help Workshop et ajouter son répertoire au PATH (voir sections 2.1 et 2.2). Message d erreur (de R CMD check) : LaTeX Error : file Rd.sty not found Solution : Cette erreur peut survenir si vous utilisez une ancienne version de MiKTeX. Pour régler le problème vous pouvez soit installer la version la plus récente de MiKTeX, soit suivre les étapes suivantes : a) Créer un sous répertoire nommé «tex» dans le répertoire «C:\localtexmf» ; b) Copier tous les dossiers du répertoire «C:\Program Files\R\R-2.5.0\share\texmf» dans le répertoire «C:\localtexmf\tex» ; c) Pour s assurer que tout fonctionne, aller dans : «Menu démarrer Programmes MiKTeX MiKTeX Options General» et cliquer sur «Refresh Now» et «Update Now». Avertissement (de R CMD check) : checking for CRLF line endings in C/C++/Fortran sources/headers... WARNING Found the following sources/headers with CRLF line endings: src/programme.c Some Unix compilers require LF line endings. Solution : Il faut convertir le fichier C. Cette conversion est effectuée avec la fonction «dos2unix». Sur Linux, dans une fenêtre terminal, faites rouler dans le répertoire du programme C la commande : dos2unix programme.c Sur Windows, il faut d abord installer le logiciel UDDU qu on peut télécharger gratuitement à partir de la page web : Mettre le contenu du fichier zip téléchargé dans le répertoire de son choix et ajouter ce répertoire au PATH de son ordinateur. Ensuite, dans une fenêtre de commandes, on se place dans le répertoire du programme C et on exécute la même commande que sur Linux («dos2unix programme.c»). 16

17 6 Utilisation de WinEdt comme éditeur de code R En terminant, mentionnons pour ceux qui travaillent sur Windows que le logiciel WinEdt, en plus d être très efficace pour la création de documents LaTeX, peut être adapté afin de devenir un éditeur de code R. L écriture de code R est plus intéressante dans WinEdt que dans un éditeur de texte usuel, tel le bloc-notes, car des fonctions y sont reconnus et mises en évidence par de la couleur, l italique ou le gras. Une fonctionnalité permet également de vérifier que les délimiteurs tel les parenthèses viennent tous en paire. En plus, on peut y soumettre directement du code. Plus besoin de faire des copier/coller! Afin d utiliser WinEdt comme éditeur de code R, vous devez préalablement avoir une version de WinEdt installée sur votre ordinateur. WinEdt s adapte à l édition de code R grâce à un package R nommé RWinEdt. Vous devez d abord télécharger ce package sur le CRAN ( Ensuite, vous devez simplement installer et charger le package en R. Le module d extension (plug-in) nommé RWinEdt sera automatiquement créé. Le seul détail qui complique un peu le processus est que le package RWinEdt fonctionne seulement avec R en mode sdi. Une façon pratique d ouvrir R en mode sdi est de créer un deuxième raccourci R. Le raccourci original ouvre R en mode mdi et le second l ouvrira en mode sdi. Pour créer ce deuxième raccourci, vous pouvez suivre les étapes suivantes : 1) Faire une copie du raccourci R standard (cliquer sur le raccourci standard avec le bouton de droite de la souris, sélectionner «Envoyer vers» puis «Bureau»). Renommer ce raccourci «R sdi» ou autre. 2) Modifier les propriétés du nouveau raccourci (cliquer sur le nouveau raccourci avec le bouton de droite de la souris, sélectionner «Propriétés») en ajoutant un espace puis la chaîne de caractères «"--sdi"» (avec les guillements) après l'emplacement de la cible du raccourci. Ainsi, dans l'onglet nommé «Raccourci» des propriétés du nouveau raccourci, la cible est maintenant : "C:\Program Files\R\R-2.5.0\bin\Rgui.exe" "--sdi" C est donc dans R ouvert avec ce raccourci que vous devez charger le package RWinEdt. Par la suite, lors de l utilisation de RWinEdt, vous devrez aussi ouvrir R en mode sdi afin de pouvoir soumettre du code directement dans RWinEdt. Plus d informations sur le module d extension RWinEdt se trouvent dans le fichier ReadMe.txt du package RWinEdt. 17

18 Bibliographie Baillargeon, S. (2006). Présentation intitulée Programmation en R : incorporation de code C et création de packages. Université Laval. Disponible en ligne : Hornik, K. (2007). The R FAQ. En ligne : Murdoch, D. (2007). Building R for Windows. En ligne : Peng, R.D et Leeuw, J. (2002). An introduction to the.c Interface to R. UCLA Department of Statistics. Disponible en ligne : R Development Core Team. (2007a). R Installation and Administration, version Disponible en ligne : R Development Core Team. (2007b). Writing R Extensions, version Disponible en ligne : Yan, J. et Rossini, A.J. (2005). Building Microsoft Windows Versions of R and Packages under Intel Linux. Disponible en ligne : 18