Working with Operators¶

Operators are computer programs written in common languages such as R or Python. They perform calculations or visualisations on data and can be simple or complex depending on their design.

Tercen provides hundreds of standard operators to choose from, and your organization may have created an operator specific to your lab's process.

Add an Operator to a workflow¶

To add an operator to your pipeline, click the Data Table and select Add from the local toolbar.

Use the Operator Tag to filter and search for Mean and SD and press OK

A Data Step will open with the Mean and SD Operator loaded.

This operator will calculate a Mean and a Standard Deviation for every data cell.

• Plus Button: Add an operator into an existing step.
• Name and Version: The name of the operator and a version number 0.0.0 which links to instructions on how to use it.
• Minus Button: Removes the operator.
• Run Button: Locks the projection in the crosstab and runs the operator code on the data.

Set up an operator¶

Operators receive data from the crosstab projection, but they need the projection to be configured according to their internal design, or it will not run properly.

To discover the projection an Operator expects, click the version number link under the operator's name.

This will take you to the operator's GitHub page, where layout instructions will be available in the README file.

• Description: Explains what the operators function is.
• Input: Specifies the crosstab projection that is required by the Operator. Input Zone: The crosstab zone a factor can be placed in. Factor Type: Operators may need a numeric or text input. Status: Whether this zone must contain a factor or can be optionally left blank. Description: Additional information to help pick an appropriate factor for this operator to get meaningful results.
• Output: Describes the outputs the Operator will create. Factor Name: The name of the new factors that the operator will create to hold the results of its calculations. Factor Type: What type of data the new factors will have such as numeric or text. Calculation: When the operator runs, it performs one calculation per defined group. These can be Cells, Rows, Columns, or Whole Crosstab. Description: A description of what the new factor is.

According to the specification, the Mean and SD expect the main measurement (VALUE in our example file) to be placed on the Y-Axis. It will make two calculations on every cell, A Mean and a Standard Deviation and will create two new factors mean and sd to hold the results.

Return to Tercen and drag VALUE to the Y-axis.

Run an Operator¶

Press the Run Button to start the operator. Some buttons in the Operator Panel will change.

• Reset Button: The run button will change to a reset button when the code is finished. It must be used before any changes to the projection or re-runs of the operator.
• Result Button: Displays the results of a calculation or any specialized visualization to be generated.

Press the Result Button to review a data table with the operator's results.

The operator created two new factors mean and sd according to the spec. There is one calculation for each as there was one Data Cell in the projection.

_Note: Tercen automatically creates a namespace prefix to prevent duplicate Factor names from being created. They are based on the Object Type. For example, Data Steps generate "ds1." "ds2." and so on. Other steps have different namespaces.

Add some groups to the projection.

Press the Reset Button to unlock the projection and drag the following.

CELL_SUBSET to Row.
SEX to Column.

Rerun the operator and check the results.

Now, a Mean and a Standard Deviation have been calculated for all 118 cells (2 Columns, 59 Rows) in the Crosstab.

Save the Data Step and return to the Workflow Canvas.

Project the results of an Operator¶

Note: The Status Indicator on the Mean and SD data step should be green.

To access the results of an operator's calculations, add a new data step to the Mean and SD using the Local Toolbar.

Note: The Tercen AI will attempt to automatically create a projection from a Data Step above. For this tutorial, we will reject the suggestions and build each projection manually.

Press the Clear Button to re-set the crosstab grid.

The Factors Panel has two folders. One with the Factors from the data file and one with the new factors created by the Mean and SD operator.

Make this projection.

mean to Y-Axis.
CELL_SUBSET to X-Axis.
CELL_SUBSET to Colors.
Graph Style Button to Bar.

Save the Data step

Return to the Workflow Canvas

Rename the Data Step to "Bar Graphs"

Plot Operator¶

Operators can generate visualizations as well as new Factors. To get more comprehensive and featureful graphs use the plot operator.

Add a Data Step to Mean and SD using the Local Toolbar

Use the Operators tag and Search to find the Plot operator.

When the Data Step opens. Clear the crosstab grid

Make the following projection.

mean to Y-Axis.
CELL_SUBSET to Row.
SEX to X-Axis.
SEX to Colors.
sd to Error Bar.
Graph Style Button to Bar.

Operators can have settings that define parameters to modify how they process data. The settings are accessed by changing from Factors in the panel window to Settings.

The Plot operator settings define export file type, image sizes, labels for data, and more.

Each setting has a tooltip icon (?) with information on how to set parameters.

Find and set the following parameters.

xlab to Patient Group.
ylab to Cell Type.
title to Mean and SD Graph.
theme to classic.

Press the Run Button.

Images are rendered using standard Bioinformatics protocols as defined by the ggplot R package.

They can be downloaded individually by clicking the relevant link.

Or scroll to the end of the page and batch download all images in a ZIP file.

Save rename the Data Step and return to the workflow canvas.

Workflow Report Panel¶

The Plot operator passes its results into the Workflow report panel.

This panel can build up a comprehensive report from all the Plot Operators in the workflow.