Créer une extension pour R

September 30, 2009
By

This post was kindly contributed by Alea - R - go there to comment and to read the full post.

Cette page décrit une des procédures possibles pour créer et diffuser sa propre extension (package) pour R. Par exemple pour regrouper, documenter et distribuer ses propres fonctions.

La documentation officielle sur ce sujet est là :

On ne traite ici que du cas de package simples ne nécessitant d'appels à des langages externes du type C ou Fortran. Toutes les opérations sont effectuées sous Linux.

Création des fichiers nécessaires

On suppose ici que l'on dispose de deux fonctions pourcentages.lignes et pourcentages.colonnes que l'on veut regrouper dans un package nommé mypack. On choisit de créer les répertoires et fichiers à l'emplacement /home/babar/r/packages/mypack.

Pour cela il suffit de lancer R et d'utiliser la fonction package.skeleton de la manière suivante :

package.skeleton(name="mypack",list=c("pourcentages.lignes","pourcentages.colonnes"),path="/home/babar/r/packages/")

La fonction crée la hiérarchie de répertoires et les fichiers nécessaires à la création du package.

Édition de la description du package

Si on se positionne dans le répertoire indiqué précédemment, on peut y trouver un fichier Read-and-delete-me qui contient quelques instructions de base, et surtout un fichier DESCRIPTION qu'il faut éditer et mettre à jour. Pour le choix de la licence le plus simple est de sélectionner l'une des licences se trouvant dans le répertoire share/licenses de votre installation de R : GPL-2, GPL-3, LGPL-3, Artistic-2.0, etc.

Pour le numéro de version, on peut utiliser des format du type 1.0, 0.1, ou 0.1-1.

Édition de la documentation des fonctions

La fonction package.skeleton a créé un répertoire R comprenant un fichier de code par fonction, et un répertoire man comprenant un fichier de documentation Rd par fonction.

On peut maintenant éditer les fichier Rd correspondants en utilisant le modèle généré automatiquement. Voir le manuel Writing R extensions pour plus d'informations.

Le fichier mypack-package.Rd est un fichier de documentation général sur le package. Il est recommandé de le maintenir plutôt court et synthétique, et d'utiliser des vignettes pour une documentation générale plus détaillée.

On peut regrouper la documentation de plusieurs fonctions dans un seul fichier en utilisant la commande \alias{}.

Si on utilise des caractères non-ASCII, il faut spécifier l'encodage à la fois avec le champ Encoding du fichier DESCRIPTION et avec la directive \encoding{} dans les fichiers .Rd.

Construction du paquet source

Pour construire le paquet source, on utilise la commande build :

R CMD build /home/babar/r/packages/mypack

On obtient ainsi un fichier tar.gz dans /home/babar/r/packages/ nommé mypack_num-version.tar.gz. On peut alors vérifier d'éventuels problèmes à l'aide de la commande check :

R CMD check /home/babar/r/packages/mypack

Installation locale

Une fois créé, la version source du package peut être directement installée en local avec :

R CMD INSTALL mypack_version.tar.gz

On peut ensuite le charger avec library et vérifier que tout fonctionne correctement.

Publication et diffusion

Plusieurs méthodes sont possibles pour la diffusion d'une extension. La solution la plus simple est de diffuser directement le fichier source pour une installation manuelle via R CMD INSTALL. Mais si on veut faciliter la diffusion et automatiser la mise à jour le mieux est soit de publier son paquet directement sur le CRAN, soit de créer un dépôt pour sa ou ses extensions.

Création de l'arborescence

On va créer une image locale de notre dépôt dans le répertoire /home/babar/r/depot. Pour cela la première chose à faire est de créer des sous-répertoires src/contrib dans lequel nous allons placer nos paquets sources.

Il faut donc copier notre fichier mypack_(version).tar.gz à cet endroit.

Construire un paquet binaire pour Windows

Si on n'a que des fichiers R dans son paquet, on peut en construire une version équivalente à un paquet binaire pour Windows simplement en zipant le contenu du répertoire d'installation locale correspondant :

https://stat.ethz.ch/pipermail/r-devel/2005-November/035684.html

Par exemple, si votre paquet est installé dans /usr/local/lib/R/site-library/, il suffit de zipper récursivement le sous-répertoire mypack qui s'y trouve :

cd /usr/local/lib/R/site-library/
zip -r9X /home/babar/r/packages/mypack.zip mypack
cd -

Attention, pour que le paquet puisse être installé via un dépôt, il faut renommer mypack.zip en mypack_version.zip avec le numéro de version correspondant, et le placer dans le répertoire de votre dépôt bin/windows/contrib/2.6 (si vous êtes sous R 2.6).

Création du fichier PACKAGES

Pour que le dépôt soit fonctionnel il faut créer un fichier PACKAGES (ou PACKAGES.gz) dans src/contrib. Ce fichier n'est en gros que la concaténation de certains champs des fichiers DESCRIPTION des paquets su dépôts.

Pour générer ces fichiers on fait appel à la fonction write_PACKAGES de la bibliothèque tools, de la manière suivante :

library(tools)
write_PACKAGES('/home/babar/r/depot/src/contrib',type='source',verbose=TRUE)

Pour créer le fichier PACKAGES pour des paquets binaires Windows, on peut utiliser :

library(tools)
write_PACKAGES('/home/babar/r/depot/bin/windows/contrib/2.6',type='win.binary',verbose=TRUE)

On peut automatiser cette étape en ligne de commande en invoquant R de la manière suivante :

R --vanilla -q -e "library(tools);
write_PACKAGES('/home/babar/r/depot/src/contrib',type='source',verbose=TRUE);
write_PACKAGES('/home/babar/r/depot/bin/windows/contrib/2.6',type='win.binary',verbose=TRUE)"

Générer la documentation au format PDF

Pour cela on utilise la commande Rd2dvi. Voir également RdConv ou Rd2txt. Par exemple :

R CMD Rd2dvi --pdf --title='mypack' --batch -o /home/babar/r/packages/mypack.pdf /home/babar/r/packages/mypack/man/*.Rd

Mettre en ligne

Il ne reste plus qu'à pousser tout ça sur un serveur qui va bien, via FTP ou rsync.

Installation distante

Supposons que l'URL du dépôt soit http://example.com/depot. Pour que les utilisateurs distants puissent installer et utiliser le package, il leur suffit d'utiliser la commande suivante :

install.packages("mypack", repos="http://example.com/depot")

Ensuite, le paquet sera automatiquement mis à jour avec un simple :

update.packages()

Si on veut faire une mise à jour ciblée de notre paquet, le plus simple est de relancer la commande install.packages ci-dessus.

Tags:

Comments are closed.