QX Designer Software
Assay Protocol File Configuration Guide
Version 1.0

QX Designer
Assay Protocol File Configuration Guide
Version 1.0

Bio-Rad Technical Support Department
The Bio-Rad Technical Support department is open Monday through Friday, 5:00 AM to 5:00 PM, Pacific time.
Phone: 1-800-424-6723, option 2
Email: Support@bio-rad.com (U.S./Canada Only)
For technical assistance outside the U.S. and Canada, contact your local technical support office.

Legal Notices
No part of this publication may be reproduced or transmitted in any form or by any means, electronic ormechanical, including photocopy, recording, or any information storage or retrieval system, without permission
in writing from Bio-Rad Laboratories, Inc.
Bio-Rad reserves the right to modify its products and services at any time. This guide is subject to change
without notice. Although prepared to ensure accuracy, Bio-Rad assumes no liability for errors or omissions, orfor any damage resulting from the application or use of this information.
BIO-RAD, DROPLET DIGITAL, DROPLET DIGITAL PCR, and DDPCR are trademarks of Bio-Rad
Laboratories, Inc. in certain jurisdictions.
Purchase of Digital PCR and/or Single-Cell NGS Sample Preparation products (the “Products”) from
Bio-Rad Laboratories is subject to Bio-Rad Laboratories, Inc. Standard Terms and Conditions of Sale, which
can be accessed at https://www.bio-rad.com/en-us/terms-conditions. Unless we expressly state otherwise inadditional Terms and Conditions, no rights are granted for you to distribute or resell the Products. Unless we
expressly state otherwise in additional Terms and Conditions, ​no rights are granted for the development orcommercialization of diagnostic assays for use with the Products without a license from Bio-Rad. It is theuser’s obligation to obtain a commercial license from Bio-Rad for (i) all commercial uses (not just diagnosticuses) and (ii) sale of assays for use on Bio-Rad's dPCR and ddSEQ instruments. The Products and/or theiruse are covered by U.S.​ and foreign patents and/or pending patent applications owned by or under license to
Bio-Rad Laboratories, Inc.
See bio-rad.com/en-us/trademarks for trademark information.
All trademarks used herein are the property of their respective owner.
Copyright © 2023 by Bio-Rad Laboratories, Inc. All rights reserved

Revision History

Revision History
Document

Date

QX Designer Assay Protocol File

June

Configuration Guide

2023

Description of Change
New document explaining how to
configure custom assay protocol files

Software version 1.0

DIR No. 10000149015 Ver A

User Guide | iii

iv QX Designer Software

Table of Contents
Front Cover
Revision History

Chapter 1 Introduction

a
iii

7

Opening QX Designer Software and Selecting an Option

7

Configuration Screens Overview

8

Chapter 2 Creating and Editing APF Packages

11

APF Package Screen

11

Plate Rules Screen

14

Plate Definition Screen

17

Kit Lots Screen

19

Quality Rules Screen

20

Data Analysis Screen

25

Data Analysis Checkbox Options

26

Defining Custom Variables

26

Defining Custom Calculations

27

Custom Results Screen

29

Custom Reports Screen

34

Appendix A External Clustering Algorithms

35

Generating Threshold Clusters

35

Python Startup Script

37

Workflow38

Error Handling

39

Data Formats

40

Conclusion

42

Appendix B Tips for Custom Calculations

43

Supported Operators

43

Input Variables

44

Well Type-Based48

User Guide | v

Table of Contents

Special Variables

48

Outputs

49

Appendix C Well Metric Options in Quality Rules

53

Back Cover57

vi QX Designer SoftwareChapter 1 Introduction
Assay protocol files (APFs) are static plate layout templates that contain detailed biological assay
designs. APFs follow specific instructions and rules for qualitative or quantitative evaluations. QX
Designer Software from Bio-Rad™ provides an interface for creating new APF packages, and editing
existing packages, with combinations of values and settings that are used frequently in your laboratory.
APFs are also connected to a specific results feature in QX Manager Software, Premium Edition (versions
2.0 and later), which facilitates viewing and analysis of targeted data.
This user guide contains instructions and procedures for creating and editing APFs by defining plate rules
and definitions, kit lots and quality rules, custom variables and calculations for data analysis, and custom
results and reports.
The content of this guide assumes you are proficient in QX Manager Software, Premium Edition, functions
and options.

Opening QX Designer Software and Selecting an Option
When you open QX Designer Software, you can create a new APF package or you can edit an existing
APF package.

To open the application and display the home screen
1.

Double-click the QX Designer shortcut icon on the computer desktop.
The Home screen appears. As you create or upload APFs, the packages appear on the left.

User Guide | 7

Chapter 1 Introduction

2.

3.

Do one of the following:n

To create a new configuration, click Create new APF Package.

n

To edit an existing configuration, click Open existing APF Package and navigate to theapplicable storage location or click an APF package in the list on the left.

Continue to Configuration Screens Overview for information on the functionality available in QX
Designer.

Configuration Screens Overview
When you click one of the options on the Home screen, the APF Package screen appears by default, asshown in the following graphic. Tabs to the other configuration screens appear on the left.

8 QX Designer SoftwareConfiguration Screens Overview

The screen associated with each tab is described in Table 1 below.
Table 1. QX Designer APF Configuration ScreensIn this screen...

You can...

APF Package

Name and describe the APF, select the instrument, identify the APF version,
select the algorithm, and identify the directory and path. Optionally, you canassign a password.
See APF Package Screen on page 11.

Plate Rules

For each assay you define, select the experiment and assay types, and targets,signals, and sample types.
See Plate Rules Screen on page 14.

