Configure a Lookup in a Lab Automation Run

Aarthi
Aarthi
  • Updated

The core concept in configuring the input file is the LookupConfig, which is an object that defines how to look up a value that goes in a cell of the input file. Every lookup starts from a run schema field.

A LookupConfig has the following properties:

  • lookupSteps: a list of between 1 and 5 LookupStep objects

  • isMulti: defines whether the looked up values should be split across rows (true) or copied into every row (false)example: a floating point field where the user inputs the one transfer volume for all samples, isMulti would be false example: an entity link field containing multiple entities where we want one row per entity, isMulti would be true

Configuring Lookups using JSON

Like all Benchling schemas, users can edit the configuration directly using JSON syntax.

The following types of LookupSteps are supported:

  • SCHEMA_FIELD { type: "SCHEMA_FIELD", schemaField: "<field_name>"}

Looks up the value of a schema field if this is the first step, must be a schema field on the runif not, must be a schema field of the entity, container, or plate returned by the previous step uses the warehouse name for runs and the display name for other objects

  • CONTAINER { type: "CONTAINER", containerSchema: "<schema_id>"}

Looks up one container per entity returned by the previous step errors if there are multiple matching containers for a single entity, optionally can be filtered by container schema ID, must follow a step that returns entities

  • PLATE { type: "PLATE", plateSchema: "<schema_id>"}

Looks up a plate based on a well/container returned by the previous step. Optionally can be filtered by plate schema ID. Must follow a step that returns containers or wells

  • BOX { type: "BOX", boxSchema: "<schema_id>"}

Looks up a box based on a container returned by the previous step. Optionally can be filtered by box schema ID. Must follow a step that returns containers

  • WELLS 

"type": "WELLS",
	"order": {
		"fillDirection": "ACROSS_ROWS" or "DOWN_COLUMNS",
		"skipRows": positive integer,
		"skipColumns": positive integer,
		"fillByQuadrant": boolean
	},
	"filter": {
		"ignoreEmpty": boolean,
		"ignoreFilled": boolean,
		"rowsToIgnore": [
			integer, integer...
		],
		"columnsToIgnore": [
			integer, integer
		]
	}
}

Looks up the wells on a plate in order of fillDirection. If fillByQuadrant is true breaks up Well lookup by quadrant and returns Wells in quadrant order.

Q1 < Q2 < Q3 < Q4.

Example: On a 4x4 well plate this would return A1, A2, B1, B2, A3, A4, B3, B4 ...Alternates rows and columns according to skipRows and skipColumns. If alternating patterns are not needed, set these to 0.

Example: With skipRows set to 1, this will first look up all odd-numbered rows then all even-numbered rowsCan filter out empty wells or filled wells with ignoreEmpty and ignoreFilled. Can filter out entire rows or columns in rowsToIgnore and columnsToIgnore. These are 1-indexed (the first row/column is 1)must follow a step that returns plates

  • WELL_COORDINATES { type: "WELL_COORDINATES"}

Looks up the well coordinates of the container returned by the previous step must follow a step that returns wells or containers

  • CONTENTS { type: "CONTENTS"}

Can be filtered with “entitySchema”:"<target_schema_id>", must be filtered if a SCHEMA_FIELD step follows looks up with contents of a container returned by the previous step must follow a step that returns wells or containers

  • VOLUME { type: "VOLUME", volumeUnits: "<units>"}

Looks up the volume of the container returned by the previous step, volume is converted to the units provided, must follow a step that returns wells or containers

  • CONCENTRATION { type: "CONCENTRATION", concentrationUnits: "<units>"}

Looks up the concentration of the container returned by the previous step, volume is converted to the units provided, must follow a step that returns wells or containers

  • SOURCE { type: "SOURCE"}

Uses the output of the source lookup in the RowConfig must be used as first step of a columnsMap LookupStep, if it is used.

 

