Introduction to renv

class: right, middle, title-slide

.title[
# Introduction to <code>renv</code>
]
.subtitle[
## 
]
.author[
### Nicolas CASAJUS .inst[nicolas.casajus at fondationbiodiversite.fr]
]
.date[
### .inst[Jeudi 1er décembre 2022]
]

---

## Degrees of Reproducibility

&nbsp;Research compendium 
 &nbsp;Version control 
 &nbsp;Literate programming 
 &nbsp;Code refactoring

What about R packages (and their versions)&nbsp;

- What are the packages versions used for my project?
  - Will my project be usable on other system or in the future?
  - How to deal with projects requiring different versions of a package?

---

## The package `renv`

.pull-leftt[
.center[[![:scale 75%](https://raw.githubusercontent.com/rstudio/renv/master/man/figures/logo.svg)](https://rstudio.github.io/renv/articles/renv.html)]
]

.pull-rightt[
- Developed by [**Kevin Ushey**](https://kevinushey.github.io/), also maintainer of the package [`reticulate`](https://rstudio.github.io/reticulate/)
- [`renv`](https://rstudio.github.io/renv/articles/renv.html) is a toolkit used to manage project-local libraries of packages
- `renv` is the successor of [`packrat`](https://rstudio.github.io/packrat/)
]

`renv` makes your project more:

&nbsp;**Isolated**: 
each project has its own library of packages.

&nbsp;**Portable** and **reproducible**: 
`renv` captures the state of your packages 
within a _lockfile_.

Inspired from and the `venv` module.

---

## Libraries _vs_ packages

&nbsp;`Package` - a 
collection of functions, data, and compiled 
code in a well-defined format.

&nbsp;`Library` - the 
directory into which packages are installed.

By default, has two (or more) libraries:

```r
.libPaths()
## [1] "/Users/nicolascasajus/Library/R/4.1/library"
## [2] "/Library/Frameworks/R.framework/Versions/4.1/Resources/library"
```

The first is the **user** library and the second the **system** library.

```r
find.package("rmarkdown")
## [1] "/Users/nicolascasajus/Library/R/4.1/library/rmarkdown"

find.package("base")
## [1] "/Library/Frameworks/R.framework/Resources/library/base"
```

---

## The system

.center[
![:scale 75%](img/library-1.png)
]

All projects share the same versions of installed packages

---

## With `renv`

.pull-left[
.center[![:scale 95%](img/library-1.png)]
The system
]
.pull-right[
.center[![:scale 95%](img/library-2a.png)]
The `renv` system
]

---

## With `renv` - Global package cache

---

## Initialization

- Installation

```r
## Install renv ----
install.packages("renv")
```

- Initialization from command line

```r
## Initiate renv for the project ----
renv::init()
```

- Initialization with RStudio

.center[![:scale 35%](img/rstudio-renv.png)]

---

## Initialization

When you open the project you will see this welcome message:

```
R version 4.1.2 (2021-11-01) -- "Bird Hippie"
Copyright (C) 2021 The R Foundation for Statistical Computing
Platform: x86_64-apple-darwin17.0 (64-bit)

* Project '~/Desktop/myproject' loaded. [renv 0.14.0]
>
```

This means that the project is currently using the `renv` system

---

## Infrastructure

What happened?

```
.
├── (.git)
├── (.gitignore)
│
├── (myproject.Rproj)
│
├── .Rprofile
│
├── renv
│   ├── .gitignore
│   ├── activate.R
│   ├── library
│   └── settings.dcf
│
└── renv.lock
```

---

## Infrastructure

What happened?

```
.
├── (.git)             # Git files
└── (.gitignore)       # Untracked files by git
```

---

## Infrastructure

What happened?

```
.
├── (.git)             # Git files
├── (.gitignore)       # Untracked files by git
│
└── (myproject.Rproj)  # RStudio files
```

---

## Infrastructure

What happened?

```
.
├── (.git)             # Git files
├── (.gitignore)       # Untracked files by git
│
├── (myproject.Rproj)  # RStudio files
│
└── .Rprofile          # Activate renv on project opening
```

---

## Infrastructure

What happened?

```
.
├── (.git)             # Git files
├── (.gitignore)       # Untracked files by git
│
├── (myproject.Rproj)  # RStudio files
│
├── .Rprofile          # Activate renv on project opening
│
└── renv
    ├── .gitignore     # Ignore large renv files (e.g. packages)
    ├── activate.R     # R script to launch renv
    ├── library        # R packages
    └── settings.dcf   # renv settings
```

---

## Infrastructure

What happened?

```
.
├── (.git)             # Git files
├── (.gitignore)       # Untracked files by git
│
├── (myproject.Rproj)  # RStudio files
│
├── .Rprofile          # Activate renv on project opening
│
├── renv
│   ├── .gitignore     # Ignore large renv files (e.g. packages)
│   ├── activate.R     # R script to launch renv
│   ├── library        # R packages
│   └── settings.dcf   # renv settings
│
└── renv.lock          # Packages metadata - Lockfile
```

---

## The lockfile `renv.lock`

```
{
  "R": {
    "Version": "4.1.2",
    "Repositories": [
      {
        "Name": "CRAN",
        "URL": "https://cloud.r-project.org"
      }
    ]
  },
  "Packages": {
    "renv": {
      "Package": "renv",
      "Version": "0.14.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Hash": "30e5eba91b67f7f4d75d31de14bbfbdc"
    }
  }
}
```

This is a simple **JSON** file that specifies metadata on the version and all packages used for the project

- With this _lockfile_ you freeze (and document) your environment

- To collaborate with others you **only** need to share this file

&nbsp;Reproducibility

---

## Installing packages

To install packages with `renv`, use the function `renv::install()`

You can install the latest version of a package, a specific version of a package,
a package from GitHub, GitLab...

```r
## Install the latest version ----
renv::install("devtools")

## Install a specific version ----
renv::install("devtools@2.3.0")

## Install the development version from GitHub ----
renv::install("r-lib/devtools")
```

If you have a `DESCRIPTION` file you can install all required packages as follow:

```r
## Install (latest versions) of packages listed in DESCRIPTION ----
renv::install()
```

Using `renv::install()` without argument will also screen `R` and `Rmd` files and
install packages mentioned as `library(pkg)`, `require(pkg)`, and `pkg::fun()`

---

## Working with `renv`

- Just work as usual

- Use `renv::status()` to check the status of your `renv` project

```r
renv::status()

## * The project is already synchronized with the lockfile.
## 
## The following package(s) are used in the project, but are not installed:
## 
##   ggplot2
## 
## Consider installing these packages, and then using `renv::snapshot()`
## to record these packages in the lockfile.
```

In this example we use the package `ggplot2` in our code but it is not installed (locally)

- Let's install this package

```r
renv::install("ggplot2")
```

---

## Working with `renv`

- Let's use `renv::status()` again

```r
renv::status()

## The following package(s) are installed but not recorded in the lockfile:
## 
##  ggplot2        [3.3.5]
##  [...]
## 
## Use `renv::snapshot()` to add these packages to your lockfile.
```

- Here we need to update the *lockfile* with `renv::snapshot()`

```r
renv::snapshot()

## The following package(s) will be updated in the lockfile:
## 
## # CRAN ===============================
## - ggplot2        [* -> 3.3.5]
## - ...
##
## Do you want to proceed? [y/N]: y
## 
## * Lockfile written to '~/Desktop/myproject/renv.lock'.
```

```r
renv::status()

## * The project is already synchronized with the lockfile.
```

---

## Cleaning the local environment

- If you no longer use some packages you need to remove them from the *lockfile*

```r
renv::status()

## The following package(s) are no longer used in this project:
## 
##  ggplot2        [3.3.5]
##  [...]
## 
## Use `renv::snapshot()` to remove them from the lockfile.
```

```r
renv::snapshot()

---

## Cleaning the local environment

- You can also remove them from your local library (optional)

```r
renv::clean()

## The following packages are installed in the project library,
## but appear to be no longer used in your project.
## 
## ggplot2
##
## These packages will be removed.
## 
## Do you want to proceed? [y/N]: y
## 
## Removing package 'ggplot2' ... Done!
##
## * Done! Removed 1 package.
## * The project has been cleaned.
```

---

## Collaborating with `renv`

- Just share the updated *lockfile* (with )

- Your collaborator will then run `renv::restore()` to locally install required 
packages (with the same versions as you)

```r
renv::restore()

## The following package(s) will be updated:
## 
## # CRAN ===============================
## - ggplot2        [* -> 3.3.5]
## 
## Do you want to proceed? [y/N]: y
##
## Installing ggplot2 [3.3.5] ...
##   OK [linked cache]
```

- If you only share the *lockfile* your collaborator needs to run `renv::init()` before

&nbsp; One limit: collaborators need
to have the **same major version** of

---

## Wrap-up

```r
## Initiate renv for the project ----
renv::init()

## Install < pkg_name > for the project ----
renv::install("pkg_name")
renv::install("pkg_name@version")
renv::install("github/pkg_name")

## Install packages listed in DESCRIPTION (and/or R and Rmd files) ----
renv::install()

## Check renv status ----
renv::status()

## Update lockfile (save local environment) ----
renv::snapshot()

## Uninstall unused packages ----
renv::clean()

## Restore local environment ----
renv::restore()

## Other functions ----
renv::deactivate()       ## Deactivate local environment
renv::activate()         ## (Re)activate local environment
renv::dependencies()     ## List used packages (R and Rmd files)
renv::history()          ## Browse previous commits (with git)
```

---

## Resources

https://kevinushey-2020-rstudio-conf.netlify.app/slides.html

https://elise.maigne.pages.mia.inra.fr/2021_package_renv/presentation.html

https://rstudio.github.io/renv/articles/renv.html

https://6chaoran.wordpress.com/2020/07/20/introduction-of-renv-package/

https://github.com/rstudio/renv/