Labware and Trash Containers

Labware

This class represents a piece of labware.

Labware available in the API generally fall under two categories.

• Consumable labware: well plates, tubes in racks, reservoirs, tip racks, etc.
• Adapters: durable items that hold other labware, either on modules or directly on the deck.

The Labware class defines the physical geometry of the labware and provides methods for accessing wells within the labware.

Create Labware objects by calling the appropriate load_labware() method, depending on where you are loading the labware. For example, to load labware on a Thermocycler Module, use load_labware(). To load labware directly on the deck, use load_labware(). See Loading Labware.

api_version property v2.0

api_version

See ProtocolContext.api_version.

calibrated_offset property v2.0

calibrated_offset

The front-left-bottom corner of the labware, including its labware offset.

The offset is an x, y, z vector in deck coordinates (see :ref:protocol-api-deck-coords).

When running a protocol in the Opentrons App or on the touchscreen, Labware Position Check sets the labware offset.

child property v2.15

child

The labware (if any) present on this labware.

columns v2.0

columns(*args)

Accessor function to navigate through a labware by column.

Use indexing to access individual columns or wells contained in the nested list. For example, access column 1 with labware.columns()[0]. On a standard 96-well plate, this will output a list of Well objects containing A1 through H1.

Note

Using args with this method is deprecated. Use indexing instead.

If your code uses args, they can be either strings or integers, but not a mix of the two. For example, .columns(1, 4) or .columns("1", "4") is valid, but .columns("1", 4) is not.

Returns:

• List[List[Well]] –

  A list of column lists.

columns_by_index v2.0

columns_by_index()

Deprecated in version 2.0: Use columns_by_name() instead.

columns_by_name v2.0

columns_by_name()

Accessor function to navigate through a labware by column name.

Use indexing to access individual columns or wells contained in the dictionary. For example, access column 1 with labware.columns_by_name()["1"]. On a standard 96-well plate, this will output a list of Well objects containing A1 through H1.

Returns:

• Dict[str, List[Well]] –

  Dictionary of Well lists keyed by column name.

highest_z property v2.0

highest_z

The z-coordinate of the highest single point anywhere on the labware.

This is taken from the zDimension property of the dimensions object in the labware definition and takes into account the labware offset.

is_adapter property v2.15

is_adapter

Whether the labware behaves as an adapter.

Returns True if the labware definition specifies adapter as one of the labware's allowedRoles.

is_tiprack property v2.0

is_tiprack

Whether the labware behaves as a tip rack.

Returns True if the labware definition specifies isTiprack as True.

load_empty v2.22

load_empty(wells)

Mark several wells as empty.

This method should be called at the beginning of a protocol, after loading the labware and before liquid handling begins. Loading liquids is required for liquid tracking functionality. If a well in a labware hasn't been assigned a starting volume with load_empty(), load_liquid(), or load_liquid_by_well(), the volume it contains is unknown and the well's liquid will not be tracked throughout the protocol.

Parameters:

• wells (Union[List[Well], List[str]]) –

  The list of wells to mark empty. To mark all wells as empty, pass labware.wells(). You can also specify wells by their names (for instance, labware.load_empty(['A1', 'A2'])).

load_labware v2.15

load_labware(name, label=None, lid=None, namespace=None, version=None, *, lid_namespace=None, lid_version=None)

Load a compatible labware onto the labware using its load parameters.

The parameters of this function behave like those of ProtocolContext.load_labware() (which loads labware directly onto the deck). Note that the parameter name here corresponds to load_name on the ProtocolContext function.

Returns:

• Labware –

  The initialized and loaded labware object.

load_labware_from_definition v2.15

load_labware_from_definition(definition, label=None)

Load a compatible labware onto the labware using an inline definition.

Parameters:

• definition (LabwareDefinition) –

  The labware definition.

• label (str, default: None ) –

  An optional special name to give the labware. If specified, this is how the labware will appear in the run log, Labware Position Check, and elsewhere in the Opentrons App and on the touchscreen.

Returns:

• Labware –

  The initialized and loaded labware object.

load_lid_stack v2.23

load_lid_stack(load_name, quantity, namespace=None, version=None)

Load a stack of Opentrons Tough Auto-Sealing Lids onto a valid deck location or adapter.

Parameters:

• load_name (str) –

  A string to use for looking up a lid definition. You can find the load_name for any standard lid on the Opentrons Labware Library.

