This topic covers the configuration of scripting engines.
Some ways to use scripting engines on LabKey Server.
- R, Java, Perl, or Python scripts can perform data validation or transformation during assay data upload (see: Transformation Scripts).
- R scripts can provide advanced data analysis and visualizations for any type of data grid displayed on LabKey Server. For information on using R, see: R Reports. For information on configuring R beyond the instructions below, see: Install and Set Up R.
- R, Python, Perl, SAS, and others can be used invoked as part of a data processing pipeline job. For details see Script Pipeline: Running Scripts in Sequence.
Add an R Scripting Engine
- Select (Admin) > Site > Admin Console.
- Click the Settings tab.
- Under Configuration, click Views and Scripting.
- Select Add > New R Engine from the drop-down menu.
- If an engine has already been added and needs to be edited, double-click the engine, or select it and then click Edit.
- Fill in the fields necessary to configure the scripting engine in the popup dialog box, for example:
- Enter the configuration information in the popup. See below for field details.
- Click Submit to save your changes and add the new engine.
- Click Done when finished adding scripting engines.
R configuration fields:
- Name: Choose a name for this engine, which will appear on the list.
- Language: Choose the language of the engine. Example: "R".
- File extensions: These extensions will be associated with this scripting engine. Example: For R, choose "R,r" to associate the R engine with both uppercase (.R) and lowercase (.r) extensions.
- Program Path: Specify the absolute path of the scripting engine instance on your LabKey Server, including the program itself. Remember: The instance of the R program will be named "R.exe" on Windows, but "R" on Linux and OSX machines.
- Program Command: This is the command used when the program is invoked.
- Example: For R, you typically use the default command: "CMD BATCH --slave". The R command is the command used by the LabKey server to execute scripts created in an R view. The default command is sufficient for most cases and usually would not need to be modified.
- Output File Name: If the console output is written to a file, the name should be specified here. If you are working with assay data, an alternative way to capture debugging information is to enable "Save Script Data" in you assay design: for details see Transformation Scripts.
- Site Default: Check this box if you want this configuration to be the site default.
- Sandboxed: Check this box if you want to mark this configuration as sandboxed.
- Use pandoc and rmarkdown: Enable if you have rmarkdown and pandoc installed. If enabled, Markdown v2 will be used to render knitr R reports; if not enabled, Markdown v1 will be used. See R Reports with knitr
- Enabled: Please click this checkbox to enable the engine.
Multiple R Scripting Engine Configurations
More than one R scripting engine can be defined on a server site. For example, you might want to use different versions of R in different projects or different sets of R packages in different folders. You can also use different R engines inside the same folder, one to handle pipeline jobs and another to handle reports.
Use a unique name for each configuration you define.
You can mark one of your R engines as the
site default, which will be used if you don't specify otherwise in a given context. If you do override the site default in a container, then this configuration will be used in any child containers, unless you specify otherwise.
In each folder where you will use an R scripting engine, you can either:
- Use the site default R engine, which requires no intervention on your part.
- Or use the R engine configuration used by the parent project or folder.
- Or use alternate engines for the current folder. If you chose this option, you must further specify which engine to use for pipeline jobs and which to use for report rendering.
- To select an R configuration in a folder, navigate to the folder and select (Admin) > Folder > Management.
- Click the R Config tab.
- You will see the set of Available R Configurations.
- Options:
- Use parent R Configuration: (Default) The configuration used in the parent container is shown with a radio button. This will be the site default unless it was already overridden in the parent.
- Use folder level R configuration: To use a different configuration in this container, select this radio button.
- Reports: The R engine you select here will be used to render reports in this container. All R configurations defined on the admin console will be shown here.
- Pipeline Jobs: The R engine you select here will be used to run pipeline jobs and transform scripts. All R configurations defined on the admin console will be shown here.
- Click Save.
- In the example configuration below, different R engines are used to render reports and to run pipeline jobs.
Sandbox an R Engine
When you define an R engine configuration, you have the option to select whether it is
Sandboxed. Sandboxing is a software management strategy that isolates applications from critical system resources. It provides an extra layer of security to prevent harm from malware or other applications.
An administrator should only mark a configuration as sandboxed when they are confident that their R configuration has been contained (using docker or another mechanism) and does not expose the native file system directly. LabKey will trust that by checking the box, the administrator has done the appropriate diligence to ensure the R installation is safely isolated from a malicious user. LabKey does not verify this programmatically.
Add a Perl Scripting Engine
To add a Perl scripting engine, follow the same process as for an R configuration.
- Select (Admin) > Site > Admin Console.
- Click the Settings tab.
- Under Configuration, click Views and Scripting.
- Select Add > New Perl Engine.
- Enter the configuration information in the popup.
- Click Submit.
You can only have a single Perl engine configuration. After one is defined, the option to define a new one will be grayed out. You may edit the existing configuration to make changes as needed.
Add a Python Scripting Engine
To add a Python engine:
- Select (Admin) > Site > Admin Console.
- Click the Settings tab.
- Under Configuration, click Views and Scripting.
- Select Add > New External Engine.
- Enter the configuration information in the popup.
- Note that Program Command and Output File Name are optional fields.
- Program Command is used only if you need to pass any additional commands or arguments to Python or for any of the scripting engines. If left blank, we will just use the default option as when running Python via the command-line. In most cases, this field can be left blank, unless you need to pass in a Python argument. If used, we recommend adding quotes around this value, for example, "${runInfo}". This is especially important if your path to Python has spaces in it.
- Output File Name is used if you want the console output to be written to a log file. If you are working with assay data, an alternative way to capture debugging information is to enable "Save Script Data" in you assay design: for details see Transformation Scripts.
Related Topics