Why would you use SOURCE? it prevents you from having to re-use the same lookupSteps, and allows you to go deeper (beyond total 5 lookupSteps)

  • DESTINATION { type: "DESTINATION"}

Uses the output of the destinationInfo referenced in the RowConfig‘s destination must be used as first step of a columnsMap LookupStep, if it is used.

  • RESIDUES { type: "RESIDUES"}

Looks up the DNA or AA bases of the entity, must follow a step that returns an entity

  • PLACEHOLDER_PLATES { type: "PLACEHOLDER_PLATES", plateSchema: "<plate_schema_id"}

Only supported within DestinationInfos (see below) Creates placeholder plate barcodes to represent plates that do not yet exist. plateSchema is required so that we know the size of the resulting plate, must be the first step in a list, if used. Can be followed by WELLS step just as with existing plates, creates placeholder plates in the input file with the form: plateSchemaName #

  • REPLICATES {type: "REPLICATES", numberLookupConfig: <LookupConfig resulting in a positive integer>}

Only supported within a RowConfig's sourceRepresents a replication factor n, which may either be constant for all sources (numberLookupConfig.isMulti=false) or may look up a different value for each source (numberLookupConfig.isMulti=true). Will generate n rows per source. Use with CONSTANT type to set a value for the replication factor that doesn’t change

  • CONSTANT { type: "CONSTANT", value: <value> }

Creates a constant value in the input file

  • COUNT { type: "COUNT", schemaField: "<field_name>" }

Counts the number of values in a schema field

  • REGISTRY_ID {type: 'REGISTRY_ID"}

Must be used after a step that returns an entity. Returns the registry id of the entity looked up in the previous step

  • FILTER{ type: "FILTER", schemaField: "<field_name>", value: <value>}

{
	"type": "FILTER",
	"schemaField": "<field_name>",
	"filterType": "<filter type>",
	"value": <value>
}

Filters the previous values by a schema field value, returning only the items that match the filter schemaField must be a schema field of the entity, container, or plate returned by the previous step

schemaField must be a text, number, or dropdown field

schemaField uses the warehouse name for runs and the display name for other objects

filterType must be one of:"eq": filters for field values equal to value

"ne": filters for field values not equal to value

"lt": filters for field values less than value, which must be a number

"le": filters for field values less than or equal to value, which must be a number

"gt": filters for field values greater than value, which must be a number

"ge": filters for field values greater than or equal to value, which must be a number

"isnull": filters for field values that are empty. value should not be provided with this filter type.

"notnull": filters for field values that are not empty. value should not be provided with this filter type.

  • null [ ] creates a blank value in the cell for this RowConfig

Below is an example of using lookup steps to set the Source of the run as the wells of the plates:

  • The first lookup step is using the SCHEMA_FIELD type lookup step to lookup the plates in the run field with the warehouse name “plate”

  • The second lookup step is using the WELLS type lookup step to lookup the wells of the previous step’s plate(s)

"source": {
	"isMulti": true,
	"lookupSteps": [
		{
			"type": "SCHEMA_FIELD",
			"schemaField": "plate"
		},
		{
			"filter": {
				"rowsToIgnore": [],
				"ignoreFilled": false,
				"ignoreEmpty": false,
				"columnsToIgnore": []
			},
			"type": "WELLS",
			"order": {
				"skipRows": 0,
				"skipColumns": 0,
				"fillByQuadrant": false,
				"fillDirection": "ACROSS_ROWS"
			}
		}
	]
}

Configuring Lookups using the UI

Sometimes it's easier to configure Lookups using the UI instead of editing JSON text directly. To do this, add a source after configuring the fields for your run.

A modal screen will appear where you can select your input sources. Choose a starting source and fill out the required fields. Choose "Add Lookup Step" to create more precise parameters. For example, if you start with a 96-well plate as a starting source, you may want to add an additional step to specify the wells in that plate, and then the contents of those wells.

When configuring your Lookups from the UI, only compatible Lookups will be visible to you.

Was this article helpful?

Have more questions? Submit a request