Configure the Output File Config of a Lab Automation Run

Note: Please read “Configure a lab automation run” for more general information about configuring the lab automation run.

What is an output file config?

An output file is a CSV where each row represents an action performed by a robot. For liquid handlers, each row represents a transfer operation: this means that each output file row specifies a source plate/container, transfer volume, usually a destination plate/container, along with other optional columns.

We map each column of each row of the output file to specific Benchling functions: registration, plate creation, and transfer. The output file ingestion functionality can register new samples, create new plates, and transfer the samples into the plates in the same action. Automation output files can be consumed by runs whose run schemas are configured to consume them.

The output file processor will take an action for each row of the output file. These actions can either be:

• Liquid handling actions. One or both of the following: Execute a transfer operation (decrement a source container by some volume, and move the contents to a destination container, or fill a destination container with a source entity)Register a new entity (this can be done by itself, or alongside a transfer)

• Analytical instrument actions. Create results associated with an entity

Entity schema fields may be populated either directly (as when importing to registry from spreadsheet) or from the contents of the source containers. Result schema fields may be populated with data directly from a spreadsheet.

The output file ingestion can be configured to register new entities or transfer existing entities to a new plate/container. When new entity registration is desired, one new entity will be registered for each unique destination container in the spreadsheet. Entity schema fields may be populated either directly (as when importing to registry from spreadsheet) or from the contents of the source containers.

Sources in output files are specified by container barcode, plate barcode and coordinates, both, or none. Source containers must already exist in Benchling Inventory before ingesting the output file.

Destinations may be specified by container barcode, plate barcode and coordinates, or both. A destination must be specified. Destination containers and plates do not need to preexist in Benchling Inventory: they will be created if they do not exist while existing empty containers and plates will be filled.

The containers, plates, and/or entities produced by ingesting the output file will be linked to the run as output samples. These will present as the RunOutputs as shown above.

Configure the output file config

Add an automationOutputFileConfigs to the schema, which is an object with the following properties:

• entitySchemaInfo: if specified, contains information about the entities to be created and registered. If not present, existing entities will be transferred rather than created

• resultSchemaInfo: If specified, contains information about results that will be created. If present, entitySchemaInfo may not be present, and no entities or transfers will be created

• name: the value to display in the UI (“pulling” in the example up top)use the same name in the inputFileConfig and the files will stack (as shown in the example up top)

• destinationInfo: if specified, contains information about the plates/containers to be created if not present, you must use existing destination plates/containers

• columnTypes: an array of strings, which are the column types present on the output file from left to right (top to bottom in the config). Exactly one of columnTypes or columnTypesByName must be present.

• columnTypesByName: a map from column header to column type. In this case the order of columns will not be respected and will instead be looked up by column header. Exactly one of columnTypes or columnTypesByName must be present.

• volumeUnits: the units of volume to transfer required if a TRANSFER_VOLUME_AMOUNT column is present

• tableType: controls the presentation of the run output table to be either one row per destination plate or one row per destination sample

• delimiter: single character, defaulting to (and hidden if set to) “,”. Controls the delimiter for parsing output files and saving processing files (if processing steps exist).

• fileExtension: a string defaulting to (and hidden if set to) “csv”. Controls the file extension for generated output processing files (if processing steps exist).

Configure the output file config using Graphical User Interface

The Lab Auto Configuration UI allows for customer admins to configure lab automation without writing in a custom domain specific language (JSON). Here is an overview of the output file configuration UI:

Step 1: Configure the display name
In this step, specify the name of the output file configuration. Giving the output file the same name as the input file allows the output file to stack on the run (appear under the same section header),

Step 2: Configure output table
First, specify the Benchling actions desired as an outcome of processing an output file (e.g. registering/updating entities, recording results, or a combination of those actions). Based on the selection, a model to configure Entity schema, Inventory schema, and/or Result schema information will open. This modal can be used to specify an action type (‘create new ’or ’use existing’) for the schema, location, name, and registry settings.
Note: If using a column from the output file as a value for a schema field, select the option “Use column from output file”.

Additionally, users can also specify whether the output table will display one row per sample (tableType: SAMPLE) or one row per plate (tableType: GRID).

Step 3: Apply transforms to the output file
Transforms (formerly known as Processing steps) can be performed on the output file prior to processing. Transforms are helpful when raw output files from instrument are not in the right dimensions to be processed (e.g. extra headers/footers).

Benchling offers some out-of-the-box transforms such as removing extra headers, filtering rows, pivot, and adding columns. Multiple transforms can be chained together; each transform will be completed in the order it is configured.
Note: if using the Custom transform, it must be the first transform.

Step 4: Configure column mapping
In step 4, columns in the output file can be mapped to Benchling actions. Columns can be specified “by column name” or “by column order”. For consistent naming between all runs, choose “by column name”. If column names are variable but the order of columns is consistent, choose “by column order”, which will ignore column names and instead look at columns in the output file from left to right.
Note: Schema fields will show up as options for column type if “Use column from output file” was selected for it in step 2.

After completing column mapping and closing the modal, a preview table of the columns and mappings will appear. To edit this, click the pencil icon on the table to open the “Set columns” modal.

Tips for configuring the output file config

• Determine the columns necessary for the output file prior to configuration

• Make sure that all of the information in the desired output file can be looked up from the values inputted into the run fields