Liquid Classes drafting for PAPI docs 2.23 #17111
Conversation
api/docs/v2/liquids.rst
Outdated
| .. _liquids: | ||
|
|
||
| ######## | ||
| Liquids |
There was a problem hiding this comment.
new liquids article, and new overall description of liquids. previously, any information about liquids (define and specifying which well they were in) was under "Labware."
api/docs/v2/liquids.rst
Outdated
| .. _labeling-liquids: | ||
|
|
||
| ************************* | ||
| Labeling Liquids in Wells |
There was a problem hiding this comment.
this section was previously in "Labware" and was written by Ed.
api/docs/v2/liquids.rst
Outdated
|
|
||
| Define a liquid class to automatically populate advanced settings in your protocol optimized for use with any of three liquid classes. | ||
|
|
||
| - **Aqueous liquids**, based on deionized water, and the system default. |
There was a problem hiding this comment.
potentially expand into a table below to describe major differences between liquid class definitions: speed, flow rate, etc.
Users will want to know what changes and advanced settings they are adding to their protocol. Review JSON definitions for this.
api/docs/v2/liquids.rst
Outdated
|
|
||
| def define_liquid_class(Viscous) | ||
|
|
||
| **TODO**: fill in code-block example when ``define_liquid_class`` is used. what do users see? |
There was a problem hiding this comment.
what kinds of arguments do users see returned for define_liquid_class? In the API proposal Sanniti suggested that liquid handling properties would be returned. Editing them isn't supported yet, but do users see them?
api/docs/v2/liquids.rst
Outdated
| **TODO**: fill in code-block example when ``define_liquid_class`` is used. what do users see? | ||
|
|
||
| To transfer liquids of a defined class, use ``transfer_liquid``, just as you would for any liquid transfer. Here, you'll only specify source and destination wells and transfer volume. The liquid class definition contains all the other required information. | ||
| **TODO**: fill in code-block example for transferring a viscous liquid; defined with that class |
There was a problem hiding this comment.
I think source, destination, volume, new_tip, and trash location are returned for transfer_liquid. Want to confirm.
emilyburghardt
changed the title
|
|
||
| Each liquid class definition accounts for steps the robot will perform to optimize your liquid transfers. Advanced settings like mix, pre-wet tip, touch tip, and blowout are disabled for liquid class transfers. | ||
|
|
||
| You can make changes or enable these settings for each liquid you use in your protocol. Here, use your liquid name, piette, and tip rack combination to access and edit properties for `liquid_1`. |
There was a problem hiding this comment.
I chose a few examples of properties that users can edit in-line to change their liquid class definition. Are there any other examples that I should include for users?
|
|
||
| ## enable blowout for dispense with liquid_1 | ||
| liquid_1_p50_props.dispense.retract.blowout.location = "source" | ||
| liquid_1_p50_props.dispense.retract.blowout.flow_rate = pipette_50.flow_rate.blow_out |
There was a problem hiding this comment.
Is the dispense flow rate in the liquid class definition (for this volume) then applied for the blowout?
| liquid_1_p50_props.dispense.retract.blowout.enabled = True | ||
|
|
||
|
|
||
| Each liquid class definition includes flow rate for the volume range of the pipette. If you use the `flex_1channel_50` pipette and `opentrons_flex_96_tiprack_50ul` tips to transfer a viscous liquid, the aspirate flow rate changes for each volume: |
There was a problem hiding this comment.
This is maybe a concept already covered elsewhere in API docs and not needed in the liquid classes section. We have a pipette flow rate by volume table, for example.
|
|
||
| If you were to perform the same transfer with changes made to `liquid_1` transfer behavior, your protocol would look the same. | ||
|
|
||
| .. code-block:: python |
There was a problem hiding this comment.
second code block possibly not needed
|
|
||
| Here, transfer behavior is defined by both the viscous `glycerol_50` liquid class definition and any changes you made for `liquid_1`. Actions the Flex performs for each aspirate and single dispense include: | ||
|
|
||
| For each aspirate, the `flex_1channel_50` pipette: |
There was a problem hiding this comment.
This is a LOT of text. I probably won't include all of this, but it would be helpful for someone to look over it and let me know that this correct. Then I can workshop a table or even just simplify the text.
| * Submerges into the destination well at 4 mm/sec and does not delay afterwards | ||
| * Dispenses 30 µL of `liquid_1` into the destination well at 25 µL/sec with a correction by volume | ||
| * Pushes out 30 µL from the tip and does not mix `liquid_1` | ||
| * Blows out at the [source?] |
There was a problem hiding this comment.
order of operations clarification: when the blowout location is source, does the pipette return to the source well to blow out as the last step? or is this the correct order?
|
|
||
| When you aspirate a liquid between these three volumes, a linear interpolation determines the flow rate. If you were to use a `flex_1channel_1000` pipette and `opentrons_flex_96_tiprack_1000ul` tips for the same transfer, the aspirate flow rate changes to 10, 100, or 200 µL per second. | ||
|
|
||
| Aspirating a Liquid |
There was a problem hiding this comment.
I made a table to summarize major changes in each liquid class definition. I took some feedback from Joe and reorganized them as they appear below. What am I missing in these summaries? What else do users need to know? I'm still ISO general opinions too!
Overview
First draft of a new API docs article for three defined liquid classes. NOT to be merged; will continue editing/committing ahead of API 2.23.
Test Plan and Hands on Testing
Sandbox (not built yet). Will continue committing and editing as I write.
Changelog
-new liquids article in PAPI docs
-liquid classes description is added for three defined classes, and can expand in this article as we develop editable liquid classes
Review requests
first checks for:
-correct code in code blocks?
-correct summary of changes implemented for a liquid class definition?
-anything missing/incorrect/confusing?
I left some comments throughout to clarify my thoughts/changes that I might make/etc.
Risk assessment
low