chore(api): update resin tip docstrings #17815

sfoster1 · 2025-03-19T14:42:04Z

Update the docstrings for the resin tip functions.

emilyburghardt

Added a few suggestions to tighten up the text. If we want, some of that pressure sensor information can be covered in a resin tips article in the docs, instead of here. Since we will include docstrings in 8.4 release (API docs 2.23), but not an article, we can wait on that.

I can make the suggestions I added here as we get closer to code freeze, and other changes as needed. Mostly just adding my thought process in here!

emilyburghardt · 2025-03-19T15:13:30Z

api/src/opentrons/protocol_api/instrument_context.py

-        tip will perform a `pick up` action but there will be no tip tracking
-        associated with the pipette.
+        The location provided should contain resin tips. The pipette will attach itself
+        to the resin tips, acting as if they are present, but does not check any tip presence


"Acting as if they are present" is throwing me off a bit. I think I know what you mean (that the pipette is going to attach without checking for tip presence), but maybe could be something like:

"The pipette will attach itself to any resin tips present, but does not check for tip presence."

emilyburghardt · 2025-03-19T15:39:33Z

api/src/opentrons/protocol_api/instrument_context.py

+        Resin tips use pressure-based dispensing rather than isobaric volume-displacement
+        pipetting. The volume and rate parameters to this function control the motion of
+        the plunger to create a desired pressure profile inside the pipette chamber. The
+        volume and rate parameters to this function do not directly relate to the volume


"The volume and rate parameters for this function control the motion of the plunger to create a desired pressure profile inside the pipette chamber. Unlike a regular dispense action, the volume and rate do not correspond to liquid volume or flow rate dispensed from the resin tips. Select your values for volume and flow rate based on experimentation with the resin tips to create a pressure profile."

emilyburghardt · 2025-03-19T15:42:15Z

api/src/opentrons/protocol_api/instrument_context.py

+        5. Unseal resin tips from the pipette using :py:meth:`resin_tip_unseal`.
+
+        On the Opentrons Flex, the pipette pressure sensors will raise an overpressure
+        error if they sense a differential pressure inside the pipette chamber above the


"Flex pipette pressure sensors will raise an overpressure when a differential pressure inside the pipette chamber above sensor limits is detected. You may need to disable the pressure sensor to create the required pressure profile, which can cause damage or failure to your pipette's pressure sensors. For more, see [link to future resin tips article]."

See what, though?

