Input/Output Substitutions Reference: /Documentation/Archive/23.7

Input/Output Substitutions Reference

An R script uses input substitution parameters to generate the names of input files and to import data from a chosen data grid. It then uses output substitution parameters to either directly place image/data files in your report or to include download links to these files. Substitutions take the form of: ${param} where 'param' is the substitution.

Input and Output Substitution Parameters
Implicit Variables
Cairo or GDD Packages
Deprecated LabKey-specific Syntax

You can find the substitution syntax directly in the R Report Builder on the Help tab.

Input and Output Substitution Parameters

Valid Substitutions:
input_data: <name>	The input datset, a tab-delimited table. LabKey Server automatically reads your input dataset (a tab-delimited table) into the data frame called labkey.data. If you desire tighter control over the method of data upload, you can perform the data table upload yourself. The 'input data:' prefix indicates that the data file for the grid and the <name> substitution can be set to any non-empty value: # ${labkey.data:inputTsv} labkey.data <- read.table("inputTsv", header=TRUE, sep="\t"); labkey.data
imgout: <name>	An image output file (such as jpg, png, etc.) that will be displayed as a Section of a View on LabKey Server. The 'imgout:' prefix indicates that the output file is an image and the <name> substitution identifies the unique image produced after you call dev.off(). The following script displays a .png image in a View: # ${imgout:labkey1.png} png(filename="labkeyl_png") plot(c(rep(25,100), 26:75), c(1:100, rep(1, 50)), ylab= "L", xlab="LabKey", xlim= c(0, 100), ylim=c(0, 100), main="LabKey in R") dev.off()
tsvout: <name>	A TSV text file that is displayed on LabKey Server as a section within a report. No downloadable file is created. For example: # ${tsvout:tsvfile} write.table(labkey.data, file = "tsvfile", sep = "\t", qmethod = "double", col.names="NA")
txtout: <name>	A text file that is displayed on LabKey Server as a section within a report. No downloadable file is created. For example: # ${txtout:tsvfile} write.csv(labkey.data, file = "csvfile")
pdfout: <name>	A PDF output file that can be downloaded from LabKey Server. The 'pdfout:' prefix indicates that he expected output is a pdf file. The <name> substitution identifies the unique file produced after you call dev.off(). # ${pdfout:labkey1.pdf} pdf(file="labkeyl_pdf") plot(c(rep(25,100), 26:75), c(1:100, rep(1, 50)), ylab= "L", xlab="LabKey", xlim= c(0, 100), ylim=c(0, 100), main="LabKey in R") dev.off()
psout: <name>	A postscript output file that can be downloaded from LabKey Server. The 'psout:' prefix indicates that the expected output is a postscript file. The <name> substitution identifies the unique file produced after you call dev.off(). # ${psout:labkeyl.eps} postscript(file="labkeyl.eps", horizontal=FALSE, onefile=FALSE) plot(c(rep(25,100), 26:75), c(1:100, rep(1, 50)), ylab= "L", xlab="LabKey", xlim= c(0, 100), ylim=c(0, 100), main="LabKey in R") dev.off()
fileout: <name>	A file output that can be downloaded from LabKey Server, and may be of any file type. For example, use fileout in the place of tsvout to allow users to download a TSV instead of seeing it within the page: # ${fileout:tsvfile} write.table(labkey.data, file = "tsvfile", sep = "\t", qmethod = "double", col.names=NA)
htmlout: <name>	A text file that is displayed on LabKey Server as a section within a View. The output is different from the txtout: replacement in that no html escaping is done. This is useful when you have a report that produces html output. No downloadable file is created: txt <- paste("<i>Click on the link to visit LabKey:</i> <a target='blank' href='http://www.labkey.org'>LabKey</a>") # ${htmlout:output} write(txt, file="output")
svgout: <name>	An svg file that is displayed on LabKey Server as a section within a View. htmlout can be used to render svg outputs as well, however, using svgout will generate a more appropriate thumbnail image for the report. No downloadable file is created: # ${svgout:output.svg} svg("output.svg", width= 4, height=3) plot(x=1:10,y=(1:10)^2, type='b') dev.off()

Implicit Variables

Each R script contains implicit variables that are inserted before your source script. Implicit variables are R data types and may contain information that can be used by the source script.

Implicit variables:
labkey.data	The data frame into which the input dataset is automatically read. The code to generate the data frame is: # ${input_data:inputFileTsv} labkey.data <- read.table("inputFileTsv", header=TRUE, sep="\t", quote="", comment.char="") Learn more in R Reports: Access LabKey Data.
labkey.url.path	The path portion of the current URL which omits the base context path, action and URL parameters. The path portion of the URL: http://localhost:8080/labkey/home/test/study-begin.view would be: /home/test/
labkey.url.base	The base portion of the current URL. The base portion of the URL: http://localhost:8080/labkey/home/test/study-begin.view would be: http://localhost:8080/labkey/
labkey.url.params	The list of parameters on the current URL and in any data filters that have been applied. The parameters are represented as a list of key / value pairs.
labkey.user.email	The email address of the current user

Using Regular Expressions with Replacement Token Names

Sometimes it can be useful to have flexibility when binding token names to replacement parameters. This can be the case when a script generates file artifacts but does not know the file names in advance. Using the syntax: regex() in the place of a token name (where LabKey server controls the token name to file mapping) will result the following actions:

Any script generated files not mapped to a replacement will be evaluated against the file's name using the regex.
If a file matches the regex, it will be assigned to the replacement and rendered accordingly.

<replacement>:regex(<expression>)	The following example will find all files generated by the script with the extension : '.gct'. If any are found they will be assigned and rendered to the replacement parameter (in this case as a download link).// #${fileout:regex(.*?(\.gct))}

Cairo or GDD Packages

You may need to use the Cairo or GDD graphics packages in the place of jpeg() and png() if your LabKey Server runs on a "headless" Unix server. You will need to make sure that the appropriate package is installed in R and loaded by your script before calling either of these functions.

GDD() and Cairo() Examples. If you are using GDD or Cairo, you might use the following scripts instead:

library(Cairo);
Cairo(file="${imgout:labkeyl_cairo.png}", type="png");
plot(c(rep(25,100), 26:75), c(1:100, rep(1, 50)), ylab= "L", xlab="LabKey",
  xlim= c(0, 100), ylim=c(0, 100), main="LabKey in R");
dev.off();

library(GDD);
GDD(file="${imgout:labkeyl_gdd.jpg}", type="jpeg");
plot(c(rep(25,100), 26:75), c(1:100, rep(1, 50)), ylab= "L", xlab="LabKey", 
  xlim= c(0, 100), ylim=c(0, 100), main="LabKey in R");
dev.off();

Deprecated LabKey-specific Syntax

Prior to release 18.1, file substitutions used a LabKey-specific syntax. The use of standard R syntax expected by RStudio as described above means the following syntax is deprecated and should be updated. You can also find this syntax within the R Report UI by selecting the Help tab, then Inline Syntax (Deprecated).

(Deprecated) Valid Substitutions:
input_data	LabKey Server automatically reads your input dataset (a tab-delimited table) into the data frame called labkey.data. For tighter control over the method of data upload, or to modify the parameters of the read.table function, you can perform the data table upload yourself: labkey.data <- read.table("${input_data}", header=TRUE); labkey.data;
imgout: <name>	An image output file (such as jpg, png, etc.) that will be displayed as a Section of a report on LabKey Server. The 'imgout:' prefix indicates that the output file is an image and the <name> substitution identifies the unique image produced after you call dev.off(). The following script displays a .png image in a report: png(filename="${imgout:labkeyl_png}"); plot(c(rep(25,100), 26:75), c(1:100, rep(1, 50)), ylab= "L", xlab="LabKey", xlim= c(0, 100), ylim=c(0, 100), main="LabKey in R"); dev.off();
tsvout: <name>	A TSV text file that is displayed on LabKey Server as a section within a report. No downloadable file is created. For example: write.table(labkey.data, file = "${tsvout:tsvfile}", sep = "\t", qmethod = "double");
txtout: <name>	A text file that is displayed on LabKey Server as a section within a report. No downloadable file is created. A CSV example: write.csv(labkey.data, file = "${txtout:csvfile}");
pdfout: <name>	A PDF output file that can be downloaded from LabKey Server. pdf(file="${pdfout:labkeyl_pdf}"); plot(c(rep(25,100), 26:75), c(1:100, rep(1, 50)), ylab= "L", xlab="LabKey", xlim= c(0, 100), ylim=c(0, 100), main="LabKey in R"); dev.off();
psout: <name>	A postscript output file that can be downloaded from LabKey Server. postscript(file="${psout:labkeyl_eps}", horizontal=FALSE, onefile=FALSE); plot(c(rep(25,100), 26:75), c(1:100, rep(1, 50)), ylab= "L", xlab="LabKey", xlim= c(0, 100), ylim=c(0, 100), main="LabKey in R"); dev.off();
fileout: <name>	A file output that can be downloaded from LabKey Server, and may be of any file type. For example, use fileout in the place of tsvout to allow users to download a TSV instead of seeing it within the page: write.table(labkey.data, file = "${fileout:tsvfile}", sep = "\t", qmethod = "double", col.names=NA);
	Another example shows how to send the output of the console to a file: options(echo=TRUE); sink(file = "${fileout:consoleoutput.txt}"); labkey.data;
htmlout: <name>	A text file that is displayed on LabKey Server as a section within a report. The output is different from the txtout: replacement in that no html escaping is done. This is useful when you have a report that produces html output. No downloadable file is created: txt <- paste("<i>Click on the link to visit LabKey:</i> <a target='blank' href='http://www.labkey.org'>LabKey</a>") write(txt, file="${htmlout:output}");
svgout: <name>	An svg file that is displayed on LabKey Server as a section within a report. htmlout can be used to render svg outputs as well, however, using svgout will generate a more appropriate thumbnail image for the report. No downloadable file is created: svg("${svgout:svg}", width= 4, height=3) plot(x=1:10,y=(1:10)^2, type='b') dev.off()

(Deprecated) Implicit Variables:
labkey.data	The data frame which the input dataset is automatically read into. The code to generate the data frame is: labkey.data <- read.table("${input_data}", header=TRUE, sep="\t", quote="", comment.char="")

Additional Reference

Documentation and tutorials about the R language can be found at the R Project website
Rlabkey package documentation: Data exchange between R and LabKey Server

LabKey Support

LabKey Support