Reproducibility with renv

Adrian Zetner

2023-07-04

Sharing R Analyses with Collaborators

• “I tried to run your code but it says I’m missing X” 😟

• “Your code used to run fine but now it’s not working” 😖

• “I upgraded my software and now your code is junk” 💔

  We’ve all been here. Headaches coming from code that we’ve written and are proud of but can’t be used by our colleagues or no longer works for them. The

Reproducibility in Data Driven Analysis

• Crucial for collaboration and transparency in science

• Software and package versions can differ between computers

• Potential code failure or inconsistent results

• Solution: Replicate the environment

- Reproducibility in analysis is crucial for collaboration and transparency in science.

- Even with free and open-source software and clean code, software and package versions can differ between computers.

- Differences in software versions, package versions, and external dependencies can lead to code failure or inconsistent results.

- One solution is to replicate the environment in which the code was developed to ensure compatibility and result consistency.

Replicate the environment ♊

• Manual replication of the environment is impractical

• Potential solutions

  • Virtual environments (Python, Conda, etc)

  • Docker

  • Binder/Jupyter Notebooks

- Manual replication of the environment is impractical, prompting the need for automated solutions.

- Solutions range from ensuring consistent package versions to replicating the entire computer environment.

- Virtual environments to install elements from packages up to system libraries (python, conda, etc)

- Docker containers package applications into portable images to run consistently in almost any environment

- Binder and jupyter make sharing online from github etc easy

Virtual Environments 🌌

• Python virtual environments are folders containing a complete copy of the Python stack used to create them.
• They consist of a separate python executable, the associated stack, and a site-packages folder for installed Python packages.
• Virtual environments ensure full isolation by handling package installations independently.
• They are easy to understand and use but can be heavyweight due to the duplication of the Python stack and packages for each environment.
• Conda is a language-agnostic tool for package management and environment management. As a package manager, Conda can install, update and remove packages. As an environment manager, it can manage virtual environments. It’s robust and broadly applicable but not useable in all contexts

Containers 🎁

• Docker containers are lightweight relative to true virtual machines and create isolated environments that package applications and their dependencies into a standardized unit

• Developing docker containers comes with increased overhead both from complexity in development and deployment along with potential security concerns and performance limitations

• Not exactly what we want to have to focus on when sharing data analysis with colleagues

Notebooks 📑

Note book options

Binder is a free service that creates a virtual computer in the cloud based on the specifications listed in a GitHub repository. In the process of building the environment, Binder also clones the GitHub repository making it painless to reproduce analyses. It is essentially read-only though and while great for sharing analyses it can be slow to load and easy to lose work

Jupyter notebooks integrate code and its output into a single document that combines visualizations, narrative text, mathematical equations, and other rich media. In other words: it’s a single document where you can run code, display the output, and also add explanations, formulas, charts, and make your work more transparent, understandable, repeatable, and shareable. Great for sharing analyses, somewhat limited by software needed to run

These all seem like a lot of work simply to share our projects with other people, enter…

• RStudio, specifically Kevin Ushey, has developed a user-friendly solution called renv to address reproducibility in R projects
• You use `renv` to store information about dependencies with your code
• Other people use `renv` to install the exact same versions of the dependencies before running your code
• A couple glossary terms before getting into it…

R Projects 📂

• Projects are the organizational tool of RStudio, essentially a folder

• Organize all aspects of an analysis (raw data, R scripts, external scripts, outputs, documentation, etc) within a root directory

• Allows for relative pathing amongst all elements

• Allows for simultaneous analyses in different folders and siloing those from each other

Packages 📦

• Extend base R with more functionality

• Called libraries or packages in other languages

• Can require compilation on your machine (source) or pre-compiled as a binary package

Extend base R with more functionality Called libraries or packages in other languages Can require compilation on your machine (source) or pre-compiled as a binary package

Binary packages offer several advantages such as Faster installation, Platform compatibility, Dependency resolution, and greater Security when installed from trusted sites. When binary packages are unavailable (OS differences etc) they must be compiled locally.

Installed from…

Repositories 🏛️

• Source of packages 📦

• Many different available

  • CRAN

  • Bioconductor

  • Posit Public Package Manager

  • R Universe

• A repository is a source of packages.