• quantity (int) –

  The quantity of lids to be loaded in the stack.

• namespace (str, default: None ) –

  The namespace that the lid labware definition belongs to. If unspecified, the API will automatically search two namespaces:

  • "opentrons", to load standard Opentrons labware definitions.
  • "custom_beta", to load custom labware definitions created with the Custom Labware Creator.

  You might need to specify an explicit namespace if you have a custom definition whose load_name is the same as an Opentrons-verified definition, and you want to explicitly choose one or the other.

• version (int, default: None ) –

  The version of the labware definition. You should normally leave this unspecified to let load_lid_stack() choose a version automatically.

Returns:

• Labware ( Labware ) –

  The initialized and loaded labware object representing the lid stack.

load_liquid v2.22

load_liquid(wells, volume, liquid)

Mark several wells as containing the same amount of liquid.

This method should be called at the beginning of a protocol, soon after loading labware and before liquid handling operations begin. Loading liquids is required for liquid tracking functionality. If a well hasn't been assigned a starting volume with load_empty(), load_liquid(), or load_liquid_by_well(), the volume it contains is unknown and the well's liquid will not be tracked throughout the protocol.

Parameters:

• wells (List[Union[str, Well]]) –

  The wells to load the liquid into. This can be a list of string well names or a list of Well objects (e.g., from wells()).

• volume (float) –

  The volume of liquid to load into each well.

• liquid (Liquid) –

  The liquid to load into each well, previously defined by define_liquid().

load_liquid_by_well v2.22

load_liquid_by_well(volumes, liquid)

Mark several wells as containing unique volumes of liquid.

This method should be called at the beginning of a protocol, soon after loading labware and before liquid handling begins. Loading liquids is required for liquid tracking functionality. If a well hasn't been assigned a starting volume with load_empty(), load_liquid(), or load_liquid_by_well(), the volume it contains is unknown and the well's liquid will not be tracked throughout the protocol.

Parameters:

• volumes (Dict[Union[str, Well], float]) –

  A dictionary of well names (or Well objects, for instance from labware['A1']) to their respective volumes.

• liquid (Liquid) –

  The liquid to load into each well, previously defined by define_liquid().

load_name property v2.0

load_name

The API load name of the labware definition.

magdeck_engage_height property v2.0

magdeck_engage_height

Return the default magnet engage height that MagneticModuleContext.engage() will use for this labware.

Warning

This currently returns confusing and unpredictable results that do not necessarily match what engage() will actually choose for its default height.

The confusion is related to how this height's units and origin point are defined, and differences between Magnetic Module generations.

For now, we recommend you avoid accessing this property directly.

name property v2.0 writable

name

The display name of the labware.

If you specified a value for label when loading the labware, name is that value.

Otherwise, it is the load_name of the labware.

parameters property v2.0

parameters

Internal properties of a labware including type and quirks.

parent property v2.0

parent

Where the labware is loaded.

This corresponds to the physical object that the labware directly rests upon.

Returns:

• Union[str, Labware, ModuleTypes, OffDeckType] –

  If the labware is directly on the robot's deck, the str name of the deck slot, like "D1" (Flex) or "1" (OT-2). See Deck Slots.

  If the labware is on a module, a module context.

  If the labware is on a labware or adapter, a Labware.

  If the labware is off-deck, OFF_DECK.

Changed in version 2.14: Return type for module parent changed. Formerly, the API returned an internal geometry interface.

Changed in version 2.15: Returns a Labware if the labware is loaded onto a labware/adapter. Returns OFF_DECK if the labware is off-deck. Formerly, if the labware was removed by using del on deck, this would return where it was before its removal.

quirks property v2.0

quirks

Quirks specific to this labware.

reset v2.0

reset()

Reset tip tracking for a tip rack.

After resetting, the API treats all wells on the rack as if they contain unused tips. This is useful if you want to reuse tips after calling return_tip().

If you need to physically replace an empty tip rack in the middle of your protocol, use move_labware() instead. See The Off-Deck Location for an example.

Changed in version 2.14: This method will raise an exception if you call it on a labware that isn't a tip rack. Formerly, it would do nothing.

rows v2.0

rows(*args)

Accessor function to navigate through a labware by row.

Use indexing to access individual rows or wells contained in the nested list. On a standard 96-well plate, this will output a list of Well objects containing A1 through A12.

