Labware¶
We spend a fair amount of time organizing and counting wells when writing Python protocols. This section describes the different ways we can access wells and groups of wells.
Labware Library¶
The Opentrons API comes with many common labware built in. These can be loaded
into your Python protocol by using the labware.load() method with the
specific load name of the labware you need.
Please see the Opentrons Labware Library for a list of currently supported labware, along with visualizations, pictures, and load names.
Tip
Copy and paste load names directly from the Labware Library to ensure
your load() statements get the correct definitions.
If you are interested in using your own labware that is not included in the
API, please take a look at how to create custom labware definitions using
labware.create(), or contact Opentrons Support.
Labware Versions¶
Some labware on the Opentrons Labware Library have multiple versions of their definitions available. Opentrons publishes new versions of a labware definition when we find an issue with a labware definition. In general, you should use the newest version of a labware definition; however, the older definitions remain available for use with previously-written protocols that may have been customized to work with the older definition.
If you do not specify a version when loading labware, version 1 will be used by default.
Placing labware on the robot deck¶
The robot deck is made up of slots labeled 1, 2, 3, 4, and so on.
To tell the robot what labware will be on the deck for your protocol, use
labware.load after importing labware as follows:
from opentrons import labware
# ...
tiprack = labware.load("opentrons_96_tiprack_300ul", slot="1")
Labware Import Reference¶
'''
Examples in this section require the following
'''
from opentrons import labware
Load¶
labware.load tells the robot that your protocol will be using a given
labware in a certain slot.
my_labware = labware.load("usascientific_12_reservoir_22ml", slot="1")
A third optional argument can be used to give a labware a nickname for display in the Opentrons App.
my_labware = labware.load("usascientific_12_reservoir_22ml",
slot="2",
label="any-name-you-want")
Sometimes, you may need to place a labware on top of something else on the
deck, like modules. For this, you should use the share parameter.
from opentrons import labware, modules
td = modules.load("tempdeck", slot="1")
plate = labware.load("opentrons_96_aluminumblock_biorad_wellplate_200ul",
slot="1",
share=True)
To specify the version of the labware definition to use, you can use the version
parameter:
from opentrons import labware
block1 = labware.load(
"opentrons_96_aluminumblock_biorad_wellplate_200ul",
slot="1",
version=2) # version 2 of the aluminum block definition
block2 = labware.load(
"opentrons_96_aluminumblock_biorad_wellplate_200ul",
slot="2",
version=1) # version 1 of the aluminum block definition
block3 = labware.load(
"opentrons_96_aluminumblock_biorad_wellplate_200ul",
slot="2") # if you don't specify version, version 1 is used
Create¶
Note
The current custom labware creation mechanisms in the API are fairly limited. We’re working on a much more robust system for custom labware definitions. If the current API isn’t able to support your labware, please reach out to our support team.
Using labware.create, you can create your own custom labware. The labware
created through this method must consist of circular wells arranged in
regularly-spaced columns and rows.
custom_plate_name = "custom_18_wellplate_200ul"
if plate_name not in labware.list():
labware.create(
custom_plate_name, # name of you labware
grid=(3, 6), # number of (columns, rows)
spacing=(12, 12), # distances (mm) between each (column, row)
diameter=5, # diameter (mm) of each well
depth=10, # depth (mm) of each well
volume=200) # volume (µL) of each well
custom_plate = labware.load(custom_plate_name, slot="3")
for well in custom_plate.wells():
print(well)
The above example will print out…
<Well A1>
<Well B1>
<Well C1>
<Well A2>
<Well B2>
<Well C2>
<Well A3>
<Well B3>
<Well C3>
<Well A4>
<Well B4>
<Well C4>
<Well A5>
<Well B5>
<Well C5>
<Well A6>
<Well B6>
<Well C6>
You only need to call labware.create once. It will save the labware
definition on the robot so that your labware will be available to all your
subsequent protocol runs.
labware.create will throw an error if you try to call it more than once
with the same load name. In the example above, the call to labware.create
is wrapped in an if-block so it does not try to add the definition twice, which
would cause an error.
If you would like to delete a labware you have already added to the database (for example: to make changes to its definition), you can do the following:
from opentrons.data_storage import database
database.delete_container("custom_18_wellplate_200ul")
Note
There is some specialty labware that will require you to specify the
type within your labware name. If you are creating a custom tip rack, it
must be tiprack-REST-OF-LABWARE-NAME in order for the software to act
reliably.
List (deprecated)¶
labware.list returns an array of all labware load names in the old,
unsupported format.
labware.list()
Tip
For a list of all currently supported labware, please visit the Opentrons Labware Library
Accessing Wells¶
Individual Wells¶
When writing a protocol using the API, you will need to select which wells to transfer liquids to and from.
The OT-2 deck and labware are all set up with the same coordinate system
Lettered rows
["A"]-["END"]Numbered columns
["1"]-["END"].
'''
Examples in this section expect the following
'''
from opentrons import labware
plate = labware.load("corning_24_wellplate_3.4ml_flat", slot="1")
Wells by Name¶
Once a labware is loaded into your protocol, you can easily access the many
wells within it using wells() method. wells() takes the name of the
well as an argument, and will return the well at that location.
a1 = plate.wells("A1")
d6 = plate.wells("D6")
Wells by Index¶
Wells can be referenced by their “string” name, as demonstrated above. However, they can also be referenced with zero-indexing, with the first well in a labware being at position 0.
plate.wells(0) # well A1
plate.wells(23) # well D6
Tip
You may find well names (e.g. B3) to be easier to reason with,
especially with irregular labware (e.g.
opentrons_10_tuberack_falcon_4x50ml_6x15ml_conical). Whichever well
access method you use, your protocol will be most maintainable if you pick
one method and don’t use the other one.
Columns and Rows¶
A labware’s wells are organized within a series of columns and rows, which are
also labelled on standard labware. In the API, rows are given letter names
("A" through "D" for example) and go left to right, while columns are
given numbered names ("1" through "6" for example) and go from front to
back.
You can access a specific row or column by using the rows() and
columns() methods on a labware. These will return all wells within that row
or column.
row = plate.rows("A")
column = plate.columns("1")
print('Column "1" has', len(column), 'wells')
print('Row "A" has', len(row), 'wells')
will print out…
Column "1" has 4 wells
Row "A" has 6 wells
The rows() or cols() methods can be used in combination with the
wells() method to access wells within that row or column. In the example
below, both lines refer to well "A1".
plate.cols("1").wells("A")
plate.rows("A").wells("1")
Tip
The example above works but is a little convoluted. If you can, always get
individual wells like A1 with wells("A1") or wells(0)
Multiple Wells¶
If we had to reference each well one at a time, our protocols could get very long.
When describing a liquid transfer, we can point to groups of wells for the liquid’s source and/or destination. Or, we can get a group of wells and loop (or iterate) through them.
'''
Examples in this section expect the following
'''
from opentrons import labware
plate = labware.load("corning_24_wellplate_3.4ml_flat", slot="1")
Wells¶
The wells() method can return a single well, or it can return a list of
wells when multiple arguments are passed.
Here is an example or accessing a list of wells, each specified by name:
w = plate.wells("A1", "B2", "C3", "D4")
print(w)
will print out…
<WellSeries: <Well A1><Well B2><Well C3><Well D4>>
Multiple wells can be treated just like a normal Python list, and can be iterated through:
for w in plate.wells("A1", "B2", "C3", "D4"):
print(w)
will print out…
<Well A1>
<Well B2>
<Well C3>
<Well D3>
Wells To¶
Instead of having to list the name of every well, we can also create a range of
wells with a start and end point. The first argument is the starting well, and
the to= argument is the last well.
for w in plate.wells("A1", to="D1"):
print(w)
will print out…
<Well A1>
<Well B1>
<Well C1>
<Well D1>
These lists of wells can also move in the reverse direction along your labware.
For example, setting the to= argument to a well that comes before the
starting position is allowed:
for w in plate.wells("D1", to="A1"):
print(w)
will print out…
<Well D1>
<Well C1>
<Well B1>
<Well A1>
Wells Length¶
Another way you can create a list of wells is by specifying the length of the
well list you need, including the starting well. The example below will
return 4 wells, starting at well "A1":
for w in plate.wells("A1", length=4):
print(w)
will print out…
<Well A1>
<Well B1>
<Well C1>
<Well D1>
Columns and Rows¶
The same arguments described above can be used with rows() and cols()
to create lists of rows or columns.
Here is an example of iterating through rows:
for r in plate.rows("A", length=3):
print(r)
will print out…
<WellSeries: <Well A1><Well A2><Well A3><Well A4><Well A5><Well A6>>
<WellSeries: <Well B1><Well B2><Well B3><Well B4><Well B5><Well B6>>
<WellSeries: <Well C1><Well C2><Well C3><Well C4><Well C5><Well C6>>
And here is an example of iterating through columns:
for c in plate.cols("1", to="6"):
print(c)
will print out…
<WellSeries: <Well A1><Well B1><Well C1><Well D1>>
<WellSeries: <Well A2><Well B2><Well C2><Well D2>>
<WellSeries: <Well A3><Well B3><Well C3><Well D3>>
<WellSeries: <Well A4><Well B4><Well C4><Well D4>>
<WellSeries: <Well A5><Well B5><Well C5><Well D5>>
<WellSeries: <Well A6><Well B6><Well C6><Well D6>>
Slices¶
Labware can also be treating similarly to Python lists, and can therefore handle slices.
# start at index 0
# slice until index 8, without including it
# increment by 2
for w in plate[0:8:2]:
print(w)
will print out…
<Well A1>
<Well C1>
<Well A2>
<Well C2>
The API’s labware are also prepared to take string values for the slice’s
start and stop positions.
for w in plate["A1":"A2":2]:
print(w)
will print out…
<Well A1>
<Well C1>
for w in plate.rows["B"]["1"::2]:
print(w)
will print out…
<Well B1>
<Well B3>
<Well B5>
Deprecated Labware Load Names¶
Prior to version 3.10.0 of the Opentrons API, we used a completely
different set of labware load names. They will continue to work until version
4.0.0 is released, but they should be considered deprecated.
We recommend you switch over to using the load names from the Labware Library as soon as possible. The following mapping can be used as a guide:
Deprecated |
Recommended |
Notes |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This labware has square wells |
|
|
|
|
|
|
|
|
|
|
|
This product has been discontinued |
|
|
|
|
|
Opentrons Aluminum Block Set |
|
|
Opentrons Aluminum Block Set |
|
|
Opentrons Aluminum Block Set |
|
|
Opentrons Aluminum Block Set |
|
|
|
|
|
Opentrons 4-in-1 Tube Rack Set |
|
|
Opentrons 4-in-1 Tube Rack Set |
|
|
Opentrons 4-in-1 Tube Rack Set |
|
|
Opentrons 4-in-1 Tube Rack Set |
|
|
Opentrons 4-in-1 Tube Rack Set |
|
|
Opentrons 4-in-1 Tube Rack Set |
|
|
|
|
|
If possible, please use an Opentrons tip rack rather than a rack with a slot adapter |
|
|
If possible, please use an Opentrons tip rack rather than a rack with a slot adapter |
|
|
If possible, please use an Opentrons tip rack rather than a rack with a slot adapter |
|
|
|
|
|
|
|
|
Discontinued; please upgrade to the Opentrons 4-in-1 Tube Rack Set |
|
|
Discontinued; please upgrade to the Opentrons 4-in-1 Tube Rack Set |
|
|
Discontinued; please upgrade to the Opentrons 4-in-1 Tube Rack Set |
Note
If your labware is missing from the list above, or you’re unsure how to update your protocol’s load names, please contact our support team
The following load names do not have a new definitions available, and could eventually be removed. They will continue to function normally for now. If you have any concerns about their deprecation and/or removal, please reach out!
24-vial-rack48-vial-plate5ml-3x496-well-plate-20mmMALDI-plateT25-flaskT75-flaske-gelgolhampton-1ml-deep-blockpointrigaku-compact-crystallization-platesmall_vial_rack_16x45temperature-platetiprack-10ul-Htrough-12row-shorttrough-1row-25mltrough-1row-testtube-rack-2ml-9x9tube-rack-5ml-96tube-rack-80wellwheaton_vial_rack