Plate Definition

Identify the well assay types and sample types for fixed wells.
See Plate Definition Screen on page 17 for

Kit Lot Information

Select to use specific lots for kits, consumables, and reagents.

See See Kit Lots Screen.
Quality Rules

Define rules and criteria for calculations and data validation.
See Quality Rules Screen on page 20.

Data Analysis

Define variables and their values, as well as custom calculations.
See Data Analysis Screen on page 25.

Custom Results

Customize the APF results display in the Analysis Module.
See Custom Results Screen on page 29.

Custom Reports

Generate reports from your customized results.
See Custom Reports Screen on page 34.

User Guide | 9

Chapter 1 Introduction

10 QX Designer SoftwareChapter 2 Creating and Editing APF Packages
This chapter provides more detailed information on options that are available for configuring an APF
Package. You can create new packages or edit existing packages.

APF Package Screen
In the APF Package screen, you can enter general information regarding the APF. When you select an
option to create or edit content from the Home window, the APF Package window appears by default.

User Guide | 11

Chapter 2 Creating and Editing APF Packages

To add or update information in the APF Package screen
1.

In the Display Name field, enter a file name for the APF and, optionally, add a brief description.

2.

From the Target Instrument dropdown, select the instrument.

3.

If you select the QX600, you must also specify the droplet size.

4.

Do one of the following:n

When creating a new APF, enter a version of three numbers.

nWhen updating an existing APF, change the version and select Standalone or Upgrade to further
control your imported versions in QX Designer Software, Premium Edition.
Note the following:oStandalone allows the import of multiple versions of the same APF

oUpgrade allows the import of a single APF version only; therefore, importing a new version
replaces the existing version.

12 QX Designer Software

APF Package Screen5.

Choose a calculation algorithm.
Important: External clustering is currently supported for two channels only (Ch1 and Ch2), for
the DropOff and Double Dropoff assay types. If you select the external clustering algorithm thesection expands and displays additional fields, as shown in the graphic below. You must have adevelopment application installed (Python or other developer language), and you must specify
the path to the executable file and any arguments that are expected to pass through
QX Manager Software, Premium Edition. For more information on external clustering algorithms,
see Appendix A, External Clustering Algorithms.

6.

(Optional) To restrict access to the file, enter a password in the Password field. To show the
password, click the icon on the right.

7.

Continue to Plate Rules.

User Guide | 13

Chapter 2 Creating and Editing APF Packages

Plate Rules Screen
Using the Plate Rules screen, you can define different settings combinations as well types. As you clicktheicons, fields and dropdown lists are enabled, depending on previous selections. Choices are

identical to settings and options in QX Manager Software, Premium Edition.

Well types begin as a blank screen, with the first supermix in the drop-down list selected.

14 QX Designer SoftwarePlate Rules Screen

To set up well types
1.

Select the Plate Rules tab, and then select a different supermix if applicable.

2.

Click theicon under Well Types.

a.

Update Well Type 1 (default entry) with a new name (for example, Assay 1).

b.

From the Experiment Type dropdown list, select an experiment type.
When you select the experiment type, corresponding assay types appear in the Assay Typedrop-down list.

c.

From the Assay Type dropdown list, select or change the assay type.
When you select an assay type, generic targets are defined under Target Info. If you change theassay type, the target information changes accordingly.

d.

Under Target Info, identify your targets and replace the default selections as applicable.
You can change the target name, target type (unknown or reference), and select an alternate
dye where applicable. For example, FAM to EvaGreen® or HEX to VIC.

User Guide | 15

Chapter 2 Creating and Editing APF Packagese.

Under Sample Types, select or change the sample type from the dropdown list (Unknown, NTC,
Pos Ctrl, Neg Ctrl).

Tip: You can click theicon next to Sample Types to add other sample types until the

maximum is reached. You can also require a certain number of wells to inherit this well typeconfiguration in the APF plate layout. Select the Required Number of Wells checkbox, andthen enter the number.
f.
3.

Click Apply.

To add and configure another well type, click theicon under Well Types and repeat thisprocedure.
4.

When your well types are configured, continue to Plate Definition.

16 QX Designer SoftwarePlate Definition Screen

Plate Definition Screenin the Plate Definition screen, you can select combinations of well types and sample types for your fixed
wells, based on your configuration on the Plate Rules screen.

To define your plate1.

Select the Plate Definition tab.

2.

(Optional) Above the Fixed Wells grid, enter information for the following:a.

If a sample ID is required for all wells, select the checkbox.

b.

Enter the number of wells required for each sample ID.

c.

Enter the number of Unknown replicates per well type.

User Guide | 17

Chapter 2 Creating and Editing APF Packages

3.

Select a group of wells in the grid.

4.

From the Well Type drop-down list, select a well type that you configured in the Plate Rules screen.
After you select the well type, the Sample Type dropdown list is enabled.

5.

Select one of the sample types you configured in the Plate Rules screen.

6.

If sample IDs are required, enter a sample ID in the corresponding field.

7.

Click Apply.

8.

Repeat for each group of wells you are setting up in the grid.
These wells will always be read according to your configuration when you select the APF for a droplet
reading run.

9.

Continue to Kit Lot Information.

18 QX Designer Software

Kit Lots Screen

Kit Lots Screen
When you select the Kit Lot Information tab, the window expands with checkboxes for lot categories for
consumables and reagents.
If you select a checkbox for a lot item, the item is required when you associate the APF with your run in
QX Manager Software, Premium Edition. For example, if you select the Cartridges checkbox underConsumables in QX Designer Software, and then do not select a lot for cartridges in QX Manager
Software, Premium Edition, QX Manager Software displays an error message.