Note

Using args with this method is deprecated. Use indexing instead.

If your code uses args, they can be either strings or integers, but not a mix of the two. For example, .rows(1, 4) or .rows("1", "4") is valid, but .rows("1", 4) is not.

Returns:

• List[List[Well]] –

  A list of row lists.

rows_by_index v2.0

rows_by_index()

Deprecated in version 2.0: Use rows_by_name() instead.

rows_by_name v2.0

rows_by_name()

Accessor function to navigate through a labware by row name.

Use indexing to access individual rows or wells contained in the dictionary. For example, access row A with labware.rows_by_name()["A"]. On a standard 96-well plate, this will output a list of Well objects containing A1 through A12.

Returns:

• Dict[str, List[Well]] –

  Dictionary of Well lists keyed by row name.

set_calibration

set_calibration(delta)

An internal, deprecated method used for updating the labware offset.

Deprecated in version 2.14

set_offset v2.12

set_offset(x, y, z)

Set the labware's position offset.

An offset of (x=0, y=0, z=0) means the labware's uncalibrated position before any offset from Labware Position Check is applied.

How the motion system applies the offset depends on the API level of the protocol.

API level	Offset behavior
2.12–2.13	Offsets only apply to the exact Labware instance. If your protocol has multiple instances of the same type of labware, you must either use set_offset() on all of them or none of them.
2.14–2.17	set_offset() is not available, and the API raises an error.
2.18–2.22	Offsets apply to any labware of the same type, in the same on-deck location. Offsets can't be set on labware that is currently off-deck. Offsets do not follow a labware instance when using `move_labware()`.
2.23+	On Flex, offsets can apply to all labware of the same type, regardless of their on-deck location.

Note

Setting offsets with this method will override any labware offsets set by running Labware Position Check in the Opentrons App.

This method is designed for use with mechanisms like get_protocol_api(), which lack an interactive way to adjust labware offsets. (See Advanced Control.)

Changed in version 2.14: Temporarily removed.

Changed in version 2.18: Restored, and now applies to labware type–location pairs.

tip_length property v2.0 writable

tip_length

For a tip rack labware, the length of the tips it holds, in mm.

This is taken from the tipLength property of the parameters object in the labware definition.

This method will raise an exception if you call it on a labware that isn't a tip rack.

uri property v2.0

uri

A string fully identifying the labware.

The URI has three parts and follows the pattern "namespace/load_name/version". For example, "opentrons/corning_96_wellplate_360ul_flat/2".

well v2.0

well(idx)

Deprecated. Use result of wells() or wells_by_name().

wells v2.0

wells(*args)

Accessor function to navigate a labware top to bottom, left to right.

i.e., this method returns a list ordered A1, B1, C1…A2, B2, C2….

Use indexing to access individual wells contained in the list. For example, access well A1 with labware.wells()[0].

Note

Using args with this method is deprecated. Use indexing instead.

If your code uses args, they can be either strings or integers, but not a mix of the two. For example, .wells(1, 4) or .wells("1", "4") is valid, but .wells("1", 4) is not.

Returns:

• List[Well] –

  Ordered list of all wells in a labware.

wells_by_index v2.0

wells_by_index()

Deprecated in version 2.0: Use wells_by_name() or dict access instead.

wells_by_name v2.0

wells_by_name()

Accessor function used to navigate through a labware by well name.

Use indexing to access individual wells contained in the dictionary. For example, access well A1 with labware.wells_by_name()["A1"].

Returns:

• Dict[str, Well] –

  Dictionary of Well objects keyed by well name.

TrashBin

Represents a Flex or OT-2 trash bin.

See load_trash_bin().

top v2.18

top(x=0, y=0, z=0)

Add a location offset to a trash bin.

The default location (x, y, and z all set to 0) is the center of the bin on the x- and y-axes, and slightly below its physical top on the z-axis.

Offsets can be positive or negative and are measured in mm. See Position Relative to the Deck.

WasteChute

Represents a Flex waste chute.

See load_waste_chute().

top v2.18

top(x=0, y=0, z=0)

Add a location offset to a waste chute.

The default location (x, y, and z all set to 0) is the center of the chute's opening on the x- and y-axes, and slightly below its physical top on the z-axis. See Waste Chute for more information on possible configurations of the chute.

Offsets can be positive or negative and are measured in mm. See Position Relative to the Deck.