Purpose 

To provide details about the necessary steps to implement the Thermo Chromeleon data connector for use with the Benchling Connect platform.

Introduction

The Thermo Chromeleon data connector is a component used in the context of the Benchling Connect platform to exchange data within the Thermo Chromeleon Chromatography Data System (CDS). Through the use of a Chromeleon ‘Connection’ in Benchling, a user is able to send data from Benchling to populate a sequence within the Chromeleon Console, parse data from Chromeleon to an Allotrope Simple Model (ASM) for liquid chromatography (LC), and make those data available within the Benchling UI in the context of a Run.

The Benchling Connect, Thermo Chromeleon data connector relies on an API-based integration, meaning that it is able to communicate directly with the Chromeleon application via methods provided by the Chromeleon application program interface. The benefit to the user is that once configured the interaction between Benchling and Chromeleon appears more seamless, with few actions that need to be performed by the user during each session.  

In order to successfully configure the Thermo Chromeleon data connector for use with the Benchling platform, there are several steps that need to be followed across both the Thermo Chromeleon and Benchling user interfaces. 

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

Steps within Thermo Chromeleon

Within Chromeleon, a Sequence represents a ‘worklist’ of samples - referred to as Injections - to be processed by the chromatography instrument. The Sequence object and constituent Injections serves as the interface through which the user specifies data acquisition and processing parameters, and retrieves data from previously measured samples.

For configuring the Benchling Connect, Thermo Chromeleon data connector, the principal step that must be performed within the Chromeleon UI is the creation of the directory in which the Benchling Connection will create new sequences and retrieve sequence data from.

Creating Sequence Folder: Chromeleon Console - Data View

Within the Chromeleon UI the Console serves as the starting point from which users access sequences, instruments, methods, reports and other objects represented in the application. data from previous experiments, and create sequences for new experiments.

The Chromeleon CDS relies on a local database for storing Chromeleon objects - referred to as a Data Vault - and displays these objects in a file-tree within the Data View panel of the Console.  

From within the Data View panel, a folder should be created to store data to be used in conjunction with the Benchling integration, and a sub-folder specifically for Sequences which will be the location that the Chromeleon data connector will read and write data to. In the example below the ‘_BenchlingConnectTesting’ represents the folder, and ‘Benchling_Sequences’ the sub-folder.

Steps within Benchling

From within Benchling, a user must:

1. Enable the Thermo Chromeleon data connector on the tenant [internal admin console]
2. Configure a Chromeleon Connection
3. Configure Dropdowns and Custom Entities
4. Create a Result schema for Chromeleon data
5. Configure a Run schema to employ Chromeleon Connection

Enable the Thermo Chromeleon Data Connector

To enable the Chromeleon data connector, as well as any other Benchling Connect data connectors, please reference the Benchling Connect Installation Guide for enabling data connectors via the Internal Admin Console, as well as details related to creating and installing a Gateway and configuring a Connection.

Configure a Chromeleon Connection

To configure a Chromeleon Connection create a new Connection from either the Connections side panel or global Create, and select the Thermo Chromeleon option. The Connection configuration modal prompts the user for (7) fields:

1. Connection Name
2. Benchling Gateway see previous step
3. Sequence Destination - the full path of the Sequence sub-folder
4. Vault Root - the full path of the parent folder in the Data Vault containing the sequence sub-folder
5. Per User Login Required - 'true' if User Mode is enabled on Chromeleon, 'false' if not
6. Username - The username used to login to Chromeleon if a shared account is used for User Mode enabled on Chromeleon
7. Password - The password used to login to Chromeleon if a shared account is used for User Mode enabled on Chromeleon

Note that the Sequence Destination and Vault Root are directory paths within the Chromeleon Data Vault and not the Windows Directory.  The most reliable way to access this information is to ‘right-click’ the folder within the Data View and select Properties, then select and copy the Location from the Folder Properties modal, and paste into the Connection configuration modal in Benchling.

Configure Dropdowns and Custom Entities

The Benchling Connect, Thermo Chromeleon data connector is able to define (10) properties of a Sequence when creating a new Sequence via the integration. Among these properties is Injection Type. Chromeleon supports an enumerated number of Injection Types and thus it is recommended to define these Injection Types via a Dropdown. 

