Agilent, Gen5 Image Configuration Guide

Purpose 

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

Introduction

The Agilent Gen5 Image connector is a component used in the context of the Benchling Connect platform to parse imaging data from Agilent, BioTek imaging plate readers and automated microscopes using Gen5 Image Plus or Gen5 Image Prime software, 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 Image connector is a ‘file-based’ based connector, meaning that it processes text file (.txt) exports generated by the Gen5 Image Plus or Prime 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 Image 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 Image Plus/Prime

From within Agilent Gen5, a user must:

1. Configure a text file export compatible with the Benchling Connect, Agilent Gen5 Image connector.
2. Update Plate ID (recommended)
3. Execute the export of that file from their Gen5 session.
4. Ensure that the file is placed with the watched directory.

Supported Detection Methods / Read Modes 

Gen5 Image Plus and Prime 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. The Benchling Connect, Agilent, Gen5 Image connector is only capable of processing data recorded from imaging detection experiments.

Similarly, Read Modes including: endpoint, kinetic, area scan, and spectral scan. At present the Benchling Connect, Agilent Gen5 Image connector is only capable of processing data recorded from endpoint measurements.

Measuring multiple plates

Gen5 allows users to measure multiple plates within a experiment file (.xpt). The Benchling Connect, Agilent Gen5 Image connector 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.

Specific to imaging, Gen5 contains an Imager Manual Mode (imager manual mode file, .imm) that can be used to record images using the instrument as a manual microscope. The Imager Manual Mode is an 'on-the-fly' session within Gen5 that allows a user to pre-define/configure optical settings for capturing images as well as performing image analysis on captured images. From the Imager Manual Mode, a user can create an experiment file from the session which compiles all the defined parameter settings and analysis steps into experiment Read steps. It is advised to 'create experiment from an image set' if capturing images through Imager Manual Mode - .imm sessions do not allow export to the Gen5 Image connector compatible text files. 

Within Gen5, an experiment file can be created by either loading an existing protocol file, from the imager manual mode session or can be done ‘ad-hoc’, 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 Image 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.  

Note: While Gen5 Image Plus and Image Prime allows export of image files (.png, .jpg, .bmp, .gif, .emf, .tif) from the software, the Agilent Gen5 Image connector only supports processing of text file exports from Gen5 Image Plus and Image Prime. Also, as there is no information of image file referenced within the text file, it is not possible to report image file paths. Described below are the steps within Gen5 to export of the supported text file output.

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.

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. 

Saving image files from Gen5

When a Gen5 session is saved, all acquired images are automatically saved in Gen5's Image Library (by default C:\Gen5 Experiments\Imaging\Library). Raw images are automatically saved as 16-bit TIFFs in native grayscale.

Gen5 provides two ways to define the file naming and location of generated image files:

1. Global Settings: Select System>Preferences>Image Save Options (under Initial Protocol Settings)
2. Per Protocol setting (Protocol>Protocol Options>Image Save Options): to override the global setting, apply distinct save options to image files, or to reconnect an experiment with its images

Note: It is recommended to apply the global settings for saving images from Gen5

It is recommended that the Gen5 Image Library be a separate file path than the 'watched' directory configured via Connection within Benchling. This will help to avoid issues with storage as well as accessibility to files in the 'watched' directory.

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 Image connector on the tenant [internal admin console]

2. Configure a Gen5 Image Connection

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

4. 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.

Note: Since non-imaging results generated with Gen5 (including Gen5 Image Prime/Plus versions) are processed with a separate Benchling Connect - Agilent, Gen5 Connector, to process both imaging and non-imaging results (even if generated from the same instrument) will require the configuration of two separate Connections within Benchling.

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 Image 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 Image connector supports only the imaging-mode plate reader functionality of Gen5. For handling of the other multi-mode detections (absorbance, fluorescence, luminescence) see the Agilent, Gen5 Configuration Guide.

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/…/allotrope/schemas/plate-reader

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 'imaging detector' 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*
• Detector Distance Setting* - where applicable
• Transmitted Light Setting* - optical-imaging only
• Magnification Setting* - optical-imaging only
• Auto Focus Setting* - optical-imaging only
• Image Count Setting* - optical-imaging only
• Fluorescent Tag Setting* - optical-imaging only
• Exposure Duration Setting* - optical-imaging only
• Illumination Setting* - optical-imaging only
• Detector Wavelength Setting* - where applicable
• Excitation Wavelength Setting* - where applicable
• Detector Carriage Speed Setting* - where applicable
• 'Image Feature'(s) - these column header(s) will vary depending on the label used for feature(s) derived from images.

* To account for experiments with multiple measurements/device settings these columns will be duplicated (as needed) and will be annotated with a number for each measurement. 

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 Image connector, select Agilent Gen5 Image 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 Image Connector Requirements