Access Your Data as ""

LabKey Server automatically reads your chosen dataset into a data frame called using Input Substitution.

A data frame can be visualized as a list with unique row names and columns of consistent lengths. Columns may also be named and their types may differ. You can see the column names for the frame by calling:


Just like any other data.frame, data in a column of can be referenced by the column’s name, converted to all lowercase and preceded by a $:$<column name>

For example,$pulse; provides all the data in the Pulse column. Learn more about column references below.

Note that the examples in this section frequently include column names. If you are using your own data or a different version of LabKey sample data, you may need to retrieve column names and edit the code examples given. You can use the examples below to

Use Pre-existing R Scripts

To use a pre-existing R script with LabKey data, try the following procedure:

  • Open the R Report Builder:
    • Open the dataset of interest ("Physical Exam" for example).
    • Select > Create R Report.
  • Paste the script into the Source tab.
  • Identify the LabKey data columns that you want to be represented by the script, and load those columns into vectors. The following loads the Systolic Blood Pressure and Diastolic Blood Pressure columns into the vectors x and y:
x <-$diastolicbp;
y <-$systolicbp;

png(filename="${imgout:myscatterplot}", width = 650, height = 480);
main="Scatterplot Example",
xlab="X Axis ",
ylab="Y Axis",
abline(lm(y~x), col="red") # regression line (y~x);
  • Click the Report tab to see the result:

Find Simple Means

Once you have loaded your data, you can perform statistical analyses using the functions/algorithms in R and its associated packages. For example, calculate the mean Pulse for all participants.

a <- mean($pulse, na.rm= TRUE);

Find Means for Each Participant

The following simple script finds the average values of a variety of physiological measurements for each study participant.

# Get means for each participant over multiple visits;

participant_means <- aggregate(, list(ParticipantID =$participantid), mean, na.rm = TRUE);

We use na.rm as an argument to aggregate in order to calculate means even when some values in a column are NA.

Create Functions in R

This script shows an example of how functions can be created and called in LabKey R scripts. Before you can run this script, the Cairo package must be installed on your server. See Install and Set Up R for instructions.

Note that the second line of this script creates a "data" copy of the input file, but removes all participant records that contain an NA entry. NA entries are common in study datasets and can complicate display results.

data= na.omit(;

chart <- function(data)
plot(data$pulse, data$pulse);

filter <- function(value)
sub <- subset(,$participantid == value);
#print("the number of rows for participant id: ")
#print("is : ")

Cairo(file="${imgout:a}", type="png");
layout(matrix(c(1:4), 2, 2, byrow=TRUE));
strand1 <-[,1];
for (i in strand1)
value <- i

Access Data in Another Dataset (Select Rows)

You can use the Rlabkey library's selectRows to specify the data to load into an R data frame, including, or a frame named something else you choose.

For example, if you use the following, you will load some example fictional data from our public demonstration site that will work with the above examples.

library(Rlabkey) <- labkey.selectRows(
folderPath="/Explore/Research Study",

Select Specific Columns

Use the colSelect option with to specify the set of columns you want to add to your dataframe. Make sure there are no spaces between the commas and column names.

In this example, we load some fictional example data, selecting only a few columns of interest.

library(Rlabkey) <- labkey.selectRows(
folderPath="/Explore/Research Study",

Display Lookup Target Columns

If you load the above example, and then execute:$language; you will see all the data in the "Language" column.

Remember that in an R data frame, columns are referenced in all lowercase, regardless of casing in LabKey Server. For consistency in your selectRows call, you can also define the colSelect list in all lowercase, but it is not required.

In this case, it will return a series of integers, because "Language" is a lookup column that references a list in the same container with an incrementing integer primary key.

If you want to access a column that is not the primary key in the lookup target, such as human-readable display values in this example, use syntax like this in your selectRows:

library(Rlabkey) <- labkey.selectRows(
folderPath="/Explore/Research Study",

You can now retrieve human-readable values from within the "Language" list by converting everything to lowercase and substituting an underscore for the slash. Executing$language_languagename; will return the list of language names.

Access URL Parameters and Data Filters

While you are developing your report, you can acquire any URL parameters as well as any filters applied on the Data tab by using labkey.url.params.

For example, if you filter the "systolicBP" column to values over 100, then use:


...your report will include:

[1] "100"

Write Result File to File Repository

The following report, when run, creates a result file in the server's file repository. Note that fileSystemPath is an absolute file path. To get the absolute path, see Using the Files Repository.

fileSystemPath = "/labkey/labkey/MyProject/Subfolder/@files/"
filePath = paste0(fileSystemPath, "test.tsv");
write.table(, file = filePath, append = FALSE, sep = "t", qmethod = "double", col.names=NA);
print(paste0("Success: ", filePath));

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all