Purpose
To provide details about the necessary steps to implement the Agilent Gen5 connector for use with the Benchling Connect platform.
Introduction
The Agilent Gen5 connector is a component used in the context of the Benchling Connect platform to parse data from Agilent, BioTek 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, Agilent Gen5 connector is a ‘file-based’ based connector, meaning that it processes text file exports generated by the Gen5 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 Agilent Gen5 connector for use with the Benchling platform, there are several steps that need to be followed across both the Agilent Gen5 and Benchling user interfaces.
This guide details the steps to be taken in both applications in order to configure the integration.
Steps within Agilent Gen5
From within Agilent Gen5, a user must:
- Configure a text file export compatible with the Benchling Connect, Agilent Gen5 connector.
- Update Plate ID (recommended)
- Execute the export of that file from their Gen5 session.
- Ensure that the file is placed with the watched directory.
Supported Detection Methods / Read Modes
Gen5 allows users to perform experiments using different Detection Methods and Read Modes, depending on the configuration of the instrument being used.
Detection Methods include: absorbance, luminescence, fluorescence, alpha, and imaging. At present the Benchling Connect, Agilent Gen5 connector is only capable of processing data recorded from absorbance, luminescence, alpha, and fluorescence measurements. For handling of imaging detection see the Agilent, Gen5 Image Configuration Guide.
Similarly, Read Modes including: endpoint, kinetic, area scan, and spectral scan. At present the Benchling Connect, Agilent Gen5 connector is capable of processing data recorded from:
- Single-endpoint measurements from a single Read (Single-endpoint image below)
- Multi-endpoint measurement from multiple Reads (Multi-endpoint image below)
- Kinetic measurements
Single-endpoint
Multi-endpoint
Kinetic
At present the Benchling Connect, Agilent Gen5 connector is not capable of processing data recorded from multi-endpoints of the same Read, area-scans and spectral scans. Additionally, at present the connector is unable to processed data recorded from Gen5's Well-Mode procedure steps.
Measuring multiple plates
Gen5 allows users to measure multiple plates within a experiment file (.xpt). The Benchling Connect, Agilent Gen5 connect requires that each plate be exported as a separate .txt files - this behavior is enforced as of connector version 0.1.28. This requirement is in place to allow for capturing the Plate ID from the filename, since Gen5 does not otherwise include this information within the default export format. Options to ensure that multi-plate experiments are exported as separate files is discuss below.
Agilent Gen5 file types and utilities
The Agilent Gen5 software uses the concepts of a protocol file (.prt) and an experiment file (.xpt), where a protocol file defines as set of measurements and calculations to be performed with the instrument; while the experiment file is created when a user is executing a measurement with the instrument and stores the data and results generated during that session.
Within Gen5, an experiment file can be created by either loading an existing protocol file or can be done ‘on-the-fly’, where a user creates a new experiment file and defines all the parameters which are otherwise defined within a protocol file - the user is then given the option to save the new protocol file at the end of the session. For integrations using the Benchling Connect - Agilent Gen5 connector, it will be best practice for users to define a protocol file with the configurations necessary to generate a compatible file export.
Gen5 contains a utility called Export Builder to format the file for export. An export format must first be configured using the Export Builder before it is possible to export data from Gen5. While the Export Builder utility is available from within both the experiment file and protocol file UI, it is advised to configure the export within the protocol file so that the settings are easily reusable.
Configuring export using Export Builder
From within the Gen5 protocol file editor, the Export Builder is accessed from the clipboard icon within the top ribbon
The Export Builder utility is a multi-step modal. On the first step, the user should select:
New export to file
On the next step of the Export Builder modal are the Properties settings, these should be left as the default.
At the top left of the modal, there is an option to give the export format a name. Since it is possible to configure multiple export formats per Gen5 protocol, it is recommended to give this export format a name to associate it with the Benchling integration. If users require an alternative export format to be associated with the protocol file for another purpose, they can repeat the configuration steps in the Export Builder.
On the third step of the Export Builder modal are the Content settings, again these should be left as the default.
On the fourth step of the Export Builder modal are the Workflow options. This modal provides the option to Auto-execute and Export Mode.
It is recommended that the user select the ‘Auto-execute on completion of the procedure’ 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).
Within the Export Mode section, the user should select the option to export Each plate in a separate file. This will ensure that each plate can be reported in a file with a name including the Plate ID.
On the fifth step of the Export Builder modal are the File options. This step allows users to define a file type, file naming convention, as well as default location to place the file export.
The user should set the naming convention to start with the format <DATE>_<TIME>_PLATE_ID>_, this will enable capture of the Plate ID from the file name.
Note: Gen5 uses both 'Plate ID' and 'Barcode' as available labels, as a convention use of Plate ID is recommended. If Plate ID is not specified by the user, the well plate identifier column will be recorded from the Plate Number field from the instrument file (e.g. "Plate 1").
Additionally, the user should leave the file extension as .txt - the default setting.
Under File Location the destination folder specified should be the same folder that will be used when configuring the Connection within Benchling. It is recommended to place these folders within the C:\Users\Public\Documents directory since this location does not require Administrative rights to create new files and folders.
The user may choose the options under Prompt user to validate pathname that they prefer. However, as a note of caution, if these settings are modified while the Auto-Execute option (previous step) is chosen AND the file naming convention does not generate unique file names, then the export file will be overwritten by subsequent exports without notification.
In the final step of the Export Builder modal are the Format settings, again these should be left as the default.
Recording Plate ID within Gen5
When performing an experiment within Gen5, the Plate ID information should be recorded as part of the Plate Information within the .xpt file. The Information view is accessed by the sidebar within the experiment.
The Plate ID is then recorded within the modal that is launched from the sidebar. Note, if the instrument is equipped with a barcode scanner, it is possible for this information to be captured as part of the plate read.
Performing file export from Gen5
Following the completion of a read the file export is executed from the experiment file UI by selecting the export icon from the top ribbon. If Auto-execute was configured with step (4) of the Export Builder modal (above), then this action should not be necessary.
Steps within Benchling
From within Benchling, a user must:
-
Enable the Agilent Gen5 connector on the tenant [internal admin console]
-
Configure a Gen5 Connection
-
Create a Result schema to structure the data to be recorded
-
Configure a Run schema to accept data from Gen5 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.
Creation of Result schema for Gen5 data
In order to record results returned via the integration a Result schema must be created. This can be done prior to configuration of the Run schema, or within the context of the Run schema Output File configuration.
The Benchling Connect - Agilent Gen5 connector uses the Allotrope Simple Model (ASM) to structure the information parsed from the Gen5 file export. The data is handled in a two step process; step one from Gen5 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 - Agilent Gen5 connector supports the multi-mode plate reader functionality of Gen5. 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 (REC/2024/06). 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, structured such that each row of the file represents a well of the plate; and a measurement file .csv, in which each row of the file represents a measurement.
The well file and measurement file can contain the following columns (if available within the data):
- Measurement Identifier - this is a UUID generated as part of data conversion
- Measurement Time
- Device Type - this will be 'plate reader' in all cases
- Analytical Method ID - this corresponds to the Gen5 protocol name
- Experimental Data ID - this corresponds to the Gen5 experiment name
- Container Type - this will be 'well plate' in all cases
- Plate Well Count
- Well Plate Identifier
- Location Identifier
- Sample Identifier
- Compartment Temperature
- Detection Type - this will refer to Absorbance, Fluorescence, or Luminescence
- Detector Wavelength Setting* - where applicable
- Detector Bandwidth Setting* - where applicable
- Excitation Wavelength Setting* - where applicable
- Excitation Bandwidth Setting* - where applicable
- Detector Carriage Speed Setting* - where applicable
- ‘Measurement’* - this column header will vary depending on the modality: absorbance, fluorescence, or luminescence - e.g absorbance_mAU
- ‘Calculated Results’ - this will be one or more columns with names defined within the Gen5 protocol for the measurement ‘labels’ and data reduction ‘data sets’
- Elapsed Time (seconds)** - measurement data file only for kinetic measurements
- Absorbance (mAU)/Fluorescence (RFU)/Luminescence (RLU)** - measurement data file only for kinetic measurements
* To account for experiments with multiple measurements these columns will be duplicated (as needed) and will be annotated with a number for each measurement.
**Columns present in measurement data file for kinetic measurements, capture time series data per read interval
Sample files can be found here.
Note: The calculated results (or "data reductions" - Gen5 terminology) included in the default export format only include 'well-level' values, and not results derived from groups of wells. Therefore, a group file is not returned by the Gen5 connector.
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 Gen5 Connection
The final step is to configure the Run schema to use the Gen5 Connection. This includes:
- Specifying the connector type
- Defining the Run Fields
- Configuring Input File Processor
- Configuring Output File Processor
Specifying Connector Type and Run Fields
When configuring the Run schema for use with the Gen5 connector, select Agilent Gen5 as the Connection Schema. The Run schemas are associated with a type of connector, rather than a specific Connection, so that Runs can be performed using any Connection of that particular type.
If the Plate ID is not being recorded in Gen5 (as discussed above) it is recommended to include Assay Plate as Run Field with field definition defined as the Inventory plate type that will be used. This is necessary for looking up samples within the plate for generating an Input file for Gen5 (optional) and for associating the data from the Gen5 file to the plate and associated sample entities in Benchling.
An example of the first portion of the Run schema is shown below.
Configuring the Input File Processor
In order to send sample information from Benchling to Gen5, it is necessary to configure an Input File within the Run schema that conforms to requirements of the import utility. While this step is optional, it allows for including Benchling identifiers directly within the original Gen5 experiment (.xpt) file.
The Gen5 utility for importing sample identifiers via a file has the following requirements and behavior:
- The sample identifiers must be in a .txt file without any headers
- Each sample identifier should be on a separate line
- Within the Gen5 protocol a ‘Plate Layout’ must be defined
- The import utility will only populate wells designated as ‘Samples’ (e.g. SPL1)
-
The import utility expects the number of samples in the .txt file to match the number of samples within the ‘Plate Layout’, any additional lines in the .txt file are ignored
- A 96 well with SPL1 : SPL96 expects a .txt with 96 lines - 1 per sample
- A 96 well with (2) replicates per sample, SPL1 : SPL48, expects a .txt with 48 lines
The example below shows a ‘Plate Layout’ within Gen5 with 96 samples
To generate the Input File with the sample entity names a LookUp step should be configured starting from wells of the Assay Plate within the Run Field as the source.
While the Input Table configuration requires a column header - “Sample Name” as shown in the example above, this column header can be removed to conform with the Gen5 requirements by using the ‘Extra headers’ Transform.
Additionally, the file extension and delimiter need to be set to ‘.txt’ and ‘Tab’.
When the Input File is created by the Run, it will be sent to the Input Directory on the local machine that was designated during Connection configuration.
To the sample names into the Gen5, the file should be imported from the ‘Sample IDs’ modal which is accessed from the plate information within the
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 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.
In order to use the plate barcode and plate well to associate the well-level measurements contained within the Gen5 file with the appropriate entity in Benchling - as shown in the sample Result schema (above) additional Transform steps must be configured.
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.
Note: If the Plate ID has been recorded in Gen5 (discussed above) then this information will be returned as the in Well Plate Identifier - eliminating the need for this 'Add Column' with LookUp to return the 'Plate Barcode'.
Next a combination of a ‘Duplicate’ and a ‘Merge’ step are used to combine the plate barcode with the well coordinates from the file, 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 may be done from this point as well.
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 Gen5 file.
Agilent Gen5 Connector Requirements
| Item | Specification |
| Gen5 | Gen5, Gen5 Image Plus, Gen5 Image Prime; version 3.12 or greater |
| Operating System | 64-bit Windows 10 or greater (per Agilent Gen5 requirement) |
| Memory | 2 GB RAM or greater (per Agilent Gen5 requirement) |
| Processor | Intel Core i5 or higher (per Agilent Gen5 requirement) |
| Gateway | Benchling Gateway installed on PC, able to communicate on port 443 |
Revision History
2023/08 Initial Version
2024/04
- Changes made to reflect behavior of Agilent Gen5 Connector v0.1.28
- Requirement for a single plate per export file
- Addition of Plate ID parsing from file name following standard naming convention
- Utilization of Plate Reader ASM format
- Updated fields returned within 'well data file' to correspond to those used in Plate Reader ASM
- Reversion of support for kinetic and spectral measurements
- Removed references to 'connection schema', 'adapter', and 'measurement file'
2024/08
- Additional changes made to reflect behavior of Agilent Gen5 Connector v0.1.28
- Context for support of endpoint measurements from a single endpoint, single read
- Update link to Plate Reader ASM schema
2024/09/03
Update link to referenced schemas in Github
2024/09/18
Added Github testdata link
2024/09/25
Add description for Gen5 mutli-endpoint read support
- Add image of support multi-endpoint reads
2024/09/27
Add description for support of kinetic measurements
- Add expected column headers:
- Elapsed Time (seconds)
- Absorbance (mAU)/Fluorescence (RFU)/Luminescence (RLU)
2024/10/07
- Add description for adapter recording of well plate identifier when Plate ID field is unspecified from user
- Update Plate Reader schema version adapter exports to as REC/2024/06