R¶

R is an interpreted computer language for statistical computing and graphics including: linear and generalised linear models, non-linear regression models, time series analysis, classical parametric and non-parametric tests.

For efficiency, procedures written in the C, C++, or Fortran languages may be interfaced within R in addition to the user-visible R functions.

R is available as a module on Apocrita.

R can also be used via Conda, please see this blog post for more information.

For interactive graphical R usage in RStudio, please see our separate documentation for RStudio via Open OnDemand.

Usage¶

To run the default installed version of R, simply load the R module:

$ module load R
Activating R shared library Spack environment, please wait...

Loading R/X.Y.Z
  Loading requirement: spack/x.y.z
[r-libraries-x.y.z] $ R --help

Usage: R [options] [< infile] [> outfile]

For further usage documentation, see the full output of R --help or Rscript --help.

R can be executed through the 'R CMD' interactive interface using R or via the Rscript non-interactive interface. The Rscript binary provides an alternative front end to the legacy R CMD BATCH method to run R commands in a non-interactive shell.

Spack environment¶

[r-libraries-x.y.z] is the name of the Spack environment that has been activated alongside the R module load. This Spack environment contains many of the most common additional libraries (such as HDF5, GDAL, GEOS, PROJ and many more) required to install popular R packages into your personal R library, without the need to load any separate additional modules. See below for a full list of packages and libraries contained in each Spack environment.

R/4.4.1 - [r-libraries-0.22.0.2] (click to expand)

Package	Version
autoconf	2.72
autoconf-archive	2023.02.20
automake	1.16.5
bdftopcf	1.1
berkeley-db	18.1.40
bison	3.8.2
bzip2	1.0.8
c-blosc	1.21.5
ca-certificates-mozilla	2023-05-30
cairo	1.16.0
cmake	3.27.9
curl	8.7.1
diffutils	3.10
elfutils	0.190
expat	2.6.2
fftw	3.3.10
findutils	4.9.0
flex	2.6.3
font-util	1.4.0
fontconfig	2.15.0
fontsproto	2.1.3
freetype	2.13.2
fribidi	1.0.12
gawk	5.3.0
gcc	12.2.0
gcc-runtime	11.4.1
gcc-runtime	12.2.0
gdal	3.8.5
gdbm	1.23
gdk-pixbuf	2.42.10
geos	3.12.1
gettext	0.22.5
git	2.42.0
glib	2.78.3
glibc	2.34
glpk	5.0
gmake	4.4.1
gmp	6.2.1
gobject-introspection	1.78.1
gperf	3.1
gsl	2.7.1
harfbuzz	8.3.0
hdf5	1.14.3
icu4c	67.1
imagemagick	7.1.1-29
inputproto	2.3.2
intltool	0.51.0
jags	4.3.2
json-c	0.16
json-glib	1.6.6
kbproto	1.0.7
krb5	1.20.1
libaec	1.0.6
libbsd	0.12.1
libedit	3.1-20230828
libffi	3.4.6
libfontenc	1.1.8
libgeotiff	1.7.1
libgit2	1.7.2
libidn2	2.3.7
libjpeg-turbo	3.0.0
libmd	1.0.4
libpng	1.6.39
libpthread-stubs	0.5
librsvg	2.56.2
libsigsegv	2.14
libssh2	1.11.0
libtiff	4.5.1
libtool	2.4.7
libunistring	1.2
libx11	1.8.7
libxau	1.0.11
libxcb	1.16
libxcrypt	4.4.35
libxdmcp	1.1.4
libxext	1.3.5
libxfont	1.5.4
libxft	2.3.8
libxml2	2.10.3
libxrender	0.9.11
lz4	1.9.4
m4	1.4.19
meson	1.3.2
mkfontdir	1.0.7
mkfontscale	1.2.3
mpc	1.3.1
mpfr	4.2.1
nasm	2.15.05
ncurses	6.5
netcdf-c	4.9.2
nghttp2	1.57.0
ninja	1.11.1
openblas	0.3.26
openjdk	11.0.20.1_1
openmpi	5.0.3-nogpfs
openssh	9.7p1
openssl	3.3.0
pango	1.50.13
pcre	8.45
pcre2	10.43
perl	5.38.0
perl-clone	0.46
perl-encode-locale	1.05
perl-extutils-config	0.008
perl-extutils-helpers	0.026
perl-extutils-installpaths	0.012
perl-file-listing	6.04
perl-html-parser	3.72
perl-html-tagset	3.20
perl-http-cookies	6.10
perl-http-daemon	6.01
perl-http-date	6.02
perl-http-message	6.44
perl-http-negotiate	6.01
perl-io-html	1.004
perl-libwww-perl	6.68
perl-lwp-mediatypes	6.02
perl-module-build	0.4232
perl-module-build-tiny	0.044
perl-net-http	6.22
perl-test-needs	0.002010
perl-try-tiny	0.31
perl-uri	5.08
perl-www-robotrules	6.02
perl-xml-parser	2.46
pigz	2.8
pixman	0.42.2
pkgconf	2.2.0
proj	9.2.1
py-pip	23.1.2
py-setuptools	69.2.0
py-wheel	0.41.2
python	3.11.7
python-venv	1.0
re2c	2.2
readline	8.2
renderproto	0.11.1
rust	1.78.0
rust-bootstrap	1.78.0
shared-mime-info	1.10
snappy	1.1.10
sqlite	3.43.2
tar	1.34
texinfo	7.0.3
udunits	2.2.28
util-linux-uuid	2.38.1
util-macros	1.19.3
which	2.21
xcb-proto	1.16.0
xextproto	7.3.0
xproto	7.0.31
xtrans	1.5.0
xz	5.4.6
zlib-ng	2.1.6
zstd	1.5.6

