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:
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.)
- Load the Rlabkey library at the start of every R script using the following command:
- 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.
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).
For example, you might use an external instance of R to do the following:
- 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.
Within the LabKey interface, the Rlabkey macros are particularly useful for accessing and manipulating datasets across folders and projects.