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 most often represents a transfer operation or event: this means that each output file row specifies a source plate/container, transfer volume, destination plate/container, along with other optional columns.
We map each column of each row of the output file to perform specific Benchling actions: registration, results recording, and sample transfer(s). The output file ingestion functionality can register new samples, record results, and transfer the samples into the plates in the same action.
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 can 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
Overview of output file configurations properties:
- Entity Schema Information: If registering entities, specify the entity schema.
- Result Schema Information: If recording results, specify the result schema.
- Output File Display Name: the name property is a label used within the user interface to identify the output file configuration. Matching this name with the input file configuration allows related files to be grouped together in the system, making them easier to manage.
- Destination Information: details about the plates or containers that will be created based on the output file. If this property is not specified, the configuration must utilize existing destination plates or containers within the system.
- Column Type: An array of strings indicating the types of columns present in the output file, arranged from left to right (or top to bottom in the configuration).
- Column Type by Name: column types can be defined by name using a mapping from column headers to column types, which allows for flexibility in the order of columns as they will be identified by header names instead of their sequence in the file
- Volume Units: this specifies the units of volume for transfers recorded in the output file. It's necessary when the file includes a column indicating the volume amount to be transferred.
- Table Type: Dictates how the run output table will be presented: either displaying one row per destination plate or one row per destination sample. This affects how information is visually organized and accessed in the user interface.w per destination plate or one row per destination sample
- Delimiter: A single character that sets the delimiter for parsing the output files. By default, this is a comma (","), but it can be changed to accommodate different file formats. This property is hidden if set to the default.
- File Extension: Indicates the file extension for generated output processing files. This property defaults to ".csv" and is hidden if set to this default value. This ensures consistency in file formats for processed output files.
Configure the output file config using the User Interface
The Connect 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 modal 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”.
Note: In cases where you are logging results and your output file contains information about a container (tube barcode, or plate barcode and well position columns), but your results schema expects an entity you will need to set the column value to "Primary sample." This tells the run to "look up" the entity in the container.
You can use a snapshot field on the results schema itself to achieve the same outcome. This may be a preferable approach if you will record data both with a run and directly in a results table.
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