To specify that lots will be used in the run
1.

Click the arrow to the left of each category to expand the section and display an array of checkboxes.

2.

Select the corresponding checkboxes for lot items that should always be included in a plate run whenthe APF is assigned.

3.

(Optional) If applicable, select the Allow Expired Lots checkbox.

4.

Continue to Quality Rules.

User Guide | 19

Chapter 2 Creating and Editing APF Packages

Quality Rules Screen
Use the Quality Rules screen to establish Pass or Fail criteria for your wells, based on parameters you set
up in the Plate Rules screen.
Within each quality rule, you specify one or more quality values, which are composed of tests that
establish passing criteria and calculations, based on well metrics and/or quality rules. Sections andsubsections expand to include applicable fields based on your selections.

To fully define a quality rule, you must name the rule and select a calculation basis type (Well, Sample, orPlate), and then define the associated quality values for the rule. Quality values are composed of one ormore tests to validate droplet digital PCR™ (ddPCR™) data.

20 QX Designer Software

Quality Rules Screen

To create a quality rule1.

Select the Quality Rules tab, and then click theicon next to Quality Rules in the upper-left corner

to expand the display. QX Designer expands to display more fields as you click theicons indifferent sections.
The default entry of Quality Rule 1 is the starting point.

2.

Under Quality Rule 1 do the following:a.

Change the name in the Rule Name field to reflect the purpose of the quality rule.

b.

Optionally, enter a description for the rule in the Description field.
Note: When you save the information, the Rule Name appears under Quality Rules so you
can easily see the rules that are defined.

c.

Select a calculation basis type (Well, Sample, or Plate) by which the quality will be measured.

User Guide | 21

Chapter 2 Creating and Editing APF Packages

To define the quality values within the rule
Within the Quality Values section, you can set up one or more tests under Passing Criteria and Calculate
Based On. You can set up one or both, and you can mix and match selections for a range of validation
capabilities.

1.

Click thesign next to Quality Values to display Quality Value 1 section and enter a name andoptionally, a description.

2.

Click thesign next to Passing Criteria or Calculate Based On. You can configure one or bothwithin the same Quality Value.

22 QX Designer Software

Quality Rules Screena.

Click theicon next to Tests and select an operator (AND, OR) from the Logical Grouping

dropdown list . If you select AND, all rules must pass. If you select OR, a minimum of one rule
must pass.

b.

Select a Metric Source (Well Metric or Quality Rule) to set up validation testing. The section
expands after you make your selection.

Well Metric — Use an analysis metric

Quality Rule —Use an existing quality rule

User Guide | 23

Chapter 2 Creating and Editing APF Packages

Important: Step 2c below describes the fields shown in the above graphics, but other fields
might appear based on different selections for the Metric.
c.

Select or enter the following:
Metric: Select a metric from the dropdown list; the dropdown list contains many options; for brief
descriptions, see Appendix A. (applies to Well Metric only).
Comparison: Select from the following: (applies to Well Metric and Quality Rule).
n

Minimum — must be a minimum of the Passing Value to pass.

n

Maximum — can be a maximum of the Passing Value to pass.

Note: Set up two tests to define a range, one with the minimum value and the second withthe maximum value.
nPrecision Percentage — can pass if within a percentage defined in Passing Value (WellMetric only).

nEquals — metric can pass if it equals the Passing Value.

n

Not Equals — metric can pass if it doesn’t equal the Passing Value (Well Metric only).

Passing Value: Enter the applicable value. (Well Metric only).
Passing Wells Count: Enter the applicable value (Quality Rule only).
Quality Rule Name: Select an existing Quality Rule from the dropdown list (Quality Rule only).
d.

Optionally, add another test.

3.

Repeat Step 2 to add another set of applicable tests for a Passing Criteria or Calculate Based on
section.

4.

Repeat all steps in this section to create another Quality Value within the Quality Rule.

5.

Repeat both sections to create another Quality Rule.

24 QX Designer Software

Data Analysis Screen

Data Analysis Screen
Use the Data Analysis screen to define the analysis configuration for the Assay Protocol File. You cancreate custom variables and calculations to perform data analysis across well types for a given sample ID.
For information on design, syntax, and variables see Appendix B, Tips for Custom Calculations.
Use the Data Analysis screen to do the following:nSelect checkboxes to enable system operator functionsn

Define custom variables and calculation code that can be applied to each sample in the plate

User Guide | 25

Chapter 2 Creating and Editing APF Packages

Data Analysis Checkbox Options
The checkboxes in the Data Analysis screen enable the system operator functions explained below:nAllow Edit Custom Variables — Before starting the run, you can change the custom variable values in
QX Manager Software, Premium Edition. The system uses the new values for the downstream
calculations defined in the custom calculations script.

nAllow Manual Analysis —Before starting a run, you can manually set thresholds and clusters in QX
Manager Software that the system uses to perform downstream calculations.

To enable editing and manual analysis
1.

Select checkboxes to enable the corresponding functionality.

2.

Click Save.

Defining Custom Variables
Custom variables are name-value pairs that you can define and use in your APF custom calculation
scripts. For information, see Defining Custom Calculations on page 27.
Tip: If you enabled the Allow Edit Custom Variables checkbox in the previous section, you can edit
the variable values in QX Manager Software, Premium Edition, before starting a droplet reading run.

26 QX Designer Software

Data Analysis Screen

To define custom variables
1.

Click thesign next to Custom Variables to display the Variable Name and Variable Value fields.

2.

