docs(api): liquid classes in API 2.23 by emilyburghardt · Pull Request #17992 · Opentrons/opentrons

emilyburghardt · 2025-04-04T20:46:39Z

Overview

the beginning of liquid classes in API 2.23! will keep committing on this next week.

Test Plan and Hands on Testing

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

Changelog

adding a new liquid classes article (do we like where I put this? I'm not convinced yet)
changes throughout complex commands section: defining and separating basic (OG) from liquid class complex commands. not entirely restructuring this section in favor of the liquid class commands yet. As you can see throughout, there are several sections (like Complex Liquid Handling Parameters) where it still makes sense to have transfer() front and center. When we document how users can edit their liquid class in 8.5, it will make more sense to begin centering the new liquid class commands.
TODO: update article for new table code, check partial tip section to include decision on well visiting. how is blowout location determined for a liquid class? review my own changes and add questions for engineers.

Review requests

this article is not a breezy read currently. it is thick, but more technically accurate than it was in my first draft
ISO ideas on the properties list/table, and appendix with liquid class definitions

Risk assessment

low.

jwwojak

A few comments for consideration. Wow, this is a big pr.

jwwojak · 2025-04-08T18:42:07Z

+        dest=plate["A2"],
+    )
+
+This time, including the ``glycerol_50`` liquid class definition optimizes transfer behavior on the Flex for your viscous liquid. 


Consider striking "This time." Start with "including."

Suggested change

This time, including the ``glycerol_50`` liquid class definition optimizes transfer behavior on the Flex for your viscous liquid.

Including the ``glycerol_50`` liquid class definition optimizes transfer behavior on the Flex for your viscous liquid.

jwwojak · 2025-04-08T18:59:51Z

+Liquid Classes 
+***************
+
+At the core of your protocol are liquid transfers, the liquid handling steps the robot performs to move liquids in labware. 


I wonder about improving the intro sentence some. A good opener is always challenging.

Maybe just a good old "This section explains how to use liquid classes in your protocols. Identifying liquids by class can help [optimize, improve, dealer's choice] transfer performance" or some such.

jwwojak · 2025-04-08T19:02:51Z

+
+Each Opentrons-verified liquid class is defined by a set of properties: 
+
+.. list-table::


List tables, yessssss.

jwwojak · 2025-04-08T19:17:09Z

+    * - Blowout
+      - Larger volume of air the pipette dispenses to ensure all liquid leaves the tip. 
+
+A :ref:`liquid class definition <liquid-class-definitions>` specifies values for each property based on the liquid class. When you transfer with a liquid class in your protocol, transfer behavior based on each property is automatically applied. For example, when you use `.InstrumentContext.transfer_with_liquid_class` to transfer a viscous liquid, your Flex pipette automatically submerges more slowly into the liquid to prevent air bubbles from forming. 


This is a style-only comment. There's something about the "When you transfer ... property is automatically applied" sentence. Passive voice. Something has to do the applying, the class? the protocol?

"When your protocol includes a liquid class, the characteristics of that class control transfer behavior."

Something something.

jwwojak · 2025-04-08T19:22:02Z

+
+A :ref:`liquid class definition <liquid-class-definitions>` specifies values for each property based on the liquid class. When you transfer with a liquid class in your protocol, transfer behavior based on each property is automatically applied. For example, when you use `.InstrumentContext.transfer_with_liquid_class` to transfer a viscous liquid, your Flex pipette automatically submerges more slowly into the liquid to prevent air bubbles from forming. 
+
+Properties marked with an asterisk, shown above, are determined by your pipette, tip, and volume combinations. For more information, see :ref:`liquid-class-definitions`. 


Passive voice here, but I don't have a good suggestion. Probably fine to just leave it alone. Into every paragraph, a little PV may fall.

jwwojak · 2025-04-08T19:24:21Z

+Opentrons-verified Liquid Classes
+=================================
+
+Opentrons-verified liquid classes are liquid class definitions based on the properties of a specific liquid: 


Could we strike "liquid class definitions"?

Suggested change

Opentrons-verified liquid classes are liquid class definitions based on the properties of a specific liquid:

Opentrons-verified liquid classes are based on the properties of a specific liquid:

or maybe, "Opentrons-verified liquid class definitions are based on the properties of a specific liquid."

jwwojak · 2025-04-08T19:30:23Z

+      - Based on 50% glycerol
+      - ``glycerol_50``
+
+You can define and specify liquid classes in your protocols to automatically apply transfer behavior like flow rate, submerge and retract speeds, and advanced settings optimized for your liquid class.


This sentence is doing a lot of work, too much perhaps. Let's try to break it up and slow things down some.

Suggested change

You can define and specify liquid classes in your protocols to automatically apply transfer behavior like flow rate, submerge and retract speeds, and advanced settings optimized for your liquid class.

You can define and specify liquid classes in your protocols. The class characteristics automatically control transfer behavior. This includes settings like flow rate, submerge and retract speeds, and other advanced parameters specific to that class.

