Chapitre 8 Création de package avec Rstudio

8.1 Introduction

L’objectif de ce petit tutoriel est

  1. de créer un projeet package sous Rstudio (avec le package devtools (Wickham and Chang 2017)),
  2. de se familiariser avec les outils de documentation,
  3. d’intégrer un code C++,
  4. de déposer un package sur github.

8.2 Création d’un package rudimentaire

Supposons qu’on dispose de la fonction

OLS <- function(X,y) {
  beta.hat <- chol2inv(chol(crossprod(X))) %*% crossprod(X,y)
  beta.hat
}

8.2.1 Exercice 1

Créer un projet package via Rstudio:

File -> New Project -> New Directory -> New Package with git repository

Vous pouvez également utiliser directement la commande

devtools::create("OLSfit")

8.2.2 Exercice 2

Effacer le fichier hello.R. Créer un fichier OLS.R contenant votre fonction.

8.2.3 Exercice 3

Éditer le fichier DESCRIPTION de manière adéquate: modifier le titre, le nom de l’auteur, du mainteneur, la description. Pour le nom de l’auteur, utiliser

person("First", "Last", email = "first.last@example.com", role = c("aut", "cre"))

8.2.4 Exercice 4

Documentez la fonction OLS à l’aide de Roxygen2 (Wickham, Danenberg, and Eugster 2017) : pour ce faire, complétez le code suivant et collez-le dans l’entête de votre fichier OLS.R. La balise @export indique que cette fonction doit être rendue public à l’utilisateur. Lors de la compilation de la documentation, le fichier NAMESPACE sera amendé en ce sens.

Question

#' Description of the function
#' 
#' @param  a paramter
#' @return what is returned
#' @examples
#' @export 
OLS <- function(X,y) {
  beta.hat <- chol2inv(chol(crossprod(X))) %*% crossprod(X,y)
  beta.hat
}

Solution

#' Compute the OLS esstimator
#' 
#' @param X A matrix
#' @param y A vector
#' @return a vector of coefficients
#' @examples
#' n <- 100; p <- 10
#' X <- matrix(rnorm(n*p), n, p)
#' beta <- runif(p, 1, 2) * sample(c(-1,1), p, rep=TRUE)
#' y <- X %*% beta + rnorm(n) 
#' OLS(X,y)
#' @export
OLS <- function(X,y) {
  beta.hat <- chol2inv(chol(crossprod(X))) %*% crossprod(X,y)
  beta.hat
}

Effacez le fichier NAMESPACE et lancez la commande

devtools::document()

pour générer les fichiers d’aide et mettre à jour le NAMESPACE.

8.2.5 Exercice 5

  • Contruire le package et l’installer. Lorsqu’on dispose d’un projet Rstudio associé à un package, ceci peut être fait simplement à l’aide du raccourci Ctrl + Shift + B ou du bouton correspondant en haut à droite.

  • Vérifier que le package et le code fonctionnent via l’exemple de votre fonction.

  • Vérifier que votre package est publibale sur CRAN à l’aide du bouton Check ou du raccourci Ctrl + Shift + E.

8.3 Intégration de code C++

On souhaite accélérer le code en réalisant la partie coûteuse des calculs à l’aide d’un code C++.

8.3.1 Exercice 1

Spécifiez via Rstudio que vous allez dorénavant utiliser du code C++, à l’aide de la commande

devtools::use_rcpp()

Observez les modifications apportées à votre packages. Commentez.

8.3.2 Exercice 2

Créer un fichier OLS-pkg.R dans lequel vous intégrerez les lignes suivantes. Vous pouvez également compléter ce fichier pour écrire un texte de présentation générale de votre package qui apparaîtra en début de documentation.

#' package OLSfit
#' 
#' Dans ce package, on trouve les fonctions trucs bidule et muche. Elles font ceci et cela. Les classes d'objets Robert et MItchoum font etc.
#' 
#' @name OLS-pkg
#' @docType package
#'
#' @useDynLib OLSfit
#' @importFrom Rcpp sourceCpp
NULL

8.3.3 Exercice 3

Créez un fichier OLS.cpp dans le répertoire src. À l’aide d’armadillo, compléter le fichier suivant:

Question

#include "RcppArmadillo.h"
// [[Rcpp::depends(RcppArmadillo)]]
NumericVector OLScpp(const arma::mat X, const arma::vec y) {

}

Solution

#include "RcppArmadillo.h"
// [[Rcpp::depends(RcppArmadillo)]]
NumericVector OLScpp(const arma::mat X, const arma::vec y) {
  return wrap( inv_sympd(X.t() * X) * X.t() * y ) ;
}

Ajoutez RcppArmadillo au champ LinkingTo du fichier DESCRIPTION.

Enfin, faites un build and reload de votre package. Constatez les fichiers nouvellement créer. Commentez.

8.3.4 Exercice 4

Ouvrez le ficher RcppExport.R. À l’aide de son contenu, créer une nouvelle fonction OLSfast dans un nouveau fichier. Regénérer les fichiers de doc à l’aide de Roxygen2. Comparer OLS à OLSfast avec microbenchmark.

8.3.5 Exercice 5

Publiez votre package sur github.

References

Wickham, Hadley, and Winston Chang. 2017. Devtools: Tools to Make Developing R Packages Easier. https://CRAN.R-project.org/package=devtools.

Wickham, Hadley, Peter Danenberg, and Manuel Eugster. 2017. Roxygen2: In-Line Documentation for R. https://CRAN.R-project.org/package=roxygen2.