Enter a variable name and corresponding value.

3.

Repeat until all variables are created.

4.

Click Save.

Defining Custom Calculations
Custom calculations are scripted formulas that define output values in the Custom Results screen. They
allow an Assay Protocol developer to perform post-ddPCR calculations on well data that are included aspart of the APF.
Note: You can create custom calculations with or without custom variables. For information on
custom variables, see Defining Custom Variables on page 26.

To define your custom calculation formulasu

Under Custom Calculations, enter a formula.
The following graphics show a formula example. For information on design, syntax, and variables you
can use in your custom calculation formulas, see Appendix B, Tips for Custom Calculations.

User Guide | 27

Chapter 2 Creating and Editing APF Packages

28 QX Designer Software

Custom Results Screen

Custom Results Screen
Use the Custom Results screen to colorize wells and define results tables in the QX Manager Software
Analysis module APF Results screen. You can set up text, table, and background colors in any
combination to design the custom Analysis layout, and to use in the Custom Reports design.

To specify Plate Layout settings
1.

For Well Color and Well Selection Outline Color, click the respective icon on the right.

User Guide | 29

Chapter 2 Creating and Editing APF Packages

2.

When the color palette appears, select a basic color for each field or click in a blank box under
Custom colors and click Define Custom Colors and continue to Step 3.

3.

Click a color in the rainbow palette and then slide the arrow on the far right down until the shade is
acceptable.

4.

Click Add to Custom Colors.
The hexadecimal color code appears in the field in QX Designer Software.

30 QX Designer Software

Custom Results Screen

To specify Custom Results Settings
1.

In the Results Decimal Places field, enter the number to expand the decimal display. For example, 2results in two decimal places after the whole number (for example, 123.45).

2.

In the Text for Undefined Values field, keep the default Undefined text or change it to a different entry.

To specify Custom Results text and colors
1.

In the Header Text field, enter the text that should appear in the APF Results display.

2.

In the Header Text Color field, click theicon on the right to open the color palette and select or

create a color.
3.

Repeat for the Table Background field.

To specify Custom Results Table text, colors, and formulas
1.

To create header text for different displays in the APF Results screen, click the + sign next to theCustom Results Tables heading.

a.

In the Header Text field, enter the heading name to be displayed in the custom report.

b.

In the Header Text Color field, click the icon on the right and select or create a color.

User Guide | 31

Chapter 2 Creating and Editing APF Packagesc.

In the Table Background field, click the icon on the right and select or create a color.

d.

In the Text field below Table Background, select a cell in the grid and enter the applicable text,
value, or formula.

e.

In the Color field, click theicon to select or create a corresponding color.

You can add multiple items, such as markers, to the grid and configure each item to appear in one ormore corresponding colors.

2.

To insert or delete a row or column, select a cell and right-click, and then select an option from the
pop-up menu.

32 QX Designer Software

Custom Results Screen

As you add to the grid, you can select a cell to configure text and color.

Note: As an Advanced feature, each of the color boxes in Custom Results accepts conditional
formatting in similar syntax to Custom Calculations. For example, to present Output1.Value in agreen color if the value is below 1, you can enter the conditional formatting as follows:
if (Output1.Value < 1 ){Return = "Green";}{
Return = "Black";}

3.

Repeat Step 4 to add another header definition.

User Guide | 33

Chapter 2 Creating and Editing APF Packages

Custom Reports Screen
You can create custom reports to display data from the categories you created in Custom Results.

To create a custom report
1.

Click the Custom Reports tab and enter a report title and a brief report summary description.

2.

Click thesign next to Custom Result and select from the custom results entries in the dropdown

list.

3.

Repeat Step 2 to add another custom report.

34 QX Designer Software

Appendix A External Clustering Algorithms
For customers interested in developing their own droplet clustering protocols, QX Designer Software
supports the ability to integrate external, custom clustering scripts into APFs. This section explores theimportant components involved in integrating external custom cluster analysis with APFs, and byextension, QX Manager Software, Premium Edition. External clustering is currently supported for twochannels only (Ch1 and Ch2), for the DropOff and Double Dropoff assay types..
Note: External Clustering Algorithm is an advanced feature that requires proficiency in programmingand bioinformatics.

Generating Threshold Clusters
To perform droplet data clustering externally, the APF and QX Manager Software, Premium Edition, must
be able to transfer data between the external application (such as Python) and QX Manager Software,
Premium Edition. For APFs that utilize external clustering, QX Manager Software, Premium Edition, sets
up a communication channel that allows the Python application to retrieve unclustered droplet data,assign clusters as determined by the user’s algorithm, and then send the clustered droplet data back to
QX Manager Software, Premium Edition, for downstream analysis.
To support this workflow, Bio-Rad provides two important files to assay developers:n

DataConnection.pyn

BioRad.IPC.Shared.dll

DataConnection.py
DataConnection.py, which is stored on the QX Designer Software USB drive, is a critical component in thecommunication between QX Manager Software, Premium Edition, and the external Python script used forcustom cluster analysis. The script is responsible for sending and receiving the ddPCR data, andestablishes a communication channel using a shared memory space provided by the
BioRad.IPC.Share.dll library. This communication channel is essential for transferring ddPCR data
between the two applications, including the unclustered input data and the resulting output data from thecustom clustering script.

User Guide | 35

Appendix A External Clustering Algorithms

DataConnection.py also performs data format conversions, as necessary, to ensure the data can beprocessed correctly by both applications. DataConnection.py converts the ddPCR data from the internal
data format of QX Manager Software, Premium Edition, to a JSON format that can be read by the external
Python script. Likewise, it converts the cluster analysis results generated by the customer’s external scriptfrom JSON format to the format expected by QX Manager Software, Premium Edition.

