Using R Packages

Seamlessly integrate R packages into your interactive Quarto HTML documents

Author

James Joseph Balamuta

Published

September 14, 2023

Modified

April 10, 2024

Whether you need specialized statistical analysis, advanced visualization, or any other R-based functionality, you can harness the rich ecosystem of R packages directly within your documents. By default, quarto-webr avoids loading additional packages. However, you have two ways to incorporate packages into your document: one where packages are installed when the document opens, and the other where packages are installed interactively within specific code cells.

Available R Packages

Before you use any R package with webR, it’s essential to check if it’s available. You can explore the available packages by executing the following R code, either with webR or just R:

Alternatively, you can navigate to the webR binary R repository here for package listings.

Note

webR reports the number of packages available in two ways:

  • Built R packages: This indicates the number of R packages with WebAssembly binaries that can be used within webR, although they may have a decreased number of features available.

  • Available R packages: This number represents feature-complete R packages that have all their dependencies compiled and are fully functional within webR.

To achieve parity with base R, the Available R packages metric serves as an indicator of whether R scripts may require further modification to function properly within webR.

Custom Repositories

If an R package is not available on the main webR repository (note, this is a large shinylive app that should not be open on mobile), fear not! You can compile your own R package to an R WASM Package binary and setup a custom repository to share it.

We have the following guides:

Another approach would be to use r-universe.dev to automatically build and supply R WASM package binaries.

Once done, please make sure to specify where the custom repository is by using the repos key under the webr option in the document header. For example, we can add two custom repositories – one to a GitHub pages hosted repository and another to the r-universe, by using:

---
webr:
  repos:
    - https://username.github.io/reponame
    - https://username.r-universe.dev
---
Note

The {quarto-webr} extension is setup to always check whether an R package is available at the main repository even without it being specified in the repos key.

Install R Packages on Document Open

To automatically install packages when the document opens, add the packages key under webr in the YAML header, listing the packages in an array:

---
webr:
  packages: ['ggplot2', 'dplyr']
---

By using this approach, you ensure that necessary packages are available right from the start when readers access your document. Moreover, the webR code cells will not become active until the packages are installed and loaded. This can be especially helpful when working with packages in multiple cells.

If you do not want the packages to be loaded by default, add the autoload-packages: false under webr in the YAML header. This will disable the calls to load each R package in the packages key, e.g. library(package).

---
webr:
  packages: ['ggplot2', 'dplyr']
  autoload-packages: false
---

Installing an R Package Interactively

If you need to install a package interactively within specific code cells, you can do so using the webr::install() function. This method allows you to install packages on-the-fly when needed.

Note

Please note that not all R packages are immediately available for use with webR due to the presence of compiled code routines. The installation process might also take some time depending on the communication channel being used.

Let’s take ggplot2 as an example:

Using this approach, you can install packages on a per-code cell basis, which can be more efficient when you only need specific packages for certain parts of your document.

Load R Packages Interactively

Once an R package is installed, you can use it just like normal by calling either library() or require() to load the package.

For instance, if you have installed ggplot2 in the prior code cell, then the following will load the ggplot2 and create a scatterplot.

Not a fan of having a code cell dedicated to load packages? You can use the packages key option above to let the quarto-webr extension take care of loading the packages after installing.