I tried to add some syntax Github must not have liked. Updated to include that we could eventually link to the resin tips article in the API docs (once it's written and published with commercial release) where we could explain the pressure issue more. We won't be able to do that for the docstrings immediately, though.

ecormany

Thanks Seth, this goes a long way towards explaining these features! So much so that I think we can eventually split out some of the content into other docs pages. For now, Emily can take these comments and clean up the prose with a follow-up commit.

In addition to my inline comments below, two things for resin_tip_unseal():

What is "a valid location to drop resin tips" / "A location ~~containing~~ that can accept tips."? Also fix the typo marked in strikethrough here.
home_after param isn't in the function signature, is this a copy-paste error?

api/src/opentrons/protocol_api/instrument_context.py

ecormany · 2025-03-19T20:05:02Z

api/src/opentrons/protocol_api/instrument_context.py

-        """Dispense a volume from resin tips into a labware.
+        """Push liquid out of resin tips that are currently sealed to a pipette.
+
+        The ``location`` provided is where the liquid will be dispensed into.


Can omit this line and rely on the param description below.

ecormany · 2025-03-19T20:06:15Z

api/src/opentrons/protocol_api/instrument_context.py


-        :param location: A location containing resin tips.
+        #. Use :py:meth:`InstrumentContext.resin_tip_dispense` to displace an experimentally


The repetition of "experimentally derived" here is almost humorous. Happy to leave it for now, it definitely gets the point across. We don't have magic numbers for you!

That's the intent hehe

ecormany · 2025-03-19T20:12:57Z

api/src/opentrons/protocol_api/instrument_context.py

+        Flex pipette pressure sensors will raise an overpressure when a differential pressure
+        inside the pipette chamber above sensor limits is detected. You may need to disable the
+        pressure sensor to create the required pressure profile, which can cause damage or
+        failure to your pipette's pressure sensors.


I think it's important to split out what is likely to happen from less likely instrument damage — which rises to the level of a warning.

Suggested change

Flex pipette pressure sensors will raise an overpressure when a differential pressure

inside the pipette chamber above sensor limits is detected. You may need to disable the

pressure sensor to create the required pressure profile, which can cause damage or

failure to your pipette's pressure sensors.

The pressure sensors in Flex pipettes will raise an overpressure error when the pressure

inside the pipette chamber exceeds their limits. You may need to disable the

pressure sensor to create the required pressure profile.

.. warning::

Building excessive pressure inside the pipette chamber (significantly above the sensor

limit) with the pressure sensors disabled can damage the pipette.

Ideally we would have some concrete guidance here — hopefully "significantly above" is accurate.

ecormany · 2025-03-19T20:16:46Z

api/src/opentrons/protocol_api/instrument_context.py

+        pressure sensor to create the required pressure profile, which can cause damage or
+        failure to your pipette's pressure sensors.
+
+        :param location: The location into which to dispense.


Yep, does what it says on the tin. We could mirror the less tautological language used for dispense(): "Tells the robot where to dispense liquid held in the pipette."

Suggested change

:param location: The location into which to dispense.

:param location: Tells the robot where to dispense to create the pressure profile.

"where to dispense to create the pressure profile" feels a little rough, maybe "where to locate the pipette while creating the pressure profile"?

ecormany · 2025-03-19T20:18:02Z

api/src/opentrons/protocol_api/instrument_context.py

+        :param volume: The volume that the plunger should displace. Does not directly relate
+                       to the volume of liquid that will be dispensed.


It's still µL of air to move, and presumably the max is governed by the nominal capacity of the tip in µL.

Suggested change

:param volume: The volume that the plunger should displace. Does not directly relate

to the volume of liquid that will be dispensed.

:param volume: The volume that the plunger should displace, in µL. Does not directly relate

to the volume of liquid that will be dispensed.

the max is governed by the physical displacement of the plunger, actually - the number in the pipette name.

ecormany · 2025-03-19T20:24:32Z

api/src/opentrons/protocol_api/instrument_context.py

        :type volume: float

        :param rate: Will default to 10.0, recommended to use the default. How quickly
-                     a pipette dispenses liquid. The speed in µL/s is calculated as
-                     ``rate`` multiplied by :py:attr:`flow_rate.dispense<flow_rate>`.
+                     the plunger moves to displace the commanded volume. The plunger speed


Would flip this around. Can't suggest because one line is unmodified, thx GitHub.

:param rate: How quickly the plunger moves to displace the commanded volume. The plunger speed Multiplied this value by :py:attr:`flow_rate.dispense<flow_rate>` to get the plunger speed in µL/s. This rate does not directly relate to the flow rate of liquid the flow rate of liquid out of the resin tip. The default value of ``10.0`` is recommended.

ecormany

Do not smash that merge button as one more commit is needed to fix a couple typos, but then this is gtg by me.

api/src/opentrons/protocol_api/instrument_context.py

Co-authored-by: Ed Cormany <edward.cormany@opentrons.com>

ecormany · 2025-04-15T01:52:57Z

This never got merged so if we need to do any renaming, we should make those edits here and then retarget onto chore_release-8.4.0.

chore(api): update resin tip docstrings

9019ef0

sfoster1 requested a review from a team as a code owner March 19, 2025 14:42

sfoster1 requested review from emilyburghardt and ecormany and removed request for a team March 19, 2025 14:42

emilyburghardt reviewed Mar 19, 2025

View reviewed changes

content suggestions and rst fixup

5ef5023

ecormany requested changes Mar 19, 2025

View reviewed changes

editing

e3660d8

ecormany approved these changes Mar 21, 2025

View reviewed changes

api/src/opentrons/protocol_api/instrument_context.py Outdated Show resolved Hide resolved

api/src/opentrons/protocol_api/instrument_context.py Outdated Show resolved Hide resolved

Apply suggestions from code review

66af119

Co-authored-by: Ed Cormany <edward.cormany@opentrons.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(api): update resin tip docstrings #17815

chore(api): update resin tip docstrings #17815

sfoster1 commented Mar 19, 2025

emilyburghardt left a comment

emilyburghardt Mar 19, 2025

emilyburghardt Mar 19, 2025

emilyburghardt Mar 19, 2025 •

edited

Loading

sfoster1 Mar 19, 2025

emilyburghardt Mar 19, 2025 •

edited

Loading

ecormany left a comment

ecormany Mar 19, 2025

ecormany Mar 19, 2025

sfoster1 Mar 20, 2025

ecormany Mar 19, 2025

ecormany Mar 19, 2025

sfoster1 Mar 20, 2025

ecormany Mar 19, 2025

sfoster1 Mar 20, 2025

ecormany Mar 19, 2025

ecormany left a comment

ecormany commented Apr 15, 2025


		:param location: A location containing resin tips.
		#. Use :py:meth:`InstrumentContext.resin_tip_dispense` to displace an experimentally

-        Flex pipette pressure sensors will raise an overpressure when a differential pressure
-        inside the pipette chamber above sensor limits is detected. You may need to disable the
-        pressure sensor to create the required pressure profile, which can cause damage or
-        failure to your pipette's pressure sensors.
+        The pressure sensors in Flex pipettes will raise an overpressure error when the pressure
+        inside the pipette chamber exceeds their limits. You may need to disable the
+        pressure sensor to create the required pressure profile.
+        .. warning::
+            Building excessive pressure inside the pipette chamber (significantly above the sensor
+            limit) with the pressure sensors disabled can damage the pipette.

	:param location: The location into which to dispense.
	:param location: Tells the robot where to dispense to create the pressure profile.

		:param volume: The volume that the plunger should displace. Does not directly relate
		to the volume of liquid that will be dispensed.

chore(api): update resin tip docstrings #17815

Are you sure you want to change the base?

chore(api): update resin tip docstrings #17815

Conversation

sfoster1 commented Mar 19, 2025

emilyburghardt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emilyburghardt Mar 19, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emilyburghardt Mar 19, 2025 • edited Loading

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

Choose a reason for hiding this comment

ecormany left a comment

Choose a reason for hiding this comment

ecormany commented Apr 15, 2025

emilyburghardt Mar 19, 2025 •

edited

Loading

emilyburghardt Mar 19, 2025 •

edited

Loading