Skip to content

Managing R Packages

Standard R Packages

Standard R packages that are available through the CRAN repositories are installed using the install.packages() command from within the R command shell, here <VERSION> represents the R release version:

$ module load R/<VERSION>
$ R
> install.packages("package_name")

As a normal user the default system location will not be writable for you so R will ask if you want to install into a personal library: 

Installing Additional R-Packages
Warning in install.packages("package_name") :
  'lib = "/.../.../.../.../.../R/<VERSION>/lib64/R/library"' is not writable
Would you like to use a personal library instead?
Here /.../.../.../.../.../ represents the system install path for R. Typically this personal library will be a directory in your home directory e.g. ~/R/x86_64-unknown-linux-gnu-library/<VERSION>/

You may see a prompt mentioning which server to download the package from, select a server of your choice and proceed. Once the installation is complete, you may load the newly installed package in your R script or shell using:

> library("package_name")

Package Dependencies

Some R packages in the CRAN repository require no additional dependencies and may be simply installed as above. Many, however, depend on external libraries and may have source code that needs to be compiled. Therefore, you must have loaded the necessary modules to satisfy the requirements of the package -- including at least a compiler (e.g. gnu10 on HOPPER), or have the required dependencies satisfied some other way. An example of an alternative method, would be to have compiled the necessary software in your own home directory and configured your environment so that the R process will be able to access any necessary include files and libraries.

Standard R Packages - Non-standard Locations

To install an R package to a specific location you need to specify the location in the install.packages command:

> install.packages("package_name", lib="/custom/path/to/R-packages/")

To load this package once it has been installed you need to modify the library command to include the location of the package:

> library("package_name", lib.loc="/custom/path/to/R-packages/")

For conveniance you may add a custom library path to the R environment which mitigates the need to specify the library path (like above) each time a library is loaded. This can be done in several ways, here is a good thread on the topic.

Non-standard R Packages

Many users want to install packages that are not in the standard CRAN repos. For example from GitHub, or other locations. There is a libarary available in CRAN called devtools which is able to simplfy the process of install such packages. The devtools module should be available in all ORC R versions. To install a package from GitHub for example you can use the command:

> library("devtools")
> devtools::install_github("<package_identifier>")

Where <package_identifier> will be a string which references the package name in the GitHub repository.

Here too any dependencies will need to be made available to the R environment before installing the package.

Self-contained R Environments

The standard R use of a single per-user location for local package installation creates difficulty if a user wants to use several different versions of a package or possibly conflicting packages. It is possible to craft a configuration using custom package locations and envirnomemnt tweaks, however it is difficult to maintain and fragile. An equivalent to python virtual environments is really what is needed

Fortunately there are R packages that provides such functionality, they are
Renv and Packrat. Renv is a newer package that addresses some of the shortcomings of packrat while retaining the same basic command structure and workfow. The ORC recommends using Renv and it should be available in the installed packages of all R installations on Hopper and Argo. The official Renv documentation can be found here.

Renv Basic Operation

Renv uses a separate "Project" directory for each environment. The user should first create a directory and make that directory their current working directory before running R. For example:

~$ mkdir ~/New_Project
~$ cd ~/New_Project
~/New_Project$ R
R version 
...snipped...
Type 'q()' to quit R.

> library("renv")

Attaching package: ‘renv’
The following object is masked from ‘package:stats’:
    update
The following objects are masked from ‘package:utils’:
    history, upgrade
The following objects are masked from ‘package:base’:
    load, remove
> renv::init()

Welcome to renv!

It looks like this is your first time using renv. This is a one-time message,
briefly describing some of the renv functionality.

renv maintains a local cache of data on the filesystem, located at:

  - '~/.local/share/renv'

This path can be customized: please see the documentation in `?renv::paths`.

renv will also write to files within the active project folder, including:

  - A folder 'renv' in the project directory, and
  - A lockfile called 'renv.lock' in the project directory.

In particular, projects using renv will normally use a private, per-project
R library, in which new packages will be installed. This project library is
isolated from other R libraries on your system.

In addition, renv will update files within your project directory, including:

  - .gitignore
  - .Rbuildignore
  - .Rprofile

Please read the introduction vignette with `vignette("renv")` for more information.
You can browse the package documentation online at https://rstudio.github.io/renv/.
Do you want to proceed? [y/N]: y
* '~/.local/share/renv' has been created.
* Initializing project ...
* Discovering package dependencies ... Done!
* Copying packages into the cache ... Done!
The following package(s) will be updated in the lockfile:

# CRAN ===============================
- renv   [* -> 0.13.2]

* Lockfile written to '~/New_Project/renv.lock'.
* Project '~/New_Project' loaded. [renv 0.13.2]
* renv activated -- please restart the R session.
>
Once renv has been initialized the user may install any packages they desire using install.packages() and, after first installing the devtools packages, any package they wish from GitHub or any other source supported by devtools. Packages will be installed in the project directory under a directory called renv.

renv creates a custom .Rprofile file in the project directory, so that if you launch R in this directory the only packages you will have avalable beyond the core R libraries are those that you have explicitly installed in this environment.

Portability

Renv projects are very portable. Users may clone the .Rprofile,renv.lock files and the renv directory to a new location and create an identical environment in a different location. If the user wants to move the project to a new cluster or computer, renv includes a snapshot method which enables the entire project to be moved to a new system. Please review the documentation (linked above) for more detailed instructions.