.. _rlang:

R Programming Environment
=========================

Finding a Version
-----------------

A quick search using module avail will return R packages with just about any package containing the letter "r", so we can use a trick to do a more specific search with module spider ...

.. hpc-prompt:: hpcterm >

   module spider -r ^R


.. admonition:: Console: /bin/bash
   :class: terminal-small

   | $ module -r spider ^R

   .. rst-class:: leaders

   * 

   R

   .. rst-class:: leaders

   *

   |  
   | Versions:
   | R/3.2.5
   | R/4.0.3


Creating a Custom Package Library
---------------------------------

The system-installed version(s) of R may not have all of the packages you want to use, or you may need to do your own package development.  R packages can be installed by system administrators to the system R instances, but it might also save some time if you have a location where you can install R packages on your own.

Here, we use R file commands to create a new path in our home directory called ``.rlib`` and a subfolder ``4.0.3``, then add that new location to R's library search paths with the R ``.libPaths(...)`` command.

.. hpc-prompt:: hpcterm >

	module load R/4.0.3
	R

	dir.create('~/.rlib/4.0.3', showWarnings = TRUE, recursive = TRUE)
	.libPaths(new='~/.rlib/4.0.3')

To be sure the location is set, check to see if the new path is listed first in R's list of package locations. The command below should display your new path in at the top of the list …

.. hpc-prompt:: hpcterm >

   .libPaths()

Your output so far should be similar to the sample terminal output below...

.. admonition:: Console: /bin/bash
   :class: terminal-small

	| hpcuser@easley01:~ > module load R/4.0.3
	| hpcuser@easley01:~ > R
	|
	| R version 4.0.3 (2020-10-10) -- "Bunny-Wunnies Freak Out"
	| ...
	| 
	| > dir.create('~/.rlib/4.0.3', showWarnings = TRUE, recursive = TRUE)
	| > .libPaths(new='~/.rlib/4.0.3') 
	| > .libPaths()
	|
	| [1] "/mmfs1/home/hpcuser/.rlib/4.0.3"     
	| [2] "/mmfs1/tools/r-4.0.3/lib64/R/library"


With the new path confirmed, choose and set the package repo location and install whatever you need.  The output should indicate that the specified package files are being written to the location in your home directory.

.. note:: The rule of thumb is to choose sites in terms of geographic proximity. The ``getCRANmirror()`` and ``subset()`` R functions demonstrated below will display a filtered list of US based mirrors. The TX mirrors seemed to work well in our testing on AU HPC.

.. hpc-prompt:: hpcterm >

   subset(getCRANmirrors(), Country=="USA", select = c("Name","City","URL"))
   chooseCRANmirror(ind=105)
   install.packages("data.table")

.. admonition:: Console: /bin/bash: R
   :class: terminal-small

   | > subset(getCRANmirrors(), Country=='USA', select = c('Name','City','URL'))
   |
   | Name        City                                    URL
   | 94  USA (IA) [https]		Ames    https://mirror.las.iastate.edu/CRAN/
   | 95  USA (IN) Bloomington          http://ftp.ussg.iu.edu/CRAN/
   | 104 USA (TN) [https]   Oak Ridge    https://mirrors.nics.utk.edu/cran/
   | 105 USA (TX 1) [https]      Dallas           https://cran.microsoft.com/
   |
   |
   | > chooseCRANmirror(ind=105)
   | > install.packages("data.table")
   |
   | Installing package into ‘/mmfs1/home/hpcuser/.rlib/4.0.3’
   | ...
   | ** package ‘data.table’ successfully unpacked and MD5 sums checked
   | ...
   | gcc -std=gnu99 4.8.5
   | ...
   | ** libs
   | gcc -std=gnu99 -I"/tools/r-4.0.3/lib64/R/include" ... -c assign.c -o assign.o
   | ...
   | ** testing if installed package keeps a record of temporary installation path
   | * DONE (data.table)

Automatically Load Custom Library Paths
---------------------------------------

To ensure that your new package location will get loaded into R when you use it, you can change your shell profile to add the path to your R environment.  To exit R, issue ``q()`` or ``quit()`` from the R prompt.

.. hpc-prompt:: hpcterm >

	> nano ~/.bashrc

.. admonition:: GNU Nano 2.0.6
   :class: terminal-small

   | if [ -n $R_LIBS ]; then
   |	export R_LIBS=~/.rlib/4.0.3:$R_LIBS
   | else
   |	export R_LIBS=~/.rlib/4.0.3
   | fi

   	.. table:: 
		:class: terminal-small

		+-------------+-------------+--------------+--------------+------------+------------+
		| ^G Get Help | ^O WriteOut | ^R Read File | ^Y Prev Page | ^K CutText | ^C Cur Pos |
		+-------------+-------------+--------------+--------------+------------+------------+
		| ^X exit     | ^J Justify  | ^W Where Is  | ^V Next Page | ^U UnCutTx | ^T ToSpell |
		+-------------+-------------+--------------+--------------+------------+------------+

Or, if you need more flexibility, you can specify the location when loading the package in your R code ...

.. hpc-prompt:: hpcterm >

	library('data.table', lib.loc='~/.rlib/4.0.3')

Custom Build Settings
---------------------

Some packages have specific dependencies that need to be accounted for when installing.  Normally, you would specify these in your shell environment, e.g. ``export LIBPATH=/tools/hpclib/mylibrary:$LIBPATH``.  However, R uses its own set of enviromnent variables which can be specified by creating a special file ``~/.R/Makevars`` which will be automatically sourced when R is excecuted.

The example below demonstrates some of the more important variables you might want to set. (We're including the paths for the GDAL and cURL libraries here, but you can set the paths according to your specific package dependencies) ...

.. hpc-prompt:: hpcterm >

	module show gdal
	<note paths>
	
	module show curl
	<note paths>
	
	mkdir ~/.R
	nano ~/.R/Makevars


.. admonition:: GNU Nano 2.0.6
   :class: terminal-small

   | CC=/tools/gcc-4.9.3/bin/gcc -std=c11
   | CXX=/tools/gcc-4.9.3/bin/g++
   | PKG_CONFIG_PATH=/tools/proj-6.3.2/lib/pkgconfig
   | PKG_LIBS = -L/tools/gdal-2.2.1/lib -lgdal
   | R_LD_LIBRARY_PATH = $(R_LD_LIBRARY_PATH):/tools/gdal-2.2.1/lib:/tools/hpclib/curl-7.47.1/lib
   | PKG_CFLAGS += -I/tools/gdal-2.2.1/include -I/tools/hpclib/curl-7.47.1/include
   | PKG_CPPFLAGS += -I/tools/gdal-2.2.1/include -I/tools/hpclib/curl-7.47.1/include
   | PKG_CXXFLAGS += -I/tools/gdal-2.2.1/include -I/tools/hpclib/curl-7.47.1/include
   |

	.. table:: 
		:class: terminal-small

		+-------------+-------------+--------------+--------------+------------+------------+
		| ^G Get Help | ^O WriteOut | ^R Read File | ^Y Prev Page | ^K CutText | ^C Cur Pos |
		+-------------+-------------+--------------+--------------+------------+------------+
		| ^X exit     | ^J Justify  | ^W Where Is  | ^V Next Page | ^U UnCutTx | ^T ToSpell |
		+-------------+-------------+--------------+--------------+------------+------------+