Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(api): update descriptions of partial tip pickup behavior for 7.3 #15003

Merged
merged 2 commits into from
Apr 29, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 9 additions & 23 deletions api/docs/v2/pipettes/partial_tip_pickup.rst
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ 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 set ``style=COLUMN``.

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.

Expand Down Expand Up @@ -106,6 +106,10 @@ When switching between full and partial pickup, you may want to organize your ti
partial_tip_racks = [tips_1, tips_2]
full_tip_racks = [tips_3, tips_4]

.. 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good and communicates what we want. Regarding the last sentence, I think we need to confirm what exactly LPC looks like for partial configuration (I personally have never encountered it) and communicate that if possible.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just spoke with Sanniti, looks like LPC for partial tips is just standard LPC. You'd account for the tip overlap offset during said LPC, then presumably only use the partial configuration you LPC'd for on that piece of labware. So I think this documentation is acceptable on that front, we don't want to over-explain and end up causing confusion once this problem is addressed in full.


Now, when you configure the nozzle layout, you can reference the appropriate list as the value of ``tip_racks``::

pipette.configure_nozzle_layout(
Expand All @@ -120,7 +124,7 @@ Now, when you configure the nozzle layout, you can reference the appropriate lis
tip_racks=full_tip_racks
)
pipette.pick_up_tip() # picks up full rack in C1

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.


Expand All @@ -135,12 +139,7 @@ The API will raise errors for potential labware crashes when using a column nozz
- Simulate your protocol and compare the run preview to your expectations of where the pipette will travel.
- Perform a dry run with only tip racks on the deck. Have the Emergency Stop Pendant handy in case you see an impending crash.

For column pickup, Opentrons recommends using the nozzles in column 12 of the pipette.

Using Column 12
---------------

The examples in this section use a 96-channel pipette configured to pick up tips with column 12::
For column pickup, Opentrons recommends using the nozzles in column 12 of the pipette::

pipette.configure_nozzle_layout(
style=COLUMN,
Expand All @@ -164,26 +163,13 @@ You would get a similar error trying to aspirate from or dispense into a well pl

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.

Using Column 1
--------------

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",
)

The major drawback of this configuration, compared to using column 12, is that tip tracking is not available with column 1. You must always specify a ``location`` parameter for :py:meth:`.pick_up_tip`. This *requires careful tip tracking* so you don't place the pipette over more than a single column of unused tips at once. You can write some additional code to manage valid tip pickup locations, like this::

tip_rack = protocol.load_labware("opentrons_flex_96_tiprack_1000ul", "C1")
pipette.configure_nozzle_layout(style=COLUMN, start="A1")
row_a = tip_rack.rows()[0]
pipette.pick_up_tip(row_a.pop()) # pick up A12-H12
pipette.drop_tip()
pipette.pick_up_tip(row_a.pop()) # pick up A11-H11
pipette.drop_tip()

This code first constructs a list of all the wells in row A of the tip rack. Then, when picking up a tip, instead of referencing one of those wells directly, the ``location`` is set to ``row_a.pop()``. This uses the `built-in pop method <https://docs.python.org/3/tutorial/datastructures.html#more-on-lists>`_ to get the last item from the list and remove it from the list. If you keep using this approach to pick up tips, you'll get an error once the tip rack is empty — not from the API, but from Python itself, since you're trying to ``pop`` an item from an empty list.
.. note::

Additionally, you can't access the rightmost columns in labware in column 3, since they are beyond the movement limit of the pipette. The exact number of inaccessible columns varies by labware type. Any well that is within 29 mm of the right edge of the slot may be inaccessible in a column 1 configuration. Call ``configure_nozzle_layout()`` again to switch to a column 12 layout if you need to pipette in that area.
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.
7 changes: 2 additions & 5 deletions api/src/opentrons/protocol_api/instrument_context.py
Original file line number Diff line number Diff line change
Expand Up @@ -1948,11 +1948,8 @@ def configure_nozzle_layout(
Required unless setting ``style=ALL``.

.. note::
When using the ``COLUMN`` layout, the only fully supported value is
``start="A12"``. You can use ``start="A1"``, but this will disable tip
tracking and you will have to specify the ``location`` every time you
call :py:meth:`.pick_up_tip`, such that the pipette picks up columns of
tips *from right to left* on the tip rack.
If possible, don't use both ``start="A1"`` and ``start="A12"`` to pick up
tips *from the same rack*. Doing so can affect positional accuracy.

:type start: str or ``None``
:param tip_racks: Behaves the same as setting the ``tip_racks`` parameter of
Expand Down
Loading