Molecular Devices, SoftMaxPro Configuration Guide

Purpose 

To provide details about the necessary steps to implement the Molecular Devices SoftMax Pro connector for use with the Benchling Connect platform.

Introduction

The Molecular Devices (MD) SoftMax Pro connector is a component used in the context of the Benchling Connect platform to parse data from Molecular Devices plate readers to an Allotrope Simple Model (ASM) and make those data available within the Benchling UI in the context of a Run.

The Benchling Connect, MD SoftMax Pro connector is a ‘file-based’ based connector, meaning that it processes text file exports generated by the SoftMax Pro application. The data within the file export is then accessed by Benchling Connect through the use of a ‘watched’ file directory on the local computer hosting a Benchling Gateway, which has been configured via a Connection from within Benchling.

In order to successfully implement the MD SoftMax Pro connector for use with the Benchling platform, there are multiple steps that need to be followed across both the MD SoftMax Pro and Benchling user interfaces. 

This guide details the steps to be taken in both applications in order to configure the integration. 

Steps within MD SoftMax Pro

From within SoftMax Pro a user must:

(i) Perform a text file export compatible with the Benchling Connect, MD SoftMax Pro connector 

(ii) Ensure that the file is placed with the watched directory configured via a Benchling Connection.

MD SoftMax Pro file types and utilities

The MD SoftMax Pro software relies on the concepts of a data file (.sda) and a protocol file (.spr). All sessions within SoftMax Pro begin within a data file and all actions within the software including data acquisition and processing are performed from this context. If a user wishes to reuse the setting from a data file as a template for subsequent experiments, this can be done by saving as a protocol file using the ‘Save As’ operation. When a protocol file is opened within SoftMax Pro, it is immediately opened as a new session as a ‘Untitled’ data file.

Supported Read Modes 

SoftMax Pro allows users to perform experiments using different Read Modes including: endpoint, kinetic, area scan, and spectral scan. At present the Benchling Connect - MD SoftMax Pro connector is only capable of processing data recorded from endpoint and kinetic measurements.

Measuring multiple plates

SoftMax Pro allows users to measure multiple plates within a data file (.sda) either in the context of a single experiment or in multiple experiments. 

The Benchling Connect, MD SoftMax Pro connector now supports the processing of multiple plates per file. However, before exporting file with multiple plates it is highly recommended that the user update the default plate names used within SoftMax Pro to correspond with plate barcodes used in Benchling. The plate names provided in SoftMax Pro may correspond to existing plate barcodes in Benchling, or may represent barcodes they intend to register as part of the processing the file. The plate names used in SoftMax Pro will appear within the "well plate identifier" column in the data returned to Benchling (discussed below). Failure to do so will present challenges for associating the experimental data with the plate and associated entities within Benchling after the fact.

Formatting of Group Blocks

SoftMax Pro reports data as Raw, Reduced, and Group, where Group data represents results derived from experimental groups. The Group data is reported within separate tables within the SoftMax Pro file referred to as Group Blocks. 

The Benchling Connect, MD SoftMax Pro connector is able to process the data reported with the Group Blocks, however, the Group Block must include a WellPlateName column, which reports the plate name. The WellPlateName should be added a as new column in each Group Block with the formula syntax of !WellPlateName.

Exporting data from SoftMax Pro

The MD SoftMax Pro provides two options for exporting data: (i) the Auto Export utility will generate an export automatically at the conclusion of a data acquisition step, and (ii) the manual Export utility that allows users to generate an export at any time.

It is recommended that the user employ the Auto Export option. This will ensure that the export file required by the integration is created without the user needing to manually execute the export from within the UI (discussed below). This option also includes the measurement data currently supported by the Benchling Connect, MD SoftMax Pro connector.     

Configuring export using Auto Export

The MD SoftMax Pro provides two options for exporting data: (i) the Auto Export utility will generate an export automatically at the conclusion of a data acquisition step, and (ii) the manual Export utility that allows users to generate an export at any time.

It is recommended that the user employ the Auto Export option. This will ensure that the export file required by the integration is created without the user needing to manually execute the export from within the UI (discussed below). This option also includes the measurement data currently supported by the Benchling Connect, MD SoftMax Pro connector.

The Auto Export utility is accessed from the main menu (plate icon) at the top left of the SoftMax Pro UI. The first step is to ‘Activate’ the Auto Export to ensure that the export is executed at the completion of each read. Then the user must select Add to configure the export settings.

Next within the Auto Export properties the Assigned Folder should be the same folder used when configuring the Connection within Benchling. Under File Format it is necessary to change the output format to either .txt (plate) or .txt (list) from the default option of .sda.