jwwojak · 2025-04-08T19:37:21Z

+Selecting a Liquid Class
+========================
+
+You'll use a :ref:`liquid class definition <liquid-class-definitions>` in your protocol to optimize transfer behavior based not only on liquid properties, but on your chosen Flex pipette and tips. Start by defining the tips, trash, pipette, and labware used in your transfers. Then, use :py:meth:`.ProtocolContext.define_liquid_class` to select a liquid class. 


This:

based not only on

stands out a bit.

Consider striking it. Try, "You'll use a :ref: liquid class definition <liquid-class-definitions> in your protocol to optimize transfer behavior based on liquid properties, along with your chosen Flex pipettes and tips."

jwwojak · 2025-04-08T19:49:10Z

+        liquid_3 = protocol_context.define_liquid_class("glycerol_50")
+
+
+You'll need to add a label to liquid classes in your protocol, like ``liquid_1``. Not only does this help you keep track of multiple liquids of the same class in a protocol, but ``transfer_with_liquid_class()`` requires a label previously defined in your protocol instead of a liquid class load name, like ``glycerol_50``. 


Again, watch out for that negation, "Not only". Instead, start that second sentence as "This label helps you track multiple liquids of the same class in a protocol."

And then go on to finish with, "It is also required by transfer_with_liquid_class() instead of a liquid class load name like glycerol_50.

jwwojak · 2025-04-08T19:52:42Z

+Liquid Class Transfers
+======================
+
+Use ``transfer_with_liquid_class`` to transfer an aqueous, volatile, or viscous liquid defined in your protocol. Here, you'll specify your liquid, volume, source, and destination wells, tip handling preferences, and the trash location. 


This is a method? Maybe should be, "Use the transfer_with_liquid_class() method to...

And then, "This method accepts arguments that let you specify your liquid, volume, source, and destination wells, tip handling preferences, and ~~the~~ trash location.

# Overview Adding methods like `transfer_with_liquid_class()` to the API reference. Addresses RTC-610. Any follow-up edits to these docstrings can be handled in #17992. ## Test Plan and Hands on Testing [Sandbox](http://sandbox.docs.opentrons.com/api-ref-liquid-classes/v2/new_protocol_api.html) ## Changelog - Param descriptions for the three main liquid class methods. - Unhide the methods - Add `LiquidClass` to the ref. - Nitpicks to allow docs to build. ## Review requests Are these "good enough"? Want to get these merged to keep other liquid class docs work moving. ## Risk assessment low, docs

codecov · 2025-04-10T17:50:27Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 28.90%. Comparing base (b40363d) to head (a4fa27b).
Report is 1 commits behind head on chore_release-8.4.0.

Additional details and impacted files

@@                 Coverage Diff                  @@
##           chore_release-8.4.0   #17992   +/-   ##
====================================================
  Coverage                28.90%   28.90%           
====================================================
  Files                     3101     3101           
  Lines                   235493   235493           
  Branches                 19129    19130    +1     
====================================================
  Hits                     68081    68081           
  Misses                  167388   167388           
  Partials                    24       24

Flag	Coverage Δ
protocol-designer	`18.80% <ø> (-0.01%)`	⬇️
step-generation	`4.34% <ø> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jwwojak · 2025-04-11T13:35:48Z

+    1. Pick up tip
+    2. Submerge into the source to the aspirate position
+    3. Delay for an amount of time
+    4. Mix at the aspirate position
+    5. Pre-wet the attached tip at the aspirate position
+    6. Aspirate from source
+    7. Delay for an amount of time
+    8. Retract from the source to the specified position
+    9. Touch tip at source
+    10. Add an air gap
+    11. Move to and submerge into the destination to the dispense position
+    12. Delay for an amount of time
+    13. Dispense into destination 
+    14. Push out into destination
+    15. Delay for an amount of time
+    16. Mix at the dispense position
+    17. Retract from the dispense to the specified position
+    18. Delay for an amount of time
+    19. Blow out at the specified location
+    20. Touch tip at the blow out location
+    21. Drop tip


This asks a reader to look at a 21-step list. Is this really necessary? Instead, I'd suggest breaking this up into related, but sequential groups, and then summarized in sentences (maybe with a few bullets or list items). Even if you have to make up artificial categories to do this, it might be worth it. Example:

Initial process
Summarize 1–8: Pick up tip, get some liquid, retract to do the next thing.

Air gap process
Summarize 9–10: air gap and move to destination

Dispense process
Summarize 11–14: dispensing into a destination

Dispense process II
Summarize 15–18: Delay, mix, retract, delay

Final process
Summarize 19–21: Everything else that finishes up.

These are all arbitrary so use your best judgement, but the point is, the list could be summed up in a few readable sentences. You'd also have room to add some description/explanation if needed.

Could even try a table:

Process category Description

Initial aspiration Some explanation here

Another process category Some explanation here

Another process category Even more explanation

emilyburghardt · 2025-04-11T21:58:50Z


 The eight pipette channels will only dispense into every other well in the column: B1, D1, F1, H1, J1, L1, N1, and P1.

+Complex Commands


Tiiiiny start of a section I made to begin on the differences in multi-channel movement between the building block command examples we use and updated liquid class commands.

I understand this the least- might need some engineer time next week.

ecormany · 2025-06-16T20:05:03Z

Closing in favor of #18619.

# Overview Liquid classes in API 2.24. Includes new articles covering liquid classes and liquid class definitions, plus changes throughout our Complex Commands section.  ## Test Plan and Hands on Testing  ## Changelog -brought over liquid classes text from [PR #17992](https://github.com/Opentrons/opentrons/pull/17992/files#diff-0f90fc8fd15163b9fb8b128ac3c358036fbb7bef07c549fbdbec8b45cb26af51) - reorganized the liquid classes article to ease into property descriptions - build issues with images in the properties table; currently in the docs as a list to avoid this. - adding custom liquid class creator section (and differentiate between customizing and *creating* from scratch) - built out liquid class definition tables section - updated API reference for tip handling options, `get_liquid_class` and `define_liquid_class` entries - linked users to github schema for creating their own liquid class  ## Review requests  ## Risk assessment  --------- Co-authored-by: Edward Cormany <edward.cormany@opentrons.com>

emilyburghardt requested review from ecormany and jwwojak April 4, 2025 20:46

emilyburghardt requested a review from a team as a code owner April 4, 2025 20:46

emilyburghardt mentioned this pull request Apr 4, 2025

Liquid Classes drafting for PAPI docs 2.23 #17111

Closed

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

ecormany mentioned this pull request Apr 8, 2025

docs(api): API reference entries for liquid class methods #17887

Merged

jwwojak reviewed Apr 8, 2025

View reviewed changes

emilyburghardt force-pushed the docs-liquid-class branch from 5ba936b to a4fa27b Compare April 10, 2025 17:44

emilyburghardt added 4 commits April 10, 2025 11:45

docs(api): liquid classes in API 2.23

c7d9e0c

starting complex commands section

93bebc9

complex commands section pt 2

4e57054

fixing build errors

a4fa27b

reference error updated + table update

1200767

jwwojak reviewed Apr 11, 2025

View reviewed changes

tiny change to start multi-channel behavior for liquid class commands

8053680

emilyburghardt commented Apr 11, 2025

View reviewed changes

emilyburghardt added 2 commits April 18, 2025 12:33

adding TODOs, splitting article, and adding transfer protocol example

92e0c20

tiny update before leaving this section for 8.5

24ac9f0

ecormany closed this Jun 16, 2025

	This time, including the ``glycerol_50`` liquid class definition optimizes transfer behavior on the Flex for your viscous liquid.
	Including the ``glycerol_50`` liquid class definition optimizes transfer behavior on the Flex for your viscous liquid.


		Each Opentrons-verified liquid class is defined by a set of properties:

		.. list-table::


		A :ref:`liquid class definition <liquid-class-definitions>` specifies values for each property based on the liquid class. When you transfer with a liquid class in your protocol, transfer behavior based on each property is automatically applied. For example, when you use `.InstrumentContext.transfer_with_liquid_class` to transfer a viscous liquid, your Flex pipette automatically submerges more slowly into the liquid to prevent air bubbles from forming.

		Properties marked with an asterisk, shown above, are determined by your pipette, tip, and volume combinations. For more information, see :ref:`liquid-class-definitions`.

	Opentrons-verified liquid classes are liquid class definitions based on the properties of a specific liquid:
	Opentrons-verified liquid classes are based on the properties of a specific liquid:

	You can define and specify liquid classes in your protocols to automatically apply transfer behavior like flow rate, submerge and retract speeds, and advanced settings optimized for your liquid class.
	You can define and specify liquid classes in your protocols. The class characteristics automatically control transfer behavior. This includes settings like flow rate, submerge and retract speeds, and other advanced parameters specific to that class.

		liquid_3 = protocol_context.define_liquid_class("glycerol_50")


		You'll need to add a label to liquid classes in your protocol, like ``liquid_1``. Not only does this help you keep track of multiple liquids of the same class in a protocol, but ``transfer_with_liquid_class()`` requires a label previously defined in your protocol instead of a liquid class load name, like ``glycerol_50``.

Process category	Description
Initial aspiration	Some explanation here
Another process category	Some explanation here
Another process category	Even more explanation


		The eight pipette channels will only dispense into every other well in the column: B1, D1, F1, H1, J1, L1, N1, and P1.

		Complex Commands

Conversation

emilyburghardt commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Test Plan and Hands on Testing

Changelog

Review requests

Risk assessment

Uh oh!

jwwojak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Apr 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ecormany commented Jun 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

emilyburghardt commented Apr 4, 2025 •

edited

Loading

codecov Bot commented Apr 10, 2025 •

edited

Loading