From 0af099a7f059f8be047743e793f8467f09c399a9 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Fri, 19 Jul 2024 16:38:12 -0400 Subject: [PATCH 01/15] new intro and stub out per-layout sections --- api/docs/v2/pipettes/partial_tip_pickup.rst | 45 +++++++++++++++++++-- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index a2ca1e614a3..c34ac39413d 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -6,18 +6,39 @@ Partial Tip Pickup ****************** -The 96-channel pipette occupies both pipette mounts on Flex, so it's not possible to attach another pipette at the same time. Partial tip pickup lets you perform some of the same actions that you would be able to perform with a second pipette. As of version 2.16 of the API, you can configure the 96-channel pipette to pick up a single column of tips, similar to the behavior of an 8-channel pipette. +By default, multi-channel pipettes always use all of their nozzles to pick up tips and handle liquids: an 8-channel pipette picks up 8 tips at once, and a 96-channel pipette picks up 96 tips at once. Partial tip pickup lets you configure a multi-channel pipette to use fewer tips. This expands the liquid handling capabilities of your robot without having to physically switch pipettes, and is especially useful for the Flex 96-Channel Pipette, which occupies both pipette mounts. + +Before getting started with partial tip pickup, make sure your protocol specifies an API version that supports the configuration you need. + +.. list-table:: + :header-rows: 1 + + * - Pipette + - Partial Configuration + - Minimum API Version + * - Flex 96-Channel Pipette + - Column + - 2.16 + * - Flex 96-Channel Pipette + - Single, partial column, row + - 2.20 + * - Flex 8-Channel Pipettes + - Single, partial column + - 2.20 + * - OT-2 Multi-Channel Pipettes + - Single, partial column + - 2.20 Nozzle Layout ============= -Use the :py:meth:`.configure_nozzle_layout` method to choose how many tips the 96-channel pipette will pick up. The method's ``style`` parameter accepts special layout constants. You must import these constants at the top of your protocol, or you won't be able to configure the pipette for partial tip pickup. +Use the :py:meth:`.configure_nozzle_layout` method to choose how many tips a pipette will pick up. The method's ``style`` parameter accepts special layout constants. You must import these constants at the top of your protocol, or you won't be able to configure the pipette for partial tip pickup. At minimum, import the API from the ``opentrons`` package:: from opentrons import protocol_api -Then when you call ``configure_nozzle_layout`` later in your protocol, you can set ``style=protocol_api.COLUMN``. +Then when you call ``configure_nozzle_layout`` later in your protocol, you can set a layout like ``style=protocol_api.COLUMN``. For greater convenience, also import the individual layout constants that you plan to use in your protocol:: @@ -25,6 +46,9 @@ For greater convenience, also import the individual layout constants that you pl Then when you call ``configure_nozzle_layout`` later in your protocol, you can set ``style=COLUMN``. +Column Layout Example +--------------------- + Here is the start of a protocol that performs both imports, loads a 96-channel pipette, and sets it to pick up a single column of tips. .. code-block:: python @@ -73,6 +97,21 @@ In this configuration, pipetting actions will use a single column:: :py:meth:`.InstrumentContext.pick_up_tip` always accepts a ``location`` argument, regardless of nozzle configuration. Do not pass a value that would lead the pipette to line up over more unused tips than specified by the current layout. For example, setting ``COLUMN`` layout and then calling ``pipette.pick_up_tip(tip_rack["A2"])`` on a full tip rack will lead to unexpected pipetting behavior and potential crashes. +Row Layout Example +------------------ + +TK + +Single Layout Example +--------------------- + +TK + +Partial Column Layout Example +----------------------------- + +TK + .. _partial-tip-rack-adapters: Tip Rack Adapters From b68ad54ff26c407ef8172d544cb1bbed32a4b5f1 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Mon, 22 Jul 2024 16:08:11 -0400 Subject: [PATCH 02/15] rephrase multi-channel movement --- api/docs/v2/pipettes/characteristics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/docs/v2/pipettes/characteristics.rst b/api/docs/v2/pipettes/characteristics.rst index a91f58d55e2..8aaf8751dd0 100644 --- a/api/docs/v2/pipettes/characteristics.rst +++ b/api/docs/v2/pipettes/characteristics.rst @@ -21,7 +21,7 @@ Multi-Channel Movement All :ref:`building block ` and :ref:`complex commands ` work with single- and multi-channel pipettes. -To keep the protocol API consistent when using single- and multi-channel pipettes, commands treat the back left channel of a multi-channel pipette as its *primary channel*. Location arguments of pipetting commands use the primary channel. The :py:meth:`.InstrumentContext.configure_nozzle_layout` method can change the pipette's primary channel, using its ``start`` parameter. See :ref:`partial-tip-pickup` for more information. +To keep the protocol API consistent when using single- and multi-channel pipettes, location arguments of pipetting commands use the pipette's *primary channel*. For multi-channel pipettes picking up tips with all of their channels, the back-left channel is considered primary. When using fewer channels, the ``start`` parameter of the :py:meth:`.InstrumentContext.configure_nozzle_layout` method can change the pipette's primary channel. See :ref:`partial-tip-pickup` for more information. With a pipette's default settings, you can generally access the wells indicated in the table below. Moving to any other well may cause the pipette to crash. From d7f14635c317be11d50503beb6c211fc624e565b Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Mon, 22 Jul 2024 16:56:09 -0400 Subject: [PATCH 03/15] ROW example --- api/docs/v2/pipettes/partial_tip_pickup.rst | 43 +++++++++++++++++++-- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index c34ac39413d..ad022d89cb6 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -44,12 +44,12 @@ For greater convenience, also import the individual layout constants that you pl from opentrons.protocol_api import COLUMN, ALL -Then when you call ``configure_nozzle_layout`` later in your protocol, you can set ``style=COLUMN``. +Then when you call ``configure_nozzle_layout`` later in your protocol, you can use the shorter ``style=COLUMN``. Column Layout Example --------------------- -Here is the start of a protocol that performs both imports, loads a 96-channel pipette, and sets it to pick up a single column of tips. +Here is the start of a protocol that imports the ``COLUMN`` and ``ALL`` layout constants, loads a 96-channel pipette, and sets it to pick up a single column of tips. .. code-block:: python :substitutions: @@ -76,7 +76,7 @@ Here is the start of a protocol that performs both imports, loads a 96-channel p Let's unpack some of the details of this code. -First, we've given a special name to the tip rack, ``column_rack``. You can name your tip racks whatever you like, but if you're performing full pickup and partial pickup in the same protocol, you'll need to keep them separate. See :ref:`partial-tip-rack-adapters` below. +First, we've given a special name to the tip rack, ``column_rack``. You can name your tip racks whatever you like, but if you're using a 96-channel pipette for full pickup and partial pickup in the same protocol, you'll need to keep them separate. See :ref:`partial-tip-rack-adapters` below. Next, we load the 96-channel pipette. Note that :py:meth:`.load_instrument` only has a single argument. The 96-channel pipette occupies both mounts, so ``mount`` is omissible. The ``tip_racks`` argument is always optional. But it would have no effect to declare it here, because every call to ``configure_nozzle_layout()`` resets the pipette's :py:obj:`.InstrumentContext.tip_racks` property. @@ -100,7 +100,42 @@ In this configuration, pipetting actions will use a single column:: Row Layout Example ------------------ -TK +Here is the start of a protocol that imports the ``ROW`` and ``ALL`` layout constants, loads a 96-channel pipette, and sets it to pick up a single row of tips. + +.. code-block:: python + :substitutions: + + from opentrons import protocol_api + from opentrons.protocol_api import ROW, ALL + + requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} + + def run(protocol: protocol_api.ProtocolContext): + column_rack = protocol.load_labware( + load_name="opentrons_flex_96_tiprack_1000ul", + location="D3" + ) + trash = protocol.load_trash_bin("A3") + pipette = protocol.load_instrument("flex_96channel_1000") + pipette.configure_nozzle_layout( + style=ROW, + start="H1", + tip_racks=[column_rack] + ) + +Setting ``start="H1"`` means the pipette will use its frontmost nozzles to pick up tips, starting from the back of the tip rack:: + + pipette.pick_up_tip() # picks up A1-A12 from tip rack + pipette.drop_tip() + pipette.pick_up_tip() # picks up B1-B12 from tip rack + +You can also set ``start="A1"`` to use the backmost nozzles and pick up from the front of the tip rack. + +.. note:: + + Picking up rows from front to back will not work with tip racks placed in row D of the deck, because the robot door prevents the pipette from moving far enough forward. Since the pipette can't pick up the frontmost tips, it can't pick up any other rows of tips either. + +.. versionadded:: 2.20 Single Layout Example --------------------- From 82d7428123ef5b2134496a8324e52ccb82db1a28 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Mon, 22 Jul 2024 18:14:55 -0400 Subject: [PATCH 04/15] fix ROW note and add SINGLE example --- api/docs/v2/pipettes/partial_tip_pickup.rst | 95 +++++++++++++++++++-- 1 file changed, 87 insertions(+), 8 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index ad022d89cb6..b788d2fa370 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -60,7 +60,7 @@ Here is the start of a protocol that imports the ``COLUMN`` and ``ALL`` layout c requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} def run(protocol: protocol_api.ProtocolContext): - column_rack = protocol.load_labware( + partial_rack = protocol.load_labware( load_name="opentrons_flex_96_tiprack_1000ul", location="D3" ) @@ -69,14 +69,14 @@ Here is the start of a protocol that imports the ``COLUMN`` and ``ALL`` layout c pipette.configure_nozzle_layout( style=COLUMN, start="A12", - tip_racks=[column_rack] + tip_racks=[partial_rack] ) .. versionadded:: 2.16 Let's unpack some of the details of this code. -First, we've given a special name to the tip rack, ``column_rack``. You can name your tip racks whatever you like, but if you're using a 96-channel pipette for full pickup and partial pickup in the same protocol, you'll need to keep them separate. See :ref:`partial-tip-rack-adapters` below. +First, we've given a special name to the tip rack, ``partial_rack``. You can name your tip racks whatever you like, but if you're using a 96-channel pipette for full pickup and partial pickup in the same protocol, you'll need to keep them separate. See :ref:`partial-tip-rack-adapters` below. Next, we load the 96-channel pipette. Note that :py:meth:`.load_instrument` only has a single argument. The 96-channel pipette occupies both mounts, so ``mount`` is omissible. The ``tip_racks`` argument is always optional. But it would have no effect to declare it here, because every call to ``configure_nozzle_layout()`` resets the pipette's :py:obj:`.InstrumentContext.tip_racks` property. @@ -111,7 +111,7 @@ Here is the start of a protocol that imports the ``ROW`` and ``ALL`` layout cons requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} def run(protocol: protocol_api.ProtocolContext): - column_rack = protocol.load_labware( + partial_rack = protocol.load_labware( load_name="opentrons_flex_96_tiprack_1000ul", location="D3" ) @@ -120,9 +120,11 @@ Here is the start of a protocol that imports the ``ROW`` and ``ALL`` layout cons pipette.configure_nozzle_layout( style=ROW, start="H1", - tip_racks=[column_rack] + tip_racks=[partial_rack] ) +.. versionadded:: 2.20 + Setting ``start="H1"`` means the pipette will use its frontmost nozzles to pick up tips, starting from the back of the tip rack:: pipette.pick_up_tip() # picks up A1-A12 from tip rack @@ -133,14 +135,91 @@ You can also set ``start="A1"`` to use the backmost nozzles and pick up from the .. note:: - Picking up rows from front to back will not work with tip racks placed in row D of the deck, because the robot door prevents the pipette from moving far enough forward. Since the pipette can't pick up the frontmost tips, it can't pick up any other rows of tips either. + Consider the placement of your tip rack when choosing the ``start`` value for row pickup. The pipette cannot pick up from back to front (``start="H1"``) on tip racks in row A of the deck, nor can it pick up from front to back (``start="A1"``) on tip racks in row D of the deck. This is because the pipette would have to move too far backward or forward, respectively, to align over those tips. -.. versionadded:: 2.20 + Use a different ``start`` value, or load the tip rack in row B or C. Single Layout Example --------------------- -TK +Single-tip pickup is available on both 8-channel and 96-channel pipettes. For 8-channel pipettes, there are two possible configurations, using either the front or back nozzle. For 96-channel pipettes, there are four possible configurations, using any of the corner nozzles. + +The ``start`` parameter sets the "first" and only nozzle used in the configuration. It also affects the order in which the pipette picks up tips. When using automatic tip tracking, single-tip configurations always consume all tips within a single column before proceeding to another column. + +.. list-table:: + :header-rows: 1 + + * - Pipette Type + - ``start`` Well + - Pickup Order + * - 8-channel + - A1 + - | Front to back, right to left, i.e. + | H1 through A1, H2 through A2, etc. + * - 8-channel + - H1 + - | Back to front, right to left, i.e. + | A1 through H1, A2 through H2, etc. + * - 96-channel + - A1 + - | Front to back, left to right, i.e. + | H12 through A12, H11 through A11, etc. + * - 96-channel + - H1 + - | Back to front, left to right, i.e. + | A12 through H12, A11 through H11, etc. + * - 96-channel + - A12 + - | Front to back, right to left, i.e. + | H1 through A1, H2 through A2, etc. + * - 96-channel + - H12 + - | Back to front, right to left, i.e. + | A1 through H1, A2 through H2, etc. + +Since they follow the same order as using a single-channel pipette, Opentrons recommends using the following configurations: + +- For 8-channel pipettes, ``start="H1"``. +- For 96-channel pipettes, ``start="H12"``. + +Here is the start of a protocol that imports the ``SINGLE`` and ``ALL`` layout constants, loads an 8-channel pipette, and sets it to pick up a single tip. + +.. code-block:: python + :substitutions: + + from opentrons import protocol_api + from opentrons.protocol_api import ROW, ALL + + requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} + + def run(protocol: protocol_api.ProtocolContext): + partial_rack = protocol.load_labware( + load_name="opentrons_flex_96_tiprack_1000ul", + location="D3" + ) + trash = protocol.load_trash_bin("A3") + pipette = protocol.load_instrument( + instrument_name="flex_8channel_1000", + mount="left" + ) + pipette.configure_nozzle_layout( + style=ROW, + start="H12", + tip_racks=[partial_rack] + ) + +.. versionadded:: 2.20 + +Since this configuration uses ``start="H12"``, it will pick up tips in the usual order:: + + pipette.pick_up_tip() # picks up A1 from tip rack + pipette.drop_tip() + pipette.pick_up_tip() # picks up B1 from tip rack + +.. note:: + + You can pick up tips row-wise first, rather than column-wise first, by specifying a location for :py:meth:`.pick_up_tip` each time you use it in ``SINGLE`` configuration. However, as with all partial tip layouts, be careful that you don't place the pipette in a position where it overlaps more tips than intended. + Partial Column Layout Example ----------------------------- From 4854610950cf4ac2d800a07844e6e31901d1fde7 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 23 Jul 2024 10:09:46 -0400 Subject: [PATCH 05/15] ROW/SINGLE typo --- api/docs/v2/pipettes/partial_tip_pickup.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index b788d2fa370..57ac79c691f 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -188,7 +188,7 @@ Here is the start of a protocol that imports the ``SINGLE`` and ``ALL`` layout c :substitutions: from opentrons import protocol_api - from opentrons.protocol_api import ROW, ALL + from opentrons.protocol_api import SINGLE, ALL requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} @@ -203,7 +203,7 @@ Here is the start of a protocol that imports the ``SINGLE`` and ``ALL`` layout c mount="left" ) pipette.configure_nozzle_layout( - style=ROW, + style=SINGLE, start="H12", tip_racks=[partial_rack] ) From 1e42752987efc644d78107c89e142c25fcca56c5 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 23 Jul 2024 17:47:39 -0400 Subject: [PATCH 06/15] start PARTIAL_COLUMN --- api/docs/v2/pipettes/partial_tip_pickup.rst | 69 ++++++++++++++------- 1 file changed, 47 insertions(+), 22 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index 57ac79c691f..d3f73dbe471 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -14,8 +14,8 @@ Before getting started with partial tip pickup, make sure your protocol specifie :header-rows: 1 * - Pipette - - Partial Configuration - - Minimum API Version + - Partial configuration + - Minimum API version * - Flex 96-Channel Pipette - Column - 2.16 @@ -131,7 +131,7 @@ Setting ``start="H1"`` means the pipette will use its frontmost nozzles to pick pipette.drop_tip() pipette.pick_up_tip() # picks up B1-B12 from tip rack -You can also set ``start="A1"`` to use the backmost nozzles and pick up from the front of the tip rack. +You can also set ``start="A1"`` to use the backmost nozzles and pick up from the front of the tip rack. .. note:: @@ -142,42 +142,42 @@ You can also set ``start="A1"`` to use the backmost nozzles and pick up from the Single Layout Example --------------------- -Single-tip pickup is available on both 8-channel and 96-channel pipettes. For 8-channel pipettes, there are two possible configurations, using either the front or back nozzle. For 96-channel pipettes, there are four possible configurations, using any of the corner nozzles. +Single-tip pickup is available on both 8-channel and 96-channel pipettes. For 8-channel pipettes, there are two possible configurations, using either the front or back nozzle. For 96-channel pipettes, there are four possible configurations, using any of the corner nozzles. The ``start`` parameter sets the "first" and only nozzle used in the configuration. It also affects the order in which the pipette picks up tips. When using automatic tip tracking, single-tip configurations always consume all tips within a single column before proceeding to another column. .. list-table:: :header-rows: 1 - * - Pipette Type - - ``start`` Well - - Pickup Order + * - Pipette type + - ``start`` well + - Pickup order * - 8-channel - A1 - - | Front to back, right to left, i.e. - | H1 through A1, H2 through A2, etc. + - | Front to back, right to left + | (H1 through A1, H2 through A2, …) * - 8-channel - H1 - - | Back to front, right to left, i.e. - | A1 through H1, A2 through H2, etc. + - | Back to front, right to left + | (A1 through H1, A2 through H2, …) * - 96-channel - A1 - - | Front to back, left to right, i.e. - | H12 through A12, H11 through A11, etc. + - | Front to back, left to right + | (H12 through A12, H11 through A11, …) * - 96-channel - H1 - - | Back to front, left to right, i.e. - | A12 through H12, A11 through H11, etc. + - | Back to front, left to right + | (A12 through H12, A11 through H11, …) * - 96-channel - A12 - - | Front to back, right to left, i.e. - | H1 through A1, H2 through A2, etc. + - | Front to back, right to left + | (H1 through A1, H2 through A2, …) * - 96-channel - H12 - - | Back to front, right to left, i.e. - | A1 through H1, A2 through H2, etc. + - | Back to front, right to left + | (A1 through H1, A2 through H2, …) -Since they follow the same order as using a single-channel pipette, Opentrons recommends using the following configurations: +Since they follow the same pickup order as a single-channel pipette, Opentrons recommends using the following configurations: - For 8-channel pipettes, ``start="H1"``. - For 96-channel pipettes, ``start="H12"``. @@ -224,7 +224,32 @@ Since this configuration uses ``start="H12"``, it will pick up tips in the usual Partial Column Layout Example ----------------------------- -TK +Partial column pickup is available on both 8-channel and 96-channel pipettes. Partial columns contain 2 to 7 consecutive tips in a single column. 8-channel pipettes always pick up partial columns with the frontmost nozzles of the pipette (``start="H1"``). 96-channel pipettes can pick up partial columns with the frontmost nozzles in the leftmost column (``start="H1"``) or the rightmost column (``start="H12"``). + +.. note:: + + Picking up partial columns with the backmost nozzles is currently not supported. Setting ``style=PARTIAL_COLUMN`` and either ``start="A1"`` or ``start="A12"`` will raise an error. + +To specify the number of tips to pick up, add the ``end`` parameter when calling :py:meth:`.configure_nozzle_layout`. Use the chart below to determine the end row (G through B) for your desired number of tips. The end column should be the same as your start column (1 or 12). + +.. list-table:: + :stub-columns: 1 + + * - Number of tips + - 2 + - 3 + - 4 + - 5 + - 6 + - 7 + * - ``end`` row + - G + - F + - E + - D + - C + - B + .. _partial-tip-rack-adapters: @@ -261,7 +286,7 @@ When switching between full and partial pickup, you may want to organize your ti .. Tip:: - It's also good practice to keep separate lists of tip racks when using multiple partial tip pickup configurations (i.e., using both column 1 and column 12 in the same protocol). This improves positional accuracy when picking up tips. Additionally, use Labware Position Check in the Opentrons App to ensure that the partial configuration is well-aligned to the rack. + It's also good practice to keep separate lists of tip racks when using multiple partial tip pickup configurations ((using both column 1 and column 12 in the same protocol). This improves positional accuracy when picking up tips. Additionally, use Labware Position Check in the Opentrons App to ensure that the partial configuration is well-aligned to the rack. Now, when you configure the nozzle layout, you can reference the appropriate list as the value of ``tip_racks``:: From 40a07827724e2b110b10225cfb853bce52856a02 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 23 Jul 2024 20:45:02 -0400 Subject: [PATCH 07/15] finish PARTIAL_COLUMN --- api/docs/v2/pipettes/partial_tip_pickup.rst | 66 +++++++++++++++++---- 1 file changed, 55 insertions(+), 11 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index d3f73dbe471..7fb8a4f5ae0 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -29,8 +29,8 @@ Before getting started with partial tip pickup, make sure your protocol specifie - Single, partial column - 2.20 -Nozzle Layout -============= +Nozzle Layouts +============== Use the :py:meth:`.configure_nozzle_layout` method to choose how many tips a pipette will pick up. The method's ``style`` parameter accepts special layout constants. You must import these constants at the top of your protocol, or you won't be able to configure the pipette for partial tip pickup. @@ -46,8 +46,8 @@ For greater convenience, also import the individual layout constants that you pl Then when you call ``configure_nozzle_layout`` later in your protocol, you can use the shorter ``style=COLUMN``. -Column Layout Example ---------------------- +Column Layout +------------- Here is the start of a protocol that imports the ``COLUMN`` and ``ALL`` layout constants, loads a 96-channel pipette, and sets it to pick up a single column of tips. @@ -97,8 +97,8 @@ In this configuration, pipetting actions will use a single column:: :py:meth:`.InstrumentContext.pick_up_tip` always accepts a ``location`` argument, regardless of nozzle configuration. Do not pass a value that would lead the pipette to line up over more unused tips than specified by the current layout. For example, setting ``COLUMN`` layout and then calling ``pipette.pick_up_tip(tip_rack["A2"])`` on a full tip rack will lead to unexpected pipetting behavior and potential crashes. -Row Layout Example ------------------- +Row Layout +---------- Here is the start of a protocol that imports the ``ROW`` and ``ALL`` layout constants, loads a 96-channel pipette, and sets it to pick up a single row of tips. @@ -135,12 +135,12 @@ You can also set ``start="A1"`` to use the backmost nozzles and pick up from the .. note:: - Consider the placement of your tip rack when choosing the ``start`` value for row pickup. The pipette cannot pick up from back to front (``start="H1"``) on tip racks in row A of the deck, nor can it pick up from front to back (``start="A1"``) on tip racks in row D of the deck. This is because the pipette would have to move too far backward or forward, respectively, to align over those tips. + Consider the placement of your tip rack when choosing the ``start`` value for row pickup. The pipette cannot pick up from back to front (``start="H1"``) on tip racks in row A of the deck, nor can it pick up from front to back (``start="A1"``) on tip racks in row D of the deck. This is because the pipette can't move far enough backward or forward, respectively, to align over those tips. Use a different ``start`` value, or load the tip rack in row B or C. -Single Layout Example ---------------------- +Single Layout +------------- Single-tip pickup is available on both 8-channel and 96-channel pipettes. For 8-channel pipettes, there are two possible configurations, using either the front or back nozzle. For 96-channel pipettes, there are four possible configurations, using any of the corner nozzles. @@ -221,8 +221,8 @@ Since this configuration uses ``start="H12"``, it will pick up tips in the usual You can pick up tips row-wise first, rather than column-wise first, by specifying a location for :py:meth:`.pick_up_tip` each time you use it in ``SINGLE`` configuration. However, as with all partial tip layouts, be careful that you don't place the pipette in a position where it overlaps more tips than intended. -Partial Column Layout Example ------------------------------ +Partial Column Layout +--------------------- Partial column pickup is available on both 8-channel and 96-channel pipettes. Partial columns contain 2 to 7 consecutive tips in a single column. 8-channel pipettes always pick up partial columns with the frontmost nozzles of the pipette (``start="H1"``). 96-channel pipettes can pick up partial columns with the frontmost nozzles in the leftmost column (``start="H1"``) or the rightmost column (``start="H12"``). @@ -250,6 +250,50 @@ To specify the number of tips to pick up, add the ``end`` parameter when calling - C - B +Here is the start of a protocol that imports the ``PARTIAL_COLUMN`` and ``ALL`` layout constants, loads an 8-channel pipette, and sets it to pick up four tips:: + + from opentrons import protocol_api + from opentrons.protocol_api import PARTIAL_COLUMN, ALL + + requirements = {"robotType": "Flex", "apiLevel": "2.20"} + + def run(protocol: protocol_api.ProtocolContext): + partial_rack = protocol.load_labware( + load_name="opentrons_flex_96_tiprack_1000ul", + location="B2" + ) + trash = protocol.load_trash_bin("A3") + pipette = protocol.load_instrument("flex_8channel_1000", mount="left") + pipette.configure_nozzle_layout( + style=PARTIAL_COLUMN, + start="H1", + end="E1", + tip_racks=[partial_rack] + ) + +.. versionadded:: 2.20 + +This configuration will pick up tips from the back half of column 1, then the front half of column 1, then the back half of column 2, and so on:: + + pipette.pick_up_tip() # picks up A1-D1 from tip rack + pipette.drop_tip() + pipette.pick_up_tip() # picks up E1-H1 from tip rack + pipette.drop_tip() + pipette.pick_up_tip() # picks up A2-D2 from tip rack + +When handling liquids in partial column configuration, remember that *the frontmost channel of the pipette is its primary channel*. For example, to use the same configuration as above to transfer liquid from wells A1–D1 to wells A2–D2 on a plate, you must use the wells in row D as the source and destination targets:: + + pipette.transfer( + volume=100, + source=plate["D1"], # aspirate from A1-D1 + dest=plate["D2"], # dispense into A2-D2 + ) + +.. warning:: + + Do not move the pipette to row A of labware when in ``PARTIAL_COLUMN`` configuration! This is different than when pipetting to a full column, either with the 8-channel pipette in ``ALL`` configuration or with the 96-channel pipette in ``COLUMN`` configuration. + + If you pipette to row A, the frontmost tip will move to row A and the other tips — further back in the layout — will hang over the back edge of the labware. They will not enter the correct wells and they will likely cause a crash. .. _partial-tip-rack-adapters: From 7dbb338c528f12345b58acf37a5b8095cf90832c Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 23 Jul 2024 20:49:03 -0400 Subject: [PATCH 08/15] fix overzealous find-and-replace --- api/docs/v2/pipettes/partial_tip_pickup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index 7fb8a4f5ae0..427e74d909f 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -330,7 +330,7 @@ When switching between full and partial pickup, you may want to organize your ti .. Tip:: - It's also good practice to keep separate lists of tip racks when using multiple partial tip pickup configurations ((using both column 1 and column 12 in the same protocol). This improves positional accuracy when picking up tips. Additionally, use Labware Position Check in the Opentrons App to ensure that the partial configuration is well-aligned to the rack. + It's also good practice to keep separate lists of tip racks when using multiple partial tip pickup configurations (i.e., using both column 1 and column 12 in the same protocol). This improves positional accuracy when picking up tips. Additionally, use Labware Position Check in the Opentrons App to ensure that the partial configuration is well-aligned to the rack. Now, when you configure the nozzle layout, you can reference the appropriate list as the value of ``tip_racks``:: From 187af72355ec65915648422b86b5447da3aed767 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 6 Aug 2024 16:42:32 -0400 Subject: [PATCH 09/15] Pipettes landing page: not just 96 ch --- api/docs/v2/new_pipette.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/api/docs/v2/new_pipette.rst b/api/docs/v2/new_pipette.rst index dfeee1ed169..840e962aafc 100644 --- a/api/docs/v2/new_pipette.rst +++ b/api/docs/v2/new_pipette.rst @@ -18,11 +18,7 @@ Pages in this section of the documentation cover: - :ref:`Loading pipettes ` into your protocol. - :ref:`Pipette characteristics `, such as how fast they can move liquid and how they move around the deck. - - The :ref:`partial tip pickup ` configuration for the Flex 96-Channel Pipette, which uses only 8 channels for pipetting. Full and partial tip pickup can be combined in a single protocol. + - :ref:`Partial tip pickup ` configurations for multi-channel pipettes. Full and partial tip pickup configurations can be combined in a single protocol. - The :ref:`volume modes ` of Flex 50 µL pipettes, which must operate in low-volume mode to accurately dispense very small volumes of liquid. For information about liquid handling, see :ref:`v2-atomic-commands` and :ref:`v2-complex-commands`. - - - - From 7486087a874381753de0043a0352fe586a496270 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 6 Aug 2024 18:21:25 -0400 Subject: [PATCH 10/15] =?UTF-8?q?edit=20Tip=20Pickup=20and=20Conflicts=20?= =?UTF-8?q?=C2=A7=20for=20consistency?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api/docs/v2/conf.py | 2 +- api/docs/v2/pipettes/partial_tip_pickup.rst | 37 ++++++++++----------- 2 files changed, 18 insertions(+), 21 deletions(-) diff --git a/api/docs/v2/conf.py b/api/docs/v2/conf.py index 1913abbfe1a..7f791b17d35 100644 --- a/api/docs/v2/conf.py +++ b/api/docs/v2/conf.py @@ -99,7 +99,7 @@ # use rst_prolog to hold the subsitution # update the apiLevel value whenever a new minor version is released rst_prolog = f""" -.. |apiLevel| replace:: 2.19 +.. |apiLevel| replace:: 2.20 .. |release| replace:: {release} """ diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index 427e74d909f..eaf216b4798 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -88,7 +88,6 @@ Finally, we configure the nozzle layout, with three arguments. In this configuration, pipetting actions will use a single column:: - # configured in COLUMN mode pipette.pick_up_tip() # picks up A1-H1 from tip rack pipette.drop_tip() pipette.pick_up_tip() # picks up A2-H2 from tip rack @@ -144,7 +143,7 @@ Single Layout Single-tip pickup is available on both 8-channel and 96-channel pipettes. For 8-channel pipettes, there are two possible configurations, using either the front or back nozzle. For 96-channel pipettes, there are four possible configurations, using any of the corner nozzles. -The ``start`` parameter sets the "first" and only nozzle used in the configuration. It also affects the order in which the pipette picks up tips. When using automatic tip tracking, single-tip configurations always consume all tips within a single column before proceeding to another column. +The ``start`` parameter sets the first and only nozzle used in the configuration. It also affects the order in which the pipette picks up tips. When using automatic tip tracking, single-tip configurations always consume all tips within a single column before proceeding to another column. .. list-table:: :header-rows: 1 @@ -250,12 +249,15 @@ To specify the number of tips to pick up, add the ``end`` parameter when calling - C - B -Here is the start of a protocol that imports the ``PARTIAL_COLUMN`` and ``ALL`` layout constants, loads an 8-channel pipette, and sets it to pick up four tips:: +Here is the start of a protocol that imports the ``PARTIAL_COLUMN`` and ``ALL`` layout constants, loads an 8-channel pipette, and sets it to pick up four tips: + +.. code-block:: python + :substitutions: from opentrons import protocol_api from opentrons.protocol_api import PARTIAL_COLUMN, ALL - requirements = {"robotType": "Flex", "apiLevel": "2.20"} + requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} def run(protocol: protocol_api.ProtocolContext): partial_rack = protocol.load_labware( @@ -300,11 +302,11 @@ When handling liquids in partial column configuration, remember that *the frontm Tip Rack Adapters ================= -You can use both partial and full tip pickup in the same protocol. This requires having some tip racks directly on the deck, and some tip racks in the tip rack adapter. +You can use both partial and full tip pickup in the same protocol. When using both with a 96-channel pipette, you must load some tip racks directly on the deck, and some tip racks in a tip rack adapter. -Do not use a tip rack adapter when performing partial tip pickup. Instead, place the tip rack on the deck. During partial tip pickup, the 96-channel pipette lowers onto the tip rack in a horizontally offset position. If the tip rack were in its adapter, the pipette would collide with the adapter's posts, which protrude above the top of the tip rack. If you configure the pipette for partial pickup and then call ``pick_up_tip()`` on a tip rack that's loaded onto an adapter, the API will raise an error. +Do not use a tip rack adapter when performing partial tip pickup with a 96-channel pipette. Instead, place the tip rack on the deck. During partial tip pickup, the 96-channel pipette lowers onto the tip rack in an offset position. If the tip rack were in its adapter, the pipette could collide with the adapter's posts, which protrude above the top of the tip rack. If you configure the 96-channel pipette for partial pickup and then call ``pick_up_tip()`` on a tip rack that's loaded onto an adapter, the API will raise an error. -On the other hand, you must use the tip rack adapter for full tip pickup. If the 96-channel pipette is in a full layout, either by default or by configuring ``style=ALL``, and you then call ``pick_up_tip()`` on a tip rack that's not in an adapter, the API will raise an error. +On the other hand, you must use the tip rack adapter for full rack pickup. If the 96-channel pipette is in a full layout, either by default or by configuring ``style=ALL``, and you then call ``pick_up_tip()`` on a tip rack that's not in an adapter, the API will raise an error. When switching between full and partial pickup, you may want to organize your tip racks into lists, depending on whether they're loaded on adapters or not. @@ -353,9 +355,9 @@ This keeps tip tracking consistent across each type of pickup. And it reduces th Tip Pickup and Conflicts ======================== -During partial tip pickup, 96-channel pipette moves into spaces above adjacent slots. To avoid crashes, the API prevents you from performing partial tip pickup when there is tall labware in these spaces. The current nozzle layout determines which labware can safely occupy adjacent slots. +During partial tip pickup, pipettes move into spaces above adjacent slots. To avoid crashes, the API prevents you from performing partial tip pickup when there is tall labware in these spaces. The current nozzle layout determines which labware can safely occupy adjacent slots. -The API will raise errors for potential labware crashes when using a column nozzle configuration. Nevertheless, it's a good idea to do the following when working with partial tip pickup: +The API will raise errors for potential labware crashes when using a partial nozzle configuration. Nevertheless, it's a good idea to do the following when working with partial tip pickup: - Plan your deck layout carefully. Make a diagram and visualize everywhere the pipette will travel. - Simulate your protocol and compare the run preview to your expectations of where the pipette will travel. @@ -368,6 +370,10 @@ For column pickup, Opentrons recommends using the nozzles in column 12 of the pi start="A12", ) +.. note:: + + When using a column 1 layout, the pipette can't reach the rightmost portion of labware in slots A3–D3. Any well that is within 29 mm of the right edge of the slot may be inaccessible. Use a column 12 layout if you need to pipette in that area. + When using column 12, the pipette overhangs space to the left of wherever it is picking up tips or pipetting. For this reason, it's a good idea to organize tip racks front to back on the deck. If you place them side by side, the rack to the right will be inaccessible. For example, let's load three tip racks in the front left corner of the deck:: tips_C1 = protocol.load_labware("opentrons_flex_96_tiprack_1000ul", "C1") @@ -383,15 +389,6 @@ You would get a similar error trying to aspirate from or dispense into a well pl .. tip:: - When using column 12 for partial tip pickup and pipetting, generally organize your deck with the shortest labware on the left side of the deck, and the tallest labware on the right side. - -If your application can't accommodate a deck layout that works well with column 12, you can configure the 96-channel pipette to pick up tips with column 1:: - - pipette.configure_nozzle_layout( - style=COLUMN, - start="A1", - ) - -.. note:: + When using column 12 nozzles for partial tip pickup and pipetting, generally organize your deck with the shortest labware on the left side of the deck, and the tallest labware on the right side. - When using a column 1 layout, the pipette can't reach the rightmost portion of labware in slots A3–D3. Any well that is within 29 mm of the right edge of the slot may be inaccessible. Use a column 12 layout if you need to pipette in that area. \ No newline at end of file + Similarly, when using the frontmost row of nozzles for partial tip pickup and pipetting, organize your deck with the shortest labware towards the back of the deck, and the tallest labware towards the front of the deck. From 1eadc93d8f08946630801d09b9e987a3b1a38864 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 6 Aug 2024 18:41:19 -0400 Subject: [PATCH 11/15] docstring and versioning --- api/docs/v2/versioning.rst | 9 ++++++++- .../opentrons/protocol_api/instrument_context.py | 15 +++++++-------- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst index 081edca651a..e4891cd06b1 100644 --- a/api/docs/v2/versioning.rst +++ b/api/docs/v2/versioning.rst @@ -68,7 +68,7 @@ The maximum supported API version for your robot is listed in the Opentrons App If you upload a protocol that specifies a higher API level than the maximum supported, your robot won't be able to analyze or run your protocol. You can increase the maximum supported version by updating your robot software and Opentrons App. -Opentrons robots running the latest software (7.3.0) support the following version ranges: +Opentrons robots running the latest software (8.0.0) support the following version ranges: * **Flex:** version 2.15–|apiLevel|. * **OT-2:** versions 2.0–|apiLevel|. @@ -84,6 +84,8 @@ This table lists the correspondence between Protocol API versions and robot soft +-------------+------------------------------+ | API Version | Introduced in Robot Software | +=============+==============================+ +| 2.20 | 8.0.0 | ++-------------+------------------------------+ | 2.19 | 7.3.1 | +-------------+------------------------------+ | 2.18 | 7.3.0 | @@ -132,6 +134,11 @@ This table lists the correspondence between Protocol API versions and robot soft Changes in API Versions ======================= +Version 2.20 +------------ + +- :py:meth:`.configure_nozzle_layout` now accepts row, single, and partial column layout constants. See :ref:`partial-tip-pickup`. + Version 2.19 ------------ diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index c39a4aba2ac..051ca21a107 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2013,15 +2013,15 @@ def configure_nozzle_layout( # noqa: C901 :param style: The shape of the nozzle layout. - - ``SINGLE`` sets the pipette to use 1 nozzle. This corresponds to a single of well on labware. + - ``ALL`` resets the pipette to use all of its nozzles. Calling + ``configure_nozzle_layout`` with no arguments also resets the pipette. - ``COLUMN`` sets the pipette to use 8 nozzles, aligned from front to back with respect to the deck. This corresponds to a column of wells on labware. - - ``PARTIAL_COLUMN`` sets the pipette to use 2-7 nozzles, aligned from front to back + - ``PARTIAL_COLUMN`` sets the pipette to use 2--7 nozzles, aligned from front to back with respect to the deck. - ``ROW`` sets the pipette to use 12 nozzles, aligned from left to right with respect to the deck. This corresponds to a row of wells on labware. - - ``ALL`` resets the pipette to use all of its nozzles. Calling - ``configure_nozzle_layout`` with no arguments also resets the pipette. + - ``SINGLE`` sets the pipette to use 1 nozzle. This corresponds to a single of well on labware. :type style: ``NozzleLayout`` or ``None`` :param start: The primary nozzle of the layout, which the robot uses @@ -2039,16 +2039,15 @@ def configure_nozzle_layout( # noqa: C901 should be of the same format used when identifying wells by name. Required when setting ``style=PARTIAL_COLUMN``. - .. note:: - Nozzle layouts numbering between 2-7 nozzles, account for the distance from - ``start``. For example, 4 nozzles would require ``start="H1"`` and ``end="E1"``. - :type end: str or ``None`` :param tip_racks: Behaves the same as setting the ``tip_racks`` parameter of :py:meth:`.load_instrument`. If not specified, the new configuration resets :py:obj:`.InstrumentContext.tip_racks` and you must specify the location every time you call :py:meth:`~.InstrumentContext.pick_up_tip`. :type tip_racks: List[:py:class:`.Labware`] + + .. versionchanged:: 2.20 + Added partial column, row, and single layouts. """ # TODO: add the following back into the docstring when QUADRANT is supported # From f9867fe27a502fe50ee32fbc845c1052a14dbc30 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Sun, 11 Aug 2024 22:23:26 -0400 Subject: [PATCH 12/15] no partial column for 96-channel --- api/docs/v2/pipettes/partial_tip_pickup.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index eaf216b4798..5e4afc992bc 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -20,7 +20,7 @@ Before getting started with partial tip pickup, make sure your protocol specifie - Column - 2.16 * - Flex 96-Channel Pipette - - Single, partial column, row + - Single, row - 2.20 * - Flex 8-Channel Pipettes - Single, partial column @@ -223,11 +223,7 @@ Since this configuration uses ``start="H12"``, it will pick up tips in the usual Partial Column Layout --------------------- -Partial column pickup is available on both 8-channel and 96-channel pipettes. Partial columns contain 2 to 7 consecutive tips in a single column. 8-channel pipettes always pick up partial columns with the frontmost nozzles of the pipette (``start="H1"``). 96-channel pipettes can pick up partial columns with the frontmost nozzles in the leftmost column (``start="H1"``) or the rightmost column (``start="H12"``). - -.. note:: - - Picking up partial columns with the backmost nozzles is currently not supported. Setting ``style=PARTIAL_COLUMN`` and either ``start="A1"`` or ``start="A12"`` will raise an error. +Partial column pickup is available on 8-channel pipettes only. Partial columns contain 2 to 7 consecutive tips in a single column. The pipette always picks up partial columns with its frontmost nozzles (``start="H1"``). To specify the number of tips to pick up, add the ``end`` parameter when calling :py:meth:`.configure_nozzle_layout`. Use the chart below to determine the end row (G through B) for your desired number of tips. The end column should be the same as your start column (1 or 12). From 05a6be6ad284bdf0dca679ea7227fed38e3bfdb6 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Mon, 12 Aug 2024 09:56:19 -0400 Subject: [PATCH 13/15] implement prose feedback --- api/docs/v2/pipettes/partial_tip_pickup.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index 5e4afc992bc..28798e3e6ce 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -32,19 +32,21 @@ Before getting started with partial tip pickup, make sure your protocol specifie Nozzle Layouts ============== -Use the :py:meth:`.configure_nozzle_layout` method to choose how many tips a pipette will pick up. The method's ``style`` parameter accepts special layout constants. You must import these constants at the top of your protocol, or you won't be able to configure the pipette for partial tip pickup. +Use the :py:meth:`.configure_nozzle_layout` method to choose how many tips a pipette will pick up. The method's required ``style`` parameter only accepts special layout constants. You must import these constants at the top of your protocol, or you won't be able to configure the pipette for partial tip pickup. At minimum, import the API from the ``opentrons`` package:: from opentrons import protocol_api -Then when you call ``configure_nozzle_layout`` later in your protocol, you can set a layout like ``style=protocol_api.COLUMN``. +This import statement lets you configure a layout with a parameter like ``style=protocol_api.COLUMN``. For greater convenience, also import the individual layout constants that you plan to use in your protocol:: from opentrons.protocol_api import COLUMN, ALL -Then when you call ``configure_nozzle_layout`` later in your protocol, you can use the shorter ``style=COLUMN``. +This more specific import statement lets you configure a layout with a parameter like ``style=COLUMN``. However, you wouldn't be able to set ``style=ROW`` without also importing that constant. + +The examples in the sections below use the shorter style and show the other required parameters of ``configure_nozzle_layout()``. Column Layout ------------- @@ -141,7 +143,10 @@ You can also set ``start="A1"`` to use the backmost nozzles and pick up from the Single Layout ------------- -Single-tip pickup is available on both 8-channel and 96-channel pipettes. For 8-channel pipettes, there are two possible configurations, using either the front or back nozzle. For 96-channel pipettes, there are four possible configurations, using any of the corner nozzles. +Single-tip pickup is available on both 8-channel and 96-channel pipettes. 8-channel pipettes can pick up a single tip with either the front or back nozzle. 96-channel pipettes can pick up a single tip with any of the corner nozzles. + +.. note:: + Remember that only the A1 and H12 nozzles of the 96-channel pipette contain pressure sensors. Avoid using the A12 and H1 nozzles for single-tip pickup if you need to detect liquid presence within wells. The ``start`` parameter sets the first and only nozzle used in the configuration. It also affects the order in which the pipette picks up tips. When using automatic tip tracking, single-tip configurations always consume all tips within a single column before proceeding to another column. @@ -217,7 +222,7 @@ Since this configuration uses ``start="H12"``, it will pick up tips in the usual .. note:: - You can pick up tips row-wise first, rather than column-wise first, by specifying a location for :py:meth:`.pick_up_tip` each time you use it in ``SINGLE`` configuration. However, as with all partial tip layouts, be careful that you don't place the pipette in a position where it overlaps more tips than intended. + You can pick up tips row by row, rather than column by column, by specifying a location for :py:meth:`.pick_up_tip` each time you use it in ``SINGLE`` configuration. However, as with all partial tip layouts, be careful that you don't place the pipette in a position where it overlaps more tips than intended. Partial Column Layout From 8120463fbccc3285b9be96714d53a1cb7355c490 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Mon, 12 Aug 2024 14:24:08 -0400 Subject: [PATCH 14/15] final edits to API ref --- api/docs/v2/pipettes/partial_tip_pickup.rst | 2 ++ .../opentrons/protocol_api/instrument_context.py | 13 ++++++++----- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index 28798e3e6ce..914d09a3bd9 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -29,6 +29,8 @@ Before getting started with partial tip pickup, make sure your protocol specifie - Single, partial column - 2.20 +.. _nozzle-layouts: + Nozzle Layouts ============== diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 051ca21a107..d5df5a8a918 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2012,16 +2012,19 @@ def configure_nozzle_layout( # noqa: C901 tips from a tip rack that is in an adapter, the API will raise an error. :param style: The shape of the nozzle layout. + You must :ref:`import the layout constant ` in order to use it. - ``ALL`` resets the pipette to use all of its nozzles. Calling ``configure_nozzle_layout`` with no arguments also resets the pipette. - - ``COLUMN`` sets the pipette to use 8 nozzles, aligned from front to back + - ``COLUMN`` sets a 96-channel pipette to use 8 nozzles, aligned from front to back with respect to the deck. This corresponds to a column of wells on labware. - - ``PARTIAL_COLUMN`` sets the pipette to use 2--7 nozzles, aligned from front to back - with respect to the deck. - - ``ROW`` sets the pipette to use 12 nozzles, aligned from left to right + For 8-channel pipettes, use ``ALL`` instead. + - ``PARTIAL_COLUMN`` sets an 8-channel pipette to use 2--7 nozzles, aligned from front to back + with respect to the deck. Not compatible with the 96-channel pipette. + - ``ROW`` sets a 96-channel pipette to use 12 nozzles, aligned from left to right with respect to the deck. This corresponds to a row of wells on labware. - - ``SINGLE`` sets the pipette to use 1 nozzle. This corresponds to a single of well on labware. + Not compatible with 8-channel pipettes. + - ``SINGLE`` sets the pipette to use 1 nozzle. This corresponds to a single well on labware. :type style: ``NozzleLayout`` or ``None`` :param start: The primary nozzle of the layout, which the robot uses From b05bee221d1ded722feafcc30c08d717632c5e91 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Mon, 12 Aug 2024 17:16:22 -0400 Subject: [PATCH 15/15] final_final_3 --- api/docs/v2/pipettes/partial_tip_pickup.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index 914d09a3bd9..e799d25554f 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -87,7 +87,7 @@ Next, we load the 96-channel pipette. Note that :py:meth:`.load_instrument` only Finally, we configure the nozzle layout, with three arguments. - The ``style`` parameter directly accepts the ``COLUMN`` constant, since we imported it at the top of the protocol. - - The ``start`` parameter accepts a nozzle name, representing the back-left nozzle in the layout, as a string. ``"A12"`` tells the pipette to use its rightmost column of nozzles for pipetting. + - The ``start`` parameter accepts a nozzle name, representing the primary nozzle in the layout, as a string. ``"A12"`` tells the pipette to use its rightmost column of nozzles for pipetting. - The ``tip_racks`` parameter tells the pipette which racks to use for tip tracking, just like :ref:`adding tip racks ` when loading a pipette. In this configuration, pipetting actions will use a single column:: @@ -160,27 +160,27 @@ The ``start`` parameter sets the first and only nozzle used in the configuration - Pickup order * - 8-channel - A1 - - | Front to back, right to left + - | Front to back, left to right | (H1 through A1, H2 through A2, …) * - 8-channel - H1 - - | Back to front, right to left + - | Back to front, left to right | (A1 through H1, A2 through H2, …) * - 96-channel - A1 - - | Front to back, left to right + - | Front to back, right to left | (H12 through A12, H11 through A11, …) * - 96-channel - H1 - - | Back to front, left to right + - | Back to front, right to left | (A12 through H12, A11 through H11, …) * - 96-channel - A12 - - | Front to back, right to left + - | Front to back, left to right | (H1 through A1, H2 through A2, …) * - 96-channel - H12 - - | Back to front, right to left + - | Back to front, left to right | (A1 through H1, A2 through H2, …) Since they follow the same pickup order as a single-channel pipette, Opentrons recommends using the following configurations: @@ -252,6 +252,8 @@ To specify the number of tips to pick up, add the ``end`` parameter when calling - C - B +When picking up 3, 5, 6, or 7 tips, extra tips will be left at the front of each column. You can use these tips with a different nozzle configuration, or you can manually re-rack them at the end of your protocol for future use. + Here is the start of a protocol that imports the ``PARTIAL_COLUMN`` and ``ALL`` layout constants, loads an 8-channel pipette, and sets it to pick up four tips: .. code-block:: python @@ -288,6 +290,7 @@ This configuration will pick up tips from the back half of column 1, then the fr When handling liquids in partial column configuration, remember that *the frontmost channel of the pipette is its primary channel*. For example, to use the same configuration as above to transfer liquid from wells A1–D1 to wells A2–D2 on a plate, you must use the wells in row D as the source and destination targets:: + # pipette in 4-nozzle partial column layout pipette.transfer( volume=100, source=plate["D1"], # aspirate from A1-D1 @@ -335,7 +338,7 @@ When switching between full and partial pickup, you may want to organize your ti .. Tip:: - It's also good practice to keep separate lists of tip racks when using multiple partial tip pickup configurations (i.e., using both column 1 and column 12 in the same protocol). This improves positional accuracy when picking up tips. Additionally, use Labware Position Check in the Opentrons App to ensure that the partial configuration is well-aligned to the rack. + It's also good practice to keep separate lists of tip racks when using multiple partial tip pickup configurations (e.g., using both column 1 and column 12 in the same protocol). This improves positional accuracy when picking up tips. Additionally, use Labware Position Check in the Opentrons App to ensure that the partial configuration is well-aligned to the rack. Now, when you configure the nozzle layout, you can reference the appropriate list as the value of ``tip_racks``:: @@ -350,7 +353,7 @@ Now, when you configure the nozzle layout, you can reference the appropriate lis style=ALL, tip_racks=full_tip_racks ) - pipette.pick_up_tip() # picks up full rack in C1 + pipette.pick_up_tip() # picks up full rack in C3 This keeps tip tracking consistent across each type of pickup. And it reduces the risk of errors due to the incorrect presence or absence of a tip rack adapter.