Benchling Connect Use Case: NGS Workflow for Library Prep Creation

This use case demonstrates how a Benchling Connect Run can be configured to automate the creation of new entities and generate an input file for an instrument. This example leverages a Next Generation Sequencing (NGS) use case where a user provides sample plates and index plates, and the Connect Run generates a file with liquid handler instructions and creates new entities in the sample plate, replacing the existing entities.

Key Components:

Sample Plate: Contains the extracted DNA, isolated from samples provided by upstream teams.
Index Plate: Holds the unique index sequences that will be joined to the DNA fragments during library preparation. These indexes allow multiple samples to be sequenced together (in a library pool) while maintaining the ability to differentiate them later.
Creating New Entities: The entities in the sample plate are replaced as part of this automation process. A new sample entity is created, combining the original sample name with the index sample name in the format SampleName_IndexName. This allows each new NGS-prepped sample to be uniquely tracked in Benchling.
1. These configurations can be modified to aliquot from the Sample Plate and/or the Index Plate if tracking volume is needed
Run Input File: A critical aspect of this automation is generating an input file, which contains the instructions for a liquid handler instrument to perform the transfer of index barcodes to the sample plate.
Output File Transforms: Adding information to the file as it’s ingested to create new entities.

Configuration Highlights

Download and Send to Output: By naming the Input File Configuration and the Output File Configuration the same, we unlock the ability to consolidate clicks for the end user. Users can now select ‘Download and Send to Output’ as one step.

Replace existing entities: Clicking this box will replace the entities with newly created entities

Consolidate results into a single row: Checking this box will place the value in all rows.

Transforming the Output File: This run utilizes out of the box transforms to add additional information necessary to create the new registered entities to the output file.

Step-by-Step Guide to Create an NGS Library Prep Run in Benchling

Prerequisite: Access to Benchling with appropriate permissions to create registry and inventory schemas.

1. Run Fields Configuration

Sample Plate: The source plate containing the biological samples used for NGS library preparation.
Index Plate: A plate containing index barcode entities that will be applied to the samples during the run. These index barcodes differentiate samples in the downstream sequencing process.

Steps to Configure Run Fields:

Enter the Registry settings. Click on the avatar in the lower left corner and select Feature Settings then Run schemas.
Create a new Run by clicking Create in the upper right corner
- Name: This is how users will search for the run and should be descriptive. For example: “Create NGS Libraries”
- Owner: This will be the organization, in most cases there is only one option
- Warehouse name: This will populate by default from the Name field
- Connection schema: If utilizing a Connect data connector, this is where it would be selected. This is not utilized in this example.
- Notebook Preference
  - Allow creating new runs from the notebook: If this option is unchecked, the "Create new run" button will not be available in the notebook. The run fields will be displayed in read-only mode.
  - Allow inserting runs from inbox in the notebook: If this option is unchecked, the "Insert from inbox" button will not be available in the notebook.
Run Fields are where users enter entities or inventory into the run that is needed to perform the action.
- Add the following fields:
  - Sample Plate: Select as required and single-select from a 96-well plate.
  - Index Plate: Select as required and single-select from a 96-well plate.

2. Input File Configuration

The input file uses information available from the run fields as well as static information to create the instructions for an instrument.The file generated in this step can also be used as the Output file configuration to complete Benchling actions (transfer inventory, create entities, etc).

In this example, the input file is intended to be used as the input to a liquid handler instrument.

Steps to Configure Input File:

In the Input File Configurations section, click + to add an Input File Configuration

Configure the display name

Sources and Destinations:
- The source determines the number of rows in your input file. The source and destination should match on level. For example, if the source is set to wells the destination should also be set to wells.
Configure Source: The wells of the Index Plate (96-well plate) will be the source.
- Click on the + next to Sources
- Select the Index Plate from the Start from dropdown
- Under Add lookup step, choose Lookup wells in plate
  - Options here include lookup direction (across rows or down columns)and skipping or ignoring rows or columns.
  - Check the box to ignore empty wells will include only wells that contain an entity. This will ensure that the input file only includes instructions for filled wells.

Configure Destinations: The wells of the Library Prep Plate as the Destination. This plate represents the destination inventory where the new entities will be created.
- Click on the + next to Destinations
- Select the Sample Plate from the Start from dropdown
- Under Add lookup step, choose Lookup wells in plate

