R Environments

Overview

This manual describes the best practices for working with R environments in your SURF Research Cloud workspace (e.g. RStudio workspaces). Using a project-specific R environment ensures that your work is:

  • reproducible
  • portable across workspaces
  • independent of system-wide package changes

Why use R environments?

R projects often depend on specific package versions. R environments allow you to install exactly the same packages and versions that were used to develop a project, even on a new system such as a SURF Research Cloud workspace with minimal effort.

Without environment management, projects may:

  • break after R or package updates
  • behave differently across machines or workspaces
  • be difficult to reproduce or share

If you would like to learn more about reproducible research workflows, the following workshop by Research Data Management at Utrecht University may be useful:

R Environment Manager on SURF Research Cloud

This repository contains an example project for demonstrating how to work with the R package renv on SURF Research Cloud.

The example provides information on working with the following workspaces:

renv is the recommended tool for reproducible R environments.

Information on how to create a workspace can be found here.

Getting Started

To follow along with this manual, it is recommended to clone the repository mentioned above to your workspace. You can do this by running the following command in your RStudio terminal:

cd <your-folder-name>  

git clone https://github.com/MindTheGap-ERC/StratPal_ms_supp.git # clone the repository

cd StratPal_ms_supp # navigate to the project directory

New to R Environments?

Step 1: Create a Lock File (On Your Local Machine)

Check if your project has an renv.lock file. If you do, move to Step 2.

If not, open your R project in RStudio on your local machine and run the following in the RStudio console tab:

install.packages("renv")  # Install renv if not already installed
renv::init()              # Initialize renv in your project
renv::snapshot()          # Create renv.lock file

This creates an renv.lock file that captures all your project’s package versions.

Step 2: Set Up on Your SURF Research Cloud Workspace

Click on File from the options in the top left corner of RStudio, then click on Open Project and select the example project and the .Rproj file in the project directory you just cloned. This will open the project in RStudio.

For a different project, upload the renv.lock file to your SURF Research Cloud workspace.

Then restore the environment by running the following in your RStudio console:

install.packages("renv")  # Install renv on the workspace
renv::restore()           # Restore packages from renv.lock

This installs the exact same package versions from your local environment.

Start working on your project:

# Your R code here

When you make changes to your dependencies, update the lock file:

renv::snapshot()  # Update renv.lock with new packages

If some packages cannot be installed with renv::restore() or you encounter issues, you can try installing the packages manually by running the following in your RStudio console:

install.packages("package_name")  # Replace with the name of the package that failed to install

After installing the missing package(s), run renv::snapshot() to update the lock file

Already Using R Projects or Package Management?

From an existing R project without renv: Open the project in RStudio, run renv::init(), then renv::snapshot() to capture your current package versions.

From packrat (older tool): Consider migrating to renv. Initialize renv in your existing project, it will detect your packages and create a new lock file.

From another machine with renv.lock: Copy the renv.lock file to your new workspace and run renv::restore() to install the exact same package versions.