Research compendium

Objectif

L’objectif de cet exercice est de créer un research compendium, c.-à-d. un dossier de travail dont la structure est dérivée de celle d’un package . Vous allez découvrir les fichiers importants que nous vous recommandons d’ajouter à un projet de recherche. Vous allez aussi apprendre à écrire et documenter des fonctions .

Ce research compendium servira de base de travail tout au long de la formation.

NB. Cet exercice s’inspire du workshop proposé par Anna Krystalli.


Préambule

Afin de nous assister dans la création de la structure de notre dossier de travail, nous allons utiliser le package rcompendium, développé dans le cadre de cette formation. Il permet d’automatiser la création des fichiers/répertoires spécifiques à un compendium/package .

Installez le package rcompendium depuis GitHub :

## Installation de 'remotes' ----
install.packages("remotes")

## Installation de 'rcompendium' ----
remotes::install_github("frbcesab/rcompendium")

## Chargement du package -----
library("rcompendium")

  Si vous rencontrez des difficultés à installer le package, lisez attentivement la section Installation du README.

Une fois le package installé, vous devez exécuter la fonction set_credentials() afin de stocker localement vos informations personnelles (prénom, nom, email, ORCID, protocole de communication avec GitHub). Ces informations permettront de remplir automatiquement certains fichiers du compendium. Cette fonction n’est à utiliser qu’une seule fois.

## Stockage de vos informations ----
set_credentials(given    = "Jane",
                family   = "Doe", 
                email    = "jane.doe@mail.me", 
                orcid    = "0000-0000-0000-0000", 
                protocol = "ssh")

Ces informations ont été copiées dans le presse-papier. Collez son contenu dans le fichier ~/.Rprofile (ouvert dans RStudio par cette fonction). Ce fichier est lu à chaque ouverture de et son contenu sera accessible aux fonctions du package rcompendium.

Redémarrez la session (Session > Restart R) et vérifiez que vos informations personnelles sont bien accessibles.

## Vérification (après redémarrage de R) ----
getOption("email")
# [1] "jane.doe@mail.me"

getOption("family")
# [1] "Doe"


Projet RStudio

Lorsque vous démarrez un nouveau projet sous , il est vivement conseillé d’utiliser les Projets RStudio.

  Créez un nouveau Projet RStudio : File > New Project > New Directory > New Project

  • Choisissez un nom pour votre projet (sans signe de ponctuation), par ex. practice
  • Sélectionnez l’emplacement où le nouveau projet sera créé
  • Décochez toutes les autres cases
  • Validez
Bonne pratique #1

Toujours travailler dans un Projet RStudio. Cela présente l’avantage de simplifier les chemins d’accès aux fichiers, notamment avec le package here et sa fonction here(). Les chemins d’accès seront toujours construits par rapport au dossier contenant le fichier .Rproj (racine du projet). On parle de chemin relatif. N’utilisez plus jamais la fonction setwd().

Structure du compendium

practice/                        # Root of the compendium
|
└─ practice.Rproj                # RStudio project file


Fichier README

Tout projet se doit de contenir un fichier README. C’est la vitrine du projet. Les rôles d’un README sont multiples :

  1. présenter le projet
  2. expliquer son contenu
  3. expliquer comment l’installer
  4. expliquer comment l’utiliser

C’est un simple fichier texte (plain text-based file) qui peut être écrit au format texte (README.txt), en Markdown (README.md), en R Markdown (README.Rmd), en Quarto (README.qmd), etc.

  Ici, vous allez créer un README.md (fichier texte écrit en Markdown) à la racine de votre projet.

  Utilisez la fonction utils::file.edit() qui permet d’ouvrir un fichier dans l’éditeur de RStudio. Si ce fichier n’existe pas, elle va aussi le créer.

## Ajout d'un README ----
utils::file.edit(here::here("README.md"))

  Exécutez cette ligne de code dans la console : here::here("README.md") et essayez de comprendre ce que fait la fonction here::here(). Comparez avec votre voisin.e.

  Editez ce README.md en ajoutant les informations pertinentes.

Proposition de README

Code 
# Practice

