TP2 : Mon premier package R

BUT 3 - Domaines d’application

NoteObjectif du TP

Nous allons apprendre à créer un package R.

NotePourquoi ?

Un package va vous permettre de réutiliser facilement des méthodes que vous avez développé.
Mais aussi de les partager et de capitaliser ces dernières.
Cela apportera un cadre et de la rigueur à vos codes.

Prérequis

• TP1
  
• Disposer d’un projet sous Rstudio versionné avec Git (avec un projet GitLab associé)

Rappel

Note

Un package R est un ensemble de fonctions développées par des utilisateurs de R, qui améliorent ou étendent les fonctionnalités de base de R.
Par exemple le package {ggplot2} permet de réaliser toutes sortes de graphiques qui ne sont pas disponibles de base dans R.

Astuce

Un package R c’est un répertoire/dossier normé qui contient à minima deux fichiers DESCRIPTION et NAMESAPCE ainsi que deux répertoires/dossiers R/ et man/ (c.f. le cours)

Important

Un membre du binôme doit faire le TP sur sa session. Au prochain TP vous changerez de membre.
Pensez à sauvegarder et à versionner votre travail aux étapes importantes.
Pensez bien à faire un pull avant de commencer à travailler.

L’issue du TP

• Créer une issue dans votre projet avec pour nom TP2.
• Y ajouter ceci :

# TP2 : Création du package <monpackage>

## Tâches :   

1. [ ] Créer un package sous Rstudio
2. [ ] Implementer le package  
3. [ ] Valider et construire le package  
etc.  

## Version

Le commit correspondant au rendu final du TP : <clé SHA>

• Dans l’issue principal du projet Rendu de notre projet associer cette dernière issue dans Linked Items
  • utiliser le numéro de l’issue ou son nom

Création d’un package

Astuce

Documentation officielle pour toutes interrogations.

Il est possible de créer un package R de plusieurs manières.

• Que ce soit via Rstudio en créant un nouveau projet de type package R plus d’info ici,
  
• En utilisant des packages R tel que : {devtools}(create()) ou {usethis}(create_package()),
  
• A la main ;-)

Ici nous allons le faire à la main pour des raisons pédagogique.

Mise en gardePensez à changer le nom de votre package dans les exemples.

Quand il est fait référence de <monpackage> il s’agit du nom de votre package. vous devez changer cette valeur régulièrement dans les TPs.
ex: <monpackage> -> Lenomdemonpackage
!!! Ne pas laisser les < et > !!!
D’autres variables avec la même nomenclature (<…>) sont à éditer.

Creation de l’arboressence

Note

Placez vous dans votre projet Rstudio créé au TP1.
Normalement vous disposez que d’un fichier README.md et <monpackage>.Rproj (et un dossier .git/ caché).

Astuce

Un fichier .Rbuildignore permet de spécifier les fichiers/dossiers qui ne sont pas à inclure dans le package source (Build).

.Rbuildignore

^.*\.Rproj$
^\.Rproj\.user$

NoteL’arborescence (pour information)

A la fin du TP, votre arborescence ressemblera à ceci.

- <monpackage>
  |- R
     |- ma_fonction.R
     |- ...
  |- DESCRIPTION
  |- NAMESPACE
  |- man
     |- ma_fonction.Rd
  |- README.md
  |- ...

Le fichier DESCRIPTION

Important

Le fichier DESCRIPTION donne les informations complètes du package (Métadonnées).
ex: ggplot2 DESCRIPTION

• Créer un fichier texte vierge appelé DESCRIPTION à la racine du projet (sans extension).

• Y insérer ceci en y complètent vos informations (attention à l’indentation et espaces en trop):

DESCRIPTION

Package: <monpackage>
Title: <Ce que le package fait (1 ligne)>
Version: 0.0.0.9000
Authors@R: 
    c(person(given="<Prenom>", family="<Nom>", email="<monemail@univ-avignon.fr>", role = c("aut", "cre")),
    person(given="<Prenom<", family="<Nom>", email="<monemail@univ-avignon.fr>", role = c("aut")))
