Agilent, Gen5 Configuration Guide

Matt
Matt
  • Updated

Purpose 

To provide details about the necessary steps to implement the Agilent Gen5 adapter for use with the Benchling Connect platform.

Introduction

The Agilent Gen5 adapter 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 adapter is a ‘file-based’ based adapter, 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 adapter 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 (i) configure a text file export compatible with the Benchling Connect, Agilent Gen5 adapter, (ii) execute the export of that file from their Gen5 session, and (iii) ensure that the file is placed with the watched directory.

 

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 adapter, 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 the export as well as the option to export each plate as a separate file or all plates in a single file.

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 Each plate in a separate file option. The rationale being that Gen5 only includes generic plate identifiers (Plate 1, Plate 2) within the default export and this presents a challenge to associate the data from multiple plates within a single Gen5 export file with the corresponding plate objects in Benchling.  

The current strategy to address associating Gen5 data with plate objects in Benchling is through supplying the plate as a Run field, and associating the plate barcode through the use of LookUp Steps via a Transform Step defined within the Output File Configuration (discussed below).

 

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 can set the naming convention as they desire, but the file extension should be left 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




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:

  1. Enable the Agilent Gen5 adapter on the tenant [internal admin console]

  2. Create a Gen5 Connection schema (soon to be deprecated)

  3. Configure a Gen5 Connection

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

  5. Configure a Run schema to accept data from Gen5 and records Results

 

For steps 1 - 3, 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 adapter 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 adapter 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.

Note: the Benchling Connect - Agilent Gen5 does not support the imaging functionality of Agilent Gen5.

There are separate ASMs for each of the differ ‘modes’ in which Gen5 readers are able to perform measurements. Therefore, the data that will be available from the Benchling Connect - Agilent Gen5 adapter to correspond to the field within the respective ASM - UV/Absorbance, ASM - Fluorescence, and ASM - Luminescence models. 

Details about the these ASM schema can be found here:

https://github.com/Benchling-Open-Source/allotropy/…/allotrope/schemas/ultraviolet-absorbance/

https://github.com/Benchling-Open-Source/allotropy/…/allotrope/schemas/fluorescence/

https://github.com/Benchling-Open-Source/allotropy/…/allotrope/schemas/luminescence/

The adapter then converts the ASM to a well file .csv file, and optionally a measurement file .csv. The well file will be generated in all cases and is structured such that each row of the file represents a well of the plate. Additionally, in those cases of experiments where repeated measurements of a well have been performed - such as kinetic reads, the adapter will generate a measurement file where each row of the file represents a single measurement (with the well property repeated).

The well file can contain the following columns (if available within the data):

  • Measurement identifier
  • Measurement time
  • Analytical Method ID - this corresponds to the Gen5 protocol name
  • Experimental Data ID - this corresponds to the Gen5 experiment name
  • Plate Barcode
  • Container Type - this will be well plate in all cases
  • Num of Wells 
  • Well
  • Sample ID
  • Mass Concentration - refers to the defined concentration of conditions (e.g. standards)
  • Compartment Temperature
  • Read Type - this will refer to Absorbance, Fluorescence, or Luminescence
  • Wavelength - where applicable
  • ‘Processed Data’ - this will be one or more columns with names defined within the Gen5 protocol for the measurement ‘labels’ and data reduction ‘data sets’

The measurement file will contain the same columns, with repeated rows for each measurement per well.

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 adapter type
  • Defining the Run Fields
  • Configuring Input File Processor
  • Configuring Output File Processor
Specifying Adapter Type and Run Fields

When configuring the Run schema for use with the Gen5 adapter, select Agilent Gen5 as the Connection Schema.  The Run schemas are associated with a type of adapter, rather than a specific Connection, so that Runs can be performed using any Connection of that particular type. 

Next, 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, measurement data) returned by the adapter 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.

 

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 Adapter 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 

Was this article helpful?

Have more questions? Submit a request