docs(api): liquid meniscus in API 2.23 #17971
Merged
+101
−11
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
emilyburghardt
commented
Apr 2, 2025
| pipette.measure_liquid_height(plate["B1"]) | ||
| pipette.dispense(200, location=plate["B1"].meniscus(z=-1)) #dispenses 1 mm below the liquid meniscus | ||
|
|
||
| The API will raise an error if no liquid is present in the well. |
There was a problem hiding this comment.
is this true? the API raises an error if no liquid is present to measure in the well?
There was a problem hiding this comment.
Looks like this was fixed in #17957
| Measure Liquids | ||
| =============== | ||
|
|
||
| The :py:meth:`.measure_liquid_height` method tells a Flex pipette to measure the height of liquid in a well. It returns the height of liquid in the well in mm. When ``measure_liquid_height()`` finds an empty well, it raises and error and pauses the protocol to let you resove the problem. |
There was a problem hiding this comment.
double check that this is 1) Flex-only and 2) requires a tip to measure liquid. fix "resove" typo in my next commit
api/docs/v2/robot_position.rst
Outdated
| - Specifying your starting liquid volume with :py:meth:`~Labware.load_liquid_by_well`, or | ||
| - Using :py:meth:`.measure_liquid_height` to define liquid volume in the well. | ||
|
|
||
| Detecting liquid in a well requires pipette sensors, so you can only measure liquid height with Flex pipettes. However... |
There was a problem hiding this comment.
load_liquid_by_well isn't OT-2 specific, so an OT-2 user could get this far and then.... the API would raise an error? or is liquid meniscus supported for OT-2?
sfoster1
changed the title
ecormany
reviewed
Apr 7, 2025
api/docs/v2/robot_position.rst
Outdated
| @@ -16,10 +16,12 @@ Position Relative to Labware | |||
|
|
|||
| When the robot positions itself relative to a piece of labware, where it moves is determined by the labware definition, the actions you want it to perform, and the labware offsets for a specific deck slot. This section describes how these positional components are calculated and how to change them. | |||
|
|
|||
| Top, Bottom, and Center | |||
| ----------------------- | |||
| Top, Bottom, Center, and Meniscus | |||
There was a problem hiding this comment.
Getting kinda long. Maybe we can call this section "Well positions" now.
Comment on lines
271
to
272
| :param target: The relative position inside the well to target when performing a liquid handling operation. | ||
| :return: A :py:class:`~opentrons.types.Location` that indicates location is meniscus and that holds the ``z`` offset in its point.z field. |
There was a problem hiding this comment.
These need some improvement, either in this PR or separately.
There was a problem hiding this comment.
Updated this today. Started to document start and end more, but remembered that we want to hold off on mentions of dynamic. Can ticket beefing this reference up for API 2.24 docs.
Other than that, roughly followed the structure of the other well position API refs.
| @@ -48,6 +48,19 @@ You can also aspirate from a location along the center vertical axis within a we | |||
| depth = plate["A1"].bottom(z=2) # tip is 2 mm above well bottom | |||
| pipette.aspirate(200, depth) | |||
|
|
|||
|
|
|||
| Use the :py:meth:`~.Labware.Well.mensicus` method to aspirate from the meniscus of liquid in a well with a Flex pipette. First, you'll need to define the volume of liquid in your well: | |||
There was a problem hiding this comment.
"relative to the meniscus"? "from" sounds like the exact location of the meniscus (which is not the usual behavior).
| pipette.measure_liquid_height(plate["A2"]) | ||
| pipette.aspirate(200, location=plate["A2"].meniscus(target="end", z=-1)) # aspirates at 1 mm below the liquid meniscus | ||
|
|
||
| The liquid meniscus changes when you aspirate liquid from a well. Set ``target`` to the ending position of the liquid within a well to ensure the pipette stays submerged while aspirating. For more information, see :ref:`well-meniscus`. |
There was a problem hiding this comment.
We'll sometimes shorten things by putting the parameter and value together in running text:
Suggested change
| The liquid meniscus changes when you aspirate liquid from a well. Set ``target`` to the ending position of the liquid within a well to ensure the pipette stays submerged while aspirating. For more information, see :ref:`well-meniscus`. | |
| The liquid meniscus changes when you aspirate liquid from a well. Set ``target=end`` to ensure the pipette stays submerged while aspirating. For more information, see :ref:`well-meniscus`. |
api/docs/v2/robot_position.rst
Outdated
| Meniscus | ||
| ^^^^^^^^ | ||
|
|
||
| Let's look at the :py:meth:`~.Labware.well-meniscus` method. It returns a position at the surface of liquid, or meniscus, inside a well. Like the `.Well.top` and `.Well.bottom` methods, you can adjust the height of the meniscus with the optional argument ``z``, which is measured in mm. Positive numbers move the position up, negative ``z`` numbers move it down. |
There was a problem hiding this comment.
Suggested change
| Let's look at the :py:meth:`~.Labware.well-meniscus` method. It returns a position at the surface of liquid, or meniscus, inside a well. Like the `.Well.top` and `.Well.bottom` methods, you can adjust the height of the meniscus with the optional argument ``z``, which is measured in mm. Positive numbers move the position up, negative ``z`` numbers move it down. | |
| Let's look at the :py:meth:`~.Labware.well-meniscus` method. It returns a position at the surface of liquid, or meniscus, inside a well. Like the `.Well.top` and `.Well.bottom` methods, you can adjust the height of the meniscus with the optional argument ``z``, which is measured in mm. Positive ``z`` values move the position up, and negative ones move it down. |
api/docs/v2/robot_position.rst
Outdated
| The liquid meniscus in a well changes during aspirating or dispensing, so you'll also need to specify a ``target`` position for the pipette: | ||
| - Set ``target= "end"`` to ensure the pipette stays submerged while aspirating. | ||
| - Set ``target= "start"`` or ``end`` to choose where the pipette begins dispensing. |
There was a problem hiding this comment.
might be useful to split these out and describe how they would create a contact or non-contact dispense.
api/docs/v2/robot_position.rst
Outdated
| - Specifying your starting liquid volume with :py:meth:`~.Labware.load_liquid`, or | ||
| - Using :py:meth:`~.InstrumentContext.measure_liquid_height` to define liquid volume in the well. | ||
|
|
||
| Detecting liquid in a well requires pipette sensors, so you can only measure liquid height with a Flex pipette. |
There was a problem hiding this comment.
i think this should also be inside the note (indented)
api/docs/v2/robot_position.rst
Outdated
| @@ -169,7 +207,7 @@ Move To | |||
|
|
|||
| The :py:meth:`.InstrumentContext.move_to` method moves a pipette to any reachable location on the deck. If the pipette has picked up a tip, it will move the end of the tip to that position; if it hasn't, it will move the pipette nozzle to that position. | |||
|
|
|||
| The :py:meth:`~.InstrumentContext.move_to` method requires the :py:class:`.Location` argument. The location can be automatically generated by methods like ``Well.top()`` and ``Well.bottom()`` or one you've created yourself, but you can't move a pipette to a well directly: | |||
| The :py:meth:`~.InstrumentContext.move_to` method requires the :py:class:`.Location` argument. The location can be automatically generated by methods like ``Well.top()``, ``Well.bottom()``, and ``Well.mensicus``, or one you've created yourself. However, you can't move a pipette to a well directly: | |||
There was a problem hiding this comment.
parens again
Suggested change
| The :py:meth:`~.InstrumentContext.move_to` method requires the :py:class:`.Location` argument. The location can be automatically generated by methods like ``Well.top()``, ``Well.bottom()``, and ``Well.mensicus``, or one you've created yourself. However, you can't move a pipette to a well directly: | |
| The :py:meth:`~.InstrumentContext.move_to` method requires the :py:class:`.Location` argument. The location can be automatically generated by methods like ``Well.top()``, ``Well.bottom()``, and ``Well.mensicus()``, or one you've created yourself. However, you can't move a pipette to a well directly: |
api/docs/v2/robot_position.rst
Outdated
| The liquid meniscus in a well changes during aspirating or dispensing, so you'll also need to specify a ``target`` position relative to the meniscus. Each position target is useful in different scenarios: | ||
|
|
||
| - Set ``target= "start"`` to target the existing liquid meniscus in the destination well before an aspirate or dispense. |
There was a problem hiding this comment.
I would say take aspirate out of aspirate or dispense here, and write a note around here telling people not to aspirate with target='start' since that'll cause the pipette to be too high during the aspirate at some point.
If this is useful info trying to do this will cause you to fail analysis
caila-marashaj
force-pushed
the
docs-liquid-meniscus
branch
from
d1cab0e to
08ec6d2
Compare
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## chore_release-8.4.0 #17971 +/- ##
====================================================
Coverage 28.32% 28.32%
====================================================
Files 3114 3114
Lines 236301 236301
Branches 19885 19885
====================================================
Hits 66939 66939
Misses 169340 169340
Partials 22 22
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
caila-marashaj
force-pushed
the
docs-liquid-meniscus
branch
from
08ec6d2 to
97b4ee9
Compare
merge latest changes into my branch
emilyburghardt
force-pushed
the
docs-liquid-meniscus
branch
from
97b4ee9 to
fbf36f6
Compare
skowalski08
reviewed
Apr 15, 2025
|
|
||
| The liquid meniscus changes when you aspirate liquid from a well. Set ``target="end"`` to ensure the pipette stays submerged while aspirating. For more information, see :ref:`well-meniscus`. | ||
|
|
||
| ``measure_liquid_height()`` works best with a new pipette tip each time. To save time and tips throughout your protocol, use ``Labware.load_liquid`` to specify starting liquid volumes. |
There was a problem hiding this comment.
If we do load_liquid() then we don't need to do measure_liquid_height() or liquid_presence_detection=True. As long as we load liquid (and the user is confident in their volumes) and .meniscus() it will work
There was a problem hiding this comment.
Suggested change
| ``measure_liquid_height()`` works best with a new pipette tip each time. To save time and tips throughout your protocol, use ``Labware.load_liquid`` to specify starting liquid volumes. | |
| ``measure_liquid_height()`` works best with a new pipette tip each time. To save time and tips throughout your protocol, use ``Labware.load_liquid`` instead to specify starting liquid volumes. |
caila-marashaj
approved these changes
Apr 15, 2025
ecormany
reviewed
Apr 15, 2025
|
|
||
| The liquid meniscus changes when you aspirate liquid from a well. Set ``target="end"`` to ensure the pipette stays submerged while aspirating. For more information, see :ref:`well-meniscus`. | ||
|
|
||
| ``measure_liquid_height()`` works best with a new pipette tip each time. To save time and tips throughout your protocol, use ``Labware.load_liquid`` to specify starting liquid volumes. |
There was a problem hiding this comment.
Suggested change
| ``measure_liquid_height()`` works best with a new pipette tip each time. To save time and tips throughout your protocol, use ``Labware.load_liquid`` to specify starting liquid volumes. | |
| ``measure_liquid_height()`` works best with a new pipette tip each time. To save time and tips throughout your protocol, use ``Labware.load_liquid`` instead to specify starting liquid volumes. |
|
Only failures in docs build are cross-references that will be resolved in #18025, to be merged next. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview
Adding liquid meniscus changes in API 2.23
Test Plan and Hands on Testing
sandbox: http://sandbox.docs.opentrons.com/docs-liquid-meniscus/v2/
Changelog
measure_liquid_heightin API 2.23Well.meniscusas a locationmeniscusas a location in a wellmeniscusto Default PositionsReview requests
targetandmeasure_liquid_heightclear enough?Risk assessment
low.