• The main repository for R packages is CRAN (Comprehensive R Archive Network), which is accessible in almost every R session.

• Other freely available repositories include Bioconductor, Posit (formerly RStudio) Public Package Manager, and R Universe.

• When a package is retrieved from a repository it is installed on your computer to a library

Libraries 📚

• Store packages installed for current R version

• System libraries

  • User

  • Site

  • Default

A library in R is a directory that contains installed packages.

Three system libraries: a user library, a site library, and a default library where base R packages are installed.

Generally, you don’t have to worry about libraries and can install all packages into a system library shared across projects.

Sometimes changes to packages can break functionality in older projects.

With the use of renv, you can employ project libraries, which provide each project with its own separate set of packages.

Project Local Libraries with renv 📚

• Project local dependency management
• Store and restore your project dependencies
• Mimic Packrat
• Little to no change to workflows

• Project local dependency management
• Store and restore your project dependencies
• Mimic Packrat
• Little to no change to workflows

OK, so we have the concepts of projects, packages, libraries, and repositories down now, correct? So the natural extension of that is to individualize dependencies to a single project in order to save and load the state of your project as you wrote it. renv is designed to more robustly mimic much of the functionality of the now defunct packrat package with fewer surprises and better default behaviours. The philosophy behind renv is that your project workflow shouldn’t meaningfully change due to incorporating it into your projects.

Workflow 🔀

1. Initialize a new project local environment with a private R library with renv::init()
2. Work in the project as normal adding packages with install.packages()
3. Save the state of the working project with renv::snapshot() to lock file (renv.lock)
4. Keep working with the option to save state after successful changes (renv::snapshot()) or revert to previous if updates introduce new problems (renv::restore())

The general workflow when working with renv is: 1. Call [renv::init()](../reference/init.html) to initialize a new project-local environment with a private R library
2. Work in the project as normal, installing and removing new R packages as they are needed in the project
3. Call [renv::snapshot()](../reference/snapshot.html) to save the state of the project library to the lockfile (called renv.lock)
4. Keep working with the option to save state after successful changes (renv::snapshot()) or revert to previous if updates introduce new problems (renv::restore())

Initialize ✨

1. Searches R scripts for implicitly included dependencies using dependencies()
   • library("dplyr")
   • dplyr::mutate()
2. Copy discovered packages into the renv global package cache for re-use
3. Missing R package dependencies are installed into the project’s private library
4. Initial lockfile capturing the state of the project’s library is created
5. The project is activated with activate()

What does renv actually do when you call init? The primary steps taken when initializing a new project are:
1. R package dependencies are discovered within the R files used within the project with [dependencies()](dependencies.html)
2. Discovered packages are copied into the renv global package cache, so these packages can be re-used across future projects as necessary
3. Any missing R package dependencies discovered are then installed into the project’s private library
4. A lockfile capturing the state of the project’s library is created with [snapshot()](snapshot.html)
5. The project is activated with [activate()](activate.html) which adds the necessary code to the project’s .Rprofile to use the project’s own library on start up

Initialize - Infrastructure & Files ✨

File	Usage
.Rprofile	Updated to activate renv for new project R sessions
renv.lock	The lockfile
renv/	Folder containing all environment details
renv/activate.R	Activation script run by the project .Rprofile.
renv/library	The private project library
renv/settings.json	Project settings
renv/.gitignore	renv specific gitignore

• Project Rprofile with appended activation scripts
• Lockfile describing the state of your project’s library at some point in time.
• Project subfolder that holds all the the important environment details like: Activation script, project library, settings, and .gitignore
• .Rprofile, renv.lock and renv/activate.R files should be committed to your version control system which is usually done by renv::init(). Changes to settings.json should also be tracked.

renv.lock 🔒

• Version of renv
  
• Version of R
• R repositories active for lockfile
  
• Package records

{
  "R": {
    "Version": "4.2.3",
    "Repositories": [
      {
        "Name": "CRAN",
        "URL": "https://cloud.r-project.org"
      }
    ]
  },
  "Packages": {
    "markdown": {
      "Package": "markdown",
      "Version": "1.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Hash": "4584a57f565dd7987d59dda3a02cfb41"
    },
    "here": {
      "Package": "here",
      "Version": "0.7",
      "Source": "Repository",
      "Repository": "CRAN",
      "Hash": "908d95ccbfd1dd274073ef07a7c93934"
    }
  }
}

