R is a statistical programming environment frequently used with to analyze and visualize datasets on LabKey Server. This topic describes how to install and configure R.
Set Up Steps:
Additional Steps for Linux/OSX:
Once an administrator has set up the R environment, your users can create
R Reports.
Install R
- On the R site, choose a CRAN mirror near you.
- Click Download R for the OS you are using (Linux, OSX, or Windows).
- Click the subcategory base.
- Download the installer using the link provided for your platform, for example Download R #.#.# for Windows.
- Install using the downloaded file.
Tips:
- You don’t need to download the “contrib” folder on the Install site. It’s easy to obtain additional R packages individually from within R.
- Details of R installation/admin can be found here.
OS-Specific Instructions: Windows
- Windows. On Windows, install R in a directory whose path does not include a space character. The R FAQ warns to avoid spaces if you are building packages from sources.
OS-Specific Instructions: Linux
There are different distributions of R for different versions of Linux. Find and obtain the correct package for your version here, along with version specific instructions:
This example shows installation of version 4.0 on an
Ubuntu machine. This snippet uses "lsb_release -cs" to access which Ubuntu flavor you run ( one of "jammy", "focal", "bionic", ...):
# update indices
sudo apt update -qq
# install two helper packages we need
sudo apt install --no-install-recommends software-properties-common dirmngr
# add the signing key (by Michael Rutter) for these repos
# To verify key, run gpg --show-keys /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc
# Fingerprint: E298A3A825C0D65DFD57CBB651716619E084DAB9
wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | sudo tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc
# add the R 4.0 repo from CRAN -- adjust 'focal' to 'groovy' or 'bionic' as needed
sudo add-apt-repository "deb https://cloud.r-project.org/bin/linux/ubuntu $(lsb_release -cs)-cran40/"
Additional Notes for Linux
- These instructions install R under /usr/local (with the executable installed at /usr/local/bin/R)
- Support for the X11 device (including png() and jpeg()) is compiled in R by default.
- In order to use the X11, png and jpeg devices, an Xdisplay must be available.
- Continue with this topic until you can test the graphical rendering of jpg() and/or png() in the R View Builder.
- Additional information is below.
Configure LabKey Server to Work with R
Configure Authentication and Permissions
Authentication. If you wish to modify a password-protected LabKey Server database through the
Rlabkey macros, you will need to set up authentication. See:
Create a netrc file.
Permissions. Refer to
Configure Permissions for information on how to adjust the permissions necessary to create and edit R Views. Note that only users who have the "Editor" role (or higher)
plus either one of the developer roles "Platform Developer" or "Trusted Analyst" can create and edit R reports. Learn more here:
Developer Roles.
Batch Mode. Scripts are executed in batch mode, so a new instance of R is started up each time a script is executed. The instance of R is run using the same privileges as the LabKey Server, so care must be taken to ensure that security settings (see above) are set accordingly. Packages must be re-loaded at the start of every script because each script is run in a new instance of R.
Install & Load Additional R Packages
You will likely need additional packages to flesh out functionality that basic install does not include. Additional details on CRAN packages are available
here. Packages only need to be
installed once on your LabKey Server. However, they will need to be
loaded at the start of every script when running in batch mode.
How to Install R PackagesUse the R command line or a script (including a LabKey R script) to install packages. For example, use the following to install two useful packages, "GDD" and "Cairo":
install.packages(c("GDD", "Cairo"), repos="http://cran.r-project.org" )To install knitr:
install.packages('knitr', dependencies=TRUE)You can also use the R GUI (
Packages > Install Packages) to select and install packages.
How to LoadEach package needs to be installed AND loaded. If the installed package is not set up as part of your native R environment (check ‘R_HOME/site-library’), it needs to be loaded every time you start an R session. Typically, when running R from the LabKey interface, you will need to load (but not install) packages at the start of every script because each script is run in a new instance of R.
To load an installed package (e.g., Cairo), call:
Recommended PackagesGDD &/or Cairo: If R runs on a headless Linux server, you will likely need at least one extra graphics package. When LabKey R runs on a headless Linux server, it may not have access to the X11 device drivers (and thus fonts) required by the basic graphics functions jpeg() and png(). Installing the Cairo and/or GDD packages will allow your users to output .jpeg and .png formats without using the jpeg() and png() functions. More details on these packages are provided on the
Determine Available Graphing Functions page.
You can avoid the use of Cairo and/or GDD by installing a display buffer for your headless server (see below for more info).
Lattice: Optional. This package is the commonly used, sophisticated graphing package for R. It is particularly useful for creating
Participant Charts.
Headless Linux Servers Only: Rendering and the X Virtual Frame Buffer
On Linux servers, the png() and jpg() functions use the device drivers provided by the X-windows display system to do rendering. This is a problem on a headless server where there is generally no display running at all. Your users may need to use graphics packages such as GDD or Cairo to replace the png() and jpeg() functions. See
Determine Available Graphing Functions for further details.
If with those packages you are able to see the expected rendering, you can skip this section.
If not, as a workaround, you can install the X Virtual Frame Buffer. This allows applications to connect to an X Windows server that renders to memory rather than a display.
Example instructions for configuring an X Virtual Frame Buffer on Linux are available in this topic:
Configure the Virtual Frame Buffer on Linux.
OSX Only: Fix Hostname Resolution Problems
When a LabKey Server runs on OSX, R views can only resolve hostnames that are stored in the server's host file.
It appears that OSX security policy blocks spawned processes from accessing the name service daemon for the operating system.
You can use one of two work-arounds for this problem:
- Add the hostname (e.g., www.labkey.org) to the hosts file (/etc/hosts). Testing has shown that the spawned process is able to resolve hostnames that are in the host file.
- Use the name "localhost" instead of DNS name in the R script.
Related Topics