BioRad.IPC.Shared.dll
BioRad.IPC.Shared.dll enables communication between QX Manager Software, Premium Edition, andthe external Python script, allowing the exchange of data and the integration of custom analysis
algorithms into QX Manager Software, Premium Edition.
BioRad.IPC.Shared.dll is a .NET assembly, which is included in QX Designer Software, Premium Edition,and is used in the communication mechanism between the software and the external Python script.
Specifically, it provides an inter-process communication (IPC) mechanism to facilitate the transfer of data
between the two applications. It can act as server as well as client, with bi-directional data transfer
capabilities.
IPC allows multiple processes or applications to communicate with each other and share resources. In
this case, BioRad.IPC.Shared.dll is used to establish a named pipe connection between QX Manager
Software, Premium Edition, and the external Python script. This connection enables data to be passed
securely between the two applications.
QX Manager Sotware, Premium Edition creates the communication channel using a unique channelname or identifier. The identifier is passed to the Python application as a required argument. With the helpof DataConnection.py, the Python main script uses the identifier to create and connect to the named pipeand establishes the communication channel. Once the connection is established, data can be sent andreceived using the methods provided by DataConnection.py.

36 QX Designer Software

Python Startup Script

Python Startup Script
Assay developers use the two files, DataConnection.py and BioRad.IPC.Shared.dll, in their Python script,
which is the starting point for the python application. In this script the following tasks are performed:
1

Importing the necessary modules and classes, including DataConnection.py2Creating an instance of the DataTransferConnection class to establish a connection withQX Manager Software, Premium Edition

3

Importing the data passed to the application through command-line arguments

4

Converting the data to a suitable format for performing the cluster task

5

Performing the cluster task to generate cluster groups

6

Converting the output cluster groups to a suitable format for exporting

7

Transfer the output cluster groups to QX Manager Software, Premium Edition, through theestablished connection.

User Guide | 37

Appendix A External Clustering Algorithms

Workflow
Following is the workflow for the Python application:
1

QX Manager Software, Premium Edition, extracts the cluster generation engine from the
APFackage into a temporary location.

2

Before starting the cluster generation engine, QX Manager Software, Premium Edition, opens a
communication pipe with a unique identifier. QX Manager Software, Premium Edition, uses the
DataTransferConnection class inside the BioRad.IPC.Shared.dll, which has the necessary
implementation for creating a pipe with the given unique name. This named pipe provides a way tocommunicate securely between processes.
Note: The unique pipe identifier is only accessible to an external Python process when it islaunched by QX Manager Software, Premium Edition.

3

When QX Manager Software, Premium Edition, starts the external module executable engine in thetemporary location, it passes the unique identifier of the communication pipe as an argument.

4

The Python application creates an instance of the DataTransferConnection class imported from
BioRad.IPC.Shared.dll with the provided communication channel name, and then establishes aconnection with QX Manager Software, Premium Edition.

5

QX Manager Software, Premium Edition, monitors the communication channel connection and theengine process during the execution period. Once the engine establishes a connection to thecommunication pipe, QX Manager Software, Premium Edition, prepares the required data to send
through the pipe.

6

QX Manager Software, Premium Edition, passes the necessary data in JSON format to the Python
application through the communication pipe.

7

The Python application imports the JSON data and converts it to a suitable format (such as NumPy)for performing the cluster task.

8

The Python application performs the cluster task to generate cluster groups for all the wells, andconverts the newly clustered data back to the JSON format for transfer back to QX Manager
Software, Premium Edition.

9

The Python application uses the DataConnection class methods to export the output cluster groups
to QX Manager Software, Premium Edition, through the established connection.

38 QX Designer SoftwareError Handling

10

QX Manager Software, Premium Edition, receives the data through the communication pipe fromthe external Python process module.

11

The Python process module then ends its execution and QX Manager Software, Premium Edition,and closes the communication pipe.

12

The generated cluster data is available as needed for the rest of the analysis process within
QX Manager Software, Premium Edition.

Fig. 1: Data pathway diagram

Error Handling
QX Manager Software, Premium Edition, handles errors by checking the return values from thesubprocess calls and raising an exception if an error occurs. The errors are logged for further analysis. QXManager Software, Premium Edition, also handle errors related to the communication pipe.

User Guide | 39

Appendix A External Clustering Algorithms

Data Formats
Following is an example JSON data structure when QX Manager Software, Premium Edition, sends theunclustered data to Python application.

Class: AutoClusteringInput
This class represents the input data for the auto clustering process, and contains the following properties:n

WellDescriptions — an array of WellMetaData objects. It provides information about the wells,
including their metadata (sample type, target names, well index, and so forth). Each element in thearray represents a specific well in the auto clustering process.

n

WellDropletData — an array of WellDropletInputData objects. It contains the input data for each well,including the amplitudes of droplets in different channels and the well index. Each element in thearray corresponds to a specific well.

Fig. 2: Auto clustering input JSON

40 QX Designer Software

Data Formats

Class: WellMetaDatan

SampleType — This property represents the type of sample present in a well. It is a string value that
describes the sample in a human-readable format.

nTargetNames — This property is an array of strings that holds the assigned target names associatedwith the well. Each element in the array represents a target name, providing additional information
about the samples present in the well.

n

WellIndex — This property serves as a unique identifier for a well. It is an integer value ranging from 0
to 95, representing the different wells in the system.

Class: WellDropletInputDatan

Amplitudes — a two-dimensional array of floats. The first dimension represents the channels and thesecond dimension represents the droplets within each channel. For a given well, each channel might
have multiple droplets, and their corresponding amplitudes are stored in this array. The size of thearray varies, depending on the number of channels and droplets in each channel.

nWellIndex — Similar to the WellMetaData class, this property represents the unique identifier of awell and helps associate the input data with the corresponding well.

Following is an example JSON data structure when the Python application sends the clustered data backto QX Manager Software, Premium Edition.

Class: AutoClusteringOutput
This class represents the output data of the auto clustering process. It contains the following properties:n

Results — an array of WellDropletOutputData objects. It contains the clustering results for each wellin the auto clustering process. Each element in the array corresponds to a specific well, providing theoutput data related to clustering.

Fig. 3: Auto clustering output JSON

User Guide | 41

Appendix A External Clustering Algorithms

Class: WellDropletOutputDatanDropletResults — an array of integers that represents the clustering results for each droplet in a well.
Each element in the array corresponds to a droplet and indicates its assigned cluster. The size of thearray is the same as the number of droplets in the well.
Cluster labels range from 0-3:
All Negative = 0
Fam Mutant = 1
Wild Type = 2
Hex Mutant = 3
Important: Clustered data must be sent in the same target names order as specified in
WellMetaData class aboven

Message — a string that holds a message associated with the clustering results. When a wellclustering process is unsuccessful, additional information indicates the reason for the failure. The
message is empty when the cluster process is successful.

nSuccess — a boolean value that indicates the success or failure of the clustering process for a well. If
the clustering process is successful, the value is True and if unsuccessful, the value is False.

n

WellIndex — represents the unique identifier of a well to associate the clustering results with thecorresponding well.

Conclusion
The use of external thresholding applications for generating cluster groups in QX Manager Software,
Premium Edition, provides a flexible and powerful way to perform complex data analysis. The application
can be customized and extended to perform a wide range of data analysis tasks, as needed, for the
specific assay types analysis. This feature is a valuable addition to QX Manager Software, Premium
Edition.

42 QX Designer Software

Appendix B Tips for Custom Calculations
QX Designer Software allows APF developers to create custom calculations using a simple scripting
grammar that can be applied to the ddPCR data of your experiment. This section includes the syntax andoperators supported by the Custom Calculation scripting language.

Supported Operators
You can use the operators specified in the following table in your custom formulas.
Table 2. Supported operators

Name

Operators

Assignment operator=

Comparison operators

==
<>
<
>
<=
>=

Logical operators|&

Math operators

+
*
/
^

log(x,y)log base y of xlog2(x)log base 2 of x

log10(x)log base 10 of xln(x)natural log of xabs(x)

absolute value of xUser Guide | 43

Appendix B Tips for Custom Calculations

Additionally, the following can apply:

Name

Operators

Keywords

IF, ELSE

Grouped expressions{and}Grouped statements{ and }IF and ELSE clausesStatements end with a semicolon (;)

Boolean literals

TRUE
FALSE

String literals"Hello world"
Character sequences enclosed by double quote

Number literals

1, 0, -8.44

Note: All math operators use standard order of operations and associativity. When in doubt, use
parentheses to enforce your own order of operations.

Input Variables
Targets are identified by Tx, with the x replaced by 1, 2, 3, and so forth. The target identifier should
precede the variable; for example, T1.CpPerµl.

Variable

Description

Positives

Number of droplets that contain the target

Negatives

Number of droplets that do not contain the target

Observed copies

Copies per droplet * accepted droplets

CpPerµLMax95

Copies per droplet * accepted droplets; max 95% confidence

CpPerµL

Well concentration in copies per µl

Ratio

Ratio of target over reference.

PoissonRatioMax

Maximum ratio of the unknown against the reference
normalized for the high error bar of the droplet Poisson
distribution for the 95% confidence interval

44 QX Designer Software

Variable

Description

PoissonRatioMin

Minimum ratio of the unknown against the reference
normalized for the low error bar of the droplet Poisson
distribution for the 95% confidence interval

FractionalAbundance

Calculation of fractional abundance of this unknown target
vs. the reference target

PoissonFractionalAbundanceMax

Maximum fractional abundance normalized for the high error
bar of the droplet Poisson distribution for the 95%
confidence interval

PoissonFractionalAbundanceMin

Minimum fractional abundance normalized for the low error
bar of the droplet Poisson distribution for the 95%
confidence interval

PgPerulMolecular weight

CopiesPer20 µL

Concentration of the target normalized to a volume of 20 µL

TotalConfMax

For merged wells the high error bar for the target
concentration of the combined wells at a 95% confidence
interval

TotalConfMin

For merged wells the low error bar for the target
concentration of the combined wells at a 95% confidence
interval

PoissonConfMax

Maximum target concentration normalized for the high error
bar of the droplet Poisson distribution for the 95%
confidence interval

PoissonConfMin

Minimum target concentration normalized for the low error
bar of the droplet Poisson distribution for the 95%
confidence interval

CNV

Copy number calculated for the target relative to thereference

TotalCNVMax

For merged wells, the high error bar for the copy number ofthe combined wells at a 95% confidence interval

TotalCNVMin

For merged wells, the low error bar for the copy number ofthe combined wells at a 95% confidence interval

User Guide | 45

Appendix B Tips for Custom Calculations

Variable

Description

PoissonCNVMax

Maximum copy number normalized for the high error bar ofthe droplet Poisson distribution for the 95% confidence
interval

PoissonCNVMin

Minimum copy number normalized for the low error bar ofthe droplet Poisson distribution for the 95% confidence
interval

