docs(api): load liquids in API 2.23 #18025

emilyburghardt · 2025-04-09T23:16:05Z

Overview

documenting a new method for loading liquids into labware in API 2.23.

Test Plan and Hands on Testing

sandbox: http://sandbox.docs.opentrons.com/docs-load-liquid/v2/

Changelog

updated "labeling liquids in wells" to "labeling liquids in labware"; changed examples in this section to use our new methods: Labware.load_liquid and Labware.load_liquid_by_well, and a mention for Labware.load_empty.
updated the API reference entries for the methods above, + added a deprecated message for the original load_liquid.

Review requests

code blocks correct? especially wells in each example...
anything I'm missing?
I edited the original API reference entries to remove the examples (used to write the examples in Labeling Liquids in Labware). Do we want them back?

Risk assessment

emilyburghardt · 2025-04-09T23:16:39Z

api/src/opentrons/protocol_api/labware.py


-        :param volume: The volume of liquid to load into each well, in 10µL.
+        :param volume: The volume of liquid to load into each well. Must be a multiple of 10.


Making an assumption here that this meant the volume must be a multiple of 10... but I could be wrong.

No thats definitely just a typo. Should be a multiple of 1.

Thank you!!

ecormany

Good overall. Some small, but necessary, fixes remain. Tried to leave suggestions for all.

One open content question is whether we need to keep some mention of Well.load_liquid() in the article. It was in the API for a good long time (and still technically is) and I don't think we would want to imply that loading liquids is effectively only available in 2.23+.

ecormany · 2025-04-14T14:04:48Z

api/docs/v2/new_labware.rst

@@ -298,18 +298,35 @@ The ``display_color`` parameter accepts a hex color code, which adds a color to
 Labeling Wells and Reservoirs
 =============================

-This example uses ``load_liquid`` to label the initial well location, contents, and volume (in µL) for the liquid objects created by ``define_liquid``. Notice how values of the ``liquid`` argument use the variable names ``greenWater`` and ``blueWater`` (defined above) to associate each well with a particular liquid: 
+This example uses ``load_liquid`` to label the initial well location, contents, and volume (in µL) for the liquid objects created by ``define_liquid``. Notice how values of the ``liquid`` argument use the variable names ``greenWater`` and ``blueWater`` (defined above) to associate each labware with a particular liquid: 


I think it's important to note that the new Labware method still makes reference to individual wells — it's not all or nothing.

Suggested change

This example uses ``load_liquid`` to label the initial well location, contents, and volume (in µL) for the liquid objects created by ``define_liquid``. Notice how values of the ``liquid`` argument use the variable names ``greenWater`` and ``blueWater`` (defined above) to associate each labware with a particular liquid:

This example uses ``load_liquid`` to label the initial well location, contents, and volume (in µL) for the liquid objects created by ``define_liquid``. Notice how values of the ``liquid`` argument use the variable names ``greenWater`` and ``blueWater`` (defined above) to associate wells in each labware with a particular liquid:

ecormany · 2025-04-14T14:06:38Z

api/docs/v2/new_labware.rst

+        ## load entire well plate with greenWater
+        well_plate.load_liquid(
+            wells=()[0],
+            volume=50,
+            liquid="greenWater"
+        )
+
+        ## load entire reservoir with blueWater
+        reservoir.load_liquid(
+            wells=[A1],
+            volume=50,
+            liquid="blueWater"
+        )


Fix up this code so it simulates and has proper comment formatting.

Suggested change

## load entire well plate with greenWater

well_plate.load_liquid(

wells=()[0],

volume=50,

liquid="greenWater"

)

## load entire reservoir with blueWater

reservoir.load_liquid(

wells=[A1],

volume=50,

liquid="blueWater"

)

# load entire well plate with greenWater

plate.load_liquid(

wells=plate.wells(), # using accessor

volume=50,

liquid=greenWater

)

# load entire reservoir with blueWater

reservoir.load_liquid(

wells=["A1"], # using list of well names

volume=50,

liquid=blueWater

)

ecormany · 2025-04-14T14:07:04Z

api/docs/v2/new_labware.rst

+    well_plate.load_liquid_by_well({'A1': 200, 'A2': 100, 'A3': 50}, greenWater)
+    well_plate.load_liquid_by_well({'B1': 200, 'B2': 100, 'B3': 50}, blueWater)


Let's use plate as the labware name here too. Not sure why we had well_plate before — it doesn't match our docs template protocol.

ecormany · 2025-04-14T14:22:41Z

api/docs/v2/new_labware.rst


-.. versionadded:: 2.14
+.. versionadded:: 2.23


Double checked and these were added in 2.22.

ecormany · 2025-04-14T14:32:30Z

api/src/opentrons/protocol_api/labware.py


        :param wells: The wells to load the liquid into.
-        :type wells: List of well names or list of Well objects, for instance from :py:meth:`~Labware.wells`.
+        :type wells: List of well names or list of Well objects- for instance, from :py:meth:`~Labware.wells`.


A little clearer on the types. And sewing up the clauses more neatly.

Suggested change

:type wells: List of well names or list of Well objects- for instance, from :py:meth:`~Labware.wells`.

:type wells: List of string well names or list of :py:class:`.Well` objects (e.g., from :py:meth:`~Labware.wells`).

ecormany · 2025-04-14T14:32:58Z

api/src/opentrons/protocol_api/labware.py

