Phaedra 2 – In Depth

Documentation: Perform Plate Analysis

Mon, 01 Jan 0001 00:00:00 +0000

Apply Plate Layout

Before we can start with plate analysis we first need to create a project, an experiment and one or more plates. How to set up/create a project and an experiment and how to add plates to the experiment you can go through the getting started tutorial.

When we have set up a project and added experiments and plates to it, then we can start by applying a plate layout to a plate or plate(s). To apply a plate layout to a specif late browse to the experiment view and click on the … icon of a specific plate in the experiment plate list section. By clicking on the … icon, a plate action menu will appear.

Next click on the Set Plate Layout option.

After clicking Set Plate Layout option, a Select Plate Layout dialog should appear

Within the dialog a prefiltered list (filtered on plate dimensions) will be shown. You can select one of the plate templates and apply it to the plate by clicking on LINK button in the right lower corner of the dialog.

Before applying the selected plate layout, you can also display a preview of the selected plate template by clicking on the SHOW QUICK VIEW button.

Once the selected plate is linked with the selected plate layout a green check icon in the L column of the plate list section for the selected plate will appear.

Link Measurement

Next step is to link a specific measurement to the selected plate. For this we need to browse to the plate view by clicking on a specific plate in the plate list section of the experiment view

In order to link the plate with a specific measurement browse to Measurements tab in the plate overview section

Here we can link a measurement by clicking on the LINK MEASUREMENT button in the right upper corner of the plate measurements section. Click on the LINK MEASUREMENT button and a Link Measurement dialog will appear the show a prefiltered list (filtered on plate dimensions) of captured plate measurements.

Select a measurement and click on the LINK button to link the selected measurement to the plate

When the selected measurement is linked it will appear in the linked measurements list of the plate measurements section

Now when we browse to the plate Heatmap section tab we will be able to se a heatmap of the well columns of the selected measurements.

(Re)Calculate Plate

Under construction …

Validate/Invalidate Plate

Under construction …

Approve/Disapprove Plate

Under construction …

Documentation: Plate Layout Templates

Mon, 01 Jan 0001 00:00:00 +0000

A plate layout template defines how the plate looks like, for example a plate layout can define witch wells are marked as control wells (high/low control) and which wells are marked as sample wells. Next to well type definition, the user can also for every well set a substance type and number of even enter substance concentration. This plate layout templates can later be applied/linked on existing plates as plate definition.

Create a template

To create a new plate layout template, go to the Plate Layouts/New Template… menu item in the Phaedra Navigator.

A New Template form will appear:

Fill in the Name for the plate template
Fill in the Description (optional) for the plate template
Fill in the number of Rows for the plate template
Fill in the number of Columns for the plate template
Click button to create the plate layout and you be redirected to:

Initially you will see an empty plate template layout. To make it meaningful to use, you’ll need to update the plate layout template.

To skip wells (skipped wells are ignored) select the wells and click on
Click button to save the plate layout template changes

To set the well types got to Well Type tab
To set the well types, select the wells and select a well type from the input field and click

Click button to save the plate layout template changes

After defining the well type you might want to also set substance type and numbers for specific wells.

To set the well substance types and numbers click on the Substance tab

Select the wells you want to add substance type and name to
Fill in the Substance Type and click
Fill in the Substance Name and click

The updated layout template view should look something like:

Click button to save the plate layout template changes

Final step is to set the Substance concentrations for specific wells.

To set the substance concentrations click on the Concentration tab

You will notice that the concentration values are by default set to 0.

To set the concentrations select the wells you want to update
Fill in the Concentration value (in Molar (M)) and click

Click button to save the plate layout template changes

After successfully completing all the above steps, you’ll have now created a plate layout template that can be linked to any plate that matches the dimensions.

Create a template from a json file

Under construction!

Viewing a template

In order to view details of a specific plate layout template navigate to the Plate Layouts/Templates menu item in the Phaedra Navigator.

An overview table of all the plate layout templates will be displayed:

To view the details of a specific plate layout template click on one of the rows (e.g. previously created)
You’ll be navigated to the plate layout template details page:

Editing a template

To Edit a existing template follow the steps from View Template and Create Template sections.

Do not forget to click in order to save your changes!

Documentation: Calculation Formulas

Mon, 01 Jan 0001 00:00:00 +0000