ReferenceCopies

Copy number identified for the reference target in the Plate
EditorDefault is 2, indicating 2 copies per diploid genome.

TotalRatioMax

For merged wells the high error bar for the ratio of theunknown against the reference of the combined wells at a95% confidence interval

TotalRatioMin

For merged wells the low error bar for the ratio of theunknown against the reference of the combined wells at a95% confidence interval

TotalFractionalAbundanceMax

For merged wells the high error bar for the fractional
abundance of the combined wells at a 95% confidence
interval

TotalFractionalAbundanceMin

For merged wells the low error bar for the fractional
abundance of the combined wells at a 95% confidence
interval

TotalConfidenceMax68

For merged wells the high error bar for the target
concentration of the combined wells at a 68% confidence
interval

TotalConfidenceMin68

For merged wells the low error bar for the target
concentration of the combined wells at a 68% confidence
interval

PoissonConfidenceMax68

Maximum target concentration normalized for the high error
bar of the droplet Poisson distribution for the 68%
confidence interval

46 QX Designer Software

Variable

Description

PoissonConfidenceMin68

Minimum target concentration normalized for the low error
bar of the droplet Poisson distribution for the 68%
confidence interval

TotalCNVMax68

For merged wells the high error bar for the copy number ofthe combined wells at a 68% confidence interval

TotalCNVMin68

For merged wells the low error bar for the copy number ofthe combined wells at a 68% confidence interval

PoissonCNVMax68

Maximum target concentration normalized for the high error
bar of the droplet Poisson distribution for the 68%
confidence interval

PoissonCNVMin68

Minimum target concentration normalized for the low error
bar of the droplet Poisson distribution for the 68%
confidence interval

TotalRatioMax68

For merged wells the high error bar for the ratio of theunknown against the reference of the combined wells at a
68% confidence interval

TotalRatioMin68

For merged wells the low error bar for the ratio of theunknown against the reference of the combined wells at a
68% confidence interval

PoissonRatioMax68

Maximum ratio of the unknown against the reference
normalized for the high error bar of the droplet Poisson
distribution for the 68% confidence interval

PoissonRatioMin68

Minimum ratio of the unknown against the reference
normalized for the low error bar of the droplet Poisson
distribution for the 68% confidence interval

TotalFractionalAbundanceMax68

For merged wells the high error bar for the fractional
abundance of the combined wells at a 68% confidence
interval

TotalFractionalAbundanceMin68

For merged wells the low error bar for the fractional
abundance of the combined wells at a 68% confidence
interval

User Guide | 47

Appendix B Tips for Custom Calculations

Variable

Description

PoissonFractionalAbundanceMax68

Maximum fractional abundance normalized for the high error
bar of the droplet Poisson distribution for the 68%
confidence interval

PoissonFractionalAbundanceMin68

Minimum fractional abundance normalized for the low error
bar of the droplet Poisson distribution for the 68%
confidence interval plate list after correcting the issue

Well Type-Based
The following variables are Well Type-based have the following format: WT1.Variable(T1.AcceptedDroplets)n

Ch1PosCh2Posn

Ch1NegCh2PosnCh1PosCh2Negn

Ch1NegCh2NegnAcceptedDroplets

Special Variables
The following variable is a special variable that can output calculation for linkage between any two targets
within the same well type (example syntax = T1.LinkageWith.T2):nLinkageWith

48 QX Designer SoftwareOutputs
Outputs from the custom calculations are indicated by the keyword Output. The term Output is always
followed by a number, which should start with one and increment by one with each new output.
Each output has a Name and a Value, as shown below:
Output1.Name = “My Output One”;
Output1.Value = “Output One Value”;
Output2.Name = “My Output Two”;
Output2.Value = 3.14;
Note the following:n

The names must be configured as strings, and must be identical across all samples.

n

The values can be numbers, strings, or booleans.

n

For each specified output, one column is added to the export CSV, and is named as the output isnamed.

nEach line of the CSV that corresponds to a sample is given a value in that column, according to thevalue provided in the custom code.
BAT25LOB = 2.11;
BAT26LOB = 0.34;
NR21LOB = 2.38;
NR24LOB = 1.51;
Mono27LOB = 0.56;
DoubleDropoffWTFactor = .5;

BAT25FA = T1.CpPerUl / ((T3.CpPerUl * DoubleDropoffWTFactor) + T1.CpPerUl);
BAT25Positive = BAT25FA > BAT25LOB;
Output1.Name = "BAT25 Fractional Abundance";
Output1.Value = BAT25FA;
BAT26FA = T2.CpPerUl / ((T3.CpPerUl * DoubleDropoffWTFactor) + T2.CpPerUl);
BAT26Positive = BAT26FA > BAT26LOB;
Output2.Name = "BAT26 Fractional Abundance";
Output2.Value = BAT26FA;

User Guide | 49

Appendix B Tips for Custom Calculations

