Reproducible research in computational ecology

Course information

The objective of this five-day training course, co-organized by the FRB-CESAB and the GdR EcoStat, is to train researchers in reproducibility, software development and version control tools (e.g. git, GitHub, Quarto, renv, Docker), applied to biodiversity research.

A word about Docker

During this training course we will introduce Docker, a containerization solution to reach a high level of reproducibility. But the installation of Docker is not required as no exercise is planned for this topic.

Installation

Required software

Please install the following software before attending the course:

Software	Description	Website
`R 4.5.2`	The R environment	link
`Rtools 4.5`	A toolbox to build R packages from source	link
`Quarto`	Scientific publishing system (alternative to Rmarkdown)	link
`Git`	Version control software	link
`Positron`	Integrated development environment for R (alternative to RStudio)	link

Note: Positron bundles the Quarto software: you don’t need to install Quarto manually. Rtools note: download the default Rtools (not the 64-bit ARM installer). Positron note: Download the system level installer (not the user level installer). Git note: accept all default options during installation.

Check installation

After restarting your laptop, open Positron. Then, launch R (click on Start Session button) and run the following lines:

# Get R version ----
R.version.string
# "R version 4.5.2 (2025-10-31 ucrt)"

# Check if git is installed and detected ----
Sys.which("git")
# "C:\\PROGRA~1\\Git\\cmd\\git.exe"

# Check if Rtools is installed and detected ----
Sys.which("make")
# "C:\\rtools45\\usr\\bin\\make.exe"

# Check if you can install packages from sources (need Rtools) ----
install.packages("jsonlite", type = "source")

Required software

Please install the following software before attending the course:

Software	Description	Website
`R 4.5.2`	The R environment	link
`XQuartz`	Graphical window system	link
`Quarto`	Scientific publishing system (alternative to Rmarkdown)	link
`Git`	Version control software	link
`Positron`	Integrated development environment for R (alternative to RStudio)	link

Note: Positron bundles the Quarto software: you don’t need to install Quarto manually.

Installation with Homebrew

Homebrew is a package manager for macOS. A package manager is a way to get software (and software updates) onto your machine using the command line. It’s the macOS equivalent of dnf, pacman or apt.

Before installing Homebrew, you need to install the Apple software Xcode Command Line Tools. It is a self-contained package for software developers who wish to build Mac apps using UNIX-style commands. It’s required by Homebrew.

Open a Terminal, run this line (you will have to accept the license):

# Install Xcode Command Line Tools ----
sudo xcode-select --install

You can now install Homebrew itself by running:

# Install Homebrew ----
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Check installation ----
brew --version
# Homebrew 5.0.2

# Update repositories (list of available software) ----
brew update

It’s time to install the required software:

# Install utilities for R ----
brew install --cask xquartz     ## Graphical window system
brew install gfortran           ## FORTRAN compiler for GCC

# Install R ----
brew install --cask r

# Install Positron ----
brew install --cask positron

# Install git ----
brew install git

Check installation

After restarting your laptop, open Positron. Then, launch R (click on Start Session button) and run the following lines:

# Get R version ----
R.version.string
# "R version 4.5.2 (2025-10-31 ucrt)"

# Check if git is installed and detected ----
Sys.which("git")
# "/usr/bin/git"

# Check if Rtools is installed and detected ----
Sys.which("make")
# "/usr/bin/make"

# Check if you can install packages from sources ----
install.packages("jsonlite", type = "source")

Required software

Here is the list of the required software:

Software	Description	Website
`R 4.5.2`	The R environment	link
`Quarto`	Scientific publishing system (alternative to Rmarkdown)	link
`Git`	Version control software	link
`Positron`	Integrated development environment for R (alternative to RStudio)	link

Note: Positron bundles the Quarto software: you don’t need to install Quarto manually.

Install R

# Update APT repository indices ----
sudo apt update -qq

# Install helper packages ----
sudo apt install --no-install-recommends software-properties-common dirmngr wget

# Add CRAN GPG key ----
wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | sudo tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc

# Add CRAN repository to APT repository list ----
sudo add-apt-repository "deb https://cloud.r-project.org/bin/linux/ubuntu $(lsb_release -cs)-cran40/"

# Update APT repository indices ----
sudo apt update

# Install R ----
sudo apt install r-base r-base-dev

Install git

# Install git ----
sudo apt install git

Install Positron

# Install helper package ----
sudo apt install gdebi-core

# Download Positron ---
POSITRON_VERSION='2025.11.0-234'
wget https://cdn.posit.co/positron/releases/deb/x86_64/Positron-$POSITRON_VERSION-x64.deb

# Install/update Positron ----
sudo gdebi Positron-$POSITRON_VERSION-x64.deb

# Clean directory ----
rm Positron-$POSITRON_VERSION-x64.deb

Check installation

After restarting your laptop, open Positron. Then, launch R (click on Start Session button) and run the following lines:

# Get R version ----
R.version.string
# "R version 4.5.2 (2025-10-31)"

# Check if git is installed and detected ----
Sys.which("git")
# "/usr/bin/git"

# Check if compilation tools are installed and detected ----
Sys.which("make")
# "/usr/bin/make"

# Check if Quarto is installed and detected ----
Sys.which("quarto")
# "/usr/share/positron/resources/app/quarto/bin/quarto"

# Check if you can install packages from sources ----
install.packages("jsonlite", type = "source")

Required software

Here is the list of the required software:

Software	Description	Website
`R 4.5.2`	The R environment	link
`Quarto`	Scientific publishing system (alternative to Rmarkdown)	link
`Git`	Version control software	link
`Positron`	Integrated development environment for R (alternative to RStudio)	link

Note: Positron bundles the Quarto software: you don’t need to install Quarto manually.

Install R

# Install R ----
sudo dnf install R

Install git

# Install git ----
sudo dnf install git

Install Positron

# Download Positron ---
POSITRON_VERSION='2025.11.0-234'
wget https://cdn.posit.co/positron/prereleases/rpm/x86_64/Positron-$POSITRON_VERSION-x64.rpm

# Install Positron ----
sudo rpm -ivh Positron-$POSITRON_VERSION-x64.rpm

# Update Positron ----
# sudo rpm -Uvh Positron-$POSITRON_VERSION-x64.rpm

# Clean directory ----
rm Positron-$POSITRON_VERSION-x64.rpm

Check installation

After restarting your laptop, open Positron. Then, launch R (click on Start Session button) and run the following lines:

# Get R version ----
R.version.string
# "R version 4.5.2 (2025-10-31)"

# Check if git is installed and detected ----
Sys.which("git")
# "/usr/bin/git"

# Check if compilation tools are installed and detected ----
Sys.which("make")
# "/usr/bin/make"

# Check if Quarto is installed and detected ----
Sys.which("quarto")
# "/usr/share/positron/resources/app/quarto/bin/quarto"

# Check if you can install packages from sources ----
install.packages("jsonlite", type = "source")

Configuration

git

To use git to version your projects, you need to store your credentials (username and email) on your laptop.

Open Positronand run these lines in the console:

# Install 'gert' R package ----
install.packages("gert")

# Store your git user name ----
gert::git_config_global_set(
  name = "user.name", 
  value = "Jane Doe"            ## replace this value
)

# Store your git user email ----
gert::git_config_global_set(
  name = "user.email", 
  value = "jane.doe@mail.com"   ## replace this value
)

When you create a new git project, the default branch is named master. It’s recommended to replace master by main (for more information read this article).

Run this line in the console:

# Rename git default branch name ----
gert::git_config_global_set(
  name = "init.defaultBranch", 
  value = "main"
)

From now, when you will initialize git in a project, the default branch will be main.

Finally, let’s add this option to use nano as the default text editor for editing commits (instead of vi):

# Define nano as the default cli text editor ----
gert::git_config_global_set(
  name = "core.editor", 
  value = "nano"
)

Check your git configuration:

# Print git global configuration ----
gert::git_config_global()
#               name                 value      level
#          user.name              Jane Doe     global
#         user.email     jane.doe@mail.com     global
# init.defaultbranch                  main     global
#        core.editor                  nano     global

GitHub account

For this course, you need to create a GitHub account by visiting https://github.com/signup.

GitHub API token

If you want to use the GitHub API, essentially with the packages usethis and rcompendium, you need to create a GitHub Personal Access Token (PAT).

Proceed as follow:

Go to https://github.com/settings/tokens
Click on Generate new token (classic)
Choose a name for your new token (e.g. your laptop name)
Select no expiration date
In the section Select scopes, select at least repo and workflow
Copy this token

Then open Positronand run these lines in the console:

## Install usethis package ----
install.packages("usethis")

## Open ~/.Renviron file ----
usethis::edit_r_environ()
# • Modify '~/.Renviron'
# • Restart R for changes to take effect

The last command will open the ~/.Renviron file. Add this new line: GITHUB_PAT='ghp_XXX' where ghp_XXX is your token. Do not forget to restart the R session.

Finally, let’s check that your GitHub PAT is accessible from :

Sys.getenv("GITHUB_PAT")
# ghp_XXX

To go further

The .Renviron file is a good place to store secrets (API tokens, password, etc.). This file is read by at startup. To access these variables, you can use the function Sys.getenv("GITHUB_PAT").
The .Rprofile file allows you to run command lines at startup. You can customize the default behaviour of and define some variables with options(). To access these variables, you can use options()$"usethis.protocol".

More information here.

packages

# Project management ----
pkgs <- c(
  "devtools", 
  "gert", 
  "here", 
  "rdeps",
  "remotes",
  "renv", 
  "targets", 
  "tarchetypes", 
  "usethis"
)

install.packages(pkgs)

# Literate programming ----
pkgs <- c(
  "knitr", 
  "quarto", 
  "rmarkdown"
)

install.packages(pkgs)

# Data wrangling/visualization ----
pkgs <- c(
  "dplyr",
  "ggplot2",
  "readr",
  "rlang"
)

install.packages(pkgs)

The `rcompendium` package

In order to assist us in creating the structure of our research compendium (project directory), we will use the rcompendium package. This package allows for the automation of creating files and directories specific to a research compendium (and to a package).

The package is released on the CRAN but we will install the development version from GitHub:

# Install 'rcompendium' package from GitHub ----
remotes::install_github("frbcesab/rcompendium")

# Attach 'rcompendium' package -----
library("rcompendium")

Issue with rcompendium installation

Some Linux users may have trouble installing rcompendium. Try this:

# Download V8 software ----
Sys.setenv(DOWNLOAD_STATIC_LIBV8 = 1)

# Install 'rcompendium' package from GitHub ----
remotes::install_github("frbcesab/rcompendium")

# Attach 'rcompendium' package -----
library("rcompendium")

Once the package is installed, you need to store some personal information locally (first name, last name, email, ORCID, communication protocol with GitHub). This information will automatically populate certain files in the compendium. You will store this information in the ~/.Rprofile file.

# Open the ~/.Rprofile file ----
usethis::edit_r_profile()
# • Modify '~/.Rprofile'
# • Restart R for changes to take effect

And paste these lines in the ~/.Rprofile file:

options(
  given = "Jane",
  family = "Doe",
  email = "jane.doe@mail.me",
  orcid = "0000-0000-0000-0000"
)

options(usethis.protocol = "https") # or "ssh" if you deployed SSH keys to communicate w/ GitHub

Restart the session and verify that your personal information is accessible by :

# Retrieve email ----
getOption("email")
# [1] "jane.doe@mail.me"

# Retrieve family name ----
getOption("family")
# [1] "Doe"

Installation

Required software

Check installation

Required software

Check installation

Required software

Install R

Install git

Install Positron

Check installation

Required software

Install R

Install git

Install Positron

Check installation

Configuration

git

GitHub account

GitHub API token

packages

The rcompendium package

The `rcompendium` package