renv uses a lockfile to capture the state of your library at some point in time. It is stored as a collection of records, with different records defining:

• The version of renv used when generating the lockfile;
• The version of R used in that project;
• The R repositories that were active when the lockfile was created;
• Package records defining each R package, their version, and their installation source.

Here is an example lockfile, including the packages markdown and here

Cache 🏦

• Global package installation location shared across all projects
• Project specific libraries built from symlinks to cache
• Primary benefits:
  • Speed up renv::restore() and renv::install()
  • Save disk space

One of renv’s primary features is the use of a global package cache, which is shared across all projects using renv. This means that project specific libraries are actually built from symlinks to the user’s cache

The renv package cache provides two primary benefits:

1. Future calls to [renv::restore()](../reference/restore.html) and [renv::install()](../reference/install.html) will become much faster, as renv will be able to find and re-use packages already installed in the cache.
   
2. Because it is not necessary to have duplicate versions of your packages installed in each project, the renv cache should also help you save disk space relative to an approach with project-specific libraries without a global cache.

Cache 🏦

• Install process
  • Installation requested
  • Available? Link, otherwise install.
  • Copy to cache
  • Link back to project
• Location
  • Default to ~/.local/share/renv
  • Multiple locations allowed

The process by which packages enter the cache is roughly as follows:

