r: R statistical computing scripting language

Contents

1. Overview of package
   1. General usage
2. Availability of package by cluster
3. System installed R packages, by cluster/R version
4. Installing Modules
5. Running R in batch mode
6. Using R and MPI

Overview of package

General usage information

R is a language and environment for statistical computing and graphics. It is similar to the S language and environment, and can be considered as an open-source implementation of S. There are some important differences, but much code written for S runs unaltered under R.

This module will add the R and Rscript commands to your path.

In case you need to link against this library in your code, the following environmental variables have been defined:

• \$R_ROOT has been set to the root of the r installation
• \$R_LIBDIR points to the directory containing the libraries
• \$R_INCDIR points to the directory containing the header files

You will probably wish to use these by adding the following flags to your compilation command (e.g. to CFLAGS in your Makefile):

• -I\$R_INCDIR

• -L\$R_LIBDIR -Wl,-rpath,\$R_LIBDIR

Available versions of the package r, by cluster

This section lists the available versions of the package ron the different clusters.

Available versions of r on the Zaratab cluster

System installed R packages/modules

The system installations of R include a large number of R modules to enhance the capability of R. The table below list those modules and version numbers for the various installations of R which are made available with the "module load r" or similar commands.

Packages/modules for R

Installing Modules

R's capabilities can be significantly enhanced through the addition of modules. Code can then enable the library with the library command. The supported R interpretters on the system have a selection of modules preinstalled. If a module you are interested in is not in that list, you can either install a personal copy of the module for yourself, or request that it be installed system wide. We will make reasonable efforts to accomodate such requests as staffing resources allow.

Installing modules yourself

Installing your own R modules with R CMD INSTALL

The recommended method for installing your own R packages is with the R CMD INSTALL command or similar. This method for installing R packages is usually fairly straightforward, and generally allows for you to install your own packages while still availing yourself of system installed packages. Obviously not all packages will install i n the same manner. But most will follow the procedure below:

1. module load R/X.Y.Z to select the version of R you wish to use
2. Create the directory to hold your R modules, if you have not already done so. The default is in the directory R underneath your home directory, but you might wish to put it elsewhere; this will have subdirectories for R version and platform added.
3. Unless you opted for the default directory ~/R, you need to tell R what directory you are using. To do this, you must set the environmental variable R_LIBS_USER. Multiple directories can be listed; separate the paths with the colon (:) character. This needs to be set whenever you wish to use the modules in R, so you will generally want to set it in your .cshrc.mine or .Renviron files.
4. There are two standard methods for installing a package, one from the command line, and one from inside R itself. Assuming you are putting stuff in ~/myRpkgs and installing the package foo the commands would be:
   • From the command line, you will first need to download a tarball with the source code for the package. Many packages can be found at the Comprehensive R Archive Network (CRAN). Assuming you downloaded foo.tar.gz to the current directory, you could then install it with:

     R CMD INSTALL -l ~/myRpkgs foo.tar.gz

   • From within R, the install.packages function will connect to CRAN and download and install the package all in one step, with:

     install.packages("foo", lib="~/myRpkgs", repos="http://cran.r-project.org")

If all goes well, the package is now installed in the directory you specified and should be available for use by your R scripts.

Of course, not all packages install quite that easily. If you are comfortable building modules, hopefully the error messages will provide reasonable guidance as to how to proceed. Otherwise, you can just request for Division of Information Technology staff to install it, but that might take time depending on the availability of our time.

Installing your own R modules with conda

NOTE: We generally recommend that you try installing your own R packages using the previously mentioned method (R CMD INSTALL) setup.py rather than using conda as that integrates better with the system installed R packages.

Conda is another option for installing python and R packages, but it does even more separation and isolation than the venv method. This can either be an advantage or a liability depending on the use case. This isolation means that you are not constrained but what system staff have installed on the cluster, but it also means it is very difficult if not impossible to take advantage of any packages system staff have installed on the cluster. Also, since you are relying on an entire environment which you installed, the ability of HPC staff to provide assistance should there be issues is limited. Therefore, we encourage users to try one of the other methods if such is feasible.

NOTE:The Anaconda distribution of Python and R is restrictively licensed. The Anaconda company states that the use of Anaconda's offerings at an organization of more than 200 employees requires a Business or Enterprise license. As the Univesity of Maryland does not have such a license, the use of the anaconda distribution or its repositories at UMD (outside of use in a formally scheduled curriculum based course) is not free and is not allowed. See e.g. the Anaconda blog for more information regarding Anaconda licensing.

