Liquid Classes drafting for PAPI docs 2.22

api/docs/v2/index.rst

@@ -10,6 +10,7 @@ Welcome
     tutorial
     versioning
     new_labware
+    liquids
     moving_labware
     new_modules
     deck_slots

api/docs/v2/liquids.rst

@@ -0,0 +1,137 @@
+:og:description: How to define, load, and specify liquids in an Opentrons protocol, including labeling liquids in wells and defining liquid class. 
+
+.. _liquids:
+
+########
+Liquids
+########
+
+At the core of your protocol are liquid transfers: steps the robot will perform to move liquids within labware.
+
+Liquid definitions aren't required in Python protocols. However, defining and specifying liquids you use can help keep track of each throughout your protocol. It also lets you take advantage of advanced pipetting settings optimized for certain liquid classes. This section covers defining and labeling liquids used in your protocol. 
+
+.. _labeling-liquids:
+
+*************************
+Labeling Liquids in Wells
+*************************
+
+Optionally, you can specify the liquids that should be in various wells at the beginning of your protocol. Doing so helps you identify well contents by name and volume, and adds corresponding labels to a single well, or group of wells, in well plates and reservoirs. You can view the initial liquid setup:
+
+- For Flex protocols, on the touchscreen.
+- For Flex or OT-2 protocols, in the Opentrons App (v6.3.0 or higher).
+
+To use these optional methods, first create a liquid object with :py:meth:`.ProtocolContext.define_liquid` and then label individual wells by calling :py:meth:`.Well.load_liquid`.
+
+Let's examine how these two methods work. The following examples demonstrate how to define colored water samples for a well plate and reservoir.
+
+.. _defining-liquids:
+
+Defining Liquids
+================
+
+This example uses ``define_liquid`` to create two liquid objects and instantiates them with the variables ``greenWater`` and ``blueWater``, respectively. The arguments for ``define_liquid`` are all required, and let you name the liquid, describe it, and assign it a color:
+
+.. code-block:: python
+
+        greenWater = protocol.define_liquid(
+            name="Green water",
+            description="Green colored water for demo",
+            display_color="#00FF00",
+        )
+        blueWater = protocol.define_liquid(
+            name="Blue water",
+            description="Blue colored water for demo",
+            display_color="#0000FF",
+        )
+
+.. versionadded:: 2.14
+
+The ``display_color`` parameter accepts a hex color code, which adds a color to that liquid's label when you import your protocol into the Opentrons App. The ``define_liquid`` method accepts standard 3-, 4-, 6-, and 8-character hex color codes.
+
+.. _loading-liquids:
+
+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: 
+
+.. code-block:: python
+
+        well_plate["A1"].load_liquid(liquid=greenWater, volume=50)
+        well_plate["A2"].load_liquid(liquid=greenWater, volume=50)
+        well_plate["B1"].load_liquid(liquid=blueWater, volume=50)
+        well_plate["B2"].load_liquid(liquid=blueWater, volume=50)
+        reservoir["A1"].load_liquid(liquid=greenWater, volume=200)
+        reservoir["A2"].load_liquid(liquid=blueWater, volume=200)
+
+.. versionadded:: 2.14
+
+This information is available after you import your protocol to the app or send it to Flex. A summary of liquids appears on the protocol detail page, and well-by-well detail is available on the run setup page (under Initial Liquid Setup in the app, or under Liquids on Flex).
+
+.. note::
+    ``load_liquid`` does not validate volume for your labware nor does it prevent you from adding multiple liquids to each well. For example, you could label a 40 µL well with ``greenWater``, ``volume=50``, and then also add blue water to the well. The API won't stop you. It's your responsibility to ensure the labels you use accurately reflect the amounts and types of liquid you plan to place into wells and reservoirs.
+
+Labeling vs Handling Liquids
+============================
+
+The ``load_liquid`` arguments include a volume amount (``volume=n`` in µL). This amount is just a label. It isn't a command or function that manipulates liquids. It only tells you how much liquid should be in a well at the start of the protocol. You need to use a method like :py:meth:`.transfer` to physically move liquids from a source to a destination.
+
+
+.. _v2-location-within-wells:
+.. _new-labware-well-properties:
+
+**************
+Liquid Classes
+**************
+
+When handing liquids, accounting for specific properties of a liquid can improve robot accuracy in pipetting. 
+
+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. 
+- **Volatile liquids**, based on 80% ethanol. 
+- **Viscous liquid**, based on 50% glycerol. 
+
+The above liquid classes can be used with any pipette and compatible tips only on the Flex. Some settings like flow rate and air gap volume vary between pipette and tip combinations, regardless of liquid class. 
+
+
+Use :py:meth:`.ProtocolContext.define_liquid_class` to define a liquid in your protocol as one of the three classes.
+
+.. code-block:: python
+
+   def define_liquid_class(
+        liquid_class: "Viscous",
+        pipette_load_name: "insert pipette", 
+        tiprack_uri: "insert tiprack", 
+   )
+
+When you define a liquid as `aqueous`, `volatile`, or `viscous`, you'll need to enter the pipette and tip rack combination to use with this liquid. Advanced settings for that liquid class, shown below, are then automatically used in your liquid transfers. 
+
+##TODO: insert table of changes between liquid classes, like submerge/retract speed, flow rate, and correction by volume for flow rate. anything else?
+
+Next, load and transfer liquids of a defined class. Use ``load_liquid_class`` and ``transfer_liquid``. Here, you'll only specify source and destination wells and transfer volume. The liquid class definition contains all other required information. 
+
+.. code-block:: python
+
+    ## Load a viscous liquid in a well plate on the deck with class-specific commands.## 
+    def load_liquid_class(
+        liquid_class: "Viscous",
+        pipette_load_name: "insert pipette",
+        tiprack_uri: "insert tiprack"
+    )
+
+    well_plate["A1"].load_liquid_class(liquid_class=Viscous, volume=50)
+
+    def transfer_liquid(
+        liquid_class_id: "Viscous", 
+        volume: "insert volume", 
+        source: "[wells]", 
+        dest: "[Wells]", 
+        new_tip: "once", 
+        trash_location: "[TrashBin]"
+    )
+
+##TODO: insert description of the transfer step the robot will perform, with advanced settings and changes included in liquid class description. 
+
+.. versionadded:: 2.22

