Genotoul-Bioinfo

CC BY-NC-SA

Reproducible R environment with renv

Basics of renv

The goal of renv is to freeze, for one project, the version of R packages used in order to be able to (re)install/share same environment elsewhere/later.

The renv logic is explain at its website.

You will find some slides explaining it here

On the cluster

On the cluster, you will use renv the same way you will use it on you computer, but you must pay attention to not fill the quota of your $HOME directory. You must move the directory ~/.cache/R/renv where renv installs libraries in your work.

# We move the renv cache to workmkdir -p ~/work/.cache/Rmv ~/.cache/R/renv ~/work/.cache/R/# We create a shortcut to maintain compatibilityln -s ~/work/.cache/R/renv ~/.cache/R/renv

Create a renv on the cluster

# We go on work spacecd ~/work# Create a project directory and go in itmkdir my-projectcd my-project# Enable a R version, here R-4.5.0module load compilers/gcc/15.1.0module load statistics/R/4.5.0# Run RR...
# We install renv globallyinstall.packages("renv", repos=c("https://cloud.r-project.org"))...
# We initialize our projectrenv::init()...
Do you want to proceed? [y/N]: y
...
- Lockfile written to "/work/user/username/my-project/renv.lock".
- renv activated -- please restart the R session.
# We quitq()

Now the renv is ready to use. You project directory must look like that:

.
├── renv/
│   ├── activate.R
│   ├── .gitignore
│   ├── library/
│   ├── settings.json
│   └── staging/
├── renv.lock
└── .Rprofile

You can install packages in the renv this way:

R...
- Project '/work/user/username/my-project' loaded. [renv 1.2.3]
# We install some packages in the renv.install.packages("tidyverse", repos=c("https://cloud.r-project.org"))...
# We register which packages are installed renv::snapshot()...

In order to use packages installed in a renv, you must run R or Rscript from the directory where the renv is installed.

Use renv from anywhere

An easy way is to create a file .Rprofile with the following content in the working directory from where you want to run R or Rscript.

renv::load("path/to/my/renv/root")

For example, we want to be able to run R or RScript from a scripts directory in our project.

# We are at the root of a project managed with renvtree -aF -L 2.
├── renv/
│   ├── activate.R
│   ├── .gitignore
│   ├── library/
│   ├── settings.json
│   └── staging/
├── renv.lock
└── .Rprofile

# Enable a R version, here R-4.5.0module load compilers/gcc/15.1.0module load statistics/R/4.5.0# We check that the renv is foundRscript -e 'file.exists(renv::paths$lockfile())'[1] TRUE
# We create a scripts directory and we go in itmkdir scriptscd scripts# We check if the renv is foundRscript -e 'file.exists(renv::paths$lockfile())'[1] FALSE
# We enable the renv loading by creating, in the scripts directory, a .Rprofile file targeting the renv root directory (which is "..")echo 'renv::load("..")' > .Rprofile# We check again if the renv is foundRscript -e 'file.exists(renv::paths$lockfile())'[1] TRUE

You can also create a Rprofile file in your project directory that you will use globally (and avoid creating a .Rprofile file in each directory from where you need to run R or Rscript). For example, we created a Rprofile file named RScriptProfile, containing:

# Please, avoid to share this file as it is not portable
# and reveals information about you project path.
renv::load("/absolute/path/to/my/project")

Then use it this way:

# Set RScriptProfile as default Rprofile file with R_PROFILE_USERexport R_PROFILE_USER="/absolute/path/to/RScriptProfile"# Run as many R or Rscript as you want Rscript ...# Restore default Rprofile configuration when finishedunset R_PROFILE_USER

Example:

# We are at the root of you project with renvtree -aF -L 2.
├── data/
├── renv/
│   ├── activate.R
│   ├── .gitignore
│   ├── library/
│   ├── settings.json
│   └── staging/
├── renv.lock
├── scripts/
└── .Rprofile
# Enable a R version, here R-4.5.0module load compilers/gcc/15.1.0module load statistics/R/4.5.0# We create an alternative Rprofile file, named here RScriptProfile, that will enable our project renv# Note: The path used here must be an **absolute** path# Please avoid to share this fileecho 'renv::load("'$PWD'")' > RScriptProfile# We set it as default Rprofile file with the environment variable R_PROFILE_USERexport R_PROFILE_USER="$PWD/RScriptProfile"# We go elsewherecd data# We check again if the renv is foundRscript -e 'file.exists(renv::paths$lockfile())'[1] TRUE
# We unset the RScriptProfile file as the default Rprofileunset R_PROFILE_USER