1. Package installation is requested via e.g. [install.packages()](https://rdrr.io/r/utils/install.packages.html), or [renv::install()](../reference/install.html), or as part of [renv::restore()](../reference/restore.html).
2. If renv is able to find the requested version of the package in the cache, then that package is linked into the project library, and installation is complete.
   
3. Otherwise, the package is downloaded and installed into the project library.
   
4. After installation of the package has successfully completed, the package is then copied into the global package cache, and then linked back into the project library.

Renv defaults to the user’s home .local folder but multiple locations cache locations can be indicated and shared between users. If using a shared cache the time and disk savings can be leveraged across many users

Shims 🔼

Function	Shim
install.packages()	renv::install()
remove.packages()	renv::remove()
update.packages()	renv::update()

To help you take advantage of the package cache, renv places a couple of shims (or aliases) on the search path - Package related functions like install/remove/update from the utils package become renv functions In effect, calling [install.packages()](https://rdrr.io/r/utils/install.packages.html) within an renv project will call [renv::install()](../reference/install.html) instead. This can be useful when installing packages which have already been cached. For example, if you use renv::install("dplyr"), and renv detects that the latest version on CRAN has already been cached, then renv will just install using the copy available in the cache – thereby skipping some of the installation overhead. This can be disabled but is a really lovely convenience feature.

Isolation 🫧

• Require that all packages be distributed with a project
• renv::isolate(): copies all dependencies into the local library
• Vastly increases project folder size
• No reliance on external libraries

• Sometimes one requires that a project can be distributed in a more contained fashion with all packages included in a zip file.
• Renv’s isolate function copies all dependencies in the project library from the cache into the project folder: project can be zipped and shared at the cost of a large increase of folder size

Collaboration - Setup ⚒️

• Create a new project repository and folder
• One user explicitly initializes renv in the version controlled project folder
• Commit all files including renv generated ones
• renv will now bootstrap the project environment on collaborators computers

1. One user (perhaps yourself) should explicitly initialize renv in the project, via [renv::init()](../reference/init.html). This will create the initial renv lockfile, and also write the renv auto-loaders to the project’s .Rprofile and renv/activate.R. These will ensure the right version of renv is downloaded and installed for your collaborators when they start in this project.
2. Share your project sources, alongside the generated lockfile renv.lock. Be sure to also share the generated auto-loaders in .Rprofile and renv/activate.R.
3. When a collaborator first launches in this project, renv should automatically bootstrap itself, thereby downloading and installing the appropriate version of renv into the project library. After this has completed, they can then use [renv::restore()](../reference/restore.html) to restore the project library locally on their machine.

Collaboration - Workflow 🔀

• Ensure all collaborators using the same package version
  • Install and test locally
  • Snapshot project
  • Share lockfile
  • Restore locally
• Lockfile changes can be viewed with renv::history()

While working on a project, you or your collaborators may need to update or install new packages in your project. When this occurs, you’ll also want to ensure your collaborators are then using the same newly-installed packages. In general, the process looks like this: 1. A user installs, or updates, one or more packages in their local project library; 2. That user calls [renv::snapshot()](../reference/snapshot.html) to update the renv.lock lockfile;
3. That user then shares the updated version of renv.lock with their collaborators;
4. Other collaborators then call [renv::restore()](../reference/restore.html) to install the packages specified in the newly-updated lockfile.

A bit of care is required if collaborators wish to update the shared renv.lock lockfile concurrently – in particular, if multiple collaborators are installing new packages and updating their own local copy of the lockfile, then conflicts would need to be sorted out afterwards.

One way to guard against this it to use a version control system, and have all collaborators work off the same branch. This way, if someone needs to update renv.lock in the public repository, all collaborators will see that updated lockfile and will gain access to it next time they pull those changes. Depending on the size of your team, you may want to ensure any changes to renv.lock are communicated so that everyone knows and understands when and why packages have been installed or updated.

Caveats ☠️

• Not a panacea for reproducibility
• Solves one part of the problem
  • Records R and package versions
  • Tools to reinstall above
• Problems
  • Results may depend on other system components
  • Packages may be removed from repositories

It is important to emphasize that renv is not a panacea for reproducibility. Rather, it is a tool that can help make projects reproducible by solving one small part of the problem: it records the version of R + R packages being used in a project, and provides tools for reinstalling the declared versions of those packages in a project. Ultimately, making a project reproducible requires some thoughtfulness from the user: what does it mean for a particular project to be reproducible, and how can renv (and other tools) be used to accomplish that particular goal of reproducibility?

There are a still a number of factors that can affect whether this project could truly be reproducible in the future – for example,

1. The results produced by a particular project might depend on other components of the system it’s being run on – for example, the operating system itself, the versions of system libraries in use, the compiler(s) used to compile R and the R packages used, and so on. Keeping a ‘stable’ machine image is a separate challenge, but Docker is one popular solution. See also [vignette("docker", package = "renv")](../articles/docker.html) for recommendations on how Docker can be used together with renv.

2. The R packages that the project depends on may no longer be available. If your project depends on R packages available on CRAN, it’s possible those packages may be removed in the future – either by request of the package maintainer, or by the maintainers of CRAN itself. This is quite rare, but needs consideration if reproducibility of a project is paramount.

In addition, be aware that package installation may fail if a package was originally installed through a CRAN-available binary, but that binary is no longer available. renv will attempt to install the package from sources in this situation, but attempts to install from source can (and often do) fail due to missing system prerequisites for compilation of a package. The [renv::equip()](../reference/equip.html) function may be useful in these scenarios, especially on Windows: it will download external software commonly used when compiling R packages from sources, and instruct R to use that software during compilation.

A salient example of this is the rmarkdown package, as it relies heavily on the pandoc command line utility. However, because pandoc is not bundled with the rmarkdown package (it is normally provided by RStudio, or installed separately by the user), simply restoring an renv project using rmarkdown may not be sufficient – one also needs to ensure the project is run in a environment with the correct version of pandoc available.

Use Case - Shiny🌟

• Shiny apps utilize site library
• Changes to one app’s dependencies can break others
  • Eg. dplyr update from version 1.0.10 to 1.1.12 replaced summarise() with reframe()
  • Installing new dplyr to system library breaks older apps
• Solution:
  • Initialize renv project in shiny app dir (shared shiny user cache)
  • Restore lockfile to symlink and install all dependencies to app local library
  • Include sourcing of renv/activate.R in app.R
• Now Shiny apps can rely on some shared packages and some unique packages
• Easier addition of more shiny apps without clobbering existing

When to Use renv

• Collaborating on project and sharing results

• Ensure forward compatibility

• Project small enough to not warrant using more intense encapsulation

• Use of more robust encapsulation problematic (eg. Docker on Shiny Server)

Questions?

Use Case - Operational Reports

• Updating dplyr caused a change in the functionality of if_else() where Surveiller relied on the

Hot off the presses.