api/docs/v2/new_labware.rst

@@ -254,77 +254,6 @@ Equivalently, using ``rows_by_name``::
 .. versionadded:: 2.0
 
 
-.. _labeling-liquids:
-
-*************************
-Labeling Liquids in Wells
-*************************
-
-Optionally, you can specify the liquids that should be in various wells at the beginning of your protocol. Doing so helps you identify well contents by name and volume, and adds corresponding labels to a single well, or group of wells, in well plates and reservoirs. You can view the initial liquid setup:
-
-- For Flex protocols, on the touchscreen.
-- For Flex or OT-2 protocols, in the Opentrons App (v6.3.0 or higher).
-
-To use these optional methods, first create a liquid object with :py:meth:`.ProtocolContext.define_liquid` and then label individual wells by calling :py:meth:`.Well.load_liquid`.
-
-Let's examine how these two methods work. The following examples demonstrate how to define colored water samples for a well plate and reservoir.
-
-.. _defining-liquids:
-
-Defining Liquids
-================
-
-This example uses ``define_liquid`` to create two liquid objects and instantiates them with the variables ``greenWater`` and ``blueWater``, respectively. The arguments for ``define_liquid`` are all required, and let you name the liquid, describe it, and assign it a color:
-
-.. code-block:: python
-
-        greenWater = protocol.define_liquid(
-            name="Green water",
-            description="Green colored water for demo",
-            display_color="#00FF00",
-        )
-        blueWater = protocol.define_liquid(
-            name="Blue water",
-            description="Blue colored water for demo",
-            display_color="#0000FF",
-        )
-
-.. versionadded:: 2.14
-
-The ``display_color`` parameter accepts a hex color code, which adds a color to that liquid's label when you import your protocol into the Opentrons App. The ``define_liquid`` method accepts standard 3-, 4-, 6-, and 8-character hex color codes.
-
-.. _loading-liquids:
-
-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: 
-
-.. code-block:: python
-
-        well_plate["A1"].load_liquid(liquid=greenWater, volume=50)
-        well_plate["A2"].load_liquid(liquid=greenWater, volume=50)
-        well_plate["B1"].load_liquid(liquid=blueWater, volume=50)
-        well_plate["B2"].load_liquid(liquid=blueWater, volume=50)
-        reservoir["A1"].load_liquid(liquid=greenWater, volume=200)
-        reservoir["A2"].load_liquid(liquid=blueWater, volume=200)
-
-.. versionadded:: 2.14
-
-This information is available after you import your protocol to the app or send it to Flex. A summary of liquids appears on the protocol detail page, and well-by-well detail is available on the run setup page (under Initial Liquid Setup in the app, or under Liquids on Flex).
-
-.. note::
-    ``load_liquid`` does not validate volume for your labware nor does it prevent you from adding multiple liquids to each well. For example, you could label a 40 µL well with ``greenWater``, ``volume=50``, and then also add blue water to the well. The API won't stop you. It's your responsibility to ensure the labels you use accurately reflect the amounts and types of liquid you plan to place into wells and reservoirs.
-
-Labeling vs Handling Liquids
-============================
-
-The ``load_liquid`` arguments include a volume amount (``volume=n`` in µL). This amount is just a label. It isn't a command or function that manipulates liquids. It only tells you how much liquid should be in a well at the start of the protocol. You need to use a method like :py:meth:`.transfer` to physically move liquids from a source to a destination.
-
-
-.. _v2-location-within-wells:
-.. _new-labware-well-properties:
-
 ***************
 Well Dimensions
 ***************