General information about creating and using transformation scripts can be found in this topic: Transform Scripts. This topic contains information related to using R as the transformation scripting language.

• Include Other Scripts
• Connect Back to the Server from an R Transform Script
• Debugging an R Transform Script
• Example

Include Other Scripts

If your transform script calls other script files to do its work, the normal way to pull in the source code is using the source statement, for example:

source("C:\lktrunk\build\deploy\files\MyAssayFolderName\@files\Utils.R")

To keep dependent scripts so that they are easily moved to other servers, it is better to keep the script files together in the same directory. Use the built-in substitution token "${srcDirectory}" which the server automatically fills in to be the directory where the called script file (the one identified in the Transform Scripts field) is located, for example:

source("${srcDirectory}/Utils.R");

Connect Back to the Server from an R Transform Script

Sometimes a transform script needs to connect back to the server to do its job. One example is translating lookup display values into key values. The Rlabkey library available on CRAN has the functions needed to connect to, query, and insert or update data in the local LabKey Server where it is running. To give the connection the right security context (that of the current user), the assay framework provides the substitution token ${rLabkeySessionId}. Including this token on a line by itself near the beginning of the transform script eliminates the need to use a config file to hold a username and password for this loopback connection. It will be replaced with two lines that looks like:

labkey.sessionCookieName = "JSESSIONID"
labkey.sessionCookieContents = "TOMCAT_SESSION_ID"

where TOMCAT_SESSION_ID is the actual ID of the user's HTTP session.

Debugging an R Transform Script

You can load an R transform script into the R console/debugger and run the script with debug(<functionname>) commands active. Since the substitution tokens described above ( ${srcDirectory} , ${runInfo}, and ${rLabkeySessionId} ) are necessary to the correct operation of the script, the framework conveniently writes out a version of the script with these substitutions made, into the same subdirectory where the runProperties.tsv file is found. Load this modified version of the script into the R console.

Example Script

Scenario

Suppose you have the following Assay data in a TSV format:

You want a transform script that can flag values greater than 1 and less than 0 as "Out of Range", so that the data enters the database in the form:

sampleTransform.R

The following R transform script accomplishes this and will write to the Message column if it sees out of range values:

library(Rlabkey)

################################################
# Read in the run properties and results data. #
################################################

run.props = labkey.transform.readRunPropertiesFile("${runInfo}");

# save the important run.props as separate variables
# Get the original file uploaded by the user. (Use this if the assay framework fails to convert it to an TSV format.)
# run.data.file = labkey.transform.getRunPropertyValue(run.props, "runDataUploadedFile");
# Get the file produced after the assay framework converts the user uploaded file to TSV format. 
run.data.file = labkey.transform.getRunPropertyValue(run.props, "runDataFile");
# Get the file output by the transform script.
run.output.file = run.props$val3[run.props$name == "runDataFile"];
error.file = labkey.transform.getRunPropertyValue(run.props, "errorsFile");

# read in the results data file content
run.data = read.delim(run.data.file, header=TRUE, sep="\t", stringsAsFactors = FALSE);

#######################
# Transform the data. #
#######################

# Your tranformation code goes here.

# If any Score value is less than 0 or greater than 1, 
# then place "Out of Range" in the Message vector. 
for(i in 1:nrow(run.data))
{
    if (run.data$Score[i] < 0 | run.data$Score[i] > 1) {run.data$Message[i] <- "Out of Range"}
}

###########################################################
# Write the transformed data to the output file location. #
###########################################################

# write the new set of run data out to an output file
write.table(run.data, file=run.output.file, sep="\t", na="", row.names=FALSE, quote=FALSE);

# print the ending time for the transform script
writeLines(paste("nProcessing end time:",Sys.time(),sep=" "));

Setup

Before installing this example, ensure that an R engine is configured on your server.

• Create a new folder of type Assay.
• Download this R script: sampleTransform.R
• Upload the script to the Files Repository of your new folder.
• Select (Admin) > Go To Module > FileContent then drop the sampleTransform.R file into the drag and drop area and it will upload.
• Create an Assay Design named "Score" with the following data fields. You can either enter them yourself or download and import this assay design: Score.xar
• SpecimenId - type Text (String)
• Date - type DateTime
• Score - type Number (Double)
• Message - type Text (String)
• Determine the absolute path to the script in the files repository. You can see it after uploading or by concatenating the <folder-root> with "/@files/sampleTransform.R"
• Add the path to the script to the Transform Scripts field in the Assay Design.
• Import data to the Assay Design. Include values less than 0 or greater than 1 to trigger "Out of Range" values in the Message field. You can use this example data file: R Script Assay Data.tsv
• View the transformed results imported to the database to confirm that the R script is working correctly.

Related Topics

• Transform Scripts
• Rlabkey Package
• Install and Set Up R