Due to the license restrictions above, we encourage users to use the miniforge/mambaforge installer which pulls packages from the conda-forge repository, which is not covered by the restrictive Anaconda license and is free to use. (You still may need to check for any This provides similar functionality to miniconda without the license restrictions.

Miniconda is a subset of Anaconda, without some extras like Anaconda Navigator, etc. By default, it pulls packages from the default Anaconda repositories, which requires licensing from Anaconda. The actual conda program which installs packages is free to use, but only if you are downloading packages from repositories which are free to use. If you insist on using miniconda, please be sure to remove the default channel (as well as any subchannels of the default channel) as these are restrictively licensed and require licesnses, and replace it with conda-forge channel, e.g.

conda config --show channels
conda config --remove channels defaults
# You might also need to remove subchannels like ananconda, main, r, pro, etc

conda config --add channels conda-forge

But we encourage you to use miniforge/mambaforge instead.

To install python packages using conda, you should usually follow a process like outlined below:

1. If you have not already done so, install a copy of mambaforge/miniforge or similar, as follows:
   1. Choose a location for your conda environments. Because conda environments potentially can get quite large, a subdirectory of your scratch directory is usually best. E.g. ~/scratch/condaroot. Create that directory if it does not already exist.
   2. Download Mambaforge from https://conda-forge.org/miniforge into your condaroot directory.
   3. Make a copy of your initialization dot files, e.g. cp ~/.bashrc ~/.bashrc.HOLD. You might wish to do similar for .cshrc and other init dot files if they exist.
   4. Install miniforge/mambaforge, cd ~/scratch/condaroot; bash Mambaforge-X.Y.Z-A-Linux-s86_64.sh -p mambaforge-X.Y.z This will install mambaforge to the mabaforge-X.Y.Z subdirectory of the directory you ran the script from (~/scratch/condaroot). The script will ask some questions, ansering yes to all should generally work.
   5. The script will have updated your ~/.bashrc and possibly some other dot files. Although you can leave things like that, in which case conda will be initialized in every shell whether it needs it or not (and potentially causing delays in shell startup), we recommend that you copy the modifications made to the initialization scripts to a conda specific script (e.g. cp ~/.bashrc ~/bashrc.conda; cp ~/.bashrc.HOLD ~/.bashrc and edit the new ~/bashrc.conda to remove the lines before the # >>> conda initialize >>> line. You can then source this file whenever you wish to use conda.
2. Initialize conda if needed. If you followed the instructions to remove the conda initialization from your initialization dot files, you should initialize conda with something like source ~/bashrc.conda.
3. If you do not already have a conda environment you are working in, create one. You should generally have a separate environment for each project and/or major software package you intend to use. To create an environment, do something like: cd ~/scratch/condaroot; conda create -n myenv This will create a conda environment myenv; we recommend you choose a more meaningful name.
4. Activate your conda environment. E.g. conda activate myenv, replacing myenv with the name of the environment to activate.
5. If this is a new miniforge environment, you will need to install R. Do conda install r.
6. Install your R packages. The exact procedure may vary a bit depending on the package, but usually it is something like conda install PACKAGE_NAME where PACKAGE_NAME is the name of the package, usually starting with "r-"

Assorted Tips and Tricks

Matplotlib Tricks

• Using matplotlib in batch jobs/without an X server: By default, the matplotlib package in Python expects to work with a graphical user interface (GUI), which on Unix-like systems means an X server running. This can be problematic if one wishes to use matplotlib in batch jobs (e.g. on an HPC cluster) because typically a display will not be available. The easiest way to do this is to specify a non-interactive backend. There are several ways to do this, but since you probably want to continue using an interactive backend when using python interactively, the best approach is to have your batch code select a non-interactive backend. A common choice for such is Agg (for Anti-Grain Geometry engine) which can produce PNG files, Cairo and Gdk are other options. Use would be something like:

          import matplotlib
          # This needs to be done *before* importing pyplot or pylab
          matplotlib.use('Agg')
          import matplotlib.pyplot as plt
  
          #Do your plotting, e.g.
          fig = plt.figure()
          ax = fig.add_subplot(111)
          ax.plot(range(10))
          fig.savefig('test.png')

  For more information, see: Matplotlib Documentation on running without a GUI

Running R in batch mode

Although R's interactive mode is nice for certain things, when you are doing production runs with tried and true scripts, it is usually easier to use R's batch interface. This is especially useful when submitting jobs to an HPC cluster.

If you have some R code in a file test.R and you wish to run it from the command line (or equivalently, from a shell script), you can simply use the Rscript command. E.g.

Rscript --no-save --no-restore test.R

The --no-save and --no-restore prevent the saving of the workspace at the end of the session and the restoring of saved objects at startup. These are typically what you want when running in batch mode. Older versions of R used the R CMD BATCH instead of the Rscript command; the main difference with the former is that it optionally takes the name of an output file. Both should work with currently installed versions of R.

For use on one of the HPC clusters, you will generally need to include the above in a job script, like:

#!/bin/bash
#Request 5 hours
#SBATCH -t 5:00
#Request 4 GiB per CPU-core
#SBATCH --mem-per-cpu=4096
#Request 1 core
#SBATCH -n 1

#Get our profile (and define module command)
. ~/.profile

#Load required modules
module load R/3.3.2

cd MY_WORK_DIRECTORY

#Make sure OpenMP is not "on"
OMP_NUM_THREADS=1
export OMP_NUM_THREADS

Rscript --no-save --no-restore my_R_code.R

Using R and MPI

User of one of the high-performance computing (HPC) clusters will likely be interested in running R codes that span multiple processors often over multiple nodes. This generally is done using MPI. There are a number of R packages that deal with MPI, including

• Rmpi
• snow
• doSNOW: provides a dopar functionality via snow

Most users seem to prefer the snow package, which is presumably higher level and therefore easier to use than Rmpi. There are assorted guides to using R with the snow package on the web, including:

• Glenn Lockwoods page on R and HPC clusters
• University of Chicago's R page
• Harvard's Rmpi page
• Bioinfomagician's page on Rmpi
• Simon Fraser University's snow page

Below are just a few tips gleaned from these pages, etc. that users at UMD might find helpful.

1. For best results, use the same version of compiler and MPI as used for building R and its MPI packages. The MPI libraries and compiler used for the different versions of R are listed in the version table at the top of this page. It is best to module load the compiler first (not needed for gcc/4.6.1) and then the OpenMPI library.
2. We have also had reports of wierd errors occurring when using Rmpi (and the packages depending on it) with Infiniband; segfaults and other seemingly random errors when setting up connections. This appears to be related to complications with the used of pinned memory and forking within the R interpretter (see e.g. CRMDA blog and OpenMPI developers mailing list archives regarding this issue). As such, we strongly recommend R users who wish to use MPI disable Infiniband in their mpirun command by adding the arguments --mca btl tcp,self as shown in the example below.
3. When using snow or one of its derivatives (e.g. doSNOW), you should launch your code with something like

   #!/bin/bash
   #Request 5 hours
   #SBATCH -t 5:00
   #Request 4 GiB per CPU-core
   #SBATCH --mem-per-cpu=4096
   #Request 40 cores
   #SBATCH -n 40
   
   #Get our profile (and define module command)
   . ~/.profile
   
   #Load required modules
   module load gcc/4.9.3
   module load openmpi/1.8.6
   module load R/3.3.2
   
   cd MY_WORK_DIRECTORY
   
   #Make sure OpenMP is not "on"
   OMP_NUM_THREADS=1
   export OMP_NUM_THREADS
   
   #NOTE THE -np 1 below!!!!
   #The --mca btl tcp,self arguments restricts communications to
   #tcp instead of infiniband.  We have seen issues with Rmpi and infiniband
   mpirun -np 1 --mca btl tcp,self R CMD BATCH --no-save --no-restore my_R_code.R
   

   NOTE the use of -np 1 in the above. Although that looks suspicious (telling mpirun to only start one MPI tasks when we asked for 40 cores), it is actually correct for most uses of the snow (and derivative) libraries. This is because when using snow, typically snow will spawn its own workers. If you request something more than 1 MPI task to be launched via the openmpi, or omit the -np 1 altogether (which effectively is asking for mpirun to launch the number of tasks given in the #SBATCH -n line, 40 in this case), you will end up running e.g. 40 copies of the same code, each of which will try to spawn about 40 workers via snow, resulting in a mess (at best very sluggish performance, and more likely wierd errors).

4. Most snow based R code will at some point invoke the makeCluster function. This takes a parameter specifying the size of the "cluster" to create. Typically, one wants this size to be one less than the number of cores requested from Slurm. This is because the process running the R code which spawns the workers is already consuming one CPU core, so if you try to spawn a number of workers equal to the number of cores requested of Slurm, there will be one core oversubscribed, which causes issues. I typically see an error about there being an insufficient number of "slots" available, and typically the R script just hangs (doing nothing, but not dying until the job is killed for exceeding its walltime, and thereby wasting a lot of SUs). Typically, it is better to do something like:

   cl<-makeCluster(mpi.universe.size()-1, type="MPI")