Configure columns for the input file
- The columns defined in the Input table will generate the file users can download from the Run in a notebook entry.

- The first three columns (Source, Destination, Plate Layout) will not be included in the downloaded file.
  - Source: This was defined in the previous step. This example uses Wells as the source because we want one row in our input file for each well.
  - Destination: This can be either None (the default option) or the Destination set in the previous step.
  - Plate Layout: This dropdown allows for different transfer patterns.
- Add additional columns
  - Right click a column header and click Insert column left/right

Right click on the new column header and choose Rename column
Click on Set lookup to define the attributes for each column

Add a column for Source Plate Barcode:
- Choose the Index Plate from the Start from dropdown

Select Barcode from the Lookup attributes
Select ‘Consolidate results into single row’
- This will repeat this attribute for each row

Add a column for Source Plate Well:

From the Position dropdown users can choose from different display options for well coordinates.

Add a column for Destination Plate Barcode:

Add a column for Destination Plate Well:
- Repeat the steps to set up Source Plate Well
Transfer Volume: Set a constant value for the transfer

Check ‘Consolidate results into single row’ which will apply the same constant value to each row of the file

Note: For use cases where the transfer volume is variable, a run field can be used instead of applying a static value.

Optional:

Apply transforms to the input file
- This article describes out of the box transforms
Configure file format
- Here you can customize how the input file will be named, set the file extension and delimiter

Completed input table:

Tip: At this point the Run can be tested. The input file generated should look similar to the file below:

Final Input File Configuration

3. Output File Generation

The output file is uploaded into Benchling to complete an action: create results, update or register entity or perform an inventory action.

In this example the input file is uploaded to perform two actions: create new entities and perform an inventory transfer. Transforms are used to add additional information to the file on upload to perform these actions.

Steps to Configure Output File:

In the Output File Configurations section, add an output file

Configure the display name
- Tip: Using the exact same name for both input and output display names will allow users the option to ‘Download and send to output’ in one click
Benchling Action:
- Select Register and/or update entities.
- Select Transfer samples.
- For this example Record results is not applicable.
Output table display: The run will create a table. This dropdown will determine whether this table should display one row per sample (default) or one row per plate.
Output table sorting: This dropdown will determine whether the output table is sorted alphabetically (default) or preserves the order in the uploaded file.

Entity Schema: This will define the schema used in creating or updating entities
- Action type: Register new entities
- Entity Schema: Choose the appropriate schema
- Check the box to replace existing entities
  - We are adding the index barcodes to the sample plate to create the new samples, rather than transferring both the sample and the index barcode to a new empty plate.

Inventory schema: This option is available because we selected ‘Transfer Samples’. Choose whether the run will use existing inventory or create new inventory

Transforms: These functions will alter the file being uploaded. Upload the file generated by the input file configurations to see a preview of each transform added.
- Because this run will utilize the input file configured above, there are already columns for Source Plate Barcode, Source Plate Well, Destination Plate Barcode, Destination Plate Well and Transfer Volume (uL). We need to use transforms to add additional information needed to perform the virtual transfer and create new entities.
- Tip: Uploading an example file will show in real time the impact of each transform
- Add a column for Zero Transfer
  - This column is necessary to perform the virtual transfer of the Index Barcodes. It is often not necessary to track inventory of these samples, so this step allows us to utilize one representative plate of indexes repeatedly.
  - Click the ‘Consolidate results into a single row’.

Add a column for Sample Name:

Add a column for Index Barcode:

Add a column for Sample:
- Duplicate the Sample Name column
- Note: Two columns cannot share the same name

Index Barcode Set: Duplicate the Index Barcode above

Merge:
- Name the columns to merge (comma separated)
- Type in the delimiter (common choices: underscore, comma, hyphen)
- Name the new column
- Tip: Notice that this transform removes the columns used to create it. Because those columns are still needed we created duplicates before the merge step.

Additional transform details can be found here

File extension for intermediate files:
- Choose from .csv, .tsv, .txt or a custom value
Configure Columns:
- Columns in the output file must be mapped to the intended metadata field or ignored
- Mapping type can be either
  - By column order: this will ignore the name of the column
  - By column name: this will ignore the order of the columns
  - In this example the Mapping type is by column name.
- Source Plate Barcode: