This topic is under construction for the 17.3 release of LabKey Server. For current documentation of this feature, click here.
Create an R Report
Base an R Report on a Data Grid
R reports are ordinarily associated with individual data grids. Choose the dataset of interest and further filter the grid as needed. Only the portion of the dataset visible within this data grid become part of the analyzed dataset.
To use the sample dataset we describe in this tutorial, please Tutorial: Set Up a New Study
if you have not already done so. Alternately, you may simply add the PhysicalExam.xls
demo dataset to an existing study for completing the tutorial. You may also work with your own dataset, in which case steps and screencaps will differ.
- View the "Physical Exam" dataset in a LabKey study.
- If you want to filter the dataset and thus select a subset or rearrangement of fields, select or create a custom grid view.
- Select > Create R Report.
If you do not see the "Create R Report" menu, check to see that R is installed and configured on your LabKey Server. See Configure Scripting Engines
for more information.
Alternative: Create an R report independent of any grid view
R reports do not necessarily need to be associated with individual data grids. You can also create an R report that is independent of any grid:
- Select (Admin) > Manage Views.
- Select Add Report > R Report.
R reports associated with a grid automatically load the grid data into the object "labkey.data". R reports created independently of grids do not have access to labkey.data objects. R reports that pull data from additional tables (other than the associated grid) must use the Rlabkey API to access the other table(s). For details on using Rlabkey, see Rlabkey Package
. By default, R reports not associated with a grid are listed under the Uncategorized
heading in the list on the Manage Views
Review the R report builder
The R report builder opens on the Source
tab which looks like this:Script Source
Paste an R script for execution or editing into this text box. Notice the options
available below the source entry panel.
When you select the Report
tab, you'll see the resulting graphics and console output for your R report. If the pipeline option is not selected, the script will be run in batch mode on the server.
Select the data tab to see the data on which your R report is based. This can be a helpful resource as you write or refine your script.
When your script is complete and report is satisfactory, return to the Source
tab, scroll down, and click Save
to save both the script and the report you generated.
A saved report will look similar to the results in the design view tab, minus the help text. Reports are saved on the LabKey Server, not on your local file system. They can be accessed through the Reports
drop-down menu on the grid view of you dataset, or directly from the Data Views
The script used to create a saved report becomes available to source() in future scripts. Saved scripts are listed under the “Shared Scripts” section of the LabKey R report builder.
This Syntax Reference
list provides a quick summary of the substitution parameters for LabKey R. See Input/Output Substitutions Reference
for further details.
On the Source Tab
you can expand additional option sections:Options
- Make this report available to all users: Enables other users to see your R report and source() its associated script if they have sufficient permissions. Only those with read privileges to the dataset can see your new report based on it.
- If you choose to share your report, you can also opt to Show source tab to all users but it is not required.
- Make this report available in child folders: Make your report available in data grids in child folders where the schema and table are the same as this data grid.
- Run this report in the background as a pipeline job: Execute your script asynchronously using LabKey’s Pipeline module. If you have a big job, running it on a background thread will allow you to continue interacting with your server during execution.
If you choose the asynchronous option, you can see the status of your R report in the pipeline. Once you save your R report, you will be returned to the original data grid. From the Reports
drop-down menu, select the report you just saved. This will bring up a page that shows the status of all pending pipeline jobs. Once your report finishes processing, you can click on “COMPLETE” next to your job. On the next page you’ll see "Job Status." Click on Data
to see your report.
Note that reports are always generated from live data by re-running their associated scripts. This makes it particularly important to run computationally intensive scripts as pipeline jobs when their associated reports are regenerated often.
- Knitr: select None, HTML, or Markdown processing of HTML source; include semicolon separated list of dependencies if needed.
- Report Thumbnail: Choose to auto-generate a default thumbnail if desired. You can later edit the thumbnail or attach a custom image. See Manage Views.
- Shared Scripts: Once you save a View, its associated script becomes available to execute using source(“<Script Name>.R”) in future scripts. Check the box next to the appropriate script to make it available for execution.
- Study Options: Participant Chart: A participant chart shows measures for only one participant at a time. Select the participant chart checkbox if you would like this chart to be available for review participant-by-participant.
- Study Options: Enable automatic caching of this report for faster reloading.
Regardless of where you have accessed the R report builder, you can create a first R report which is data independent. This sample was adapted from the R help files.
- Paste the following into the Source tab of the R report builder.
# Execute 100 Bernoulli trials;
coin_flip_results = sample(c(0,1), 100, replace = TRUE);
- Click the Report tab to run the source and see your results, in this case the coin flip outcomes.
Note: Echo to Console
By default, most R commands do not generate output to the console as part of your script. To enable output to console, use the following line at the start of your scripts:
Note that when the results of functions are assigned, they are also not printed to the console. To see the output of a function, assign the output to a variable, then just call the variable. For further details, please see the FAQs for LabKey R Reports