Incorporation de code C dans un programme R

Programmation en R :
incorporation de code C et création de packages1
Sophie Baillargeon
Université Laval
Rédigé en février 2006, révisé en juin 2007.
Table des matières
1 Introduction
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2
2 Préalables informatiques . . . . . . . . . . . . . . . .
2.1 Installation de programmes. . . . . . . . . . . . . .
2.2 Détermination du PATH . . . . . . . . . . . . . . .
2.3 Définition de la variable d’environnement TMPDIR
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
3
3
4
3 Incorporation de code C en R . . . . . . . . . . . . .
3.1 Particularités du code C . . . . . . . . . . . . . .
3.2 Démarche d’incorporation de code C en R . . . . .
3.2.1 Compilation du code C . . . . . . . . . . .
3.2.2 Chargement en R du code C compilé . . . .
3.2.3 Appel en R des fonctions programmées en C
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5
5
6
6
7
7
4 Packages R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1 Installation et utilisation d’un package R . . . . . . . . . . . . . . . . . . . .
4.2 Création d’un package R . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.1 É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 . . . . . . . .
4.2.4 Vérification et construction du package . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
8
8
9
9
9
11
12
12
5 Solution à différents messages d’erreur . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
6 Utilisation de WinEdt comme éditeur de code R
. . . . . . . . . . . . . . . . . . . . .
17
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
Bibliographie
1
Remarque : Le fonctionnement des techniques présentées dans ce document n’est pas garanti pour des versions de R
antérieures à la version 2.2.0. 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 http://www.r-project.org/).
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 (http://www.r-project.org/). 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
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 ; http://www.murdoch-sutherland.com/Rtools/) :
Installations obligatoires :
• Perl : http://www.activestate.com/Products/ActivePerl/Download.html
• Rtools : http://www.murdoch-sutherland.com/Rtools/installer.html
- 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 : http://msdn.microsoft.com/library/enus/htmlhelp/html/hwmicrosofthtmlhelpdownloads.asp
- 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 http://www.miktex.org/)
- 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
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
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
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 ».
3.2.1 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
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 « \ ».
3.2.3 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
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 (http://cran.rproject.org). 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 :
http://www.maths.bris.ac.uk/~maman/computerstuff/Rhelp/Rpackages.html
http://zoonek2.free.fr/UNIX/48_R/02.html#15.
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
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.
4.2.1 É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
> 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
f <- function(x,y) x+y
g <- function(x,y) x-y
d <- data.frame(a=1, b=2)
e <- rnorm(1000)
Puis, on exécute les commandes R suivantes :
> rm(list = ls())
> source("programme.R")
> package.skeleton(name="monpkg")
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
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 : http://zoonek2.free.fr/UNIX/48_R/02.html#15
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.
4.2.1 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
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
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 » : http://cran.r-project.org/doc/contrib/Makefile-rcb
(documentés par Yan et Rossini, 2005). :
a) Créer le répertoire ‘./RCrossBuild’.
b) Placer dans ce répertoire le fichier http://cran.r-project.org/doc/contrib/Makefile-rcb en le
nommant Makefile.
c) Modifier le Makefile :
• Remplacer R = R-2.1.0 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 http://www.stats.ox.ac.uk/pub/Rtools/ (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
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 : http://www.stats.uwo.ca/faculty/murdoch/software/compilingDLLs/index.html#badname).
• 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
• 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 : http://www.bastet.com. 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
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 (http://cran.rproject.org/src/contrib/Descriptions/RWinEdt.html). 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
2.2.1 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
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 :
http://www.mat.ulaval.ca/fileadmin/informatique/LogicielR/ProgR_AppelC_Package_Pres.pdf
Hornik, K. (2007). The R FAQ. En ligne : http://cran.r-project.org/doc/FAQ/R-FAQ.html
Murdoch, D. (2007). Building R for Windows. En ligne :
http://www.murdoch-sutherland.com/Rtools/
Peng, R.D et Leeuw, J. (2002). An introduction to the .C Interface to R. UCLA Department of
Statistics. Disponible en ligne : http://www.cs.colostate.edu/~sokolov/interface.pdf.
R Development Core Team. (2007a). R Installation and Administration, version 2.5.0. Disponible
en ligne : http://cran.r-project.org/doc/manuals/R-admin.pdf.
R Development Core Team. (2007b). Writing R Extensions, version 2.5.0. Disponible en ligne :
http://cran.r-project.org/doc/manuals/R-exts.pdf.
Yan, J. et Rossini, A.J. (2005). Building Microsoft Windows Versions of R and Packages under Intel
Linux. Disponible en ligne : http://cran.r-project.org/doc/contrib/cross-build.pdf
18