NR21FA = T4.CpPerUl / ((T6.CpPerUl * DoubleDropoffWTFactor) + T4.CpPerUl);
NR21Positive = NR21FA > NR21LOB;
Output3.Name ="NR21 Fractional Abundance";
Output3.Value = NR21FA;
NR24FA = T5.CpPerUl / ((T6.CpPerUl * DoubleDropoffWTFactor) + T5.CpPerUl);
NR24Positive = NR24FA > NR24LOB;
Output4.Name = "NR24 Fractional Abundance";
Output4.Value = NR24FA;
Mono27FA = T7.CpPerUl / (T8.CpPerUl + T7.CpPerUl);
Mono27Positive = Mono27FA > Mono27LOB;
Output5.Name = "Mono27 Fractional Abundance";
Output5.Value = Mono27FA;
Output6.Name = "BAT25 Status";
Output6.Value = "Negative";
Output7.Name = "BAT26 Status";
Output7.Value = "Negative";
Output8.Name = "NR21 Status";
Output8.Value = "Negative";
Output9.Name = "NR24 Status";
Output9.Value = "Negative";
Output10.Name = "Mono27 Status";
Output10.Value = "Negative";
NumberPositive = 0;
if (BAT25Positive){
NumberPositive = NumberPositive + 1;
Output6.Value = "Positive";}
if (BAT26Positive){
NumberPositive = NumberPositive + 1;
Output7.Value = "Positive";}

50 QX Designer Softwareif (NR21Positive){
NumberPositive = NumberPositive + 1;
Output8.Value = "Positive";}
if (NR24Positive){
NumberPositive = NumberPositive + 1;
Output9.Value = "Positive";}
if (Mono27Positive){
NumberPositive = NumberPositive + 1;
Output10.Value = "Positive";}
Output11.Name = "Microsatellite Instability Status";if (NumberPositive <= 1)
Output11.Value = "MSS";
else
Output11.Value = "MSI-H";

User Guide | 51

Appendix B Tips for Custom Calculations

52 QX Designer Software

Appendix C Well Metric Options in Quality Rules
As part of configuring quality rules, Table 3 explains the dropdown list options when Well Metric isselected as the Metric Source in the Quality Rules screen.

The metric you choose serves as a basis for calculations and their reliability.
Important: When selecting a Ch(x) well metric, the calculation is based on droplet or target counts,
or by assay, in the selected channel.

User Guide | 53

Appendix C Well Metric Options in Quality Rules

Table 3. Options in the Well Metric dropdown list

Selection

Calculation basis and outcome

None

No specified selection

SampleName

Groups and calculates by sample name

SampleTypeGroups and calculates by the selected sample types:
n Unknown
n NTC (no template control)n Pos Ctrl
n Neg Ctrl

WellType

Uses an overall well type for calculations (Plate, Well,
or Sample)

AcceptedEvents

Total number of events accepted by the quality
algorithm.

MeanAmplitudesCh(x)Mean (average) amplitude value of targets

MeanAmplitudesCvCh(x)Mean (average) amplitude value of targets, withstandard deviation ratio (Cv) included

PositivePeaksCh(x)Positive peak value

NegativePeaksCh(x)Negative peak value

PositiveAmplitudeMeanCh(x)Mean (average) positive amplitude

PositiveAmplitudeMedianCh(x)Median (middle) positive amplitude

PositiveAmplitudeCvPctCh(x)Positive amplitude with standard deviation
percentage

NegativeAmplitudeMeanCh(x)Mean (average) negative amplitude

NegativeAmplitudeMedianCh(x)Median (middle) negative amplitude

NegativeAmplitudeCvPctCh(x)Negative amplitude with standard deviation
percentage

SValueCh(x)54 QX Designer Software

Not available

Selection

Calculation basis and outcome

ConcentrationCh(x)Concentration of the target molecules recorded as
copies per microliter.

Ratio

The ratio of the targets against the identified
reference

CnvCh(x)Copy number variation value of targets
By count, where

nnCount

n Both targets are negative

pnCount

n Target 1 is positive and Target 2 is negative

npCount

n Target 1 is negative and Target 2 is positive

ppCount

n Both targets are positive
By mean (average), where

nnMeanCh(x)n Both targets are negativepnMeanCh(x)n Target 1 is positive and Target 2 is negative

npMeanCh(x)n Target 1 is negative and Target 2 is positiveppMeanCh(x)n Both targets are positive
By mean (average) standard deviation percentage fordroplet concentration. where

nnCvPctCh(x)n Both targets are negative

pnCvPctCh(x)n Target 1 is positive and Target 2 is negative

npCvPctCh(x)n Target 1 is negative and Target 2 is positive

ppCvPctCh(x)n Both targets are positive
By standard deviation, where

nnSdCh(x)n Both targets are negative

pnSdCh(x)n Target 1 is positive and Target 2 is negative

pnSdCh(x)n Target 1 is negative and Target 2 is positive

pnSdCh(x)n Both targets are positive

DoubleNegShiftExternalNormCh(x)Not available

SinglePosShiftExternalNormCh(x)Not available

CpdCh(x)Copies per droplet

ObservedCopiesCh(x)Copies per droplet * accepted dropletsUser Guide | 55

Appendix C Well Metric Options in Quality Rules

Selection

Calculation basis and outcome

DropletVolume

Partitioned volume of droplets, used to measure CNV

ThresholdStabilityCONFRoomAboveCh(x)Not available

ThresholdStabilityCONFRoomBelowCh(x)Not available

ThresholdStabilityCONFNormRoomAboveCh(x)Not available

ThresholdStabilityCONFNormRoomBelowCh(x)Not available

ConcentrationPerTarget (1)Concentration of the target molecules recorded as
copies per microliter

FractionalAbundancePerTarget (1)Calculation of fractional abundance of the unknown
target vs. the reference target

ObservedCopiesPerTarget (1)Number of observed copies of the selected target

DropletsPerTarget (1)Droplet count for each target(1)To define a quality rule based on a PerTarget metric, you must create the rule under the Quality Value,

Calculate Based On, calculation type. This filters your quality rule for Metric =WellType, allowing you toselect a well type so the quality rule can populate the Target dropdown.

56 QX Designer Software

10000149015 Ver A

Sig 0123