R Language
Créer des paquets avec devtools

Introduction

Remarques

Créer et distribuer des paquets

Ceci est un guide compact sur la façon de créer rapidement un package R à partir de votre code. Les documentations exhaustives seront liées lorsqu'elles seront disponibles et devront être lues si vous souhaitez approfondir votre connaissance de la situation. Voir Remarques pour plus de ressources.

Le répertoire dans lequel se trouve votre code sera appelé ./ , et toutes les commandes sont destinées à être exécutées depuis une invite R dans ce dossier.

Création de la documentation

La documentation de votre code doit être dans un format très similaire à LaTeX.

Cependant, nous allons utiliser un outil nommé roxygen afin de simplifier le processus:

install.packages("devtools")
library("devtools")
install.packages("roxygen2")
library("roxygen2")

La page de manuel complète de roxygen est disponible ici . C'est très similaire au doxygen .

Voici un exemple pratique sur la façon de documenter une fonction avec roxygen :

#' Increment a variable.
#'
#' Note that the behavior of this function
#' is undefined if `x` is not of class `numeric`.
#'
#' @export
#' @author  another guy
#' @name    Increment Function
#' @title   increment
#'
#' @param x   Variable to increment
#' @return    `x` incremented of 1
#'
#' @seealso   `other_function`
#'
#' @examples
#' increment(3)
#' > 4
increment <- function(x) {
  return (x+1)
}

Et voici le résultat .

Il est également recommandé de créer une vignette (voir la rubrique Création de vignettes ), qui constitue un guide complet sur votre package.

Construction du squelette du colis

En supposant que votre code est écrit par exemple dans les fichiers ./script1.R et ./script2.R , lancez la commande suivante afin de créer l'arborescence de fichiers de votre package:

package.skeleton(name="MyPackage", code_files=c("script1.R","script2.R"))

Supprimez ensuite tous les fichiers dans ./MyPackage/man/ . Vous devez maintenant compiler la documentation:

roxygenize("MyPackage")

Vous devez également générer un manuel de référence à partir de votre documentation à l'aide de R CMD Rd2pdf MyPackage partir d'une invite de commande lancée dans ./ .

Edition des propriétés du paquet

1. Description du colis

Modifiez ./MyPackage/DESCRIPTION selon vos besoins. Les champs Package , Version , License , Description , Title , Author et Maintainer sont obligatoires, les autres sont facultatifs.

Si votre package dépend d'autres packages, spécifiez-les dans un champ nommé Depends (version R <3.2.0) ou Imports (version R> 3.2.0).

2. Dossiers facultatifs

Une fois que vous avez lancé la construction du squelette, ./MyPackage/ ne ./MyPackage/ que des sous man/ dossiers R/ et man/ . Cependant, il peut en avoir d'autres:

• data/ : ici vous pouvez placer les données dont votre bibliothèque a besoin et qui ne sont pas du code. Il doit être enregistré en tant que jeu de données avec l'extension .RData et vous pouvez le charger à l'exécution avec data() et load()
• tests/ : tous les fichiers de code de ce dossier seront exécutés au moment de l'installation. S'il y a une erreur, l'installation échouera.
• src/ : pour les fichiers source C / C ++ / Fortran dont vous avez besoin (en utilisant Rcpp ...).
• exec/ : pour les autres exécutables.
• misc/ : pour à peine tout le reste.

Finalisation et construction

Vous pouvez supprimer ./MyPackage/Read-and-delete-me .

À l’heure actuelle, votre paquet est prêt à être installé.

Vous pouvez l'installer avec devtools::install("MyPackage") .

Pour créer votre package en tant qu'archive source, vous devez exécuter la commande suivante à partir d'une invite de commande dans ./ : R CMD build MyPackage

Distribution de votre colis

À travers Github

Créez simplement un nouveau référentiel appelé MyPackage et téléchargez-le dans MyPackage/ vers la branche principale. Voici un exemple .

Ensuite, n'importe qui peut installer votre paquet depuis github avec devtools:

install_package("MyPackage", "your_github_usename")

Par CRAN

Votre package doit être conforme à la politique de référentiel CRAN . Y compris, mais sans s'y limiter: votre paquetage doit être multi-plateformes (sauf quelques cas très particuliers), il doit réussir le test de R CMD check .

Voici le formulaire de soumission . Vous devez télécharger l'archive source.

Création de vignettes

Une vignette est un guide détaillé de votre colis. La documentation de fonction est géniale si vous connaissez le nom de la fonction dont vous avez besoin, mais cela ne sert à rien autrement. Une vignette est comme un chapitre de livre ou un article académique: elle peut décrire le problème que votre paquet est conçu pour résoudre, puis montrer au lecteur comment le résoudre.

Les vignettes seront créées entièrement en démarques.

Exigences

• Rmarkdown: install.packages("rmarkdown")
• Pandoc

Création de vignette

devtools::use_vignette("MyVignette", "MyPackage")

Vous pouvez maintenant éditer votre vignette à ./vignettes/MyVignette.Rmd .

Le texte de votre vignette est formaté en Markdown .

Le seul ajout au Markdown d'origine est une balise qui prend le code R, l'exécute, capture la sortie et la traduit en Markdown formaté:

```{r}
# Add two numbers together
add <- function(a, b) a + b
add(10, 20)
```

S'affichera comme:

# Add two numbers together
add <- function(a, b) a + b
add(10, 20)
## [1] 30

Ainsi, tous les packages que vous utiliserez dans vos vignettes doivent être répertoriés en tant que dépendances dans ./DESCRIPTION .