Scripting is an important aspect of Phaedra, as it adds a degree of flexibility to the application that is needed to support:
- Data capture: different types of instruments and file formats
- Feature calculation: different types of assays and feature calculation formulae
- Misc scripting: for example, automatisation of day-to-day tasks, such as validation and workflow execution
An addon is available that allows you to script in Python as well, see the Python Addon.
The rest of this document assumes you are familiar with scripting in general, including concepts such as function calls, variables, etc.
To test a script snippet, you can use the Console view. To open this view:
Select Window > Show View > Other... > General > Console.
In the Console's toolbar, click on the blue screen icon and select the language you want to script in.
Every script language (except JEP) by default exposes an object named API. This object is a registry of services that grant you access to data in Phaedra, and methods to manipulate that data.
To view the list of services available in the API, type:
To obtain a particular service, use the
get function, for example:
plateService = API.get("PlateService") plate = plateService.getPlateById(1)
All services that are exposed by the API, are documented in the Javadoc pages.
Phaedra's data capture component is heavily scripted. The primary reason for this is the fact that data capture is very much dependent on the user's infrastructure and data file formats. Phaedra offers a number of generic data capture scripts out of the box, but in a real life scenario it is very likely that at some point, you will have to customize or write your own data capture script.
Data capture scripts are stored on the file server, and can only be uploaded or modified by an administrator. To view or edit a data capture script as an administrator, click Administrator > File Server Browser.
The folder 'data.capture.modules' contains all the scripted modules that are currently known to Phaedra. Double-click on a file to open it.
You will notice that most data capture scripts start with this line:
This is a reference to the script catalog, to a script named 'common.js'. To see the contents of this common.js script (and the whole script catalog), navigate to script.catalog > dc > common.js
The purpose of the common.js script is to provide a number of convenience functions, for example to find files or folders based on regular expressions, or to parse XML or CSV files.
Data capture scripts are only called during a data capture job; they cannot be called directly. When they are called, they receive several additional objects to work with:
- ctx: a reference to the DataCaptureContext
- config: a reference to the ModuleConfig
- task: a reference to the DataCaptureTask
- monitor: a reference to the data capture job's progress monitor
When setting up or editing a Protocol Class, you can attach calculation formulae to well features.
This piece of script will be evaluated for every well, and thus expects one return value (numeric or string) for each invocation. For example, the below JEP expression returns a division of two other well features:
For most simple calculations, the JEP language is recommended as it is the most compact language. Use the Edit expression button to get assistance with the language syntax.
However, you can choose another language from the list, and enter a much more complex formula if you like. Custom calculation scripts have access to these additional objects:
- data: a reference to the PlateDataAccessor
- well: a reference to the Well
- feature: a reference to the Feature
Some additional notes on calculated well features:
- After adding or modifying a feature calculation formula, remember to save the protocol class and recalculate your plates. This is not done automatically.
- If a formula generates an error, the well's value will be NaN (Not a Number, for numeric features) or null (for string features).
- Keep in mind that the formula is evaluated against each well. Avoid repeating expensive calculations, use the StatService instead.
In addition to the scenarios described above, you can also write and run arbitrary scripts on plates, at any time. There are two ways to go about this: Console Scripting and Catalog Scripting.
The Script Console
You can write scripts on the fly in the Console view. For example, to modify a plate's barcode:
plateService = API.get("PlateService") plate = plateService.getPlateById(1) plate.setBarcode(plate.getBarcode() + "_modified") plateService.updatePlate(plate)
This is most suited for small, one-off scripts. For more complex scripts that can be reused, use the Catalog approach below.
The Script Catalog
Scripts can also be uploaded into the script catalog, but this requires administrator privileges. To view or modify the catalog, select Administrator > File Server Browser > script.catalog > misc
Catalog scripts can be run by any user on any plate they have access to. To do this, select one or more plates, right-click and select Scripts > Run Script from Catalog.
Scripts that are uploaded into the Script Catalog, can also be used to generate plots. To view such plots, open the Scripted Chart view: select Window > Show View > Other... > Scripted Chart.
For more information on scripted charts, take a look at the scripting tutorials (see below).
A number of tutorials on the above script types can be found on GitHub.