The supported entries for Injection Type are:

• Unknown
• Blank
• CheckStandard
• CalibrationStandard
• Matrix
• Spiked
• Unspiked

Note, that these entries must be defined without spaces (e.g. CheckStandard, not Check Standard).

In order to capture all of the necessary data for generating an Injection via the integration, a ‘Chromeleon Injection’ custom entity should be configured within Benchling.

This custom entity should include: 

• Sample Entity - representing the biological entity being assayed
• Injection Type - referencing the Dropdown created in the previous step
• Spike Group - used to associate unspiked (unknown) injections with spiked injections
• Volume - the microliter volume of how much sample should be injected
• Weight - the sample weight to be accounted for in concentration calculations
• Dilution Factor - the correction factor for diluted samples
• Replicate ID - indicator for repeated injections from the same vial
• Comment - comment field for the injection  

Create Results schema for Chromeleon 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, Thermo Chromeleon data connector extracts data from Chromeleon and formats it according to the Allotrope Simple Model (ASM) for Liquid Chromatography (LC). Note, that the data connector is currently only able to extract data from Chromeleon that was collected using the UV/VIS detector channel. 

Details about the ASM LC schema can be found here: https://github.com/Benchling-Open-Source/allotropy/blob/main/src/allotropy/allotrope/schemas/.../liquid-chromatography.schema.json 

The data connector then converts the LC-ASM to (2) .csv files: an injection file in which each row represents an injection and a peak file in which each row represents a peak, aggregated across all injections.

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

• analyst
• submitter
• device identifier
• pump model number
• detector model number
• column part number
• column serial number
• device type
• detection type
• detection wavelength
• reference wavelength
• reference bandwidth
• detector offset
• detector sampling rate
• sample identifier
• sample name
• sample description
• injection id
• injection time
• injection volume

Any CustomField set on the injection will automatically be populated in the INJECTIONS output file.

The peak file can contain the following columns (if available) in addition to the columns within the injection file:

• peak name
• peak identifier
• retention time
• peak start
• peak end
• peak height
• peak area
• relative peak height
• relative peak area
• peak width baseline
• peak width half height
• peak width percentage
• asymmetry factor
• statistical skew
• Capacity factor

In most cases, the peak file will contain the most relevant information.

The example below shows a Results schema capturing: Sample Name, Injection ID, Injection Time, Peak Number, Retention Time, Peak Height, and Peak Area from a peak file.

Configure Run schema to employ Chromeleon Connection

The final step is to configure the Run schema to use the Chromeleon integration. This includes:

• Specifying the data connector type
• Defining the Run Fields
• Configuring Input File Processor
• Configuring Output File Processor

Specifying Data Connector Type and Run Fields

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

Next, Run fields for Sequence Name, Comment, and Injections should be included. Sequence Name is required as this is the name that will be used for the Sequence created within the Chromeleon UI. Injections is also required and should be designated as a ‘Multi-Select’ so multiple injection entities can be used in the Run. Additionally, Injections should be limited to the ‘Chromeleon Injection’ custom entity created in the previous step. Other Run fields may be added if necessary.

An example of the first portion of the Run schema is shown below.

Configuring the Input File Processor

In order to send information from Benchling to Chromeleon, the Run requires an Input File with the requisite information for defining the Sequence. The Input File must have these 10 columns:

• sequenceName
• sequenceComment
• name
• injectionType
• spikeGroup
• volume
• weight
• dilutionFactor
• replicateId
• comment

The sequenceName and sequenceComment are taken from the Sequence Name and Comment Run fields, while the remaining 8 fields should be drawn from LookUps starting from the Injections entry.

As the entries for sequenceName and sequenceComment must be repeated for each injection, ensure that the ‘Consolidate results into single row’ option is selected for these LookUp steps.

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. 

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 so from this point as well.

As the incoming .csv files have been formatted by the Chromeleon data connector, no formatting transforms should be necessary. However, Custom Transforms or Arithmetic transforms may be employed if additional calculations are required. 

An example of the Output File configuration is shown below.

Thermo Fisher Chromeleon Data Connector Requirements

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

Revision History

2024/09 Updates to include Chromeleon User Mode support, additional data capture from custom report values

2023/09 Initial Version