Should you find anything is missing from the Spack environment, please raise a ticket with us - we can either look into adding it into a future version of the Spack environment, or give you instructions for using an additional module to provide it.

Example jobs¶

Do not use detectCores() for makeCluster()

detectCores() is not cluster aware and will incorrectly return all cores on a machine even if they are not actually available.

The documentation for R covers this:

"This is not suitable for use directly for ... specifying the number of cores in makeCluster.
First because it may return NA, second because it does not give the number of allowed cores"

We advise specifying the number of cores directly, using the NSLOTS UGE variable:

library(parallel); cluster <- makeCluster(as.integer(Sys.getenv('NSLOTS', '1')))

Serial job¶

Here is an example job running on 2 cores and 4GB total memory:

#!/bin/bash
#$ -cwd
#$ -j y
#$ -pe smp 2
#$ -l h_rt=1:0:0
#$ -l h_vmem=2G

module load R
Rscript myscript.R

Using Rscript within Apocrita jobs

When running R jobs on Apocrita, use Rscript to submit a file containing R commands; R output will be written to the stdout and stderror streams.

Additional R Packages¶

Think twice before using renv!

The renv project manager has become popular, but we strongly advise users to think twice before using it on Apocrita. It aggressively caches existing binaries, but sometimes the cached binaries for personal installs aren't compatible with all environments and can cause issues. We have tested renv fairly extensively a number of times, and there are still quite a few issues that need to be resolved before we would recommend (or support) its use.

If you still choose to use renv on Apocrita despite this, the ITSR team can't really offer any support in doing so. There are details for using alternative locations for your libraries on Apocrita below.

Additional packages can be installed to extend the capabilities of R using the install.packages() command. Personally installed packages are stored in libraries.

Do not use a login node for installing R packages

Installing R packages requires a reasonably large amount of resources as many packages will be compiled from source. Do not use a login node for these installations. Please use an interactive qlogin session.