Within the Save Options, the user may select Raw or Both. The Benchling Connect is not able to process files containing Reduced data without the accompanying Raw data. It is recommended that the  Create a New Document option is used and encouraged to append the Date and Time to the filename - although this is not necessary.

Finally, the user can select ‘OK’ and proceed with the experiment in SoftMax Pro.

At the conclusion of the session, it is recommended to save the file as a protocol file (.spr). In a subsequent session when the protocol file is loaded as a new data file the Auto Export parameters will be included.

Note that files generated by Auto Export do not include Group tables, which can be included in manually exported files. 

Performing manual file export

The alternative means of generating a file export from SoftMax Pro that is compatible with the Benchling Connect, SoftMax Pro connector is to perform a manual file export. 

The manual Export utility is also accessed from the main menu (plate icon) at the top left of the SoftMax Pro UI.

From within the Export modal, the user should select All Plates. The user may also choose to include All Groups if they wish to process data from the Group Blocks. The Benchling Connect - SoftMaxPro connector is not able to process contents from the Notes sections within the SMP export.

Within the Plate Data Options, the user may select Raw or Both. The Benchling Connect is not able to process files containing Reduced data without the accompanying Raw data.

For Output Format, either Columns or Plate may be used, but not XML. After clicking ‘OK’ the ‘Save As’ modal will load and the user must save the file as a .txt in the same folder used when configuring the Connection within Benchling.

Steps within Benchling

From within Benchling, a user must:

1. Enable the MD SoftMax Pro connector on the tenant [internal admin console]

2. Configure a SoftMax Pro Connection

3. Create a Result schema to structure the data to be recorded

4. Configure a Run schema to accept data from SoftMax Pro and records Results

For steps 1 and 2, please reference the Benchling Connect Installation Guide for details related to creating and installing a Gateway and configuring a Connection.

Create Result Schema for SoftMax Pro data

The Benchling Connect - MD SoftMax Pro connector uses the Allotrope Simple Model (ASM) to structure the information parsed from the SoftMax Pro file export. The data is handled in a two step process; step one from SoftMax Pro export to the .json based ASM, and step two from the ASM .json to a .csv file available for ingest to Benchling. 

The Benchling Connect - MD SoftMax Pro connector supports the multi-mode plate reader functionality of SoftMax Pro. Multi-mode plate readers are instruments that are capable of performing Absorbance, Fluorescence, and Luminescence measurements.

These data are structured using the Allotrope Plate Reader ASM data model. Details about the this ASM schema can be found here:

https://github.com/Benchling-Open-Source/allotropy/tree/main/src/allotropy/allotrope/schemas/adm

The connector then converts the ASM to a well file .csv, a measurement file .csv and optionally a group file .csv. The well file is structured such that each row of the file represents a well of the plate; and the measurement file is structured such that each row of the file represents a measurement. While the optionally generated group file represents the aggregate data derived from groups of wells representing experimental conditions.

For SoftMax Pro, the well file and measurement file will typically contain the following columns (if available within the data):

• Device identifier
• Model Number
• File Name
• Software Version
• ASM Converter Name
• ASM Converter Version
• Container Type
• Device Type
• Measurement identifier
• Measurement Time - SMP does not include a measurement time, so the default value is 1970-01-01T00:00:00Z
• Well Plate identifier - this refers to the plate name
• Location identifier - this refers to the well position
• Sample identifier
• Number of Wells 
• Compartment Temperature
• Detection Type - this will refer to Absorbance, Fluorescence, or Luminescence
• Detector Wavelength Setting - where applicable
  • In cases of experiments measured at multiple wavelengths, this column will be annotated with a number indicating the read.
• ‘Measurement’ - this column header will vary depending on the modality: absorbance, fluorescence, or luminescence - e.g absorbance_mAU
  • In cases of experiments measured at multiple wavelengths, the column will be annotated with a number indicating the read
• Elapsed Time (seconds)* - measurement data file only for kinetic measurements
• Absorbance (mAU)/Fluorescence (RFU)/Luminescence (RLU)* - measurement data file only for kinetic measurements
• ‘Reduced’ - this will correspond to the the Reduced data within SoftMax Pro

*Columns present in measurement data file for kinetic measurements, capture time series data per read interval

Sample files can be found here.

The well file will also include any columns from the Group Blocks which contain results corresponding to individual wells.

The group file will contain similar columns to the well file as well as columns from the Group Blocks which contain results corresponding to the group - an not individual wells.

The example below shows an example Result schema for an endpoint absorbance measurement, where the sample being measured is associated using a LookUp from the plate well.

Configure Run Schema to employ SoftMax Pro Connection

The Run schema can be created from the menu under Feature Settings.

As part of the Run schema creation, the user should specify 'MD SoftMax Pro' as the Connection Schema.

Configuring the Output File Processor

