Using R Packages

Seamlessly integrate R packages into your interactive Quarto HTML documents

Author

James Joseph Balamuta

Published

September 14, 2023

Modified

July 1, 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, the community quarto-webr extension 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 navigating to the webR binary R repository (link is not mobile friendly) 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.

Alternatively, you can run the following R code, either with webR or just R:

Custom Repositories

If an R package is not available on the main webR repository (link is not mobile friendly), fear not! You can compile your own R package to an R WASM Package binary and setup a custom repository to share it.

The quickest way is to opt into using the r-universe.dev service. This is a free service that allows you to host R packages and binaries not just for webR, but also macOS, Linux, and Windows variants of R.

If you want tighter integration with your development repository, we have the following guides:

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 community {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 either the webr::install() or install.packages() 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.

Important

This Quarto extension is open source software and is not affiliated with Posit, Quarto, or webR. The extension is at best a community effort to simplify the integration of webR inside of Quarto generated documents.