This project contains files to create a simple **research compendium** as 
presented in the training course 
[Reproducible Research in Computational Ecology](https://rdatatoolbox.github.io).


## Content

This project is structured as follow:

- `README.md`: presentation of the project
- `compendium.Rproj`: RStudio project file


## Installation

Coming soon...


## Usage

Coming soon...


## Citation

> Doe J (2024) Minimal structure of a research compendium.
Bonne pratique #2

Ajoutez un README à votre projet afin d’aider l’utilisateur à comprendre votre projet. Si vous souhaitez exécuter du code à l’intérieur, écrivez-le en R Markdown (README.Rmd) ou Quarto (README.qmd), sinon utilisez simplement du Markdown (README.md).

NB. Si vous écrivez un .Rmd ou un .qmd, n’oubliez pas de le transpiler en .md. GitHub n’est capable d’interpréter que les .md.

## Conversion d'un Rmd en un md ----
rmarkdown::render("README.Rmd")

## Conversion d'un qmd en un md ----
quarto::quarto_render("README.qmd")

  Vous pouvez aussi cliquer sur le bouton Render de RStudio.

Structure du compendium

practice/                        # Root of the compendium
|
├─ practice.Rproj                # RStudio project file
|
└─ README.md                     # Presentation of the project


Fichier DESCRIPTION

Le fichier DESCRIPTION décrit les métadonnées du projet (titre, auteur, description, dépendances requises, etc.). C’est un des éléments essentiels d’un package . Ici, nous allons le détourner pour l’utiliser dans le cadre d’un compendium afin de bénéficier des outils de développement de packages (voir plus loin).

  Ajoutez un fichier DESCRIPTION avec la fonction add_description() de rcompendium.

## Ajout d'un fichier DESCRIPTION ----
add_description()
Package: practice
Type: Package
Title: The Title of the Project
Version: 0.0.0.9000
Authors@R: c(
    person(given   = "Jane",
           family  = "Doe",
           role    = c("aut", "cre", "cph"),
           email   = "jane.doe@mail.me",
           comment = c(ORCID = "0000-0000-0000-0000")))
Description: A paragraph providing a full description of the project (on 
    several lines...)
License: {{license}}
Encoding: UTF-8

Comme vous le voyez, le fichier DESCRIPTION a été pré-rempli avec vos informations personnelles. Vous éditerez les champs Title et Description plus loin.

Bonne pratique #3

Toujours ajouter un fichier DESCRIPTION à la racine du projet. Il permet de décrire les métadonnées du projet : titre, auteur(s), description, licence, etc. Nous le verrons plus loin, mais c’est aussi l’endroit idéal pour lister les packages externes requis.

Structure du compendium

practice/                        # Root of the compendium
|
├─ practice.Rproj                # RStudio project file
|
├─ README.md                     # Presentation of the project
└─ DESCRIPTION                   # Project metadata


Choix d’une Licence

Tout matériel partagé en ligne doit disposer d’une licence qui décrit ce qu’il est possible de faire avec. Ainsi, nous vous recommandons d’ajouter dès le début du projet une licence. Pour savoir quelle licence est la plus appropriée à votre projet, vous pouvez vous rendre sur ce site : https://choosealicense.com.

  Ajoutez la licence GPL-2 à votre projet à l’aide de la fonction add_license() de rcompendium.

## Ajout d'une licence ----
add_license(license = "GPL-2")

Notez qu’un nouveau fichier a été créé : LICENSE.md. Celui-ci détaille le contenu de la license choisie et sera lu par GitHub. Regardez aussi le contenu du fichier DESCRIPTION : la section License a été mise à jour grâce à rcompendium.

  Ajoutez une section au README.md mentionnant la licence.

Proposition de README

Code 
# Practice

This project contains files to create a simple **research compendium** as 
presented in the training course 
[Reproducible Research in Computational Ecology](https://rdatatoolbox.github.io).


## Content

This project is structured as follow:

- `README.md`: presentation of the project
- `compendium.Rproj`: RStudio project file


## Installation

Coming soon...


## Usage

Coming soon...


## License

This project is released under the 
[GPL-2 license](https://choosealicense.com/licenses/gpl-2.0/).


## Citation

> Doe J (2024) Minimal structure of a research compendium.
Bonne pratique #4

Toujours ajouter une LICENCE à un projet qui sera rendu public. Visitez le site Choose a License pour choisir la plus appropriée à votre projet.

NB. Si aucune licence n’est renseignée, votre projet sera soumis aux règles de la No License : aucune permission n’est accordée. En d’autres termes, personne ne peut rien faire avec votre projet (pas d’utilisation, pas de modification, pas de partage, etc.).

Structure du compendium

practice/                        # Root of the compendium
|
├─ practice.Rproj                # RStudio project file
|
├─ README.md                     # Presentation of the project
├─ DESCRIPTION                   # Project metadata
└─ LICENSE.md                    # License of the project


Sous-répertoires

La prochaine étape consiste en la création de sous-répertoires, chacun ayant un rôle précis. L’idée ici est de séparer les données, les résultats et le code.

  Pour cela, utilisez la fonction add_compendium() de rcompendium.

## Ajout de sous-répertoires ----
add_compendium(compendium = c("data", "analyses", "R", "figures", "outputs"))
Bonne pratique #5

Un bon Research compendium sera composé de différents sous-répertoires, chacun destiné à accueillir un certain type de fichiers. Par ex.,

  • le dossier data/ contiendra toutes les données brutes nécessaires au projet
  • le dossier outputs/ contiendra tous les résultats générés (hors figures)
  • le dossier figures/ contiendra toutes les figures produites par les analyses
  • le dossier R/ ne contiendra que des fonctions (et leurs documentations). Voir plus loin
  • le dossier analyses/ contiendra des scripts (ou des fichiers .Rmd et/ou .qmd) qui appeleront les fonctions

NB. Cette structure peut bien sûr être adaptée selon les besoins, les pratiques de chacun et la complexité du projet. A l’exception du dossier R/, tous les autres répertoires peuvent être nommés différemment.

Structure du compendium

practice/                        # Root of the compendium
|
├─ practice.Rproj                # RStudio project file
|
├─ README.md                     # Presentation of the project
├─ DESCRIPTION                   # Project metadata
├─ LICENSE.md                    # License of the project
|
├─ data/                         # Contains raw data
├─ outputs/                      # Contains results
├─ figures/                      # Contains figures
├─ R/                            # Contains R functions (only)
└─ analyses/                     # Contains R scripts


Code

Nous voilà fin prêt à coder !

Le dépôt GitHub https://github.com/rdatatoolbox/datarepo contient les données que nous utiliserons tout au long de la formation. Celles-ci proviennent de deux bases de données : PanTHERIA et WWF WildFinder. Lisez attentivement le README pour plus de détails.

  L’objectif ici est d’écrire un code   qui va télécharger les quatre fichiers hébergés sur le dépôt GitHub mentionné ci-dessus.

Nous allons commencer par écrire notre code dans un script. Le fichier de données PanTHERIA, disponible ici, sera enregistré dans le sous-répertoire data/pantheria/ et les trois fichiers de données WWF WildFinder, disponibles ici, seront enregistrés dans le sous-répertoire data/wildfinder/.

  Créez, dans le dossier analyses/, le script download-data.R à l’aide de la fonction utils::file.edit().

## Ajout d'un script R ----
utils::file.edit(here::here("analyses", "download-data.R"))

Utilisez les fonctions dir.create() pour créer des sous-répertoires, here::here() pour construire vos chemins et utils::download.file() pour télécharger les fichiers.

Proposition de code pour PanTHERIA (essayez de ne pas regarder)

Code 
## Destination path ---- 
path <- here::here("data", "pantheria")

## Create destination directory ----
dir.create(path, showWarnings = FALSE, recursive = TRUE)

## File name ----
filename <- "PanTHERIA_1-0_WR05_Aug2008.txt"
  
## GitHub base URL ----
base_url <- "https://raw.githubusercontent.com/rdatatoolbox/datarepo/main/data/pantheria/"

## Build full URL ----
full_url <- paste0(base_url, filename)

## Build full path ----
dest_file <- file.path(path, filename)

## Download file ----
utils::download.file(url      = full_url,
                     destfile = dest_file,
                     mode     = "wb")
Bonne pratique #6

Essayez de scripter l’intégralité du travail. Ici, nous avons vu comment créer des fichiers (utils::file.edit()) et des répertoires (dir.create()), construire des chemins relatifs robustes (here::here()) et télécharger des fichiers (utils::download.file()) directement à partir de .

Structure du compendium

practice/                                     # Root of the compendium
|
├─ practice.Rproj                             # RStudio project file
|
├─ README.md                                  # Presentation of the project
├─ DESCRIPTION                                # Project metadata
├─ LICENSE.md                                 # License of the project
|
├─ data/                                      # Contains raw data
|  ├─ pantheria/                              # PanTHERIA database
|  |  └─ PanTHERIA_1-0_WR05_Aug2008.txt
|  └─ wildfinder/                             # WWF WildFinder database
|     ├─ wildfinder-ecoregions_list.csv
|     ├─ wildfinder-ecoregions_species.csv
|     └─ wildfinder-mammals_list.csv
|
├─ outputs/                                   # Contains results
├─ figures/                                   # Contains figures
├─ R/                                         # Contains R functions (only)
|
└─ analyses/                                  # Contains R scripts
   └─ download-data.R                         # Script to download raw data
Packages externes

Pour utiliser une fonction d’un package externe, vous avez appris à utiliser library("package"). Sous , il existe une autre syntaxe pour appeler une fonction d’un package externe : package::function(). Alors que library() charge et attache un package (rendant ses fonctions accessible directement avec function()), la syntaxe package::function() charge uniquement un package dans l’environnement de , mais n’attache pas son contenu. Ainsi, on est obligé de spécifier le nom du package en appelant la fonction.

Nous vous recommendons d’utiliser la syntaxe package::function(). Et ce pour deux raisons :

  • meilleure lisibilité du code : en un coup d’oeil, on sait dans quel package se trouve la fonction
  • limitation de conflits entre packages : deux fonctions peuvent avoir le même nom dans deux packages différentes. Par ex., le package dplyr propose une fonction filter() qui se trouve également dans le package stats (attaché à l’ouverture de ). Mais, les fonctions filter() de ces deux packages ne font pas la même chose.
library("dplyr")

## Attaching package: ‘dplyr’
## 
## The following objects are masked from ‘package:stats’:
## 
##     filter, lag
## 
## The following objects are masked from ‘package:base’:
## 
##     intersect, setdiff, setequal, union

Si vous utilisez library("dplyr"), vous ne serez jamais sûr à 100% d’utiliser la fonction filter() du package dplyr ou celle du package stats.

Cependant, pour des packages très verbeux (tels que ggplot2), vous pouvez utiliser la fonction library(), sinon votre code deviendra très vite fastidieux à écrire.

  Si vous souhaitez utiliser le pipe %>%, attachez le package magrittr avec library("magrittr").


Factorisation

On peut aller plus loin en découpant ce script en fonctions : on parle de factorisation de code. Une fonction est un ensemble de lignes de code regroupées en un seul bloc destiné à réaliser une tâche précise. Ecrire des fonctions rendra votre code plus clair et plus facilement réutilisable entre projets.

  Placez toujours vos fonctions   dans un dossier nommé R/.

  Factorisez le script précédent en deux fonctions :

  • une fonction dl_pantheria_data() pour télécharger les données PanTHERIA, et
  • une fonction dl_wildfinder_data() pour télécharger les données WWF WildFinder.

  Utilisez la fonction usethis::use_r() pour créer deux fichiers .R dans le dossier R/.

## Création du fichier pour la 1ere fonction ----
usethis::use_r("dl_pantheria_data")

Proposition de fonction (essayer de ne pas regarder)

Code 
dl_pantheria_data <- function() {
  
  ## Destination path ---- 
  path <- here::here("data", "pantheria")
  
  ## Create destination directory ----
  dir.create(path, showWarnings = FALSE, recursive = TRUE)
  
  ## File name ----
  filename <- "PanTHERIA_1-0_WR05_Aug2008.txt"
    
  ## GitHub base URL ----
  url <- "https://raw.githubusercontent.com/rdatatoolbox/datarepo/main/data/pantheria/"
  
  ## Build full URL ----
  full_url <- paste0(base_url, filename)
  
  ## Build full path ----
  dest_file <- file.path(path, filename)

  ## Download file ----
  utils::download.file(url      = full_url,
                       destfile = dest_file,
                       mode     = "wb")
  
  return(dest_file)
}
Bonne pratique #7

Ecrivez des fonctions : on parle de Factorisation de code. Cela rendra votre code plus clair et plus facilement réutilisable. Placez toujours vos fonctions dans le dossier R/. Si vous utilisez des fonctions de dépendances externes, priviligiez cette écriture : package::fonction().

Structure du compendium

practice/                                     # Root of the compendium
|
├─ practice.Rproj                             # RStudio project file
|
├─ README.md                                  # Presentation of the project
├─ DESCRIPTION                                # Project metadata
├─ LICENSE.md                                 # License of the project
|
├─ data/                                      # Contains raw data
|  ├─ pantheria/                              # PanTHERIA database
|  |  └─ PanTHERIA_1-0_WR05_Aug2008.txt
|  └─ wildfinder/                             # WWF WildFinder database
|     ├─ wildfinder-ecoregions_list.csv
|     ├─ wildfinder-ecoregions_species.csv
|     └─ wildfinder-mammals_list.csv
|
├─ outputs/                                   # Contains results
├─ figures/                                   # Contains figures
├─ R/                                         # Contains R functions (only)
|  ├─ dl_pantheria_data.R                     # Function to download PanTHERIA data
|  └─ dl_wildfinder_data.R                    # Function to download WildFinder data
|
└─ analyses/                                  # Contains R scripts
   └─ download-data.R                         # Script to download raw data


Documentation

Il est temps de documenter vos fonctions. C’est essentiel ! Pour cela, nous allons utiliser la syntaxe roxygen2. Celle-ci permet de documenter facilement les fonctions en plaçant un entête roxygen2 avant chaque fonction. Cet entête doit contenir (a minima) un titre, une description de chaque argument et le retour de la fonction.

  Ajoutez un entête roxygen2 à vos deux fonctions pour les documenter.

Proposition de documentation (essayer de ne pas regarder)

Code 
#' Download PanTHERIA dataset
#'
#' @description 
#' This function downloads the PanTHERIA dataset (text file) hosted on the 
#' GitHub repository <https://github.com/rdatatoolbox/datarepo/>.
#' The file `PanTHERIA_1-0_WR05_Aug2008.txt` will be stored in 
#' `data/pantheria/`. This folder will be created if required.
#'
#' @return This function returns the path (`character`) to the downloaded file
#' (e.g. `data/pantheria/PanTHERIA_1-0_WR05_Aug2008.txt`).
#' 
#' @export

dl_pantheria_data <- function() { ... }
Bonne pratique #8

Pensez aux autres (et au vous du futur) : documentez toujours votre code. Un code sans documentation est inutile. Utilisez les entêtes roxygen2 pour documenter vos fonctions , de simples commentaires pour documenter du code et des README pour tout le reste.

Structure du compendium

practice/                                     # Root of the compendium
|
├─ practice.Rproj                             # RStudio project file
|
├─ README.md                                  # Presentation of the project
├─ DESCRIPTION                                # Project metadata
├─ LICENSE.md                                 # License of the project
|
├─ data/                                      # Contains raw data
|  ├─ pantheria/                              # PanTHERIA database
|  |  └─ PanTHERIA_1-0_WR05_Aug2008.txt
|  └─ wildfinder/                             # WWF WildFinder database
|     ├─ wildfinder-ecoregions_list.csv
|     ├─ wildfinder-ecoregions_species.csv
|     └─ wildfinder-mammals_list.csv
|
├─ outputs/                                   # Contains results
├─ figures/                                   # Contains figures
├─ R/                                         # Contains R functions (only)
|  ├─ dl_pantheria_data.R                     # Function to download PanTHERIA data
|  └─ dl_wildfinder_data.R                    # Function to download WildFinder data
|
└─ analyses/                                  # Contains R scripts
   └─ download-data.R                         # Script to download raw data
Pour aller plus loin

Vous pouvez transpiler vos entêtes roxygen2 en fichiers .Rd, seuls fichiers acceptés par pour documenter des fonctions. Ces fichiers .Rd seront stockés dans le dossier man/.

## Génération de la doc ----
devtools::document()

L’aide de votre fonction sera accessible via ?nom_fonction.


Appel aux fonctions

Jusqu’à présent, nous n’avons fait que définir (et documenter) des fonctions , mais nous ne les avons pas exécuté.

  Adaptez le contenu du script analyses/download-data.R créé précédemment afin qu’il appelle les fonctions dl_pantheria_data() et dl_wildfinder_data().

## Ouverture du script précédent ----
utils::file.edit(here::here("analyses", "download-data.R"))

Proposition de contenu (essayer de ne pas regarder)

Code 
# Download project raw data
#
# This script will download the PanTHERIA and WWF WildFinder datasets. The
# four files will be stored in `data/`.
# 
# All functions used in the script have been developed for this project
# and can be found in the folder R/.
#
# Jane Doe <jane.doe@mail.me>

## Download PanTHERIA database ----
pantheria_path  <- dl_pantheria_data()


## Download WWF WildFinder database ----
wildfinder_path <- dl_wildfinder_data()

%%{init:{'theme':'neutral','flowchart':{'htmlLabels':false}}}%%
flowchart LR
  B("analyses/download-data.R")
  B --> C("dl_pantheria_data()")
  B --> D("dl_wildfinder_data()")

Bonne pratique #9

Le dossier analyses/ contient les scripts qui appellent les fonctions stockées dans le dossier R/. Dans le cas d’analyses complexes, n’hésitez pas à multiplier les scripts (plutôt que d’avoir un seul gros script).


Ajout des dépendances

Nos fonctions contiennent des dépendances à deux packages externes : utils et here. Comme dit précédemment, le fichier DESCRIPTION est l’endroit idéal pour centraliser la liste des packages requis.

  Ajoutez ces deux dépendances au fichier DESCRIPTION avec la fonction usethis::use_package().

## Ajout des dépendances dans DESCRIPTION ----
usethis::use_package(package = "here")
usethis::use_package(package = "utils")

Regardez le contenu du fichier DESCRIPTION : les deux packages requis sont listés dans la section Imports.

Package: practice
Type: Package
Title: The Title of the Project
Version: 0.0.0.9000
Authors@R: c(
    person(given   = "Jane",
           family  = "Doe",
           role    = c("aut", "cre", "cph"),
           email   = "jane.doe@mail.me",
           comment = c(ORCID = "0000-0000-0000-0000")))
Description: A paragraph providing a full description of the project (on 
    several lines...)
License: GPL-2
Encoding: UTF-8
Imports:
    here,
    utils
Bonne pratique #10

Listez toujours les packages requis dans le fichier DESCRIPTION. Ainsi, vous centralisez la liste des packages requis en un seul endroit et vous pourrez utiliser les fonctions devtools::install_deps() et devtools::load_all() (voir la section Chargement du projet).

Pour aller plus loin

Si, dans votre code , vous souhaitez attacher vos packages avec library(), utilisez la fonction usethis::use_package() comme suit :

## Ajout d'une dépendance forte ----
usethis::use_package(package = "ggplot2", type = "Depends")

Le package sera ajouté dans la section Depends du fichier DESCRIPTION.


Chargement du projet

Maintenant que notre compendium contient un fichier DESCRIPTION avec une liste de packages, nous pouvons utiliser les outils de développement des packages disponibles dans le package devtools pour :

1) Installer les packages avec la fonction devtools::install_deps()

Cette fonction va lire le fichier DESCRIPTION pour récupérer la liste des packages requis dans les sections Depends et Imports et les installer (uniquement s’ils ne sont pas déjà installés). Cette fonction vient donc remplacer la fonction install.packages().

  Par défaut, cette fonction va aussi vous demander de mettre à jour les packages (si une nouvelle version est disponible). Si vous souhaitez désactiver cette fonctionnalité, ajoutez l’argument upgrade = "never".

2) Charger les packages avec la fonction devtools::load_all()

Cette fonction va aussi lire le fichier DESCRIPTION pour récupérer la liste des packages requis dans les sections Depends et Imports. Elle va charger les packages listés dans la section Imports et charger et attacher les packages listés dans la section Depends. Cette fonction vient donc remplacer la fonction library().

Important

Mettez régulièrement à jour votre fichier DESCRIPTION en :

  • ajoutant les nouveaux packages que vous utilisez
  • retirant les packages que vous n’utilisez plus

3) Charger les fonctions   avec la fonction devtools::load_all()

