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.

Sign up for GitHub

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

Jump to bottom

docs(api): liquid classes in API 2.23 #17992

Open

emilyburghardt wants to merge 6 commits into chore_release-8.4.0 from docs-liquid-class

Collaborator

emilyburghardt commented Apr 4, 2025 •

edited

Loading

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.

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

Liquid Classes drafting for PAPI docs 2.23 #17111

Closed

ecormany added docs papi-v2 labels

ecormany mentioned this pull request

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

Merged

jwwojak reviewed

View reviewed changes

Contributor

jwwojak left a comment

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

api/docs/v2/complex_commands/sources_destinations.rst Outdated

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

Contributor

jwwojak Apr 8, 2025

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.

api/docs/v2/liquid_classes.rst

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

Contributor

jwwojak Apr 8, 2025

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.

api/docs/v2/liquid_classes.rst


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

		.. list-table::

Contributor

jwwojak Apr 8, 2025

List tables, yessssss.

api/docs/v2/liquid_classes.rst

+                  * - 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.

Contributor

jwwojak Apr 8, 2025

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.

api/docs/v2/liquid_classes.rst


		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`.

Contributor

jwwojak Apr 8, 2025

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.

api/docs/v2/liquid_classes.rst

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

Contributor

jwwojak Apr 8, 2025

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."

api/docs/v2/liquid_classes.rst

+                    - 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.

Contributor

jwwojak Apr 8, 2025

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.

api/docs/v2/liquid_classes.rst

+              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.

Contributor

jwwojak Apr 8, 2025

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."

api/docs/v2/liquid_classes.rst

		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``.

Contributor

jwwojak Apr 8, 2025

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.

api/docs/v2/liquid_classes.rst

+              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.

Contributor

jwwojak Apr 8, 2025

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.

ecormany added a commit that referenced this pull request


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

8d63591

# 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

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

codecov bot commented Apr 10, 2025 •

edited

Loading

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.


          reference error updated + table update

jwwojak reviewed

View reviewed changes

api/docs/v2/complex_commands/order_operations.rst

Comment on lines +40 to +60

+. Pick up tip
+. Submerge into the source to the aspirate position
+. Delay for an amount of time
+. Mix at the aspirate position
+. Pre-wet the attached tip at the aspirate position
+. Aspirate from source
+. Delay for an amount of time
+. Retract from the source to the specified position
+. Touch tip at source
+. Add an air gap
+. Move to and submerge into the destination to the dispense position
+. Delay for an amount of time
+. Dispense into destination
+. Push out into destination
+. Delay for an amount of time
+. Mix at the dispense position
+. Retract from the dispense to the specified position
+. Delay for an amount of time
+. Blow out at the specified location
+. Touch tip at the blow out location
+. Drop tip

Contributor

jwwojak Apr 11, 2025

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


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

emilyburghardt commented

View reviewed changes

api/docs/v2/pipettes/characteristics.rst

		@@ -129,6 +129,11 @@ Finally, let's tell the robot to dispense 100 µL into the well plate at locatio

		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

Collaborator Author

emilyburghardt Apr 11, 2025

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels