Overview

To do very simple queries on the clinical/phenotype data you can use the LabKey application on the Research Environment desktop. However, in order to do more complex analyses across multiple tables, or query very large tables, it is recommended that you use the provided LabKey APIs.

The LabKey client libraries (APIs) provide secure, auditable, programmatic access to LabKey data and services and allow you to:

• Analyse and visualise data stored in LabKey in a statistical tool such as R or Python

• Perform routine, automated tasks in a programmatic way.

• Query and manipulate data in a repeatable and consistent way.

Currently, LabKey supports working with the following programming languages/environments.

• Rlabkey Package

• Python API

• JavaScript API

• Java API

• Perl API

• SAS Macros

We highly recommend using either the Python LabKey API or the R LabKey API to query the Genomics England clinical/phenotype data.

Configuring access

 You firstly need to provide your credentials to the API so that you can access the data you are allowed.

This only needs to be one once in order to use the API.

These credentials are stored in a file called .netrc (dot net rc), located in your home directory. This file does not exist initially, so you will have to create it. To do this:

• Open the Terminal application from the Research Environment desktop.
• The default directory for a new terminal should be your home directory. 
  • This can be checked by entering pwd in the terminal and hitting return. 
  • The output should be /home/<your-user-name>.
• If you are not in your home directory, you can navigate there by typing cd in the terminal and hitting return. 
  • Then check the directory as above.

Once in your home directory, we will create the .netrc file. You can use any text editor to do this, but this guide we will use nano.

• Open a file called .netrc in nano by typing nano .netrc

This file needs the following three lines in it, where you change the username and password fields to your Research Environment credentials:

machine labkey-embassy.gel.zone
login username
password password

• Once the information is entered, save the file using Ctrl+O then hit return. Exit nano with Ctrl+x

Because the file contains your password, it should be set to read-write only for yourself.

• The file permissions can be checked by entering ls -alh in the terminal. 
  • You should see a line like the following: -rw------- <username> <username> .netrc
• If the permissions are in any other form, e.g. -rw-rw-rw-, they are visible to others and need to be changed.
• This can be done with the following command: chmod 600 .netrc, which will set read-write to you only.

Further configuration

For R and Python you will need to make specific changes to your scripts. Please have a look at the following pages for example scripts and how to set up your own script:

R LabKey API 

Python LabKey API

Note: For the R LabKey API you will also need, as of April 2020, to create or reconfigure the .Renviron file. See R, RStudio, and R libraries#Creatingan.Renvironfile(alsorequiredfortheRLabKeyAPI).

Troubleshooting: Potential errors upon incorrect setup (i.e. DOCTYPE, user permission denied, curl_fetch_memory)

In case the RLabKey API is incorrectly setup, please have a look here:
- LabKey DOCTYPE error

- LabKey curl_fetch_memory error
If this does not resolve the issue, and you still have problems using the R LabKey API, please contact the Service Desk.