La fonction devtools::load_all() présente un second avantage : elle va charger les fonctions stockées dans le dossier R/ et les rendre accessibles dans la session. Elle vient donc remplacer la fonction source().

  Après chaque modification d’une fonction , n’oubliez pas d’exécuter la fonction devtools::load_all(). Vous pouvez utiliser le raccourci clavier Ctrl + Shift + L dans RStudio.

  Essayez ces deux fonctions.

## Installation des packages manquants ----
devtools::install_deps(upgrade = "never")

## Chargement des packages et des fonctions R ----
devtools::load_all()
Bonne pratique #11

Avec un fichier DESCRIPTION (listant les dépendances requises) et un dossier R/, vous pouvez utiliser :

  • devtools::install_deps() pour installer (et mettre à jour) les packages : n’utilisez plus install.packages()
  • devtools::load_all() pour 1) charger (et attacher) les packages et 2) charger vos fonctions : n’utilisez plus library() ni source() (pour charger vos fonctions).


Ajout d’un make.R

Afin d’automatiser notre projet, nous allons créer un script à la racine du projet. Nous l’appelerons, par convention, make.R. Celui-ci aura deux objectifs :

  • mettre en place le projet en installant et chargeant les packages (et les fonctions)
  • exécuter le projet en sourçant les scripts de manière séquentielle

