Afficher les vignettes

Auteur.e.s
Fabrice Dessaint, Inra
Résumé

Une des grandes qualités de R, c’est sa documentation. Très bien faite, elle permet de retrouver pour chacune des fonctions présentes dans un package, une description de son utilisation ainsi que des exemples. Néanmoins, avoir la description des différentes fonctions, ne donne pas toujours d’idées sur leur utilisation dans un flux d’analyse. C’est précisément ce que font les vignettes.

Les vignettes

Les vignettes sont des documents, présents dans certains packages R, que l’on trouve sous la forme de fichiers au format .pdf ou .html. Elles ont pour principal objectif d’aider l’utilisateur à comprendre l’utilisation du package et proposent généralement le traitement d’un ou de plusieurs exemples sous la forme d’un tutoriel. Ces documents peuvent avoir été spécialement écrits pour l’occasion ou être des reprises de documents déjà publiés.

Trois fonctions R sont disponibles pour afficher et visualiser les documents.

La fonction vignette()

Elle retourne une liste des vignettes disponibles. Cette liste peut être globale et concernée l’ensemble des packages installés ou chargés (argument all=FALSE).

liste <- vignette()
liste <- liste$result
# quelques vignettes
liste[c(9, 19, 23, 109), c("Package", "Item", "Title")]
##      Package     Item              Title                                     
## [1,] "betareg"   "betareg"         "Beta Regression in R (source, pdf)"      
## [2,] "cocorresp" "cocorresp-intro" "Introduction to cocorresp (source, html)"
## [3,] "cowplot"   "plot_grid"       "Arranging plots in a grid (source, html)"
## [4,] "grid"      "grid"            "Introduction to grid (source, pdf)"

ou spécifique à un package particulier (ici le package grid).

liste <- vignette(package = "grid")
liste <- liste$result
liste[1:8, c("Item", "Title")]
##      Item          Title                                                  
## [1,] "moveline"    "Demonstrating move-to and line-to (source, pdf)"      
## [2,] "displaylist" "Display Lists in grid (source, pdf)"                  
## [3,] "interactive" "Editing grid Graphics (source, pdf)"                  
## [4,] "frame"       "Frames and packing grobs (source, pdf)"               
## [5,] "grid"        "Introduction to grid (source, pdf)"                   
## [6,] "locndimn"    "Locations versus Dimensions (source, pdf)"            
## [7,] "sharing"     "Modifying multiple grobs simultaneously (source, pdf)"
## [8,] "nonfinite"   "Non-finite values (source, pdf)"

La fonction print.vignette()

Elle affiche le document .pdf ou .html. Pour certains packages, il existe plusieurs vignettes. On accède à une vignette particulière en précisant son nom dans la fonction.

exemple <- vignette("grid", package = "grid")
print(exemple)

exemple <- vignette("broom_and_dplyr", "broom")
print(exemple)

Le programme utilisé pour afficher les vignettes (.pdf) est celui indiqué dans getOption("pdfviewer").

La fonction edit.vignette()

Elle extrait de la vignette le code R, le place dans un fichier temporaire qui est ensuite ouvert avec un éditeur. On peut alors exécuter les différentes instructions et/ou sauvegarder le fichier. Pour l’édition, c’est l’éditeur indiqué dans getOption("editor") qui est utilisé.

edit(exemple)

Pour aller plus loin

Friedrich Leisch (2003). Sweave, Part II: Package Vignettes. R News 3(2)

Versions des outils utilisés
R version 3.4.2 (2017-09-28)
Thèmes de la fiche
Thèmes