This topic is under construction for the 18.3 release of LabKey Server. For current documentation of this feature, click here.

This topic covers the configuration of scripting engines.

Some ways to use scripting engines on LabKey Server.
  • R, Java or Perl 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 R and Other Scripts in Sequence.

Add an R Scripting Engine

  • Select (Admin) > Site > Admin Console.
  • On the Admin Console Links 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 Unix and Mac 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. See below for details.
  • 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.

Use a unique name for each configuration you define. You can also decide whether each configuration qualifies as "sandboxed", described below.

You can have two site default R engine configurations: one sandboxed, and one non-sandboxed. The default for either type should have the box for Site Default checked. If you check this box on another configuration of the same sandboxing type, you will be prompted to confirm that you intend to change the default.

In each folder where you will use an R scripting engine, you can choose to use the R engine configuration used in the parent project or folder, or override it with an alternate configuration in this folder and child folders.

  • 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. Overriding the site default at the project or folder level allows R reports to be run under different configurations. Options:
    • 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. Shown below we see the "Default R Scripting Engine" name we gave the configuration we defined earlier.
    • Override R Configuration?: To use a different configuration here, select the radio button for this option. Use the pulldown to select the desired configuration from the menu. All R configurations defined on the admin console will be shown here.
  • Click Save.

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.

You can have two site default R engine configurations: one sandboxed, and one non-sandboxed.

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.
  • On the Admin Console Links 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.
  • On the Admin Console Links 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.
  • Click Submit.

Related Topics

Discussion

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand all collapse all