L’idée est, qu’une fois le projet fini, l’utilisateur n’exécute que ce script : c’est le chef d’orchestre du projet.

  Utilisez la fonction utils::file.edit() pour créer un script   à la racine du projet.

## Ajout d'un makefile ----
utils::file.edit(here::here("make.R"))

  Ajoutez-y les deux fonctions précédentes :

# Setup project ----

## Install packages ----
devtools::install_deps(upgrade = "never")

## Load packages & functions ----
devtools::load_all()

  Finalement, ajoutez une ligne dans le fichier make.R qui permettra d’exécuter le script analyses/download-data.R.

  Utilisez les fonctions source() et here::here() pour cela.

Proposition de make.R (essayer de ne pas regarder)

Code 
# Project title
#
# Project description
# ...
#
# Author: Jane Doe
# Date: 2024/12/02


# Setup project ----

## Install packages ----
devtools::install_deps(upgrade = "never")

## Load packages & functions ----
devtools::load_all()


# Run project ----

## Download raw data ----
source(here::here("analyses", "download-data.R"))

%%{init:{'theme':'neutral','flowchart':{'htmlLabels':false}}}%%
flowchart LR
  A("make.R") --> B("analyses/download-data.R")
  B --> C("dl_pantheria_data()")
  B --> D("dl_wildfinder_data()")

