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:

Best Practices in Writing Reproducible Code
Or read the chapter on dependency management

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

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:

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

Open a project and upload the renv.lock file to your SURF Research Cloud workspace.

Then restore the environment:

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

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.