The configuration of the Output File Processor is similar to that of other Runs. The Record Results should be specified as the ‘Benchling action’, and the ‘Result schema’ should be set as a previously defined schema, or created at this point - as discussed in the following steps. the schema created in the earlier step. 

It is also possible to specify the ‘default instrument data type’ (e.g. well data) returned by the connector should be processed. This step is optional - but it eliminates the need for the user to make this selection on each time a file is imported via a Run.

Configuring Results Schema from within Run Schema

Note the screen shots in the following section are representative of the process and may not reflect column names as they will appear when using the Benchling Connect, SoftMax Pro connector.

• Click “Create new result schema” to create a new schema. 
• Click the dropdown where it specifies “Copy column headers from file” and select “From Instrument data”. 
  • This defines how you are providing Benchling the instrument file from which to create the schema.
  • A “Retrieve data” table will appear after selecting this option. This displays all accessible files from across all connections of the specified Connection Schema for this specific Run schema, unless otherwise specified. 

• Select the instrument file that you would like to base the Results schema upon and click “Next”

• Depending upon the Connection Schema used, your selected file may be offered in multiple data type formats. You can preview each data type format by selecting the file. Once the desired format is specified, select “Process”. 
• Select which column headers you would like to create Result schema fields for.
  • Specify the headers to exclude from the Result schema by selecting “Ignore”.
  • Specify the headers to create a Result schema field for by selecting “Schema Field: New result schema field”.
  • Optionally specify which fields are required for data ingestion. By default all fields will remain optional. 

• Select “Create Result Schema” once field mapping has been completed. Configure the details of the Result schema
  • Specify the Result schema name, add additional fields, remove fields, and/or update field names, requirements, multi-select settings, and definitions as desired
  • Select “Next” when complete
  • Specify the desired Access Policies
  • Select “Create Result Schema” when complete
  •  
• All of the output file columns used in the Result schema will be automatically created in the Run schema
  • Add any additional columns that you would like included from elsewhere
• Confirm the Result schema mapping is set as desired and select “Done”
  • Schema fields configured in the Result schema will automatically be set to map from the output file via the specification value “Use column from output file”
  • If mapping any data from other sources (such as Run schema fields) alter the specification value appropriately

Associating experimental data with entity using plate, well information

For cases in which sample information is not entered in the SoftMax Pro file, in order to associate the well-level measurements contained within the SoftMax Pro file with the appropriate entity in Benchling based off an existing plate in the Benchling Inventory - as shown in the sample Result schema (above), Transform steps must be added to the Output File Processor.

Configuring Transform to 'LookUp' Plate entered on Run

For cases in which neither sample nor plate information is not entered in the SoftMax Pro file, the plate information must be added to the Run itself. To do so, the following configuration steps must be followed:

• The Run schema must be configure with a Run Field to enter a Well Plate
• Additional Transform steps must be configured within the Output File Processor.

Note that this method is only appropriate for ingesting Softmax Pro files with a single plate, if multiple plates are present then the plate identifiers should be entered directly in Softmax Pro as discussed above.

First an ‘Add Column’ step is needed to capture the barcode of the plate that is entered on the Run. Since this barcode value needs to be repeated for each row of the file, ensure that the ‘Consolidate results into single row’ option is selected.

Proceed to the following steps

Configuring Plate Well format from Well and Plate information

When plate and well information are present, but in separate columns, a combination of a 'Duplicate' and 'Merge' step are used to create a column containing the plate well information in the necessary ‘barcode:well-coordinate’ format . Together the Transform steps would appear as shown below.  

Finally the column mapping may be manually if the desired columns are known. Alternatively, it is possible to load sample data from an existing Connection to use for column mapping. Additionally, if the Result schema has not been previously defined, it can be created at this point (as described above).

For the example shown above, the columns would be mapped to the ‘PlateBarcode’ and ‘PlateWell’ columns generated with the Transform steps, along with the ‘Wavelength’ and ‘Absorbance’ columns returned from the SoftMax Pro file.

Molecular Devices SoftMax Pro Connector Requirements

* This is the version of SoftMax Pro with which the connector has been developed and tested. The connector may work with other versions of SoftMax Pro, but that must be verified by the user.

Revision History

2023/10

Initial Version

2024/01 

Updated to detail:

• Support for multiple plates per SMP export file
• Support for processing group blocks within SMP export export
• Revised to stipulate use of Plate Reader ASM.

2024/07

Updated to detail:

• Support for generating measurement file .csv output

2024/09/18

Added Github testdata link

2024/09/27

Add description for support of kinetic measurements

• Add expected column headers:
  • Elapsed Time (seconds)
  • Absorbance (mAU)/Fluorescence (RFU)/Luminescence (RLU)