![\"plot](\"..\/..\/lise.vaudor\/Rfigures\/RMarkdown\/headband.png\")
<\/p>\n<\/p>\n
Ce document est un document de travail<\/strong> listant toutes les \u00e9tapes n\u00e9cessaires pour cr\u00e9er un package R. Je l’ai construit pour pouvoir m’y r\u00e9f\u00e9rer moi-m\u00eame la prochaine fois que je souhaiterai cr\u00e9er un package. Il s’adresse donc \u00e0 un public certes exigeant (mon moi du futur!) mais avec des besoins bien sp\u00e9cifiques. Il ne se veut donc pas exhaustif, et les termes que j’y emploie peuvent \u00eatre, si ce n’est approximatifs, du moins imag\u00e9s. Cependant je le mets \u00e0 disposition de quiconque le souhaite car il a le m\u00e9rite de balayer l’ensemble d’un processus qui peut \u00eatre a priori assez intimidant!<\/p>\n pour soi-m\u00eame<\/strong>, parce que si l’on en fait pas des packages on a tendance \u00e0 perdre les b\u00e9n\u00e9fices des fonctions que l’on s’\u00e9crit pour soi-m\u00eame: on oublie qu’on les a faites\/on oublie o\u00f9 on les a mises\/ on oublie comment on s’en sert etc.<\/p>\n<\/li>\n pour les autres<\/strong>, parce que partager un package et la documentation associ\u00e9e, c’est plus facile que de partager des scripts \u00e9pars, surtout si l’on s’adresse \u00e0 des utilisateurs de R qui ne sont pas eux-m\u00eames d\u00e9veloppeurs.<\/p>\n<\/li>\n<\/ul>\n Voici deux liens o\u00f9 je suis all\u00e9e chercher des renseignements pour apprendre \u00e0 cr\u00e9er un package:<\/p>\n Pour d\u00e9buter: Writing an R package from scratch, Hilary Parker<\/a><\/p>\n<\/li>\n Plus long et d\u00e9taill\u00e9: R package primer, Karl Broman<\/a><\/p>\n<\/li>\n<\/ul>\n Par exemple on peut cr\u00e9er un dossier Pour l’instant le dossier est vide. Pour cr\u00e9er l’architecture d’un package R (sous sa forme \u00ab\u00a0source\u00a0\u00bb)<\/p>\n On aura besoin du package devtools<\/strong> (cr\u00e9ation et installation du package) et roxygen2<\/strong> (cr\u00e9ation de la documentation):<\/p>\n La commande suivante cr\u00e9e<\/p>\n un fichier DESCRIPTION,<\/p>\n<\/li>\n un fichier NAMESPACE,<\/p>\n<\/li>\n un dossier R (qui contiendra les scripts contenant eux-m\u00eame les fonctions)<\/p>\n<\/li>\n les fichiers .gitignore, .Rbuildignore, et un projet Rstudio<\/p>\n<\/li>\n<\/ul>\n <\/p>\n Le fichier DESCRIPTION<\/strong> doit \u00eatre modifi\u00e9. Il faut notamment pr\u00e9ciser:<\/p>\n le titre et la description<\/strong> du package (ce qu’il fait)<\/p>\n<\/li>\n l’auteur<\/strong> et les informations de contact<\/p>\n<\/li>\n les d\u00e9pendances<\/strong>: (\u00ab\u00a0Depends: \u00ab\u00a0) c’est ici qu’il faut pr\u00e9ciser quels autres packages doivent \u00eatre charg\u00e9s<\/p>\n<\/li>\n<\/ul>\n On peut si besoin cr\u00e9er ce dossier et y placer les dossiers de scripts, d’images, ou tout autre fichier n\u00e9cessaire \u00e0 l’execution des fonctions du package.<\/p>\n Lors de l’installation du package (transformation du dossier source en dossier \u00ab\u00a0librairie\u00a0\u00bb) les dossiers plac\u00e9s dans \u00ab\u00a0inst\u00a0\u00bb se retrouveront \u00e0 la racine du dossier \u00ab\u00a0librairie\u00a0\u00bb.<\/p>\n Pour ma part j’ai cr\u00e9\u00e9 une fonction findmypath<\/strong> qui permet de retrouver (une fois le package install\u00e9) facilement le chemin de tout fichier \u00ab\u00a0file\u00a0\u00bb plac\u00e9 initialement dans Si j’utilise les fonctions du package sans l’avoir install\u00e9 et charg\u00e9 au pr\u00e9alable<\/em> je dois alors utiliser une autre fonction findmypath.<\/p>\n Il faut ensuite d\u00e9poser l’ensemble des scripts contenant les fonctions du package<\/strong> sous le dossier R<\/strong>.<\/p>\n On peut organiser les fonctions soit en les regroupant dans un script soit en faisant une fonction = un script.<\/p>\n Pour l’exemple on peut imaginer une fonction \u00ab\u00a0mafonction\u00a0\u00bb sauvegard\u00e9e dans un script Il y a plusieurs mani\u00e8res de proc\u00e9der pour g\u00e9n\u00e9rer la documentation. Pour ma part je pr\u00e9f\u00e8re documenter les fonctions sous forme d’ent\u00eates puis g\u00e9n\u00e9rer la documentation<\/strong> \u00e0 l’aide des packages devtools+roxygen2.<\/p>\n Reprenons l’exemple de la fonction \u00ab\u00a0mafonction\u00a0\u00bb. Voici le genre d’ent\u00eate qui permet de g\u00e9n\u00e9rer la documentation associ\u00e9e \u00e0 cette fonction:<\/p>\n La commande suivante g\u00e9n\u00e8re les fichiers d’aide \u00e0 partir des ent\u00eates<\/strong>:<\/p>\n On peut r\u00e9executer cette fonction (puis r\u00e9installer le package) pour mettre \u00e0 jour la documentation si l’on modifie les ent\u00eates par la suite.<\/p>\n Une vignette<\/strong> correspond \u00e0 la documentation \u00ab\u00a0informelle\u00a0\u00bb<\/strong> d’un package (contrairement aux fichiers d’aide li\u00e9s aux fonctions qui sont tr\u00e8s \u00ab\u00a0contraints\u00a0\u00bb d’un point de vue formel). On peut g\u00e9n\u00e9rer la vignette de la mani\u00e8re suivante:<\/p>\n On peut alors aller modifier le fichier Voici comment installer le package depuis le d\u00e9p\u00f4t local vers une librairie.<\/p>\n Cette installation devrait cr\u00e9er un dossier L’architecture et les fichiers contenus dans ce dossier sont diff\u00e9rents<\/em> de ceux du d\u00e9p\u00f4t local (ayant pour chemin, chez moi, On peut d\u00e8s lors charger le package et utiliser ses fonctions:<\/p>\n On a document\u00e9 mafonction, on peut donc afficher l’aide associ\u00e9e:<\/p>\n pour partager<\/strong> ses scripts en ligne<\/p>\n<\/li>\n pour g\u00e9rer les versions<\/strong> du package (le syst\u00e8me Git permet de garder trace de l’historique du package: quand et pourquoi tel ou tel script a \u00e9t\u00e9 modifi\u00e9, et de quelle mani\u00e8re).<\/p>\n<\/li>\n<\/ul>\n Cr\u00e9ation d’un compte sur GitHub<\/strong> (le mien est visible ici: https:\/\/github.com\/lvaudor<\/a>)<\/p>\n<\/li>\n Installation de Git<\/strong>: https:\/\/git-scm.com\/downloads<\/a><\/p>\n<\/li>\n<\/ul>\n On cr\u00e9e un repo<\/strong> (ou repository) sur GitHub qui sera un clone du d\u00e9p\u00f4t local.<\/p>\n Il est utile d’associer un fichier On peut alors envoyer les scripts depuis le d\u00e9p\u00f4t local vers le repo (d\u00e9p\u00f4t distant).<\/p>\n On peut le faire soit depuis l’application GitHub Desktop<\/strong>, soit par ligne de commande avec Git Shell<\/strong>. J’utilise pour ma part Git Shell car je trouve que c’est la m\u00e9thode la mieux document\u00e9e en ligne (et je d\u00e9bute en Git!).<\/p>\n Je me place dans le dossier qui m’int\u00e9resse (dossier local):<\/p>\n Je cr\u00e9e le squelette git<\/strong> (un nouveau sous-dossier .git appara\u00eet dans le dossier):<\/p>\n J’ajoute l’ensemble des fichiers dans le r\u00e9pertoire local \u00e0 la liste des fichiers \u00ab\u00a0\u00e0 suivre\u00a0\u00bb par Git:<\/p>\n Je consigne les changements<\/strong> en effectuant un \u00ab\u00a0commit\u00a0\u00bb:<\/p>\n Il est n\u00e9cessaire d’associer un court message (ici \u00ab\u00a0Premier commit\u00a0\u00bb) \u00e0 chaque fois pour que la commande soit effective.<\/p>\n Je vais ensuite lier mon d\u00e9p\u00f4t local \u00e0 mon d\u00e9p\u00f4t distant<\/strong> (\u00ab\u00a0origin\u00a0\u00bb correspond \u00e0 un nom court auquel il me sera facile de faire r\u00e9f\u00e9rence par la suite):<\/p>\n Je peux alors pousser<\/strong> mes fichiers depuis le d\u00e9p\u00f4t local vers le d\u00e9p\u00f4t distant (ici vers la branche master<\/em>):<\/p>\n Remarque:<\/strong><\/p>\n Par la suite je pourrai utiliser davantage de fonctionnalit\u00e9s de Git, comme la possibilit\u00e9 de cr\u00e9er des branches.<\/p>\n Si je veux mettre \u00e0 jour le d\u00e9p\u00f4t distant par la suite je n’aurai pas besoin de r\u00e9effectuer toutes les t\u00e2ches list\u00e9es ci-dessus. Les lignes de commandes suivantes sont suffisantes:<\/p>\n D\u00e8s lors que les fichiers relatifs \u00e0 mon package ont \u00e9t\u00e9 \u00ab\u00a0pouss\u00e9s\u00a0\u00bb de ma machine vers mon repo GitHub, n’importe qui peut installer le package depuis ce repo (cependant cela n\u00e9cessite d’utiliser une fonction du package devtools):<\/p>\n Attention lorsque l’on travaille sur une version qui n’est pas la toute derni\u00e8re on peut avoir des difficult\u00e9s \u00e0 installer le package En l’\u00e9tat actuel des choses mes packages peuvent \u00eatre install\u00e9s depuis GitHub (gr\u00e2ce \u00e0 la fonction Le d\u00e9p\u00f4t d’un package sur CRAN a pour int\u00e9r\u00eat de permettre l’installation des packages par cette commande, et de garantir que le package est test\u00e9 sur divers syst\u00e8mes d’exploitation.<\/p>\n Le d\u00e9p\u00f4t sur CRAN est quelque chose que je n’ai pour le moment pas encore test\u00e9… Document \u00e0 compl\u00e9ter donc…<\/p>\n","protected":false},"excerpt":{"rendered":" Ce document est un document de travail listant toutes les \u00e9tapes n\u00e9cessaires pour cr\u00e9er un package R. Je l’ai construit pour pouvoir m’y r\u00e9f\u00e9rer moi-m\u00eame la prochaine fois que je souhaiterai cr\u00e9er un package. Il s’adresse donc \u00e0 un public certes exigeant (mon moi du futur!) mais avec des besoins bien sp\u00e9cifiques. Il ne se veut donc pas exhaustif, et les termes que j’y emploie peuvent \u00eatre, si ce n’est.. Read More<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5],"tags":[],"class_list":["post-511","post","type-post","status-publish","format-standard","hentry","category-tous-les-posts"],"_links":{"self":[{"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/posts\/511","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/comments?post=511"}],"version-history":[{"count":7,"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/posts\/511\/revisions"}],"predecessor-version":[{"id":514,"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/posts\/511\/revisions\/514"}],"wp:attachment":[{"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/media?parent=511"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/categories?post=511"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/perso.ens-lyon.fr\/lise.vaudor\/wp-json\/wp\/v2\/tags?post=511"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Cr\u00e9er un package R, pour quoi faire?<\/h2>\n
\n
\n
Cr\u00e9ation et organisation d’un d\u00e9p\u00f4t local pour le package<\/h2>\n
Cr\u00e9ation du d\u00e9p\u00f4t local et de son squelette<\/h3>\n
monpackage<\/code> sous l’emplacement par d\u00e9faut pour d\u00e9p\u00f4t sur GitHub:<\/p>\nC:\\Users\\lvaudor\\Documents\\GitHub\\monpackage<\/code><\/p>\nif(!require(devtools)){install.packages(\"devtools\")}\nif(!require(roxygen2)){devtools::install_github(\"klutometis\/roxygen\")}\n<\/code><\/pre>\n\n
devtools::create(\"monpackage\")\n<\/code><\/pre>\nModification du fichier DESCRIPTION<\/h3>\n
\n
Ajout du dossier
inst<\/code><\/h3>\ninst\/dir\/<\/code>:<\/p>\nfindmypath=function(dir,file){\n path=system.file(dir,file,package=\"monpackage\")\n return(path)\n}\n<\/code><\/pre>\nOrganisation des scripts<\/h3>\n
mafonction.R<\/code>:<\/p>\nmafonction <- function(nom=\"toi\"){\n print(paste0(\"Salut, \", nom, \"!\"))\n}\n<\/code><\/pre>\nDocumentation<\/h2>\n
Fichiers d’aide associ\u00e9s aux fonctions<\/h3>\n
#' Une fonction pour l'exemple\n#'\n#' Cette fonction ne sert a rien d'autre qu'a servir d'exemple.\n#' @param nom (par defaut, \"toi\")\n#' @keywords salutation\n#' @export\n#' @examples\n#' mafonction(\"mec\")\nmafonction <- function(nom=\"toi\"){\n print(paste0(\"Salut, \", nom, \"!\"))\n}\n<\/code><\/pre>\ndevtools::document(\"monpackage\")\n<\/code><\/pre>\nCr\u00e9ation d’une vignette<\/h3>\n
devtools::use_vignette(\"monpackage_vignette\",pkg=\"monpackage\")\n<\/code><\/pre>\nvignettes\/monpackage_vignette.Rmd<\/code> et y inclure les explications, la biblio, et les exemples d’application du package.<\/p>\nInstallation et utilisation du package en local:<\/h2>\n
devtools::install(\"monpackage\")\n<\/code><\/pre>\nmonpackage<\/code> dans vos librairies R. Chez moi, elle correspond \u00e0 la cr\u00e9ation d’un dossier au chemin suivant: C:\\Users\\lvaudor\\Documents\\R\\win-library\\3.2\\monpackage<\/code><\/p>\nC:\\Users\\lvaudor\\Documents\\GitHub\\monpackage<\/code>)<\/p>\nrequire(monpackage)\nmafonction()\n<\/code><\/pre>\nhelp(mafonction)\n<\/code><\/pre>\nDep\u00f4t du package sur GitHub<\/h2>\n
Pour quoi faire?<\/h3>\n
\n
Pr\u00e9alable<\/h3>\n
\n
Cr\u00e9ation d’un d\u00e9p\u00f4t distant (\u00ab\u00a0repo\u00a0\u00bb) sur GitHub<\/h3>\n
README.Rd<\/code><\/strong> \u00e0 ce repo de mani\u00e8re \u00e0 renseigner l’utilisateur sur son contenu. Personnellement j’y indique en quelques lignes la fonction du package et de quelle mani\u00e8re l’utilisateur peut l’installer sur sa machine.<\/p>\nCommandes Git<\/h3>\n
cd monpackage\n<\/code><\/pre>\ngit init\n<\/code><\/pre>\ngit add .\n<\/code><\/pre>\ngit commit -m \"Premier commit\"\n<\/code><\/pre>\ngit remote add origin https:\/\/github.com\/lvaudor\/monpackage\n<\/code><\/pre>\ngit push -u origin master\n<\/code><\/pre>\nModifications ult\u00e9rieures<\/h3>\n
cd monpackage\ngit add .\ngit commit -m \"nouveau commit\"\ngit push -u origin master\n<\/code><\/pre>\nInstallation du package depuis GitHub (dev version)<\/h3>\n
if(!require(devtools)){install.packages(\"devtools\")}\ndevtools::install_github(\"lvaudor\/graphiT\")\n<\/code><\/pre>\ndevtools<\/code>.<\/p>\nD\u00e9p\u00f4t du package sous CRAN<\/h2>\n
install_github<\/code> du package devtools) et non par la commande habituelle install_packages<\/code> (la plus simple pour installer un package).<\/p>\n