Calculation Formulas are the building blocks for defining features, which in turn are the building blocks of protocols. One of the primary goals of Phaedra is to provide a flexible platform onto which diverse types of calculation can be defined and performed. To this end, all calculations are modelled into formulas that are clearly defined and controlled through a unique name and version number. Making any kind of change to the formula will result in a new version being generated, and in protocols and resultsets you will always see which version of a formula was used to obtain a calculation result.

The Formula Model

A Calculation Formula has several standard properties, such as a name, description and version number. In addition, it has three settings that together define what kind of calculation the formula can perform.

Language

Is the programming language in which the formula is written. Currently, two languages are supported: R and JavaStat. Future updates will bring support for additional languages such as Python and JavaScript.

Scope

This setting determines how many output values the formula is expected to return.

PLATE indicates that the formula should return one value per whole plate. This scope is used in plate statistic formulas.
WELL indicates that the formula should return one value per well. This scope is typically used in feature calculation formulas.

Formula

The formula can be written in any one of the supported languages, and is expected to return one or multiple output values, depending on the selected scope. The formula will automatically receive a number of input variables that it can use during its execution.

The table below lists the input variables a formula will receive when configured in the R language and WELL scope:

Variable Name	Type	Description
`input$wellNumbers`	Vector, length is the number of wells in the plate	A vector of numeric values representing the well numbers.
`input$wellTypes`	Vector, length is the number of wells in the plate	A vector of character values representing the well types.
`input$wellRows`	Vector, length is the number of wells in the plate	A vector of numeric values representing the well row numbers.
`input$wellColumns`	Vector, length is the number of wells in the plate	A vector of numeric values representing the well column numbers.
`input$wellStatus`	Vector, length is the number of wells in the plate	A vector of numeric values representing the well status codes. If the value is <0, the well is rejected.
`input$lowWellType`	Character value	The Low Control welltype code as defined in the protocol
`input$highWellType`	Character value	The High Control welltype code as defined in the protocol

Note: all well-based vectors have the same order.

In addition, if the formula is used for a feature in a protocol, it may define extra variables simply by referencing them from the input object. For example:

# This formula computes a %EFFECT normalization using LC and HC controls
lcMedian <- median(input$rawValue[input$wellStatus >= 0 & input$wellTypes == 'LC'], na.rm = TRUE)
hcMedian <- median(input$rawValue[input$wellStatus >= 0 & input$wellTypes == 'HC'], na.rm = TRUE)
output <- 100 * ((input$rawValue - lcMedian) / (hcMedian - lcMedian))

This formula uses several input variables such as input$wellStatus and input$wellTypes, but it also references a variable that is not defined in the table above: input$rawValue. When this formula is selected for use in a feature, a source for this rawValue must be configured:

Here, a measurement well column named CellCount_AllRetained will be used to provide a vector of values for the input$rawValue variable in the formula. As you can see, the same formula can be used repeatedly in other features (even other protocols) to compute the same thing, but using other measurement columns or features as rawValue.

When using a measurement subwell column as the source, the variable will contain a list of vectors. Use the well number to index into the list and get a vector of values, one per cell. For example, the expression mean(input$rawValues[[5]]) would return the mean value of all subwell items for well nr 5.

Documentation: Pipelines

Mon, 01 Jan 0001 00:00:00 +0000

Pipelines are a core concept in Phaedra, as they are the “glue” that bind data processing steps together in an automated fashion. While they are entirely optional, and you can perform each step manually, you will save a lot of time and effort by using pipelines, especially in large-volume projects or assays.

But before a pipeline can be used, it must be set up correctly, a task which requires some knowledge about the Phaedra system and some careful configuration. This section describes the more technical details of pipeline setup.

The Pipeline Model

Pipelines have some evident properties such as a name, description, version number, etc. But at the heart of the pipeline model lies the definition, which is expressed as a JSON document.

For more information about the JSON syntax, see:

The pipeline definition describes a series of steps, where each step consists of a trigger and an action.

The trigger describes the event that should initiate the execution of the current step.
The action describes what should be done when the step gets executed.

However, you’ll find that many steps actually omit the trigger part. This is because most actions have an implicit trigger that fires automatically when the action is complete. The notable exception is the first step, which must always have an explicit trigger.

Consider the definition below:

{
    "steps": [
        {
            "trigger": {
                "type": "MeasurementCaptured",
                "config": {
                    "pattern": ".*Barcode1234.*"
                }
            },
            "action": {
                "type": "LinkPlateMeasurement",
                "config": {
                    "projectId": 500
                }
            }
        },
        {
            "action": {
                "type": "LinkPlateDefinition",
                "config": {
                    "name": "My 8 x 12 Layout"
                }
            }
        },
        {
            "action": {
                "type": "CalculateProtocol",
                "config": {
                    "id": 200
                }
            }
        }
    ]
}

The first step contains both a trigger (MeasurementCaptured) and an action (LinkPlateMeasurement). This is pretty straightforward: whenever a new measurement is captured into Phaedra whose name matches the given pattern, a new pipeline execution will begin for this pipeline. The first thing that will happen in this execution, is that the new measurement will be linked to a plate in the project with ID 500. More details about the LinkPlateMeasurement action can be found further down in this document.

The second step does not have an explicit trigger. This means that the step will be invoked automatically when the action of the previous step (LinkPlateMeasurement) is completed. At that moment, action LinkPlateDefinition is invoked, taking the name of a layout definition (My 8 x 12 Layout) as a parameter.

The third and last step also uses an implicit trigger, and invokes the CalculateProtocol action with protocol ID 200 as soon as the previous step’s LinkPlateDefinition action is completed.

Pipeline Execution Variables

During pipeline execution, variables are obtained and stored, to be passed on and used between the different steps of the pipeline.

For example, the MeasurementCaptured trigger will automatically capture two variables: barcode and measurementId, both obtained from the new measurement that was captured. These variables are available to all subsequent triggers and actions of the pipeline, so that they can know which measurement is being dealt with.

Similarly, the LinkPlateMeasurement action will capture an additional variable plateId, referencing the plate that the measurement was linked to.

Available Trigger Types

When designing a new pipeline, you can choose between several trigger types to start off pipeline execution.

MeasurementCaptured

This is a trigger that fires whenever a measurement gets captured by the Phaedra’s DataCapture system.

Configuration	Description
`pattern`	A regular expression that will be matched to the source path of the captured measurement. If the pattern does not match, the trigger will not fire.

Event

This is a generic trigger that can fire whenever a Kafka event is received matching certain conditions. Please note that this is a more advanced trigger type.

Configuration	Description
`topic`	The name of the Kafka topic that should be listened to. Events from other topics will be ignore.
`key`	The key of the Kafka event that should fire the trigger. Events with a different key will be ignored.
`value`	The value that must match the Kafka message in order to fire the trigger.
`pattern`	A regular expression that can be used instead of a literal value (see `value` above) to match the Kafka message.
`selector`	An optional JSON selector that can be used to select a substring of the Kafka message, if it is a JSON message.

Available Action Types

Below is a list of available action types you can choose from when building a pipeline. The same action type can be used repeatedly in a pipeline.

Each action type will list, in addition to its available configuration settings, a list of required variables. These variables should be made available by preceding steps. For example, using the MeasurementCaptured trigger ensures the required variables for the LinkPlateMeasurementAction action will be available. If any required variables are not available at the time of execution, the execution will fail with an error message.

LinkPlateMeasurementAction

This action will link a measurement to a plate whose barcode matches the measurement’s.

Configuration	Description
`projectId`	The ID of the project to find a matching plate in to link with.
`experimentNamePattern`	A regular expression that will be matched against the measurement source path and should contain at least one group, which captures the experiment name to use.
`experimentNamePatternGroup`	The number of the group in the `experimentNamePattern` that captures the experiment name. Defaults to `1`.
`createExperiment`	Set to `"true"` to auto-create an experiment if no experiment is found that matches the experiment name (determined using `experimentNamePattern`).
`createPlate`	Set to `"true"` to auto-create a plate if no plate is found matching the measurement barcode in the target experiment.

Required Variables	Description
`barcode`	The barcode of the measurement, a plate with a matching barcode will be searched for.
`measurementId`	The ID of the measurement that will be linked to the plate.

LinkPlateDefinitionAction

This action will link a plate with a plate definition.

Configuration	Description
`source`	The source of the plate definition. Default value: `template`.
`name`	The name that identifies the plate definition in its source.

Required Variables	Description
`plateId`	The ID of the plate the plate definition will be linked with.

CalculateProtocolAction

This action will execute a protocol on a plate.

Configuration	Description
`id`	The ID of the protocol that should be executed.

Required Variables	Description
`plateId`	The ID of the plate that should be calculated.
`measurementId`	The ID of the measurement that is linked to the plate and should be used for calculation.