# Best Practices for Managing R Libraries

## R Software Modules

User are advised to utilize these modules when developing workflows on MSI systems

```
15:34:44 [vega0051@ahl03 ~ ]$ ml avail R/*rocky
------------------------------ /common/software/modulefiles/manual/common ------------------------------
R/4.2.0-openblas-rocky8  R/4.2.0-rocky8  R/4.3.0-openblas-rocky8  R/4.4.0-openblas-rocky8  R/4.4.2-openblas-rocky8
```

Workflows that utilize R>=4.4.2 can make use of the newly added [r-rich](./package_docs/pages/r-rich) software module collection. These include many of the dependencies that would otherwise need to be loaded in addition to R.

```
15:34:54 [vega0051@ahl03 ~ ]$ ml avail r-rich
------------------------------ /common/software/modulefiles/bundle/views/common ------------------------------  
r-rich/4.4.2_msi1.2  r-rich/4.6.0_msi1.2
```

## Choosing R Library Installation Locations

When you load an R module on the MSI system, a base set of R libraries will be available to you from the MSI R module. However, you will likely need to install your own R libraries to accomplish your work. By default, MSI R modules will ask your permission to install libraries in your user home directory.

MSI recommends installing your R libraries for a project into a directory within that MSI project space rather than your MSI user home directory for the following reasons:

- Maintaining your R libraries in a directory within a shared project space means that you can share those libraries with other members of your project team if desired.
- You will be able to control your R library versions for that specific project.
- Using your user home directory for R libraries across multiple projects may lead to unintentional software updates and conflicts.
- You have more storage available to you in a project space than in your private user home directory.

Please note that R libraries are specific to the module version you have loaded on an MSI system; the default version of R (what is loaded with `module load R`) can and will change. It is best practice to always specify which version of R you are loading with `module load` so that you can ensure proper version control of your libraries.

## Installing R Libraries

R libraries (also known as packages) can be installed either using command-line R or from within an RStudio interactive job in Open OnDemand (OOD). For challenging library installations, MSI recommends using command-line R rather than RStudio.

For a particular project, you should use the same version of R for your work with command-line R and RStudio. When installing R libraries via command-line R, you should request an interactive compute job first and then install your packages inside the compute job to avoid CPU timeouts.

```{tip}
There are common package install instructions on our [R package reference page](./r_packages/index) with the commond dependencies that need to be loaded for certain packages to successfully install
```


Example steps for installing R libraries via the command line:

1. Request an interactive job. See [Interactive Computing with `srun`](https://msi.umn.edu/about-msi-services/interactive-hpc/interactive-computing-srun) for more details.

   ```bash
   srun -n 10 --mem 16G -t 1:00:00 -p interactive --pty bash
   ```

2. Load the version of R that you will be using for your project.
3. Make a new directory for your R libraries.

   ```bash
   mkdir $SHARED/MyRlibs_$USER
   ```

4. Start R.

   ```bash
   R
   ```

5. From within R, set your `.libPaths()` to your local installation for your project.

   ```r
   .libPaths("$SHARED/MyRlibs_$USER")
   ```

6. Install your package or packages from within R.

   Example 1: CRAN package

   ```r
   install.packages("ggplot2")
   ```

   Example 2: Bioconductor package

   ```r
   install.packages("BiocManager")
   BiocManager::install("GenomicRanges")
   ```

7. Load your library using the `library()` function.

   ```r
   library("ggplot2")
   ```

## Troubleshooting Challenging R Package Installations

Installation of some R packages may require loading system modules. These will need to be loaded when you install your R packages and whenever you want to use your R packages. For interactive [OOD RStudio sessions](https://ondemand.msi.umn.edu/pun/sys/dashboard/batch_connect/sys/bc_msi_rstudio_server/session_contexts/new), you can include module loads in the custom environment option box.

### Common Warning Messages and Issues

You may see a warning, not an error, that a system folder located in `/common/software/` is not writable. This is expected behavior: it means you have not defined a user library you have permission to modify. You can either follow the previous steps to do so, or follow the prompts provided by the warning to automatically create one in a standard location.

Another common warning may appear when attempting to install a package not located on CRAN, the default R package repository indexed by the `install.packages()` function. Even if the message states that the package is unavailable for this version of R, it may simply need to be pulled and installed from a different location. Package documentation should tell you whether packages need to be installed via Bioconductor or directly from a GitHub repository.