Description: <Ce que le package fait (1 paragraphe).>
License: GPL-2 | GPL-3
Encoding: UTF-8
LazyData: true
Imports:
  methods

Mise en garde

Il ne peut avoir qu’un seul mainteneur déclaré dans le package.
Le rôle “cre” ne peut être utilisé qu’une seul fois.

AvertissementLa Licence

La Licence dépend de l’utilisation ou des obligations sur le code développé dans votre entreprise.
Il existe une multitude de licence permissives ou restrictives.
Ici nous utilisons la licence GPL-3 qui est très utilisé dans le monde du libre et pour le développement de package R.

AvertissementDépendances à d’autres packages R (à noter)

Des champs Imports et Suggests seront nécessaires dès que votre package aura des dépendances à d’autres packages R.
Exemple :

Imports:
    ggpot2 (>= 3.4.3)
Suggests:
    rmarkdown,
    rshiny

Note

Plus d’informations synthétique sur le fichier DESCRIPTION

Le fichier NAMESPACE

Important

Le fichier NAMESPACE donne les informations sur les fonctions accessibles à l’utilisateur de votre package ainsi que les méthodes/packages qu’il utilise pour son propre fonctionnement. ex: ggplot2 NAMESPACE

• Créer un fichier texte vierge appelé NAMESPACE à la racine du projet (sans extension).

Astuce

Ce fichier est généralement rempli automatiquement mais ici dans un premier temps nous allons le faire à la main.

Note

Plus d’informations synthétique sur le fichier NAMESPACE.

Ma première fonction/méthode

Important

Les méthodes implémentées qui pourront être appelé par la suite via votre package sont à placer dans le dossier R/ sous des fichiers .R.
Généralement les fichiers portent des noms explicites.
ex: ggplot2/R

• Créer le dossier R à la racine du projet.
  
• Créer un fichier .R dans le dossier R (le nom doit être explicite, par exemple : ma_fonction.R)
• dans ce fichier .R ajouter la méthode suivante:
  

ma_fonction.R

ma_fonction <- function(monNom = "les bleus") {
    cat("Ceci est ma premiere fonction de mon package : ", getPackageName())
    cat("\nBravo ",monNom," !!!")
}

• Editer le fichier NAMESPACE est y ajouter ceci:
  

NAMESPACE

export(ma_fonction)
importFrom("methods", "getPackageName")

• Créer un dossier man à la racine du projet.
  
• Créer le fichier man/ma_fonction.Rd et personnalisé le contenu.

ma_fonction.Rd

\name{ma_fonction}
\alias{ma_fonction}
\title{ma_fonction}
\arguments{
  \item{monNom}{un string}
}
\usage{
ma_fonction(monNom="les bleus")
}
\description{
affiche ce message :
Ceci est ma premiere fonction de mon package : <monpackage>
Bravo les bleus !!!
}
\examples{
ma_fonction()
}

NoteNom des fichers et des fonctions

Ici dans l’exemple, pour une question de simplicité, nous avons utilisé le même nom pour le fichier et la fonction mais notez bien qu’ils peuvent être différents.

NoteLes fichiers dans man

Les fichiers .Rd qui se trouvent dans man/ sont les fichiers d’aides. Ils sont compilés par la suite pour avoir un rendu lisible et accessible.
Exemple du rendu pour la méthode getwd() :

?getwd

Check et build

Maintenant que notre package est créé, qu’une fonction est implémentée ainsi que sa documentation nous pouvons générer et installer ce dernier.

AstuceJe n’utilise pas Rstudio

Dans le cas où vous n’utilisez pas Rstudio comme IDE.
Vous pouvez effectuer les actions suivante via la console R ou Terminal (bash).

Depuis la console R

