Overview

The LabKey client library for R makes it easy for R users to load live data from a LabKey Server into the R environment for analysis, provided users have permissions to read the data. It also enables R users to insert, update, and delete records stored on a LabKey Server, provided they have appropriate permissions to do so. The Rlabkey APIs use HTTP requests to communicate with a LabKey Server.

All requests to the LabKey Server are performed under the user's account profile, with all proper security enforced on the server. User credentials are obtained from a separate location than the running R program so that R programs can be shared without compromising security.

The Rlabkey library can be used from the following locations:

• Within an instance of R external to LabKey
• Within the LabKey R interface.
• By scripts included in LabKey Modules

Documentation

• Rlabkey documentation (pdf)
• Rlabkey Users Guide
• Rlabkey Package Vignette
• Troubleshooting Rlabkey Connections
• For full documentation on using R on the LabKey platform, please see R Reports.
• For instructions on how to export an R script that recreates a LabKey grid view, see Export Data Grid as a Script.

Configuration Steps

Typical configuration steps for a user of Rlabkey include:

• Install R from http://www.r-project.org/
• Install the Rlabkey package once using the following command in the R console. (You may want to change the value of repos depending on your geographical location.)

install.packages("Rlabkey", repos="http://cran.fhcrc.org")

• Load the Rlabkey library at the start of every R script using the following command:

library(Rlabkey)

• Create a .netrc or _netrc file to set up authentication.
• Necessary if you wish to modify a password-protected LabKey Server database through the Rlabkey macros.
• Note that Rlabkey handles sessionid and authentication internally. Rlabkey passes the sessionid as an HTTP header for all API calls coming from that R session. LabKey Server treats this just as it would a valid JSESSIONID parameter or cookie coming from a browser.

Scenarios

The Rlabkey package supports the transfer of data between a LabKey Server and an R session.

• Retrieve data from LabKey into a data frame in R by specifying the query schema information (labkey.selectRows and getRows) or by using SQL commands (labkey.executeSql).
• Update existing data from an R session (labkey.updateRows).
• Insert new data either row by row (labkey.insertRows) or in bulk (labkey.importRows) via the TSV import API.
• Delete data from the LabKey database (labkey.deleteRows).
• Use Interactive R to discover available data via schema objects (labkey.getSchema).

• Connect to a LabKey Server.
• Use metadata queries to show which schemas are available within a specific project or sub-folder.
• Use metadata queries to show which datasets are available within a schema and query of interest in a folder.
• Create colSelect and colFilter parameters for the labkey.selectRows command on the selected schema and query.
• Retrieve a data frame of the data specified by the current url, folder, schema, and query context.
• Perform transformations on this data frame locally in your instance of R.
• Save a data frame derived from the one returned by the LabKey Server back into the LabKey Server.