Research Compendium ou comment bien ranger sa cuisine
“A collection of concise but detailed information about a particular subject”
Un abrégé, un précis, un recueil.
Une archive qui synthétise de manière exhaustive votre projet d’analyse de données.
Le problème “J’ai ma propre organisation”
Here enters …
le ‘Research Compendium’
The goal of a research compendium is to provide a standard and easily recognisable way for organising the digital materials of a project to enable others to inspect, reproduce, and extend the research.
Three Generic Principles
Utilisez les projets RStudio
Travaillez selon le modèle : “1 projet = 1 compendium = 1 répertoire”.
L’utilisation d’un projet RStudio permet de se retrouver à la racine du projet à son ouverture.
│
├── [my_project]
│ └── my_project.Rproj
│
├── [another_project]
│ └── another_project.Rproj
│
├── [again_another_project]
│ └── again_another_project.Rproj
│
Stop à setwd()
!!
Les chemins absolus (e.g. C:\\Albert\Bureau\PhD
) ne fonctionnent que (temporairement) chez vous et jamais chez les autres.
Tous les chemins seront relatifs et définis à partir de la racine du projet : e.g. outputs/01_datacleaned.csv
, data/data_raw.csv
Utilisez le package {here}
Utilisez le package {here}
This means data files must be separate from code files.
And that output files are separated too.
La séparation entre données et résultats est matérialisée par des répertoires.
.
├── my_project.Rproj
├── [data]
└── [outputs]
La séparation entre données et résultats est matérialisée par des répertoires.
.
├── my_project.Rproj
├── [data] (données brutes)
└── [outputs] (résultats)
La séparation entre données et résultats est matérialisée par des répertoires.
.
├── my_project.Rproj
├── [data] (données brutes)
└── [outputs] (résultats)
Implications
Keeping data and method separate treats the data as “read-only”, so that the original data is untouched and all modifications are transparently documented in the code.
The output files should be considered as disposable, with a mindset that one can always easily regenerate the output using the code and data.
Stop à rm(list=ls())
!!
Les résultats sont “refabricables”.
Le code (les méthodes) est factorisé en morceaux réutilisables (des fonctions), elle sont appellées par les scripts d’analyses :
.
├── my_project.Rproj
├── [data] (données brutes)
├── [R] (fonctions = morceaux de code réutilisables)
├── [analyses] (les scripts)
└── [outputs] (résultats)
Le code (les méthodes) est factorisé en morceaux réutilisables (des fonctions), elle sont appellées par les scripts d’analyses :
.
├── my_project.Rproj
├── [data] (données brutes)
├── [R] (fonctions = morceaux de code réutilisables)
├── [analyses] (les scripts)
└── [outputs] (résultats)
Le code (les méthodes) est factorisé en morceaux réutilisables (des fonctions), elle sont appellées par les scripts d’analyses :
.
├── my_project.Rproj
├── [data]
├── [R]
├── [analyses]
└── [outputs]
Attention à R
Attention le répertoire R
ne doit contenir que des fichiers .R
qui ne contiennent que des définitions de fonctions !
Car tout code présent dans R
sera executé lors d’un appel aux fonctions devtools::load_all()
ou targets::tar_source()
, bien utiles par ailleurs !
.
├── my_project.Rproj
├── [data]
├── [R]
├── [analyses]
└── [outputs]
.
├── my_project.Rproj
├── [data]
│ ├── [raw_data]
│ └── [derived_data]
├── [R]
├── [analyses]
├── [figures]
└── [outputs]
Fléxibilité
Il existe des modèles d’organisation plus ou moins complexes, on adaptera la compléxité du compendium à celle du projet.
.
├── my_project.Rproj
├── [data]
├── [R]
├── [analyses]
│ ├── 00_setup.R (chargement des packages, variables globales)
│ ├── 01_data.R (lecture et formatage des données)
│ ├── 02_length-weight.R (première étape d'analyse)
│ ├── 03_plot-length-weight.R (génération du premier plot)
│ ├── ...
└── [outputs]
############################################################
#
# 00_setup.R: load packages, set global variables
#
############################################################
The relationship between which code operates on which data in which order to produce which outputs must be specified as well.
Utilisez un script “maître” (make.R
) qui execute les étapes dans l’ordre (c’est le SEUL script R à la racine !)
.
├── my_project.Rproj
├── [data]
├── [R]
├── [analyses]
├── [outputs]
└── make.R
make.R
) qui execute les étapes dans l’ordre (c’est le SEUL script R à la racine !)Chaque script (étape) écrit des résultats (fichiers) les référençant explicitement dans leur nom.
Il devient compliqué, lorsque l’analyse n’est pas linéaire et que les relations entre les étapes sont complexes, de se souvenir de toutes les dépendances entre scripts, données et résultats.
On est souvent ammener à relancer l’ensemble des analyses.
Et si les calculs sont longs, cela devient vraiment contre-productif !
.
├── my_project.Rproj
├── [data]
├── [R]
├── [analyses]
| └── pipeline.R
├── [outputs]
| └──[pipeline]
├── _targets.yaml
└── make.R
At its most basic, this could be a plain text file that includes a short list of the names and version numbers of the software and other critical tools used for the analysis. In more complex approaches, described below, the computational environment can be automatically preserved or reproduced as well.
Placez un README à la racine du projet.
Écrivez-le en Rmd
ou qmd
, compilez le dans le make.R
.
.
├── my_project.Rproj
├── [data]
├── [R]
├── [analyses]
├── [outputs]
├── README.md
├── README.qmd
├── _targets.yaml
└── make.R
Placez un README à la racine du projet.
.
├── my_project.Rproj
├── [data]
├── [R]
├── [analyses]
├── [outputs]
├── README.md
├── README.qmd
├── _targets.yaml
└── make.R
Utilisez le fichier DESCRIPTION et le package devtools pour les packages !
.
├── DESCRIPTION
├── [data]
├── [R]
├── [analyses]
├── [outputs]
├── my_project.Rproj
├── README.md
├── README.qmd
├── _targets.yaml
└── make.R
Utilisez le fichier DESCRIPTION et le package devtools pour les packages !
Utilisez le package renv pour fixer les packages au moment de la release.
.
├── DESCRIPTION
├── [data]
├── [R]
├── [analyses]
├── [outputs]
├── my_project.Rproj
├── README.md
├── README.qmd
├── renv.lock
├── _targets.yaml
└── make.R
.
├── DESCRIPTION
├── [data]
├── [R]
├── [analyses]
├── [outputs]
├── [syntheses]
├── my_project.Rproj
├── README.md
├── README.qmd
├── Dockerfile
├── renv.lock
├── _targets.yaml
└── make.R
.
├── DESCRIPTION
├── [data]
├── [R]
├── [analyses]
├── [outputs]
├── [syntheses]
| ├── paper.qmd
| └── presentation.qmd
├── my_project.Rproj
├── README.md
├── README.qmd
├── Dockerfile
├── renv.lock
├── _targets.yaml
└── make.R
Utilisez le package quarto il est vraiment puissant.
.
├── DESCRIPTION
├── [data]
├── [R]
├── [analyses]
├── [outputs]
├── [syntheses]
├── [documents]
├── my_project.Rproj
├── README.md
├── README.qmd
├── Dockerfile
├── renv.lock
├── _targets.yaml
└── make.R
Il existe de nombreuses plateformes pour stocker votre supp. mat.
La plupat sont propriétaires/privées et/ou payantes (e.g. Dryad, https://datadryad.org/)
Il existe Zenodo (https://zenodo.org/) : Il a été créé par OpenAIRE et le CERN pour fournir aux chercheurs un lieu pour déposer des ensembles de données. Il a été lancé en 2013, permettant à des chercheurs de télécharger des fichiers jusqu’à 50 GO.
Finalement cette architecture n’est pas si différente de celle d’un package R !
En intégrant les éléments essentiels de la structure d’un package (DESCRIPTION
, R/
) on bénéficie de tous les outils développés dans ce contexte.
.
├── [data]
| └── raw-data.csv (données brutes)
├── [R]
| └── functions.R (fonctions)
├── [analyses]
| └── pipeline.R (workflow)
├── [outputs] (résultats)
├── [syntheses]
| └── paper.qmd
├── [documents]
├── my_project.Rproj (projet)
├── README.md
├── DESCRIPTION
├── Dockerfile
├── renv.lock
├── _targets.yaml (workflow)
└── make.R (setup, workflow)
.
├── [data]
| └── raw-data.csv (données brutes)
├── [R]
| └── functions.R (fonctions)
├── [analyses]
| └── pipeline.R (workflow)
├── [outputs] (résultats)
├── [syntheses]
| └── paper.qmd
├── [documents]
├── my_project.Rproj (projet)
├── README.md
├── DESCRIPTION (dépendences, packages)
├── Dockerfile (dépendences, -> OS)
├── renv.lock (dépendences, packages)
├── _targets.yaml (workflow)
└── make.R (setup, workflow)
.
├── [data]
| └── raw-data.csv (données brutes)
├── [R]
| └── functions.R (fonctions)
├── [analyses]
| └── pipeline.R (workflow)
├── [outputs] (résultats)
├── [syntheses]
| └── paper.qmd (article, supp. mat, presentation)
├── [documents] (biblio)
├── my_project.Rproj (projet)
├── README.md
├── DESCRIPTION (dépendences, packages)
├── Dockerfile (dépendences, -> OS)
├── renv.lock (dépendences, packages)
├── _targets.yaml (workflow)
└── make.R (setup, workflow)
.
├── [data]
| └── raw-data.csv (données brutes)
├── [R]
| └── functions.R (fonctions)
├── [analyses]
| └── pipeline.R (workflow)
├── [outputs] (résultats)
├── [syntheses]
| └── paper.qmd (article, supp. mat, presentation)
├── [documents] (biblio)
├── my_project.Rproj (projet)
├── README.md (help)
├── DESCRIPTION (dépendences, packages)
├── Dockerfile (dépendences, -> OS)
├── renv.lock (dépendences, packages)
├── _targets.yaml (workflow)
└── make.R (setup, workflow)