-
-        If you want to mark the well as containing no liquid, use :py:meth:`~Labware.load_empty`.
+        This method should be called at the beginning of a protocol, soon after loading labware and before
+        liquid handling operations begin. Loading liquids is required for liquid tracking functionality- if a well


Same change here and other methods.

Suggested change

liquid handling operations begin. Loading liquids is required for liquid tracking functionality- if a well

liquid handling operations begin. Loading liquids is required for liquid tracking functionality. If a well

ecormany · 2025-04-14T14:42:18Z

api/src/opentrons/protocol_api/labware.py

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


I suppose probing would also work, but the question is whether that's in scope for these docstrings.

Hmmmm. I think I'm team leave this as is. It is technically true that if you don't use any of the methods here to load liquid in your well, it won't be tracked throughout your protocol. Yes, you can probe the liquid at the beginning of the protocol or later, but feels maybe a bit can of worms to bring it up in the docstring.

emilyburghardt · 2025-04-15T15:39:10Z

Added another commit (updates based on feedback). @ecormany I did add in a versionadded and versionupdated message to tie back in Well.load_liquid. let me know what you think.

Also, still one build issue because of a meniscus ref- this one needs to be rebased on the branch and merged after the meniscus PR, or I just move the one sentence over to that PR.

ecormany · 2025-04-15T21:36:00Z

api/docs/v2/new_labware.rst

-.. versionadded:: 2.23
+.. versionadded:: 2.14
+    Use ``Well.load_liquid()`` to label liquid in individual wells. 
+.. versionchanged:: 2.22


Python pedants would say this is versionadded. If you don't need another commit for some other reason, I don't care.

ecormany · 2025-04-16T13:44:08Z

api/src/opentrons/protocol_api/labware.py

+        .. deprecated:: 2.23
+
+        In API version 2.22 and later, use :py:meth:`.Labware.load_liquid`, :py:meth:`.Labware.load_liquid_by_well`,
+            or :py:meth:`.Labware.load_empty` to load liquid into a well.
+


Sneaky but this should be 2.22.

Suggested change

.. deprecated:: 2.23

In API version 2.22 and later, use :py:meth:`.Labware.load_liquid`, :py:meth:`.Labware.load_liquid_by_well`,

or :py:meth:`.Labware.load_empty` to load liquid into a well.

.. deprecated:: 2.22

Use :py:meth:`.Labware.load_liquid`, :py:meth:`.Labware.load_liquid_by_well`,

or :py:meth:`.Labware.load_empty` instead.

docs(api): load liquids in API 2.23

197f50a

emilyburghardt requested a review from a team as a code owner April 9, 2025 23:16

emilyburghardt commented Apr 9, 2025

View reviewed changes

ecormany added docs papi-v2 Python API V2 labels Apr 10, 2025

emilyburghardt added 2 commits April 10, 2025 10:25

updating load_liquid API reference

af9d559

updating references

f51dc5a

ecormany requested changes Apr 14, 2025

View reviewed changes

updates for feedback

2e1e374

ecormany reviewed Apr 15, 2025

View reviewed changes

ecormany reviewed Apr 16, 2025

View reviewed changes

final changes

9a2aa0e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(api): load liquids in API 2.23 #18025

docs(api): load liquids in API 2.23 #18025

emilyburghardt commented Apr 9, 2025

emilyburghardt Apr 9, 2025

sfoster1 Apr 10, 2025

emilyburghardt Apr 10, 2025

ecormany left a comment

ecormany Apr 14, 2025

ecormany Apr 14, 2025

ecormany Apr 14, 2025

ecormany Apr 14, 2025

ecormany Apr 14, 2025

ecormany Apr 14, 2025

ecormany Apr 14, 2025

emilyburghardt Apr 15, 2025

emilyburghardt commented Apr 15, 2025

ecormany Apr 15, 2025

ecormany Apr 16, 2025


		:param volume: The volume of liquid to load into each well, in 10µL.
		:param volume: The volume of liquid to load into each well. Must be a multiple of 10.

	This example uses ``load_liquid`` to label the initial well location, contents, and volume (in µL) for the liquid objects created by ``define_liquid``. Notice how values of the ``liquid`` argument use the variable names ``greenWater`` and ``blueWater`` (defined above) to associate each labware with a particular liquid:
	This example uses ``load_liquid`` to label the initial well location, contents, and volume (in µL) for the liquid objects created by ``define_liquid``. Notice how values of the ``liquid`` argument use the variable names ``greenWater`` and ``blueWater`` (defined above) to associate wells in each labware with a particular liquid:

		well_plate.load_liquid_by_well({'A1': 200, 'A2': 100, 'A3': 50}, greenWater)
		well_plate.load_liquid_by_well({'B1': 200, 'B2': 100, 'B3': 50}, blueWater)

	:type wells: List of well names or list of Well objects- for instance, from :py:meth:`~Labware.wells`.
	:type wells: List of string well names or list of :py:class:`.Well` objects (e.g., from :py:meth:`~Labware.wells`).

	liquid handling operations begin. Loading liquids is required for liquid tracking functionality- if a well
	liquid handling operations begin. Loading liquids is required for liquid tracking functionality. If a well

docs(api): load liquids in API 2.23 #18025

Are you sure you want to change the base?

docs(api): load liquids in API 2.23 #18025

Conversation

emilyburghardt commented Apr 9, 2025

Overview

Test Plan and Hands on Testing

Changelog

Review requests

Risk assessment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ecormany left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emilyburghardt commented Apr 15, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment