index.Rmd

---
title: "<br />Introduction to `renv`"
subtitle: "<br />"
author: <br /><br />Nicolas CASAJUS<br />.inst[Data scientist @ FRB-CESAB]
date: .inst[November 2023]
output:
  xaringan::moon_reader:
    css: ["css/xaringan-themer.css", "css/custom.css"]
    lib_dir: "libs"
    seal: true
    yolo: false
    self_contained: false
    nature:
      ratio: "4:3"
      titleSlideClass: ["right", "middle"]
      highlightStyle: 'zenburn'
      highlightLines: false
      countIncrementalSlides: false
      slideNumberFormat: "%current% / %total%"
      beforeInit: "libs/macros.js"
---



## Degrees of Reproducibility

`r fontawesome::fa_i("thumbs-up", class = "emph")` &nbsp;Research compendium<br/>
`r fontawesome::fa_i("thumbs-up", class = "emph")` &nbsp;Version control<br/>
`r fontawesome::fa_i("thumbs-up", class = "emph")` &nbsp;Literate programming<br/>
`r fontawesome::fa_i("thumbs-up", class = "emph")` &nbsp;Code refactoring

--

<br/>

What about `r fontawesome::fa_i("r-project")` packages (and their versions)?

--

  - 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 `r fontawesome::fa_i("r-project")` packages
- `renv` is the successor of [`packrat`](https://rstudio.github.io/packrat/)
]

--

`renv` makes your project more:

`r fontawesome::fa_i("hand-point-right", class = "emph")` &nbsp;**Isolated**: 
each project has its own library of `r fontawesome::fa_i("r-project")` packages.

`r fontawesome::fa_i("hand-point-right", class = "emph")` &nbsp;**Portable** and **reproducible**: 
`renv` captures the state of your `r fontawesome::fa_i("r-project")` packages 
within a _lockfile_.

--

<br/>

Inspired from `r fontawesome::fa_i("python")` and the `venv` module.

---

## Libraries _vs_ packages

--

`r fontawesome::fa_i("hand-point-right")` &nbsp;`Package` - a 
collection of `r fontawesome::fa_i("r-project")` functions, data, and compiled 
code in a well-defined format. 

`r fontawesome::fa_i("hand-point-right")` &nbsp;`Library` - the 
directory into which packages are installed.


--

<br />

By default, `r fontawesome::fa_i("r-project")` has two (or more) libraries:

```{r eval=FALSE}
.libPaths()
## [1] "C:/Users/Jane/AppData/Local/R/win-library/4.3"
## [2] "C:/Program Files/R/R-4.3.2/library"
```

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

--

<br/>

```{r eval=FALSE}
find.package("rmarkdown")
## [1] "C:/Users/Jane/AppData/Local/R/win-library/4.3/rmarkdown"

find.package("base")
## [1] "C:/PROGRA~1/R/R-43~1.2/library/base"
```

---

## The `r fontawesome::fa_i("r-project")` 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 `r fontawesome::fa_i("r-project")` system
]
.pull-right[
.center[![:scale 95%](img/library-2a.png)]
The `renv` system
]



---

## With `renv` - Global package cache

.pull-left[
.center[![:scale 95%](img/library-1.png)]
The `r fontawesome::fa_i("r-project")` system
]
.pull-right[
.center[![:scale 95%](img/library-2b.png)]
The `renv` system
]


---

## Initialization

- Installation

```{r eval=FALSE}
## Install renv ----
install.packages("renv")
```

<br />

--

- Initialization from command line

```{r eval=FALSE}
## Initiate renv for the project ----
renv::init()
```

--

- Initialization with RStudio

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

---

## Initialization

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

```
R version 4.3.2 (2023-10-31 ucrt) -- "Eye Holes"
Copyright (C) 2023 The R Foundation for Statistical Computing
Platform: x86_64-w64-mingw32/x64 (64-bit)

- Project '~/Documents/myproject' loaded. [renv 1.0.3]
>
```

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
│
├── (myproject.Rproj)
│
├── .Rprofile
│
├── renv/
│   ├── .gitignore
│   ├── activate.R
│   ├── library/
│   └── settings.dcf
│
└── renv.lock
```


---

## Infrastructure

What happened?

```
.
├── (.git)             # Git files
├── (.gitignore)       # Untracked files by git
│
├── (myproject.Rproj)  # RStudio files
│
├── .Rprofile
│
├── renv/
│   ├── .gitignore
│   ├── activate.R
│   ├── library/
│   └── settings.dcf
│
└── renv.lock
```

---

## Infrastructure

What happened?

```
.
├── (.git)             # Git files
├── (.gitignore)       # Untracked files by git
│
├── (myproject.Rproj)  # RStudio files
│
├── .Rprofile          # Activate renv on project opening
│
├── renv/
│   ├── .gitignore
│   ├── activate.R
│   ├── library/
│   └── settings.dcf
│
└── renv.lock
```


---

## 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
```



---

## 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.3.2",
    "Repositories": [
      {
        "Name": "CRAN",
        "URL": "https://packagemanager.posit.co/cran/latest"
      }
    ]
  },
  "Packages": {
    "renv": {
      "Package": "renv",
      "Version": "1.0.3",
      "Source": "Repository",
      "Repository": "CRAN",
      "Hash": "41b847654f567341725473431dd0d5ab"
    }
  }
}
```

This is a simple **JSON** file that specifies metadata on the `r fontawesome::fa_i("r-project")` version and all packages used for the project

--

- With this _lockfile_ you freeze (and document) your `r fontawesome::fa_i("r-project")` environment

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


---

## 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 eval = FALSE}
## 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")
```

--

<br />

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

```{r eval = FALSE}
## 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 eval = FALSE}
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 eval = FALSE}
renv::install("ggplot2")
```



---

## Working with `renv`

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

```{r eval = FALSE}
renv::status()

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

--

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

```{r eval = FALSE}
renv::snapshot()

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

--


```{r eval = FALSE}
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 eval = FALSE}
renv::status()

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

--

<br />

```{r eval = FALSE}
renv::snapshot()

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


---

## Cleaning the local environment

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

```{r eval = FALSE}
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 `r fontawesome::fa_i("github")`)

--


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

```{r eval = FALSE}
renv::restore()

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


`r fontawesome::fa_i("hand-point-right")`&nbsp; If you only share the *lockfile* your collaborator needs to run `renv::init()` before

--

<br />

`r fontawesome::fa_i("exclamation-triangle", class = "emph")` &nbsp; One limit: collaborators need
to have the **same major version** of `r fontawesome::fa_i("r-project")`


---

## Wrap-up

```{r eval=FALSE}
## 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/