More detailed information about optimal resources for installing R packages can be found in this blog post, but most users should request a maximum of 8 cores, 2GB RAM per core for 8x2GB=16GB total for 24 hours (you can exit your session earlier if all package installs are complete, but one hour probably won't be enough):

qlogin -pe smp 8 -l h_vmem=2G -l h_rt=24:0:0

Alternatively, you can also run package installation interactively in an RStudio session, or unattended in a job script requesting similar resources.

Personal R libraries¶

By default, personal packages will be installed into:

/data/home/abc123/R/x86_64-pc-linux-gnu-library/<VERSION>

If this doesn't exist the first time you run an install.packages() command, the interactive R shell will offer to create it and ask for confirmation:

Warning in install.packages("<package_name>") :
  'lib = "/opt/R/<VERSION>/lib/R/library"' is not writable
Would you like to use a personal library instead? (yes/No/cancel) yes
Would you like to create a personal library
'/data/home/abc123/R/x86_64-pc-linux-gnu-library/<VERSION>'
to install packages into? (yes/No/cancel) yes

The Rscript non-interactive R command won't offer to create a personal library for you. If you run an R script via the Rscript command and it can't find a writable personal library location, the script will fail. You can overcome this either by installing a simple package in an interactive R shell prior to running the Rscript, or creating a personal library location in advance before submitting any script, e.g.:

mkdir -p ${HOME}/R/x86_64-pc-linux-gnu-library/<VERSION>

To display the list of active libraries, execute:

> .libPaths()
[1] "/data/home/abc123/R/x86_64-pc-linux-gnu-library/<VERSION>"
[2] "/opt/R/<VERSION>/lib/R/library"

Customising personal library location¶

Set your custom library path in each new session or job script

R will always default to /data/home/abc123/R/x86_64-pc-linux-gnu-library/<VERSION> every time it is launched. Make sure you manually set .libPaths() at the start of every job script or R session if you wish to use an alternative personal library location.

You may wish to store your library in an alternative location such as in your Research Group storage space to allow collaboration with others. You may also wish to have multiple personal libraries.

You can change your library location using the .libPaths() command. Note, in this case, the directory you wish to use must already exist:

.libPaths("/custom/path/to/library")

You can check the new path has been set:

> .libPaths()
[1] "/custom/path/to/library"   "/opt/R/4.4.1/lib/R/library"

All subsequent package installations in that session will then be written to this new location.

Displaying loaded packages¶

To display the list of currently loaded packages (including default packages), execute:

> (.packages())
[1] "stats"     "graphics"  "grDevices" "utils"     "datasets"  "methods"
[7] "base"

To display all packages available in the currently loaded libraries, execute:

> .packages(all.available = TRUE)
 [1] "base"       "boot"       "class"      "cluster"    "codetools"
 [6] "compiler"   "datasets"   "foreign"    "graphics"   "grDevices"
...

To install additional R packages, execute:

> install.packages("<package_name>")

Packages which are not included in the R main library will be added to the personal library.

To load an R package, execute:

> library("<package_name>")

To find the location where a package is installed, execute:

> find.package("<package_name>")
[1] "/path/to/package"

R packages with external dependencies¶

Installing an R package will automatically install other R packages on which that package depends. However, R packages often depend on software packages provided outside R, such as C libraries. These packages may be provided by the automatically activated Spack environment as detailed above.

For example, the library gdal is required to build the rgdal R package and the library gmp is required for several numerical R packages. Both are included as part of the Spack environment that is activated automatically when you load an R module.

Very occasionally you may need to load an additional module to fulfil dependencies that are not included in the Spack environment that is automatically loaded with the R module and in RStudio. Please double-check first whether anything you need is included, and if in doubt, raise a ticket with us.

R packages using code in other languages¶

The R Spack environment will provide an appropriate version of the GCC compiler for manual compilation.

R packages which compile code written in other languages, such as C or Fortran, often use a Makevars options file to determine how that code is compiled. When you launch an R shell after loading an Apocrita R module, an appropriate opinionated Makevars file is loaded which has been heavily tested and will provide appropriate compilation flags for the majority of users.

Should you feel you need to change your Makevars arguments, please raise a ticket so we can help you.

Bioinformatics packages for R¶

Bioinformatics packages for R can be installed with the bioconductor script and then loaded like a normal R package. You can install a package using:

if (!require("BiocManager", quietly = TRUE))
  install.packages("BiocManager")
BiocManager::install("<package_name>")

R¶