Bonne pratique #12

Un fichier make.R placé à la racine du projet permet de facilement mettre en place le projet (installation et chargement des packages requis et des fonctions ) et d’exécuter les différentes analyses de manière séquentielle (en sourçant les scripts qui appellent eux-même les fonctions ). C’est le chef d’orchestre du projet.

NB. Vu la simplicité de ce projet, nous aurions très bien pu placer le contenu du script   analyses/download-data.R) dans ce make.R. La structure d’un compendium n’est pas figée, mais nous vous recommandons d’utiliser a minima des fonctions et un make.R.

Structure du compendium

practice/                                     # Root of the compendium
|
├─ practice.Rproj                             # RStudio project file
|
├─ README.md                                  # Presentation of the project
├─ DESCRIPTION                                # Project metadata
├─ LICENSE.md                                 # License of the project
|
├─ data/                                      # Contains raw data
|  ├─ pantheria/                              # PanTHERIA database
|  |  └─ PanTHERIA_1-0_WR05_Aug2008.txt
|  └─ wildfinder/                             # WWF WildFinder database
|     ├─ wildfinder-ecoregions_list.csv
|     ├─ wildfinder-ecoregions_species.csv
|     └─ wildfinder-mammals_list.csv
|
├─ outputs/                                   # Contains results
├─ figures/                                   # Contains figures
├─ R/                                         # Contains R functions (only)
|  ├─ dl_pantheria_data.R                     # Function to download PanTHERIA data
|  └─ dl_wildfinder_data.R                    # Function to download WildFinder data
|
├─ analyses/                                  # Contains R scripts
|  └─ download-data.R                         # Script to download raw data
|
└─ make.R                                     # Script to setup & run the project