install.packages("devtools")
# Installer le package
devtools::install("repertoire_du_package")
# Check du package
devtools::check("repertoire_du_package")
# Build (construction) du package
devtools::build("repertoire_du_package")

Depuis un Terminal (shell)

# Installer le package
R CMD INSTALL <repertoire_du_package>
# Check du package
R CMD check --as-cran <repertoire_du_package>
# Build (construction) du package
R CMD build <repertoire_du_package>

• Dans le menu “Build” de Rstudio -> “Check Package” puis “Install Package”

Mise en gardeRien dans le menu Build ?

Si le menu n’apparaît pas, déconnectez vous de Rstudio et reconnectez vous.
Vous pouvez aussi, selectionner dans le menu Build -> Configure Build Tools l’option type de projet “package”.

Mise en gardeDes warnings, erreurs ou notes lors du Check.

Si vous avez des erreurs lors du check de votre package, il faut bien lire ce que dit la console. Généralement c’est très explicite et l’erreur peut être corrigé facilement.

• Une fois l’installation terminé, exécuter les commandes suivantes dans votre console R:

ma_fonction("test")
?ma_fonction

• Votre premier fonction fonctionne ? l’aide aussi ?

Note

Tester les autres méthodes du Menu “Build”.

Important

La commande “Check Package” doit retourner 0 warning, error et notes.

AvertissementLe package source

Générer le source du package (depuis le menu Build -> “Source package”) et ouvrir ce dernier.
Que constatez-vous ?

Astuce

Le package source est la version brut de votre package, qui peut être partagé et soumisse au CRAN.

AvertissementPartager son package (pour information)

Pour partager son package vous pouvez :

• fournir le source
• fournir le binaire (! les binaires Windows, MacOs et Linux ne sont pas compatible !)
• fournir l’URL de votre dépôt GitLab

Pour installer depuis un dépôt git, utiliser le package {remotes}.
Par exemple pour installer votre package dans R

remotes::install_gitlab("http://docker.univ-avignon.fr/<URL_DE_VOTRE_PROJET>.git")

• déposer le package sur le CRAN <- Le dépot officiel des packages R

• Compléter le fichier README.md de votre package vous inspirant de celui de {ggplot2} (pas de copie, juste les champs pertinents à votre package, description, comment installer…)

---

Maintenant vous disposez d’un package R de base normé et valide. Que vous pouvez réutiliser et partager.

---

Avant d’aller plus loin

• Vérifier que vous avez suivie les consignes.
• Vérifier que la documentation du package est à jour.
• Vérifier que votre package est toujours normé et valide (Check, Source, Install)
• Vérifier que le dépôt GitLab de votre package est à jour.
  • Versionnement avec Git :
    • faire un commit avec pour message “notre premier Package R <monpackage>”
      
    • et un push
      
  • Aller sur la page gitlab du projet
    • Vérifier le contenu du projet
      
    • Compléter les issues du projet

Questions:

• Dans l’issue de ce TP (“TP2”).
• Ajouter le message et la version du commit correspondant à ce TP
  (menu de gauche -> Code -> Commits) le commit correspond à la clé SHA.
  
• Ajouter le Tags TP2 au commit
  
• Répondez aux questions suivantes dans la description de l’issue :
  • Comment est formé un package R ? Serez vous en capacité de refaire un nouveau package ?
  • Quel est la différence entre les champs Imports et Suggests du fichier DESCRIPTION ?
  • Quel sont les déclarations les plus importantes dans le fichier NAMESPACE ?
  • Quel est la différence entre ces actions check, test, build et install qui peuvent être faite sur un package R ?
  • Serez-vous en capacité de récuperer un projet Git sous rstudio et de mettre à jour le serveur distant ?
  • Définir simplement ce qu’est le CRAN ?

---

Pour aller plus loin

• TP3
  
• Explorer les packages {devtools} et {usethis}
  
• Explorer les principaux concepts d’un package R https://r-pkgs.org/