Pour finir

N’oubliez pas de finaliser la documentation de votre projet.

  Editez les sections Title et Description du fichier DESCRIPTION.

Proposition de DESCRIPTION

Code 
Package: practice
Type: Package
Title: Download PanTHERIA and WWF WildFinder databases
Version: 0.0.0.9000
Authors@R: c(
    person(given   = "Jane",
           family  = "Doe",
           role    = c("aut", "cre", "cph"),
           email   = "jane.doe@mail.me",
           comment = c(ORCID = "0000-0000-0000-0000")))
Description: This project aims to download PanTHERIA and WWF WildFinder 
    databases. It is structured as a research compendium to be reproducible.
    This is the result of the Practice 1 of the training course Reproducible 
    Research in Computational Ecology available at:
    <https://rdatatoolbox.github.io/chapters/ex-compendium.html>.
License: GPL-2
Encoding: UTF-8
Imports:
    here,
    utils

  Editez le README.

Proposition de README

Code 
# Practice

This project aims to download the [PanTHERIA](https://doi.org/10.1890/08-1494.1) 
database (Kate _et al._, 2009) and the 
[WWF WildFinder](https://www.worldwildlife.org/pages/wildfinder-database) 
database (World Wildlife Fund 2006). It is structured as a research compendium 
to be reproducible.

**NB.** This is the result of the Practice 1 of the training course
[Reproducible Research in Computational Ecology](https://rdatatoolbox.github.io).


## Content

This project is structured as follow:

.
├─ practice.Rproj                             # RStudio project file
|
├─ README.md                                  # Presentation of the project
├─ DESCRIPTION                                # Project metadata
├─ LICENSE.md                                 # License of the project
|
├─ data/                                      # Contains raw data
|  ├─ pantheria/                              # PanTHERIA database
|  |  └─ PanTHERIA_1-0_WR05_Aug2008.txt
|  └─ wildfinder/                             # WWF WildFinder database
|     ├─ wildfinder-ecoregions_list.csv
|     ├─ wildfinder-ecoregions_species.csv
|     └─ wildfinder-mammals_list.csv
|
├─ outputs/                                   # Contains results
├─ figures/                                   # Contains figures
├─ R/                                         # Contains R functions (only)
|  ├─ dl_pantheria_data.R                     # Function to download PanTHERIA data
|  └─ dl_wildfinder_data.R                    # Function to download WildFinder data
|
├─ analyses/                                  # Contains R scripts
|  └─ download-data.R                         # Script to download raw data
|
└─ make.R                                     # Script to setup & run the project


## Installation

Coming soon...


## Usage

Open the `practice.Rproj` file in RStudio and run `source("make.R")` to launch 
analyses. 

- All packages will be automatically installed and loaded
- Datasets will be saved in the `data/` directory


## License

This project is released under the 
[GPL-2](https://choosealicense.com/licenses/gpl-2.0/) license.


## Citation

> Doe J (2024) Download PanTHERIA and WWF WildFinder databases.


## References

Kate EJ, Bielby J, Cardillo M _et al._ (2009) PanTHERIA: A 
species-level database of life history, ecology, and geography of extant and 
recently extinct mammals. _Ecology_, 90, 2648. 
DOI: [10.1890/08-1494.1](https://doi.org/10.1890/08-1494.1)

World Wildlife Fund (2006) WildFinder: Online database of species distributions. 
Version Jan-06. URL: https://www.worldwildlife.org/pages/wildfinder-database


Félicitation

Votre projet est devenu un véritable research compendium fonctionnel et reproductible.


  The final compendium can be found here.


La fonction new_compendium()

L’ensemble de ces étapes peut être réalisé avec une seule fonction : new_compendium() de rcompendium. Lisez attentivement la documentation avant d’utiliser cette fonction.