From ea7d51e5e5153a3e16eff43ae0790afed778c6ef Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 10 Oct 2023 16:27:38 -0400 Subject: [PATCH 01/40] Spelling check Line 116, "millimiters" should be "millimeters". --- api/src/opentrons/protocol_api/instrument_context.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index cc215d23386..fb392213789 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -608,7 +608,7 @@ def air_gap( (Default will use all remaining volume in tip) :type volume: float - :param height: The number of millimiters to move above the current Well + :param height: The number of millimeters to move above the current Well to air-gap aspirate. (Default: 5mm above current Well) :type height: float From a9f79286039e89a795f131ba4c4863b468c33ed2 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 10 Oct 2023 16:58:24 -0400 Subject: [PATCH 02/40] fix microliters abbreviation-use mu not u MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use "µL" instead of "uL". --- api/src/opentrons/protocol_api/instrument_context.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index fb392213789..55453d6d0b6 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -256,7 +256,7 @@ def dispense( push_out: Optional[float] = None, ) -> InstrumentContext: """ - Dispense a volume of liquid (in microliters/uL) using this pipette + Dispense a volume of liquid (in microliters/µL) using this pipette into the specified location. If only a volume is passed, the pipette will dispense from its current @@ -377,7 +377,7 @@ def mix( rate: float = 1.0, ) -> InstrumentContext: """ - Mix a volume of liquid (uL) using this pipette, by repeatedly + Mix a volume of liquid (µL) using this pipette, by repeatedly aspirating and dispensing in the same place. :param repetitions: how many times the pipette should mix (default: 1) @@ -604,7 +604,7 @@ def air_gap( """ Pull air into the pipette current tip at the current location - :param volume: The amount in uL to aspirate air into the tube. + :param volume: The amount in µL to aspirate air into the tube. (Default will use all remaining volume in tip) :type volume: float @@ -1388,7 +1388,7 @@ def speed(self) -> "PlungerSpeeds": @property # type: ignore @requires_version(2, 0) def flow_rate(self) -> "FlowRates": - """The speeds (in uL/s) configured for the pipette. + """The speeds (in µL/s) configured for the pipette. This is an object with attributes ``aspirate``, ``dispense``, and ``blow_out`` holding the flow rates for the corresponding operation. From 21d16a325377795f8b721d2fa553034fb6f30a17 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 10:52:57 -0400 Subject: [PATCH 03/40] starting_tips, reset_tipracks, default_speed --- api/src/opentrons/protocol_api/instrument_context.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 55453d6d0b6..98260614003 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -112,8 +112,7 @@ def starting_tip(self) -> Union[labware.Well, None]: .. note:: - In robot software versions 6.3.0 and 6.3.1, protocols specifying API level 2.14 would - not respect ``starting_tip`` on the second and subsequent calls to + In robot software versions 6.3.0 and 6.3.1, protocols specifying API level 2.14 ignored ``starting_tip`` on the second and subsequent calls to :py:meth:`.InstrumentContext.pick_up_tip` with no argument. This is fixed for all API levels as of robot software version 7.0.0. """ @@ -125,7 +124,7 @@ def starting_tip(self, location: Union[labware.Well, None]) -> None: @requires_version(2, 0) def reset_tipracks(self) -> None: - """Reload all tips in each tip rack and reset starting tip""" + """Reload all tips in each tip rack and reset starting tip.""" for tiprack in self.tip_racks: tiprack.reset() self.starting_tip = None @@ -133,12 +132,13 @@ def reset_tipracks(self) -> None: @property # type: ignore[misc] @requires_version(2, 0) def default_speed(self) -> float: - """The speed at which the robot's gantry moves. + """The speed at which the robot's gantry moves in mm/s. - By default, 400 mm/s. Changing this value will change the speed of the - pipette when moving between labware. In addition to changing the + The default speed for Flex varies between 300 and 350 mm/s. + The OT-2 default is 400 mm/s. In addition to changing the default, the speed of individual motions can be changed with the ``speed`` argument to :py:meth:`InstrumentContext.move_to`. + See also, :ref:`gantry_speed` and :ref:`axis_speed_limits`. """ return self._core.get_default_speed() From 49f3e70944c27147cc1f8212ab667d6b028ccb16 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 10:55:20 -0400 Subject: [PATCH 04/40] reset_tipracks description --- api/src/opentrons/protocol_api/instrument_context.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 98260614003..0a95f4f9bd9 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -124,7 +124,7 @@ def starting_tip(self, location: Union[labware.Well, None]) -> None: @requires_version(2, 0) def reset_tipracks(self) -> None: - """Reload all tips in each tip rack and reset starting tip.""" + """Reload all tips in each tip rack and resets the starting tip.""" for tiprack in self.tip_racks: tiprack.reset() self.starting_tip = None From ad96ba7166bdbd63efb2a4bcd62842f8e9de3795 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 11:07:37 -0400 Subject: [PATCH 05/40] Sandbox test --- api/src/opentrons/protocol_api/instrument_context.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 0a95f4f9bd9..2384f10f814 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -138,7 +138,8 @@ def default_speed(self) -> float: The OT-2 default is 400 mm/s. In addition to changing the default, the speed of individual motions can be changed with the ``speed`` argument to :py:meth:`InstrumentContext.move_to`. - See also, :ref:`gantry_speed` and :ref:`axis_speed_limits`. + See also, :ref:`gantry_speed` + and :ref:`axis_speed_limits`. """ return self._core.get_default_speed() From 91034ec896e3c793d5880e1f6059c5914eba22e7 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 11:14:01 -0400 Subject: [PATCH 06/40] sandbox test ignore --- api/src/opentrons/protocol_api/instrument_context.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 2384f10f814..a9a10e8605e 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -137,9 +137,8 @@ def default_speed(self) -> float: The default speed for Flex varies between 300 and 350 mm/s. The OT-2 default is 400 mm/s. In addition to changing the default, the speed of individual motions can be changed with the - ``speed`` argument to :py:meth:`InstrumentContext.move_to`. - See also, :ref:`gantry_speed` - and :ref:`axis_speed_limits`. + ``speed`` argument to :py:meth:`InstrumentContext.move_to`. See + also, :ref:`gantry_speed`. """ return self._core.get_default_speed() From 4af8fe0a3deb584edfd36583f76597ccb8b0367c Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 13:42:25 -0400 Subject: [PATCH 07/40] aspirate and assoc arguments --- .../protocol_api/instrument_context.py | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index a9a10e8605e..2a70ba7333c 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -137,8 +137,8 @@ def default_speed(self) -> float: The default speed for Flex varies between 300 and 350 mm/s. The OT-2 default is 400 mm/s. In addition to changing the default, the speed of individual motions can be changed with the - ``speed`` argument to :py:meth:`InstrumentContext.move_to`. See - also, :ref:`gantry_speed`. + ``speed`` argument to :py:meth:`InstrumentContext.move_to`. + See also, :ref:`gantry_speed`. """ return self._core.get_default_speed() @@ -154,12 +154,13 @@ def aspirate( rate: float = 1.0, ) -> InstrumentContext: """ - Aspirate a given volume of liquid from the specified location, using - this pipette. + Draw liquid into a pipette tip. Includes parameters that control + aspiration volume, well location, tip position in a well, + and pipette flow rate. - :param volume: The volume to aspirate, in microliters (µL). If 0 or - unspecified, defaults to the highest volume possible - with this pipette and its currently attached tip. + :param volume: The volume to aspirate. Measured in µL. If 0 or + unspecified, defaults to the maximum volume for + the pipette and its currently attached tip. :type volume: int or float :param location: Where to aspirate from. If `location` is a :py:class:`.Well`, the robot will aspirate from @@ -170,10 +171,9 @@ def aspirate( robot will aspirate from the exact specified location. If unspecified, the robot will aspirate from the current position. - :param rate: A relative modifier for how quickly to aspirate liquid. - The flow rate for this aspirate will be - `rate` * :py:attr:`flow_rate.aspirate `. - If not specified, defaults to 1.0. + :param rate: How quickly a pipette aspirates liquid. Measured in µL/s. + Calculated as `rate` * :py:attr:`flow_rate.aspirate `. + If not specified, defaults to 1.0. See also, :ref:`new-plunger-flow-rates`. :type rate: float :returns: This instance. From 6bc0835a104702e84f14c766505b3e0b91a87e41 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 13:53:10 -0400 Subject: [PATCH 08/40] Aspirate and This instance Inconsistent punctuation for the text ":returns: This instance." Sometimes ended with a period, sometimes not. Changed to end all instances w/ a period. --- .../protocol_api/instrument_context.py | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 2a70ba7333c..0d5045e512a 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -395,7 +395,7 @@ def mix( and when dispensing, it will be `rate` * :py:attr:`flow_rate.dispense `. :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette. - :returns: This instance + :returns: This instance. .. note:: @@ -463,7 +463,7 @@ def blow_out( without first calling a method that takes a location (eg, :py:meth:`.aspirate`, :py:meth:`dispense`) - :returns: This instance + :returns: This instance. """ well: Optional[labware.Well] = None move_to_location: types.Location @@ -545,7 +545,7 @@ def touch_tip( without first calling a method that takes a location (eg, :py:meth:`.aspirate`, :py:meth:`dispense`) - :returns: This instance + :returns: This instance. .. note:: @@ -620,7 +620,7 @@ def air_gap( location (eg, :py:meth:`.aspirate`, :py:meth:`dispense`) - :returns: This instance + :returns: This instance. .. note:: @@ -654,7 +654,7 @@ def return_tip(self, home_after: Optional[bool] = None) -> InstrumentContext: This will not reset tip tracking, so the well flag will remain ``False``. - :returns: This instance + :returns: This instance. :param home_after: See the ``home_after`` parameter of :py:obj:`drop_tip`. @@ -758,7 +758,7 @@ def pick_up_tip( prepare during :py:meth:`.aspirate`. Version 2.12 and earlier will raise an ``APIVersionError`` if a value is set for ``prep_after``. - :returns: This instance + :returns: This instance. """ if presses is not None and self._api_version >= _PRESSES_INCREMENT_REMOVED_IN: @@ -930,7 +930,7 @@ def drop_tip( extensively test ``home_after=False`` with your particular pipette and your particular tips before relying on it. - :returns: This instance + :returns: This instance. """ alternate_drop_location: bool = False if location is None: @@ -1027,7 +1027,7 @@ def distribute( - ``mix_after`` is ignored. - :returns: This instance + :returns: This instance. """ _log.debug("Distributing {} from {} to {}".format(volume, source, dest)) kwargs["mode"] = "distribute" @@ -1059,7 +1059,7 @@ def consolidate( :param kwargs: See :py:meth:`transfer` and the :ref:`complex_params` page. Some parameters behave differently than when transferring. ``disposal_volume`` and ``mix_before`` are ignored. - :returns: This instance + :returns: This instance. """ _log.debug("Consolidate {} from {} to {}".format(volume, source, dest)) kwargs["mode"] = "consolidate" @@ -1173,7 +1173,7 @@ def transfer( See :ref:`param-disposal-volume` for details. - :returns: This instance + :returns: This instance. """ _log.debug("Transfer {} from {} to {}".format(volume, source, dest)) From ef267175817df123c0d22a7130e5ac9a7d9bbfc1 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 14:30:35 -0400 Subject: [PATCH 09/40] blow_out --- .../protocol_api/instrument_context.py | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 0d5045e512a..4a32f30cc1e 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -445,17 +445,16 @@ def blow_out( self, location: Optional[Union[types.Location, labware.Well]] = None ) -> InstrumentContext: """ - Blow liquid out of the tip. + Blows an extra amount of air through a pipette's tip to clear it. - If :py:attr:`dispense` is used to completely empty a pipette, - usually a small amount of liquid will remain in the tip. This - method moves the plunger past its usual stops to fully remove - any remaining liquid from the tip. Regardless of how much liquid - was in the tip when this function is called, after it is done - the tip will be empty. + If :py:attr:`dispense` is used to empty a pipette, usually + a small amount of liquid remains in the tip. During + a blowout, the pipette moves the plunger beyond its normal + limits to help remove all liquid from the pipette tip. + See also, :ref:`blow-out`. - :param location: The location to blow out into. If not specified, - defaults to the current location of the pipette + :param location: The blowout location. If no location is specified, + the pipette will blowout from its current position. :type location: :py:class:`.Well` or :py:class:`.Location` or None :raises RuntimeError: If no location is specified and location cache is From 6ca3bb77c191d3785c46231a05923f7085db23e8 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 14:37:15 -0400 Subject: [PATCH 10/40] blow_out code formatting to monospace --- api/src/opentrons/protocol_api/instrument_context.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 4a32f30cc1e..a66edff8819 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -458,7 +458,7 @@ def blow_out( :type location: :py:class:`.Well` or :py:class:`.Location` or None :raises RuntimeError: If no location is specified and location cache is - None. This should happen if `blow_out` is called + None. This should happen if ``blow_out`` is called without first calling a method that takes a location (eg, :py:meth:`.aspirate`, :py:meth:`dispense`) From 6c245cdf52b356e068debffb72d82a5a14d7f0fb Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 14:55:57 -0400 Subject: [PATCH 11/40] configure_for_volume and e.g. Too many instances of "eg". Should be "e.g.," or "e.g." --- .../protocol_api/instrument_context.py | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index a66edff8819..c8ea121fed3 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -460,7 +460,7 @@ def blow_out( :raises RuntimeError: If no location is specified and location cache is None. This should happen if ``blow_out`` is called without first calling a method that takes a - location (eg, :py:meth:`.aspirate`, + location (e.g., :py:meth:`.aspirate`, :py:meth:`dispense`) :returns: This instance. """ @@ -542,7 +542,7 @@ def touch_tip( :raises RuntimeError: If no location is specified and location cache is None. This should happen if `touch_tip` is called without first calling a method that takes a - location (eg, :py:meth:`.aspirate`, + location (e.g., :py:meth:`.aspirate`, :py:meth:`dispense`) :returns: This instance. @@ -616,7 +616,7 @@ def air_gap( :raises RuntimeError: If location cache is None. This should happen if `touch_tip` is called without first calling a method that takes a - location (eg, :py:meth:`.aspirate`, + location (e.g., :py:meth:`.aspirate`, :py:meth:`dispense`) :returns: This instance. @@ -1583,15 +1583,13 @@ def __str__(self) -> str: @requires_version(2, 15) def configure_for_volume(self, volume: float) -> None: - """Configure a pipette to handle a specific volume of liquid, specified in µL. Depending on the - volume, the pipette will enter a certain pipetting mode. Changing pipette modes alters properties - of the instance of :py:class:`.InstrumentContext`, such as default flow rate, minimum volume, and - maximum volume. The pipette will remain in the mode set by this function until it is called again. + """Configure a pipette to handle a specific volume of liquid, measured in µL. Depending on the volume, the pipette will enter a certain pipetting mode. + Changing pipette modes alters properties of the instance of + :py:class:`.InstrumentContext`, such as default flow rate, minimum volume, + and maximum volume. The pipette remains in the mode set by this function until it is called again. - The Flex 1-Channel 50 µL and Flex 8-Channel 50 µL pipettes must operate in a low-volume mode - to accurately dispense 1 µL of liquid. Low-volume mode can only be set by calling this function. - - For more information on available modes for certain pipettes, see :ref:`pipette-volume-modes`. + The Flex 1-Channel 50 µL and Flex 8-Channel 50 µL pipettes must operate in a low-volume mode to accurately dispense 1 µL of liquid. Low-volume mode can + only be set by calling ``configure_for_volume``. See also, :ref:`pipette-volume-modes`. .. note :: From 08949b34207a8632849940cb3cf0397b626bc924 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 15:23:46 -0400 Subject: [PATCH 12/40] configure_for_volume part 2 --- api/src/opentrons/protocol_api/instrument_context.py | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index c8ea121fed3..d00caaf236a 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -1593,15 +1593,11 @@ def configure_for_volume(self, volume: float) -> None: .. note :: - Changing a pipette's mode will reset its :ref:`flow rates `. + Changing a pipette's mode will reset its :ref:`flow rate `. - This function will raise an error if called when the pipette's tip contains liquid. It won't - raise an error if no tip is attached, but changing modes may affect which tips the pipette can - subsequently pick up without raising an error. + This function will raise an error if called when the pipette's tip contains liquid. It won't raise an error if a tip is not attached, but changing modes may affect which tips the pipette can subsequently pick up without raising an error. - This function will also raise an error if ``volume`` is outside the :ref:`overall minimum and - maximum capacities ` of the pipette (e.g., setting ``volume=1`` for a Flex - 1000 µL pipette). + This function will also raise an error if ``volume`` is outside of the :ref:`minimum and maximum capacities ` of the pipette (e.g., setting ``volume=1`` for a Flex 1000 µL pipette). :param volume: The volume, in µL, that the pipette will prepare to handle. :type volume: float From 9287abdcde65dca2e0a254b2aa0eeed7bfd0d883 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 11 Oct 2023 16:10:59 -0400 Subject: [PATCH 13/40] current_volume, channels, default_speed --- api/src/opentrons/protocol_api/instrument_context.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index d00caaf236a..6d6036a344d 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -137,7 +137,7 @@ def default_speed(self) -> float: The default speed for Flex varies between 300 and 350 mm/s. The OT-2 default is 400 mm/s. In addition to changing the default, the speed of individual motions can be changed with the - ``speed`` argument to :py:meth:`InstrumentContext.move_to`. + ``speed`` argument of the :py:meth:`InstrumentContext.move_to` method. See also, :ref:`gantry_speed`. """ return self._core.get_default_speed() @@ -1492,7 +1492,7 @@ def max_volume(self) -> float: @requires_version(2, 0) def current_volume(self) -> float: """ - The current amount of liquid, in microliters, held in the pipette. + The current amount of liquid held in the pipette. Measured in µL. """ return self._core.get_current_volume() @@ -1523,7 +1523,7 @@ def hw_pipette(self) -> PipetteDict: @property # type: ignore @requires_version(2, 0) def channels(self) -> int: - """The number of channels on the pipette.""" + """The number of channels on the pipette. See also, :ref:`new-pipette`.""" return self._core.get_channels() @property # type: ignore From 586b4fdf1a5b3c72bb92d32768e90dddf81c3205 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 11:26:11 -0400 Subject: [PATCH 14/40] dispense description-definitions --- .../protocol_api/instrument_context.py | 57 ++++++++++--------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 6d6036a344d..dda117283af 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -158,7 +158,7 @@ def aspirate( aspiration volume, well location, tip position in a well, and pipette flow rate. - :param volume: The volume to aspirate. Measured in µL. If 0 or + :param volume: The volume to aspirate, measured in µL. If 0 or unspecified, defaults to the maximum volume for the pipette and its currently attached tip. :type volume: int or float @@ -171,7 +171,7 @@ def aspirate( robot will aspirate from the exact specified location. If unspecified, the robot will aspirate from the current position. - :param rate: How quickly a pipette aspirates liquid. Measured in µL/s. + :param rate: How quickly a pipette aspirates liquid, measured in µL/s. Calculated as `rate` * :py:attr:`flow_rate.aspirate `. If not specified, defaults to 1.0. See also, :ref:`new-plunger-flow-rates`. :type rate: float @@ -256,35 +256,38 @@ def dispense( push_out: Optional[float] = None, ) -> InstrumentContext: """ - Dispense a volume of liquid (in microliters/µL) using this pipette - into the specified location. + Dispense liquid from a pipette tip. Includes parameters that control + dispense volume, well location, tip position in a well, and pipette + flow rate. - If only a volume is passed, the pipette will dispense from its current - position. If only a location is passed (as in - ``instr.dispense(location=wellplate['A1'])``), all of the liquid - aspirated into the pipette will be dispensed (this volume is accessible - through :py:attr:`current_volume`). - - :param volume: The volume of liquid to dispense, in microliters. If 0 + :param volume: The volume to dispense, measured in µL. If 0 or unspecified, defaults to :py:attr:`current_volume`. + + If only a volume is passed, the pipette will dispense + from its current position. :type volume: int or float - :param location: Where to dispense into. If `location` is a - :py:class:`.Well`, the robot will dispense into - :py:obj:`well_bottom_clearance.dispense ` - mm above the bottom of the well. If `location` is a - :py:class:`.Location` (i.e. the result of - :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the - robot will dispense into the exact specified location. - If unspecified, the robot will dispense into the - current position. - :param rate: A relative modifier for how quickly to dispense liquid. - The flow rate for this dispense will be - `rate` * :py:attr:`flow_rate.dispense `. - If not specified, defaults to 1.0. + :param location: Where to dispense liquid held in the pipette. + If `location`is a :py:class:`.Well`, the robot will + dispense into :py:obj:`well_bottom_clearance.dispense ` + mm above the bottom of the well. If `location` is a + :py:class:`.Location` (i.e. the result of + :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), + the robot will dispense into the exact specified location. + + If only a location is passed (as in + ``instr.dispense(location=wellplate['A1'])``), + all of the liquid aspirated into the pipette will be dispensed + (this volume is accessible through :py:attr:`current_volume`). + + If unspecified, the robot will dispense into the + current position. + :param rate: How quickly a pipette dispenses liquid. Measured in µL/s. + Calculated as `rate` * :py:attr:`flow_rate.dispense `. + If not specified, defaults to 1.0. See also, :ref:`new-plunger-flow-rates`. :type rate: float - :param push_out: Continue past the plunger bottom to guarantee all liquid - leaves the tip. Specified in microliters. By default, this value is None. + :param push_out: Continue past the plunger bottom to help ensure all liquid + leaves the tip. Measured in µL. The default value is ``None``. :type push_out: float :returns: This instance. @@ -1492,7 +1495,7 @@ def max_volume(self) -> float: @requires_version(2, 0) def current_volume(self) -> float: """ - The current amount of liquid held in the pipette. Measured in µL. + The current amount of liquid held in the pipette, measured in µL. """ return self._core.get_current_volume() From 362f0979723ff81ddfb76736d6e92d6305723853 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 11:51:28 -0400 Subject: [PATCH 15/40] dispense format testing Not rendering in a nice way. Might be exceeding character count per line. --- api/src/opentrons/protocol_api/instrument_context.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index dda117283af..a658073c113 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -260,11 +260,11 @@ def dispense( dispense volume, well location, tip position in a well, and pipette flow rate. - :param volume: The volume to dispense, measured in µL. If 0 - or unspecified, defaults to :py:attr:`current_volume`. - - If only a volume is passed, the pipette will dispense - from its current position. + :param volume: The volume to dispense, measured in µL. + If 0 or unspecified, defaults to + :py:attr:`current_volume`. + If only a volume is passed, the pipette + will dispense from its current position. :type volume: int or float :param location: Where to dispense liquid held in the pipette. From d4b960920fc193550fedd5862ae2517f152c6e67 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 12:53:01 -0400 Subject: [PATCH 16/40] dispense formatting test Again, more line length testing. --- .../protocol_api/instrument_context.py | 27 +++++++++---------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index a658073c113..77413b5e694 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -268,20 +268,19 @@ def dispense( :type volume: int or float :param location: Where to dispense liquid held in the pipette. - If `location`is a :py:class:`.Well`, the robot will - dispense into :py:obj:`well_bottom_clearance.dispense ` - mm above the bottom of the well. If `location` is a - :py:class:`.Location` (i.e. the result of - :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), - the robot will dispense into the exact specified location. - - If only a location is passed (as in - ``instr.dispense(location=wellplate['A1'])``), - all of the liquid aspirated into the pipette will be dispensed - (this volume is accessible through :py:attr:`current_volume`). - - If unspecified, the robot will dispense into the - current position. + If ``location`` is a :py:class:`.Well`, + the robot will dispense into + :py:obj:`well_bottom_clearance.dispense ` + mm above the bottom of the well. + If `location` is a :py:class:`.Location` + (i.e. the result of :py:meth:`.Well.top` or + :py:meth:`.Well.bottom`), the robot will dispense into + the exact specified location. If only a location is + passed (e.g., ``instr.dispense(location=wellplate['A1'])``), + all of the liquid aspirated into the pipette + will be dispensed (this volume is accessible through + :py:attr:`current_volume`). If unspecified, + the robot will dispense into the current position. :param rate: How quickly a pipette dispenses liquid. Measured in µL/s. Calculated as `rate` * :py:attr:`flow_rate.dispense `. If not specified, defaults to 1.0. See also, :ref:`new-plunger-flow-rates`. From 040f5d561c250fb99004554ec74930ec8e83894f Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 13:22:28 -0400 Subject: [PATCH 17/40] dispense format layout test --- api/src/opentrons/protocol_api/instrument_context.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 77413b5e694..652eb988c75 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -272,13 +272,13 @@ def dispense( the robot will dispense into :py:obj:`well_bottom_clearance.dispense ` mm above the bottom of the well. - If `location` is a :py:class:`.Location` + If ``location`` is :py:class:`.Location` (i.e. the result of :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the robot will dispense into - the exact specified location. If only a location is - passed (e.g., ``instr.dispense(location=wellplate['A1'])``), + the specified position. If only a ``location`` is passed + (e.g., ``instr.dispense(location=wellplate['A1'])``), all of the liquid aspirated into the pipette - will be dispensed (this volume is accessible through + will be dispensed (amount is accessible through :py:attr:`current_volume`). If unspecified, the robot will dispense into the current position. :param rate: How quickly a pipette dispenses liquid. Measured in µL/s. From d608ca0758922644077a41d7a92b3965ec8c9fae Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 13:33:25 -0400 Subject: [PATCH 18/40] drop tip and new anchor Anchor to pipette_tips.rst, "Dropping a Tip" section. Anchor is .. _pipette-drop-tip: --- api/docs/v2/basic_commands/pipette_tips.rst | 2 ++ .../protocol_api/instrument_context.py | 20 +++++++++---------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/api/docs/v2/basic_commands/pipette_tips.rst b/api/docs/v2/basic_commands/pipette_tips.rst index 4495ea1f71f..c1be40a75cc 100644 --- a/api/docs/v2/basic_commands/pipette_tips.rst +++ b/api/docs/v2/basic_commands/pipette_tips.rst @@ -70,6 +70,8 @@ Finally, sum the tip count in the range:: For a more advanced "real-world" example, review the :ref:`off-deck location protocol ` on the :ref:`moving-labware` page. This example also uses a ``for`` loop to iterate through a tip rack, but it includes other commands that pause the protocol and let you replace an on-deck tip rack with another rack stored in an off-deck location. +.. _pipette-drop-tip: + Dropping a Tip ============== diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 652eb988c75..0c81260bebe 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -863,7 +863,7 @@ def drop_tip( home_after: Optional[bool] = None, ) -> InstrumentContext: """ - Drop the current tip. + Drop the current tip. See also, :ref:`pipette-drop-tip`. If no location is passed, the Pipette will drop the tip into its :py:attr:`trash_container`, which if not specified defaults to @@ -878,24 +878,24 @@ def drop_tip( - If the only thing to specify is which well into which to drop a tip, `location` can be a :py:class:`.Well`. For instance, - if you have a tip rack in a variable called `tiprack`, you can + if you have a tip rack in a variable called ``tiprack``, you can drop a tip into a specific well on that tiprack with the call - `instr.drop_tip(tiprack.wells()[0])`. This style of call can + ``instr.drop_tip(tiprack.wells()[0])``. This style of call can be used to make the robot drop a tip into arbitrary labware. - If the position to drop the tip from as well as the :py:class:`.Well` to drop the tip into needs to be specified, for instance to tell the robot to drop a tip from an unusually - large height above the tiprack, `location` + large height above the tiprack, ``location`` can be a :py:class:`.types.Location`; for instance, you can call `instr.drop_tip(tiprack.wells()[0].top())`. :param location: - The location to drop the tip + The location to drop the tip. :type location: :py:class:`.types.Location` or :py:class:`.Well` or None - :param home_after: - Whether to home this pipette's plunger after dropping the tip. - If not specified, defaults to ``True`` on an OT-2. + :param home_after: Whether to home this pipette's plunger after + dropping the tip. If not specified, + defaults to ``True`` on an OT-2. Setting ``home_after=False`` saves waiting a couple of seconds after the pipette drops the tip, but risks causing other problems. @@ -905,12 +905,12 @@ def drop_tip( * You're using a GEN2 pipette, not a GEN1 pipette. * You've tested ``home_after=False`` extensively with your - particular pipette and your particular tips. + pipette and tips. * You understand the risks described below. The ejector shroud that pops the tip off the end of the pipette is driven by the plunger's stepper motor. Sometimes, the strain of - ejecting the tip can make that motor *skip* and fall out of sync + ejecting the tip can make that motor skip and fall out of sync with where the robot thinks it is. Homing the plunger fixes this, so, to be safe, we normally do it From 52e622af892f5c5c6fa486969f18706519240322 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 13:48:40 -0400 Subject: [PATCH 19/40] drop_tip text formatting --- api/src/opentrons/protocol_api/instrument_context.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 0c81260bebe..d3e1dae9121 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -893,8 +893,8 @@ def drop_tip( The location to drop the tip. :type location: :py:class:`.types.Location` or :py:class:`.Well` or None - :param home_after: Whether to home this pipette's plunger after - dropping the tip. If not specified, + :param home_after: Whether to home this pipette's plunger + after dropping the tip. If not specified, defaults to ``True`` on an OT-2. Setting ``home_after=False`` saves waiting a couple of seconds From c8f0baf8a1f2007a43a2ab60b4523d392577439f Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 14:00:08 -0400 Subject: [PATCH 20/40] drop_tip formatting yet again --- api/src/opentrons/protocol_api/instrument_context.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index d3e1dae9121..423bc4a7b8e 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -893,9 +893,9 @@ def drop_tip( The location to drop the tip. :type location: :py:class:`.types.Location` or :py:class:`.Well` or None - :param home_after: Whether to home this pipette's plunger - after dropping the tip. If not specified, - defaults to ``True`` on an OT-2. + :param home_after: + Whether to home this pipette's plunger after dropping the tip. + If not specified, defaults to ``True`` on an OT-2. Setting ``home_after=False`` saves waiting a couple of seconds after the pipette drops the tip, but risks causing other problems. From f9104b6e83c5f22784bca7bd4ac79995b539ea0f Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 14:23:06 -0400 Subject: [PATCH 21/40] Punctuation, links, vol measurement units --- api/docs/v2/basic_commands/pipette_tips.rst | 2 ++ .../opentrons/protocol_api/instrument_context.py | 14 +++++++------- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/api/docs/v2/basic_commands/pipette_tips.rst b/api/docs/v2/basic_commands/pipette_tips.rst index c1be40a75cc..c3fb7de569d 100644 --- a/api/docs/v2/basic_commands/pipette_tips.rst +++ b/api/docs/v2/basic_commands/pipette_tips.rst @@ -10,6 +10,8 @@ Your robot needs to attach a disposable tip to the pipette before it can aspirat The following sections demonstrate how to use each method and include sample code. The examples used here assume that you've loaded the pipettes and labware from the basic :ref:`protocol template `. +.. _basic-tip-pickup: + Picking Up a Tip ================ diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 423bc4a7b8e..701b0441a76 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -997,7 +997,7 @@ def home(self) -> InstrumentContext: @requires_version(2, 0) def home_plunger(self) -> InstrumentContext: - """Home the plunger associated with this mount + """Home the plunger associated with this mount. :returns: This instance. """ @@ -1343,7 +1343,7 @@ def move_to( @property # type: ignore @requires_version(2, 0) def mount(self) -> str: - """Return the name of the mount this pipette is attached to""" + """Return the name of the mount this pipette is attached to.""" return self._core.get_mount().name.lower() @property # type: ignore @@ -1432,7 +1432,7 @@ def tip_racks(self) -> List[labware.Labware]: The tip racks that have been linked to this pipette. This is the property used to determine which tips to pick up next when - calling :py:meth:`pick_up_tip` without arguments. + calling :py:meth:`pick_up_tip` without arguments. See also, :ref:`basic-tip-pickup`. """ return self._tip_racks @@ -1459,7 +1459,7 @@ def trash_container(self, trash: labware.Labware) -> None: @requires_version(2, 0) def name(self) -> str: """ - The name string for the pipette (e.g. 'p300_single') + The name string for the pipette (e.g. 'p300_single). """ return self._core.get_pipette_name() @@ -1480,10 +1480,10 @@ def min_volume(self) -> float: @requires_version(2, 0) def max_volume(self) -> float: """ - The maximum volume, in microliters (µL), that this pipette can hold. + The maximum volume, in µL, that the pipette can hold. The maximum volume that you can actually aspirate might be lower than - this, depending on what kind of tip is attached to this pipette. For + this, depending on what kind of tip is attached to this pipette. For example, a P300 Single-Channel pipette always has a ``max_volume`` of 300 µL, but if it's using a 200 µL filter tip, its usable volume would be limited to 200 µL. @@ -1546,7 +1546,7 @@ def well_bottom_clearance(self) -> "Clearances": This is an object with attributes ``aspirate`` and ``dispense``, describing the default heights of the corresponding operation. The - default is 1.0mm for both aspirate and dispense. + default is 1.0 mm for both aspirate and dispense. When :py:meth:`aspirate` or :py:meth:`dispense` is given a :py:class:`.Well` rather than a full :py:class:`.Location`, the robot From 76f0503679f5a92a1efa1f2299f56fb9374cd0b8 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 14:43:27 -0400 Subject: [PATCH 22/40] Mix --- .../protocol_api/instrument_context.py | 35 ++++++++++--------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 701b0441a76..70d342b46c3 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -156,7 +156,7 @@ def aspirate( """ Draw liquid into a pipette tip. Includes parameters that control aspiration volume, well location, tip position in a well, - and pipette flow rate. + and pipette flow rate. See also, :ref:`new-aspirate`. :param volume: The volume to aspirate, measured in µL. If 0 or unspecified, defaults to the maximum volume for @@ -258,7 +258,7 @@ def dispense( """ Dispense liquid from a pipette tip. Includes parameters that control dispense volume, well location, tip position in a well, and pipette - flow rate. + flow rate. See also, :ref:`new-dispense`. :param volume: The volume to dispense, measured in µL. If 0 or unspecified, defaults to @@ -379,23 +379,24 @@ def mix( rate: float = 1.0, ) -> InstrumentContext: """ - Mix a volume of liquid (µL) using this pipette, by repeatedly - aspirating and dispensing in the same place. - - :param repetitions: how many times the pipette should mix (default: 1) - :param volume: number of microliters to mix. If 0 or unspecified, - defaults to the highest volume possible with this - pipette and its currently attached tip. - :param location: a Well or a position relative to well. - e.g, `plate.rows()[0][0].bottom()`. If unspecified, - the pipette will mix from its current position. + Mixes a volume of liquid by repeatedly aspirating and dispensing it in a single location. + See also, :ref:`mix`. + + :param repetitions: Number of times to mix (default is 1). + :param volume: The volume to mix, measured in µL. If 0 or unspecified, + defaults to the maximum volume for the pipette and its + attached tip. + :param location: A well or a position relative to well + (e.g, ``plate.rows()[0][0].bottom()``). + If unspecified, the pipette will mix from + its current position. :type location: types.Location - :param rate: A relative modifier for how quickly to aspirate and - dispense liquid during this mix. When aspirating, the flow - rate will be - `rate` * :py:attr:`flow_rate.aspirate `, - and when dispensing, it will be + :param rate: How quickly a pipette aspirates and dispense liquid + while mixing. The aspiration flow rate is calculated as + `rate` * :py:attr:`flow_rate.aspirate `. + The dispense flow rate is calculated as `rate` * :py:attr:`flow_rate.dispense `. + See also, :ref:`new-plunger-flow-rates`. :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette. :returns: This instance. From 66f346ee55cf8ab29d46e011e3b61a9d79427cc9 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 14:55:25 -0400 Subject: [PATCH 23/40] mix text formatting --- api/src/opentrons/protocol_api/instrument_context.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 70d342b46c3..e82104464f2 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -393,10 +393,10 @@ def mix( :type location: types.Location :param rate: How quickly a pipette aspirates and dispense liquid while mixing. The aspiration flow rate is calculated as - `rate` * :py:attr:`flow_rate.aspirate `. + `rate` * :py:attr:`flow_rate.aspirate `. The dispense flow rate is calculated as - `rate` * :py:attr:`flow_rate.dispense `. - See also, :ref:`new-plunger-flow-rates`. + `rate` * :py:attr:`flow_rate.dispense `. + See also, :ref:`new-plunger-flow-rates`. :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette. :returns: This instance. From 990bdec2f97167435c9147efc8543bab3b99ea14 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 15:08:52 -0400 Subject: [PATCH 24/40] Mix: more formatting --- api/src/opentrons/protocol_api/instrument_context.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index e82104464f2..778f9e4a871 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -393,9 +393,9 @@ def mix( :type location: types.Location :param rate: How quickly a pipette aspirates and dispense liquid while mixing. The aspiration flow rate is calculated as - `rate` * :py:attr:`flow_rate.aspirate `. + ``rate`` * :py:attr:`flow_rate.aspirate `. The dispense flow rate is calculated as - `rate` * :py:attr:`flow_rate.dispense `. + ``rate`` * :py:attr:`flow_rate.dispense `. See also, :ref:`new-plunger-flow-rates`. :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette. :returns: This instance. From d58a971de113314fe0f199b4c1e8d6362467ea71 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 15:19:17 -0400 Subject: [PATCH 25/40] Mix one more format try --- api/src/opentrons/protocol_api/instrument_context.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 778f9e4a871..2dc7dcc1c2b 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -394,8 +394,8 @@ def mix( :param rate: How quickly a pipette aspirates and dispense liquid while mixing. The aspiration flow rate is calculated as ``rate`` * :py:attr:`flow_rate.aspirate `. - The dispense flow rate is calculated as - ``rate`` * :py:attr:`flow_rate.dispense `. + The dispense flow rate is calculated + as ``rate`` * :py:attr:`flow_rate.dispense `. See also, :ref:`new-plunger-flow-rates`. :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette. :returns: This instance. From 50f7022b86393a136148556026c5579035720f6a Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 15:49:29 -0400 Subject: [PATCH 26/40] Adding an anchor --- api/docs/v2/basic_commands/utilities.rst | 2 + .../protocol_api/instrument_context.py | 39 ++++++++++--------- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/api/docs/v2/basic_commands/utilities.rst b/api/docs/v2/basic_commands/utilities.rst index 13633f419f3..1117d0d0b97 100644 --- a/api/docs/v2/basic_commands/utilities.rst +++ b/api/docs/v2/basic_commands/utilities.rst @@ -34,6 +34,8 @@ Call the :py:meth:`.ProtocolContext.pause` method to stop a protocol at a specif .. versionadded:: 2.0 +.. _utility-homing: + Homing ====== diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 2dc7dcc1c2b..914f9c687ff 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -523,23 +523,23 @@ def touch_tip( ) -> InstrumentContext: """ Touch the pipette tip to the sides of a well, with the intent of - removing left-over droplets + removing left-over droplets. See also, :ref:`touch-tip`. :param location: If no location is passed, pipette will - touch tip at current well's edges + touch tip at current well's edges. :type location: :py:class:`.Well` or None :param radius: Describes the proportion of the target well's radius. When `radius=1.0`, the pipette tip will move to - the edge of the target well; when `radius=0.5`, it will + the edge of the target well. When `radius=0.5`, it will move to 50% of the well's radius. Default: 1.0 (100%) :type radius: float - :param v_offset: The offset in mm from the top of the well to touch tip - A positive offset moves the tip higher above the well, - while a negative offset moves it lower into the well - Default: -1.0 mm + :param v_offset: The offset in mm from the top of the well to touch tip. + A positive offset moves the tip higher above the well. + A negative offset moves it lower into the well. + Default is -1.0 mm. :type v_offset: float :param speed: The speed for touch tip motion, in mm/s. - Default: 60.0 mm/s, Max: 80.0 mm/s, Min: 20.0 mm/s + Default: 60.0 mm/s, Max: 80.0 mm/s, Min: 1.0 mm/s. :type speed: float :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette :raises RuntimeError: If no location is specified and location cache is @@ -604,14 +604,16 @@ def air_gap( self, volume: Optional[float] = None, height: Optional[float] = None ) -> InstrumentContext: """ - Pull air into the pipette current tip at the current location + Pull air into the pipette current tip at the current location. + See also, :ref:`air-gap`. :param volume: The amount in µL to aspirate air into the tube. - (Default will use all remaining volume in tip) + Calling ``air_gap()`` with no arguments uses + the entire remaining volume in the pipette. :type volume: float - :param height: The number of millimeters to move above the current Well - to air-gap aspirate. (Default: 5mm above current Well) + :param height: The number of millimeters to move above the current well + before aspirating air. The default is 5 mm above current well. :type height: float :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette @@ -683,8 +685,9 @@ def pick_up_tip( ) -> InstrumentContext: """ Pick up a tip for the pipette to run liquid-handling commands. + See also, :ref:`basic-tip-pickup`. - If no location is passed, the Pipette will pick up the next available + If no location is passed, the pipette will pick up the next available tip in its :py:attr:`InstrumentContext.tip_racks` list. Within each tip rack, tips will be picked up in the order specified by the labware definition and :py:meth:`.Labware.wells`. @@ -702,8 +705,8 @@ def pick_up_tip( was not specified when creating the :py:class:`.InstrumentContext`. * If you want to pick up the next available tip(s) in a specific - tip rack, you may use the tip rack directly: - e.g. ``instr.pick_up_tip(tiprack)`` + tip rack, you may use the tip rack directly + (e.g. ``instr.pick_up_tip(tiprack)``). * If the position to move to in the well needs to be specified, for instance to tell the robot to run its pick up tip routine @@ -982,7 +985,7 @@ def drop_tip( @requires_version(2, 0) def home(self) -> InstrumentContext: - """Home the robot. + """Home the robot. See also, :ref:`utility-homing`. :returns: This instance. """ @@ -1390,7 +1393,7 @@ def speed(self) -> "PlungerSpeeds": @property # type: ignore @requires_version(2, 0) def flow_rate(self) -> "FlowRates": - """The speeds (in µL/s) configured for the pipette. + """The speeds (in µL/s) configured for the pipette. See also, :ref:`new-plunger-flow-rates`. This is an object with attributes ``aspirate``, ``dispense``, and ``blow_out`` holding the flow rates for the corresponding operation. @@ -1586,7 +1589,7 @@ def __str__(self) -> str: @requires_version(2, 15) def configure_for_volume(self, volume: float) -> None: - """Configure a pipette to handle a specific volume of liquid, measured in µL. Depending on the volume, the pipette will enter a certain pipetting mode. + """Configure a pipette to handle a specific volume of liquid, measured in µL. Depending on the volume, the pipette will enter a unique pipetting mode. Changing pipette modes alters properties of the instance of :py:class:`.InstrumentContext`, such as default flow rate, minimum volume, and maximum volume. The pipette remains in the mode set by this function until it is called again. From 827c866137b8f6f8d01ce5650cc9f230264b8966 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 12 Oct 2023 17:25:05 -0400 Subject: [PATCH 27/40] air_gap volume text Last minute, saw some weird original text to fix. --- api/src/opentrons/protocol_api/instrument_context.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 914f9c687ff..eafc0880eb5 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -607,7 +607,7 @@ def air_gap( Pull air into the pipette current tip at the current location. See also, :ref:`air-gap`. - :param volume: The amount in µL to aspirate air into the tube. + :param volume: The amount of air to aspirate, measured in µL. Calling ``air_gap()`` with no arguments uses the entire remaining volume in the pipette. :type volume: float From 1b47670be65824c331116928424ba37021c2e9de Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 18 Oct 2023 12:37:30 -0400 Subject: [PATCH 28/40] Check and fix any remaining MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Returning to this after problems last week. Just a few additional changes. Ran Black on the file. Returns the following: joewojak@admins-Air-2 protocol_api % black instrument_context.py --diff --color All done! ✨ 🍰 ✨ 1 file would be left unchanged. --- api/src/opentrons/protocol_api/instrument_context.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index eafc0880eb5..187c880f67c 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -124,7 +124,7 @@ def starting_tip(self, location: Union[labware.Well, None]) -> None: @requires_version(2, 0) def reset_tipracks(self) -> None: - """Reload all tips in each tip rack and resets the starting tip.""" + """Reloads all tips in each tip rack and resets the starting tip.""" for tiprack in self.tip_racks: tiprack.reset() self.starting_tip = None @@ -264,7 +264,7 @@ def dispense( If 0 or unspecified, defaults to :py:attr:`current_volume`. If only a volume is passed, the pipette - will dispense from its current position. + will dispense from its current position. :type volume: int or float :param location: Where to dispense liquid held in the pipette. @@ -391,7 +391,7 @@ def mix( If unspecified, the pipette will mix from its current position. :type location: types.Location - :param rate: How quickly a pipette aspirates and dispense liquid + :param rate: How quickly a pipette aspirates and dispenses liquid while mixing. The aspiration flow rate is calculated as ``rate`` * :py:attr:`flow_rate.aspirate `. The dispense flow rate is calculated @@ -457,7 +457,7 @@ def blow_out( See also, :ref:`blow-out`. :param location: The blowout location. If no location is specified, - the pipette will blowout from its current position. + the pipette will blow out from its current position. :type location: :py:class:`.Well` or :py:class:`.Location` or None :raises RuntimeError: If no location is specified and location cache is @@ -535,7 +535,7 @@ def touch_tip( :type radius: float :param v_offset: The offset in mm from the top of the well to touch tip. A positive offset moves the tip higher above the well. - A negative offset moves it lower into the well. + A negative offset moves the tip lower into the well. Default is -1.0 mm. :type v_offset: float :param speed: The speed for touch tip motion, in mm/s. @@ -612,7 +612,7 @@ def air_gap( the entire remaining volume in the pipette. :type volume: float - :param height: The number of millimeters to move above the current well + :param height: The height, in mm, to move above the current well before aspirating air. The default is 5 mm above current well. :type height: float From 4673f022e848c2ef1653a2dee2757c4aecc6abee Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 18 Oct 2023 12:58:04 -0400 Subject: [PATCH 29/40] Line 618 remove spaces, keep same line Line count doesn't change --- api/src/opentrons/protocol_api/instrument_context.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index b6f108e48d7..6c15075247b 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -615,7 +615,7 @@ def air_gap( :param height: The height, in mm, to move above the current well before aspirating air. The default is 5 mm above current well. - + :type height: float :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette From a1c38a403a8917291aee1036086f0ad9054ad610 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 20 Oct 2023 15:14:44 -0400 Subject: [PATCH 30/40] Apply suggestions from code review Making batch commits before other changes. Will do a batch commit, pull locally, more revisions, and push again. Co-authored-by: Ed Cormany --- .../protocol_api/instrument_context.py | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 6c15075247b..77271164cd7 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -171,7 +171,7 @@ def aspirate( robot will aspirate from the exact specified location. If unspecified, the robot will aspirate from the current position. - :param rate: How quickly a pipette aspirates liquid, measured in µL/s. + :param rate: A multiplier for the default flow rate of the pipette. Calculated as `rate` * :py:attr:`flow_rate.aspirate `. If not specified, defaults to 1.0. See also, :ref:`new-plunger-flow-rates`. :type rate: float @@ -269,11 +269,11 @@ def dispense( :param location: Where to dispense liquid held in the pipette. If ``location`` is a :py:class:`.Well`, - the robot will dispense into - :py:obj:`well_bottom_clearance.dispense ` - mm above the bottom of the well. + the pipette will dispense at or above the center bottom of the well. + The distance from the bottom is specified by + :py:obj:`well_bottom_clearance.dispense `. If ``location`` is :py:class:`.Location` - (i.e. the result of :py:meth:`.Well.top` or + (e.g., the result of :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the robot will dispense into the specified position. If only a ``location`` is passed (e.g., ``instr.dispense(location=wellplate['A1'])``), @@ -523,7 +523,7 @@ def touch_tip( ) -> InstrumentContext: """ Touch the pipette tip to the sides of a well, with the intent of - removing left-over droplets. See also, :ref:`touch-tip`. + removing leftover droplets. See also :ref:`touch-tip`. :param location: If no location is passed, pipette will touch tip at current well's edges. @@ -871,7 +871,7 @@ def drop_tip( """ Drop the current tip. See also, :ref:`pipette-drop-tip`. - If no location is passed, the Pipette will drop the tip into its + If no location is passed, the pipette will drop the tip into its :py:attr:`trash_container`, which if not specified defaults to the fixed trash in slot 12. From API version 2.15 on, if the trash container is the default fixed trash in A3 (slot 12), the API will default to @@ -891,14 +891,14 @@ def drop_tip( - If the position to drop the tip from as well as the :py:class:`.Well` to drop the tip into needs to be specified, for instance to tell the robot to drop a tip from an unusually - large height above the tiprack, ``location`` + large height above the tip rack, ``location`` can be a :py:class:`.types.Location`; for instance, you can call `instr.drop_tip(tiprack.wells()[0].top())`. :param location: The location to drop the tip. :type location: - :py:class:`.types.Location` or :py:class:`.Well` or None + :py:class:`.types.Location` or :py:class:`.Well` or ``None`` :param home_after: Whether to home this pipette's plunger after dropping the tip. If not specified, defaults to ``True`` on an OT-2. @@ -914,7 +914,7 @@ def drop_tip( pipette and tips. * You understand the risks described below. - The ejector shroud that pops the tip off the end of the pipette is + The ejector that pops the tip off the end of the pipette is driven by the plunger's stepper motor. Sometimes, the strain of ejecting the tip can make that motor skip and fall out of sync with where the robot thinks it is. @@ -1465,7 +1465,7 @@ def trash_container(self, trash: labware.Labware) -> None: @requires_version(2, 0) def name(self) -> str: """ - The name string for the pipette (e.g. 'p300_single). + The name string for the pipette (e.g., ``p300_single``). """ return self._core.get_pipette_name() From b9111970460e7773f9c997a4088ed0fb4eb2653c Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 20 Oct 2023 15:39:05 -0400 Subject: [PATCH 31/40] Remove commas in introductory signals For text like "See, . . . " and "See also, . . . " let's get rid of the commas. Also, most, if not all, of these should be just "See" not "See also" because we're referring to stuff that directly supports the text. --- .../protocol_api/instrument_context.py | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 77271164cd7..c336a708573 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -138,7 +138,7 @@ def default_speed(self) -> float: The OT-2 default is 400 mm/s. In addition to changing the default, the speed of individual motions can be changed with the ``speed`` argument of the :py:meth:`InstrumentContext.move_to` method. - See also, :ref:`gantry_speed`. + See :ref:`gantry_speed`. """ return self._core.get_default_speed() @@ -156,7 +156,7 @@ def aspirate( """ Draw liquid into a pipette tip. Includes parameters that control aspiration volume, well location, tip position in a well, - and pipette flow rate. See also, :ref:`new-aspirate`. + and pipette flow rate. See :ref:`new-aspirate`. :param volume: The volume to aspirate, measured in µL. If 0 or unspecified, defaults to the maximum volume for @@ -173,7 +173,7 @@ def aspirate( current position. :param rate: A multiplier for the default flow rate of the pipette. Calculated as `rate` * :py:attr:`flow_rate.aspirate `. - If not specified, defaults to 1.0. See also, :ref:`new-plunger-flow-rates`. + If not specified, defaults to 1.0. See :ref:`new-plunger-flow-rates`. :type rate: float :returns: This instance. @@ -258,7 +258,7 @@ def dispense( """ Dispense liquid from a pipette tip. Includes parameters that control dispense volume, well location, tip position in a well, and pipette - flow rate. See also, :ref:`new-dispense`. + flow rate. See :ref:`new-dispense`. :param volume: The volume to dispense, measured in µL. If 0 or unspecified, defaults to @@ -270,7 +270,7 @@ def dispense( :param location: Where to dispense liquid held in the pipette. If ``location`` is a :py:class:`.Well`, the pipette will dispense at or above the center bottom of the well. - The distance from the bottom is specified by + The distance from the bottom is specified by :py:obj:`well_bottom_clearance.dispense `. If ``location`` is :py:class:`.Location` (e.g., the result of :py:meth:`.Well.top` or @@ -283,7 +283,7 @@ def dispense( the robot will dispense into the current position. :param rate: How quickly a pipette dispenses liquid. Measured in µL/s. Calculated as `rate` * :py:attr:`flow_rate.dispense `. - If not specified, defaults to 1.0. See also, :ref:`new-plunger-flow-rates`. + If not specified, defaults to 1.0. See :ref:`new-plunger-flow-rates`. :type rate: float :param push_out: Continue past the plunger bottom to help ensure all liquid leaves the tip. Measured in µL. The default value is ``None``. @@ -380,7 +380,7 @@ def mix( ) -> InstrumentContext: """ Mixes a volume of liquid by repeatedly aspirating and dispensing it in a single location. - See also, :ref:`mix`. + See :ref:`mix`. :param repetitions: Number of times to mix (default is 1). :param volume: The volume to mix, measured in µL. If 0 or unspecified, @@ -396,7 +396,7 @@ def mix( ``rate`` * :py:attr:`flow_rate.aspirate `. The dispense flow rate is calculated as ``rate`` * :py:attr:`flow_rate.dispense `. - See also, :ref:`new-plunger-flow-rates`. + See :ref:`new-plunger-flow-rates`. :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette. :returns: This instance. @@ -454,7 +454,7 @@ def blow_out( a small amount of liquid remains in the tip. During a blowout, the pipette moves the plunger beyond its normal limits to help remove all liquid from the pipette tip. - See also, :ref:`blow-out`. + See :ref:`blow-out`. :param location: The blowout location. If no location is specified, the pipette will blow out from its current position. @@ -605,7 +605,7 @@ def air_gap( ) -> InstrumentContext: """ Pull air into the pipette current tip at the current location. - See also, :ref:`air-gap`. + See :ref:`air-gap`. :param volume: The amount of air to aspirate, measured in µL. Calling ``air_gap()`` with no arguments uses @@ -687,7 +687,7 @@ def pick_up_tip( ) -> InstrumentContext: """ Pick up a tip for the pipette to run liquid-handling commands. - See also, :ref:`basic-tip-pickup`. + See :ref:`basic-tip-pickup`. If no location is passed, the pipette will pick up the next available tip in its :py:attr:`InstrumentContext.tip_racks` list. @@ -869,7 +869,7 @@ def drop_tip( home_after: Optional[bool] = None, ) -> InstrumentContext: """ - Drop the current tip. See also, :ref:`pipette-drop-tip`. + Drop the current tip. See :ref:`pipette-drop-tip`. If no location is passed, the pipette will drop the tip into its :py:attr:`trash_container`, which if not specified defaults to @@ -987,7 +987,7 @@ def drop_tip( @requires_version(2, 0) def home(self) -> InstrumentContext: - """Home the robot. See also, :ref:`utility-homing`. + """Home the robot. See :ref:`utility-homing`. :returns: This instance. """ @@ -1395,7 +1395,7 @@ def speed(self) -> "PlungerSpeeds": @property # type: ignore @requires_version(2, 0) def flow_rate(self) -> "FlowRates": - """The speeds (in µL/s) configured for the pipette. See also, :ref:`new-plunger-flow-rates`. + """The speeds (in µL/s) configured for the pipette. See :ref:`new-plunger-flow-rates`. This is an object with attributes ``aspirate``, ``dispense``, and ``blow_out`` holding the flow rates for the corresponding operation. @@ -1438,7 +1438,7 @@ def tip_racks(self) -> List[labware.Labware]: The tip racks that have been linked to this pipette. This is the property used to determine which tips to pick up next when - calling :py:meth:`pick_up_tip` without arguments. See also, :ref:`basic-tip-pickup`. + calling :py:meth:`pick_up_tip` without arguments. See :ref:`basic-tip-pickup`. """ return self._tip_racks @@ -1531,7 +1531,7 @@ def hw_pipette(self) -> PipetteDict: @property # type: ignore @requires_version(2, 0) def channels(self) -> int: - """The number of channels on the pipette. See also, :ref:`new-pipette`.""" + """The number of channels on the pipette. See :ref:`new-pipette`.""" return self._core.get_channels() @property # type: ignore @@ -1597,7 +1597,7 @@ def configure_for_volume(self, volume: float) -> None: and maximum volume. The pipette remains in the mode set by this function until it is called again. The Flex 1-Channel 50 µL and Flex 8-Channel 50 µL pipettes must operate in a low-volume mode to accurately dispense 1 µL of liquid. Low-volume mode can - only be set by calling ``configure_for_volume``. See also, :ref:`pipette-volume-modes`. + only be set by calling ``configure_for_volume``. See :ref:`pipette-volume-modes`. .. note :: From b77c25d73c746d10a299ac9468c806be6677a312 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Fri, 20 Oct 2023 16:38:42 -0400 Subject: [PATCH 32/40] Style code formatting, text, and code sample Single quotes made code italics. Replace with ``code`` to get monospace. Remove * as a multiplication operator. Replace with "multiplied by". Fix code sample in dispense. Run Black check. Looks ok. --- .../opentrons/protocol_api/instrument_context.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index c336a708573..2d007a8183f 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -172,7 +172,7 @@ def aspirate( If unspecified, the robot will aspirate from the current position. :param rate: A multiplier for the default flow rate of the pipette. - Calculated as `rate` * :py:attr:`flow_rate.aspirate `. + Calculated as ``rate`` multiplied by :py:attr:`flow_rate.aspirate `. If not specified, defaults to 1.0. See :ref:`new-plunger-flow-rates`. :type rate: float :returns: This instance. @@ -282,7 +282,7 @@ def dispense( :py:attr:`current_volume`). If unspecified, the robot will dispense into the current position. :param rate: How quickly a pipette dispenses liquid. Measured in µL/s. - Calculated as `rate` * :py:attr:`flow_rate.dispense `. + Calculated as ``rate`` multiplied by :py:attr:`flow_rate.dispense `. If not specified, defaults to 1.0. See :ref:`new-plunger-flow-rates`. :type rate: float :param push_out: Continue past the plunger bottom to help ensure all liquid @@ -297,7 +297,7 @@ def dispense( to guess whether the argument is a volume or location - it is required to be a volume. If you want to call ``dispense`` with only a location, specify it as a keyword argument: - ``instr.dispense(location=wellplate['A1'])`` + ``pipette.dispense(location=plate['A1'])``. """ if self.api_version < APIVersion(2, 15) and push_out: @@ -393,9 +393,9 @@ def mix( :type location: types.Location :param rate: How quickly a pipette aspirates and dispenses liquid while mixing. The aspiration flow rate is calculated as - ``rate`` * :py:attr:`flow_rate.aspirate `. + ``rate`` multiplied by :py:attr:`flow_rate.aspirate `. The dispense flow rate is calculated - as ``rate`` * :py:attr:`flow_rate.dispense `. + as ``rate`` multiplied by :py:attr:`flow_rate.dispense `. See :ref:`new-plunger-flow-rates`. :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette. :returns: This instance. @@ -879,11 +879,11 @@ def drop_tip( in order to prevent tips from piling up in a single location in the trash. The location in which to drop the tip can be manually specified with - the `location` argument. The `location` argument can be specified in + the ``location`` argument. The ``location`` argument can be specified in several ways: - If the only thing to specify is which well into which to drop - a tip, `location` can be a :py:class:`.Well`. For instance, + a tip, ``location`` can be a :py:class:`.Well`. For instance, if you have a tip rack in a variable called ``tiprack``, you can drop a tip into a specific well on that tiprack with the call ``instr.drop_tip(tiprack.wells()[0])``. This style of call can @@ -893,7 +893,7 @@ def drop_tip( for instance to tell the robot to drop a tip from an unusually large height above the tip rack, ``location`` can be a :py:class:`.types.Location`; for instance, you can call - `instr.drop_tip(tiprack.wells()[0].top())`. + ``instr.drop_tip(tiprack.wells()[0].top())``. :param location: The location to drop the tip. From 8fc2d905a63f50b998751a51acdf1a8bb31ce754 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Mon, 23 Oct 2023 16:58:16 -0400 Subject: [PATCH 33/40] Revisions from reviewers part 1 Incorporating reviewer comments. - aspirate - dispense - reset_tipracks - touch_tip - remove (s) - small adjustments Not finished yet. More to come. --- .../protocol_api/instrument_context.py | 80 ++++++++++--------- 1 file changed, 44 insertions(+), 36 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 2d007a8183f..86fc49f0fc4 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -124,7 +124,7 @@ def starting_tip(self, location: Union[labware.Well, None]) -> None: @requires_version(2, 0) def reset_tipracks(self) -> None: - """Reloads all tips in each tip rack and resets the starting tip.""" + """Reload all tips in each tip rack and reset the starting tip.""" for tiprack in self.tip_racks: tiprack.reset() self.starting_tip = None @@ -155,22 +155,24 @@ def aspirate( ) -> InstrumentContext: """ Draw liquid into a pipette tip. Includes parameters that control - aspiration volume, well location, tip position in a well, - and pipette flow rate. See :ref:`new-aspirate`. + aspiration volume, well location, tip position in a well,and pipette flow rate. + See :ref:`new-aspirate`. :param volume: The volume to aspirate, measured in µL. If 0 or unspecified, defaults to the maximum volume for the pipette and its currently attached tip. :type volume: int or float - :param location: Where to aspirate from. If `location` is a - :py:class:`.Well`, the robot will aspirate from - :py:obj:`well_bottom_clearance.aspirate ` - mm above the bottom of the well. If `location` is a - :py:class:`.Location` (i.e. the result of - :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the - robot will aspirate from the exact specified location. - If unspecified, the robot will aspirate from the - current position. + :param location: Tells the robot where to aspirate from. The location can be a + :py:class:`.Well` or a :py:class:`.Location`. + + - If the location is a ``well``, the robot will aspirate at or above + the center of the bottom of the well. The distance (in mm) from the + well bottom is specified by the :py:obj:`well_bottom_clearance.aspirate` object. + + - If the location is a ``location`` (e.g., the result of :py:meth:`.Well.top` + or :py:meth:`.Well.bottom`), the robot will aspirate from that specified position. + + - If the ``location is unspecified, the robot will aspirate from its current position. :param rate: A multiplier for the default flow rate of the pipette. Calculated as ``rate`` multiplied by :py:attr:`flow_rate.aspirate `. If not specified, defaults to 1.0. See :ref:`new-plunger-flow-rates`. @@ -183,7 +185,7 @@ def aspirate( to guess whether the argument is a volume or location - it is required to be a volume. If you want to call ``aspirate`` with only a location, specify it as a keyword argument: - ``instr.aspirate(location=wellplate['A1'])`` + ``pipette.aspirate(location=plate['A1'])`` """ _log.debug( @@ -267,20 +269,24 @@ def dispense( will dispense from its current position. :type volume: int or float - :param location: Where to dispense liquid held in the pipette. - If ``location`` is a :py:class:`.Well`, - the pipette will dispense at or above the center bottom of the well. - The distance from the bottom is specified by - :py:obj:`well_bottom_clearance.dispense `. - If ``location`` is :py:class:`.Location` - (e.g., the result of :py:meth:`.Well.top` or - :py:meth:`.Well.bottom`), the robot will dispense into - the specified position. If only a ``location`` is passed - (e.g., ``instr.dispense(location=wellplate['A1'])``), - all of the liquid aspirated into the pipette - will be dispensed (amount is accessible through - :py:attr:`current_volume`). If unspecified, - the robot will dispense into the current position. + :param location: Tells the robot where to dispense liquid held in the pipette. + The location can be a :py:class:`.Well` or a + :py:class:`.Location`. + + - If the location is a ``well``, the pipette will dispense at or above + the center of the bottom of the well. The distance from the well bottom + (in mm) is specified by the :py:obj:`well_bottom_clearance.dispense ` + object. + + - If the location is a ``location`` (e.g., the result of :py:meth:`.Well.top` or + :py:meth:`.Well.bottom`), the robot will dispense into the specified position. + + - If only a ``location`` is passed (e.g., ``(location=plate['A1'])``), + all of the liquid aspirated into the pipette will be dispensed + (the amount is accessible through :py:attr:`current_volume`). + + - If the ``location`` remains unspecified, the robot will dispense into its + current position. :param rate: How quickly a pipette dispenses liquid. Measured in µL/s. Calculated as ``rate`` multiplied by :py:attr:`flow_rate.dispense `. If not specified, defaults to 1.0. See :ref:`new-plunger-flow-rates`. @@ -390,7 +396,6 @@ def mix( (e.g, ``plate.rows()[0][0].bottom()``). If unspecified, the pipette will mix from its current position. - :type location: types.Location :param rate: How quickly a pipette aspirates and dispenses liquid while mixing. The aspiration flow rate is calculated as ``rate`` multiplied by :py:attr:`flow_rate.aspirate `. @@ -525,7 +530,7 @@ def touch_tip( Touch the pipette tip to the sides of a well, with the intent of removing leftover droplets. See also :ref:`touch-tip`. - :param location: If no location is passed, pipette will + :param location: If no location is passed, the pipette will touch tip at current well's edges. :type location: :py:class:`.Well` or None :param radius: Describes the proportion of the target well's @@ -533,13 +538,16 @@ def touch_tip( the edge of the target well. When `radius=0.5`, it will move to 50% of the well's radius. Default: 1.0 (100%) :type radius: float - :param v_offset: The offset in mm from the top of the well to touch tip. + :param v_offset: How far above or below the well to touch the tip, measured in mm. A positive offset moves the tip higher above the well. A negative offset moves the tip lower into the well. Default is -1.0 mm. :type v_offset: float :param speed: The speed for touch tip motion, in mm/s. - Default: 60.0 mm/s, Max: 80.0 mm/s, Min: 1.0 mm/s. + + - Default: 60.0 mm/s + - Max: 80.0 mm/s + - Min: 1.0 mm/s :type speed: float :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette :raises RuntimeError: If no location is specified and location cache is @@ -690,23 +698,23 @@ def pick_up_tip( See :ref:`basic-tip-pickup`. If no location is passed, the pipette will pick up the next available - tip in its :py:attr:`InstrumentContext.tip_racks` list. + tip in its :py:attr:`~.InstrumentContext.tip_racks` list. Within each tip rack, tips will be picked up in the order specified by the labware definition and :py:meth:`.Labware.wells`. To adjust where the sequence starts, see :py:obj:`.starting_tip`. - The tip to pick up can be manually specified with the `location` - argument. The `location` argument can be specified in several ways: + The tip to pick up can be manually specified with the ``location`` + argument. The ``location`` argument can be specified in several ways: * If the only thing to specify is which well from which to pick - up a tip, `location` can be a :py:class:`.Well`. For instance, + up a tip, ``location`` can be a :py:class:`.Well`. For instance, if you have a tip rack in a variable called `tiprack`, you can pick up a specific tip from it with ``instr.pick_up_tip(tiprack.wells()[0])``. This style of call can be used to make the robot pick up a tip from a tip rack that was not specified when creating the :py:class:`.InstrumentContext`. - * If you want to pick up the next available tip(s) in a specific + * If you want to pick up the next available tip in a specific tip rack, you may use the tip rack directly (e.g. ``instr.pick_up_tip(tiprack)``). From 8d90e617b07cdf9941769d8628f7001f69ae2058 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 24 Oct 2023 14:42:03 -0400 Subject: [PATCH 34/40] Revisions from comments - Replace (text only) "tiprack" with "tip rack" - Fix single quotes around code elements. Replace with double single quotes (`not this`, but ``this instead``). Rendered text in italics. - drop_tip revisions - mount revisions, add "left" and "right" - min_volume revision, add definition - configure_for_volume changes --- .../protocol_api/instrument_context.py | 102 +++++++++--------- 1 file changed, 54 insertions(+), 48 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 86fc49f0fc4..588ba2f7c11 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -491,7 +491,7 @@ def blow_out( if isinstance(target, validation.WellTarget): if target.well.parent.is_tiprack: _log.warning( - "Blow_out being performed on a tiprack. " + "Blow_out being performed on a tip rack. " "Please re-check your code" ) move_to_location = target.location or target.well.top() @@ -589,7 +589,7 @@ def touch_tip( return self if parent_labware.is_tiprack: _log.warning( - "Touch_tip being performed on a tiprack. Please re-check your code" + "Touch_tip being performed on a tip rack. Please re-check your code" ) if self.api_version < APIVersion(2, 4): @@ -708,7 +708,7 @@ def pick_up_tip( * If the only thing to specify is which well from which to pick up a tip, ``location`` can be a :py:class:`.Well`. For instance, - if you have a tip rack in a variable called `tiprack`, you can + if you have a tip rack in a variable called ``tiprack``, you can pick up a specific tip from it with ``instr.pick_up_tip(tiprack.wells()[0])``. This style of call can be used to make the robot pick up a tip from a tip rack that @@ -721,7 +721,7 @@ def pick_up_tip( * If the position to move to in the well needs to be specified, for instance to tell the robot to run its pick up tip routine starting closer to or farther from the top of the tip, - `location` can be a :py:class:`.types.Location`; for instance, + ``location`` can be a :py:class:`.types.Location`; for instance, you can call ``instr.pick_up_tip(tiprack.wells()[0].top())``. :param location: The location from which to pick up a tip. @@ -737,7 +737,7 @@ def pick_up_tip( Use the Opentrons App to change pipette pick-up settings. :type presses: int :param increment: The additional distance to travel on each successive - press (e.g.: if `presses=3` and `increment=1.0`, then + press (e.g.: if ``presses=3`` and ``increment=1.0``, then the first press will travel down into the tip by 3.5mm, the second by 4.5mm, and the third by 5.5mm). @@ -879,71 +879,69 @@ def drop_tip( """ Drop the current tip. See :ref:`pipette-drop-tip`. - If no location is passed, the pipette will drop the tip into its - :py:attr:`trash_container`, which if not specified defaults to - the fixed trash in slot 12. From API version 2.15 on, if the trash container is - the default fixed trash in A3 (slot 12), the API will default to - dropping tips in different points within the trash container - in order to prevent tips from piling up in a single location in the trash. + If no location is passed (e.g. ``pipette.drop_tip()``), the pipette will drop the + attached tip into its default :py:attr:`trash_container`. For the Flex and OT-2 the + default slots for their in-deck trash containers are A3 and 12, respectively. + + Starting with API version 2.15, if the trash container is the default fixed trash, + the API will instruct the pipettes to drop their tips in different locations within + the trash container. Varying the tip drop location helps prevent tips from piling up + in a single location in the trash. The location in which to drop the tip can be manually specified with the ``location`` argument. The ``location`` argument can be specified in several ways: - - If the only thing to specify is which well into which to drop + - If the only thing to specify is the well into which to drop a tip, ``location`` can be a :py:class:`.Well`. For instance, if you have a tip rack in a variable called ``tiprack``, you can - drop a tip into a specific well on that tiprack with the call + drop a tip into a specific well on that tip rack with the call ``instr.drop_tip(tiprack.wells()[0])``. This style of call can - be used to make the robot drop a tip into arbitrary labware. - - If the position to drop the tip from as well as the - :py:class:`.Well` to drop the tip into needs to be specified, - for instance to tell the robot to drop a tip from an unusually - large height above the tip rack, ``location`` - can be a :py:class:`.types.Location`; for instance, you can call - ``instr.drop_tip(tiprack.wells()[0].top())``. + be used to make the robot drop a tip into labware like a well plate or + a reservoir. + - If the drop position and :py:class:`.Well` to drop the tip into needs to be + specified, for instance to tell the robot to drop a tip from an unusually + large height above the tip rack, ``location`` can be a :py:class:`.types.Location`. + For instance, you can call ``instr.drop_tip(tiprack.wells()[0].top())``. :param location: The location to drop the tip. :type location: :py:class:`.types.Location` or :py:class:`.Well` or ``None`` :param home_after: - Whether to home this pipette's plunger after dropping the tip. + Whether to home the pipette's plunger after dropping the tip. If not specified, defaults to ``True`` on an OT-2. - Setting ``home_after=False`` saves waiting a couple of seconds - after the pipette drops the tip, but risks causing other problems. - - .. warning:: - Only set ``home_after=False`` if: + When ``home_after=False``, the pipette does not home its plunger. This can + save a few seconds, but may cause other problems. For example, you should only + set ``home_after=False`` if: * You're using a GEN2 pipette, not a GEN1 pipette. - * You've tested ``home_after=False`` extensively with your - pipette and tips. - * You understand the risks described below. + * You've tested this parameter with your pipette and tips. + * You understand the risks described below. - The ejector that pops the tip off the end of the pipette is + The ejector that pushes the tip off the end of the pipette is driven by the plunger's stepper motor. Sometimes, the strain of ejecting the tip can make that motor skip and fall out of sync with where the robot thinks it is. - Homing the plunger fixes this, so, to be safe, we normally do it - after every tip drop. + GEN1 pipettes are especially vulnerable to this location sync problem. + You should never set ``home_after=False`` when using a GEN1 pipette. + + GEN2 pipettes can be affected by this the location sync problem, but less + frequently than GEN1 pipettes. As a best practice, always test your GEN2 pipette + with ``home_after=False`` before running your protocol. If you set ``home_after=False`` to disable homing the plunger, and - the motor happens to skip, you might see problems like these until - the next time the plunger is homed: + the motor happens to skip, you might encounter problems similar to these listed + below: * The run might halt with a "hard limit" error message. * The pipette might aspirate or dispense the wrong volumes. * The pipette might not fully drop subsequent tips. - GEN1 pipettes are especially vulnerable to this skipping, so you - should never set ``home_after=False`` with a GEN1 pipette. - - Even on GEN2 pipettes, the motor can still skip. So, always - extensively test ``home_after=False`` with your particular pipette - and your particular tips before relying on it. + Homing the plunger fixes this motor skipping/location synchronization problem. + As a safety procedure, the robot normally homes the plunger after every tip drop. :returns: This instance. """ @@ -1357,7 +1355,10 @@ def move_to( @property # type: ignore @requires_version(2, 0) def mount(self) -> str: - """Return the name of the mount this pipette is attached to.""" + """ + Return the name of the mount the pipette is attached to. The names are + ``left`` and ``right``. + """ return self._core.get_mount().name.lower() @property # type: ignore @@ -1488,6 +1489,9 @@ def model(self) -> str: @property # type: ignore @requires_version(2, 0) def min_volume(self) -> float: + """ + The minimum volume, in µL, that the pipette can hold. + """ return self._core.get_min_volume() @property # type: ignore @@ -1545,7 +1549,7 @@ def channels(self) -> int: @property # type: ignore @requires_version(2, 2) def return_height(self) -> float: - """The height to return a tip to its tiprack. + """The height to return a tip to its tip rack. :returns: A scaling factor to apply to the tip length. During a drop tip, this factor will be multiplied by the tip length @@ -1599,12 +1603,14 @@ def __str__(self) -> str: @requires_version(2, 15) def configure_for_volume(self, volume: float) -> None: - """Configure a pipette to handle a specific volume of liquid, measured in µL. Depending on the volume, the pipette will enter a unique pipetting mode. - Changing pipette modes alters properties of the instance of - :py:class:`.InstrumentContext`, such as default flow rate, minimum volume, - and maximum volume. The pipette remains in the mode set by this function until it is called again. - - The Flex 1-Channel 50 µL and Flex 8-Channel 50 µL pipettes must operate in a low-volume mode to accurately dispense 1 µL of liquid. Low-volume mode can + """Configure a pipette to handle a specific volume of liquid, measured in µL. + The pipette enters a volume mode depending on the volume provided. Changing pipette + modes alters properties of the instance of :py:class:`.InstrumentContext`, + such as default flow rate, minimum volume, and maximum volume. The pipette remains + in the mode set by this function until it is called again. + + The Flex 1-Channel 50 µL and Flex 8-Channel 50 µL pipettes must operate in a + low-volume mode to accurately dispense 1 µL of liquid. Low-volume mode can only be set by calling ``configure_for_volume``. See :ref:`pipette-volume-modes`. .. note :: From 9f029f95717775269c1f99898d6a98c135379c6c Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 24 Oct 2023 14:43:56 -0400 Subject: [PATCH 35/40] Fogot to save recent and run Black --- .../opentrons/protocol_api/instrument_context.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 588ba2f7c11..d8069211e9b 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -612,17 +612,16 @@ def air_gap( self, volume: Optional[float] = None, height: Optional[float] = None ) -> InstrumentContext: """ - Pull air into the pipette current tip at the current location. - See :ref:`air-gap`. + Draw air into the pipette's tip at the current location. See :ref:`air-gap`. - :param volume: The amount of air to aspirate, measured in µL. + :param volume: The amount of air to draw, measured in µL. Calling ``air_gap()`` with no arguments uses the entire remaining volume in the pipette. :type volume: float :param height: The height, in mm, to move above the current well - before aspirating air. The default is 5 mm above current well. + before creating the air gap. The default is 5 mm above current well. :type height: float @@ -882,7 +881,7 @@ def drop_tip( If no location is passed (e.g. ``pipette.drop_tip()``), the pipette will drop the attached tip into its default :py:attr:`trash_container`. For the Flex and OT-2 the default slots for their in-deck trash containers are A3 and 12, respectively. - + Starting with API version 2.15, if the trash container is the default fixed trash, the API will instruct the pipettes to drop their tips in different locations within the trash container. Varying the tip drop location helps prevent tips from piling up @@ -918,7 +917,7 @@ def drop_tip( * You're using a GEN2 pipette, not a GEN1 pipette. * You've tested this parameter with your pipette and tips. - * You understand the risks described below. + * You understand the risks described below. The ejector that pushes the tip off the end of the pipette is driven by the plunger's stepper motor. Sometimes, the strain of @@ -1490,7 +1489,7 @@ def model(self) -> str: @requires_version(2, 0) def min_volume(self) -> float: """ - The minimum volume, in µL, that the pipette can hold. + The minimum volume, in µL, that the pipette can hold. """ return self._core.get_min_volume() From 77faa569648056db87bf3ef1a209b2b0e0c6b21a Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Tue, 24 Oct 2023 14:56:54 -0400 Subject: [PATCH 36/40] Fix code snippet in touch_tip Another instance of italics instead of monospace. --- api/src/opentrons/protocol_api/instrument_context.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index d8069211e9b..cd3b629d10c 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -534,8 +534,8 @@ def touch_tip( touch tip at current well's edges. :type location: :py:class:`.Well` or None :param radius: Describes the proportion of the target well's - radius. When `radius=1.0`, the pipette tip will move to - the edge of the target well. When `radius=0.5`, it will + radius. When ``radius=1.0``, the pipette tip will move to + the edge of the target well. When ``radius=0.5``, it will move to 50% of the well's radius. Default: 1.0 (100%) :type radius: float :param v_offset: How far above or below the well to touch the tip, measured in mm. @@ -551,7 +551,7 @@ def touch_tip( :type speed: float :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette :raises RuntimeError: If no location is specified and location cache is - None. This should happen if `touch_tip` is called + None. This should happen if ``touch_tip`` is called without first calling a method that takes a location (e.g., :py:meth:`.aspirate`, :py:meth:`dispense`) From 1d06051d40d41bb977f495196015b72d7ea09424 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 25 Oct 2023 11:59:32 -0400 Subject: [PATCH 37/40] Everything but the intro --- .../protocol_api/instrument_context.py | 82 +++++++------------ 1 file changed, 28 insertions(+), 54 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index cd3b629d10c..c18559f2788 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -172,7 +172,7 @@ def aspirate( - If the location is a ``location`` (e.g., the result of :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the robot will aspirate from that specified position. - - If the ``location is unspecified, the robot will aspirate from its current position. + - If the ``location`` is unspecified, the robot will aspirate from its current position. :param rate: A multiplier for the default flow rate of the pipette. Calculated as ``rate`` multiplied by :py:attr:`flow_rate.aspirate `. If not specified, defaults to 1.0. See :ref:`new-plunger-flow-rates`. @@ -285,7 +285,7 @@ def dispense( all of the liquid aspirated into the pipette will be dispensed (the amount is accessible through :py:attr:`current_volume`). - - If the ``location`` remains unspecified, the robot will dispense into its + - If the ``location`` is unspecified, the robot will dispense into its current position. :param rate: How quickly a pipette dispenses liquid. Measured in µL/s. Calculated as ``rate`` multiplied by :py:attr:`flow_rate.dispense `. @@ -614,7 +614,7 @@ def air_gap( """ Draw air into the pipette's tip at the current location. See :ref:`air-gap`. - :param volume: The amount of air to draw, measured in µL. + :param volume: The ``air_gap``, measured in µL. Calling ``air_gap()`` with no arguments uses the entire remaining volume in the pipette. :type volume: float @@ -628,7 +628,7 @@ def air_gap( :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette :raises RuntimeError: If location cache is None. - This should happen if `touch_tip` is called + This should happen if ``touch_tip`` is called without first calling a method that takes a location (e.g., :py:meth:`.aspirate`, :py:meth:`dispense`) @@ -669,8 +669,7 @@ def return_tip(self, home_after: Optional[bool] = None) -> InstrumentContext: :returns: This instance. - :param home_after: - See the ``home_after`` parameter of :py:obj:`drop_tip`. + :param home_after: See the ``home_after`` parameter of :py:obj:`drop_tip`. """ if not self._core.has_tip(): _log.warning("Pipette has no tip to return") @@ -705,13 +704,11 @@ def pick_up_tip( The tip to pick up can be manually specified with the ``location`` argument. The ``location`` argument can be specified in several ways: - * If the only thing to specify is which well from which to pick - up a tip, ``location`` can be a :py:class:`.Well`. For instance, - if you have a tip rack in a variable called ``tiprack``, you can - pick up a specific tip from it with - ``instr.pick_up_tip(tiprack.wells()[0])``. This style of call can - be used to make the robot pick up a tip from a tip rack that - was not specified when creating the :py:class:`.InstrumentContext`. + * If the only thing to specify is which well from which to pick up a tip, ``location`` + can be a :py:class:`.Well`. For instance, if you have a tip rack in a variable + called ``tiprack``, you can pick up a specific tip from it with + ``instr.pick_up_tip(tiprack.wells()[0])``. You can use this style of call to + pick up a tip from a rack that is not a member of :py:obj:`.InstrumentContext.tip_racks`. * If you want to pick up the next available tip in a specific tip rack, you may use the tip rack directly @@ -724,10 +721,9 @@ def pick_up_tip( you can call ``instr.pick_up_tip(tiprack.wells()[0].top())``. :param location: The location from which to pick up a tip. - :type location: :py:class:`.types.Location` or :py:class:`.Well` to - pick up a tip from. + :type location: :py:class:`.types.Location` or :py:class:`.Well` :param presses: The number of times to lower and then raise the pipette - when picking up a tip, to ensure a good seal (0 [zero] + when picking up a tip, to ensure a good seal. Zero (``0``) will result in the pipette hovering over the tip but not picking it up--generally not desirable, but could be used for dry-run). @@ -738,7 +734,7 @@ def pick_up_tip( :param increment: The additional distance to travel on each successive press (e.g.: if ``presses=3`` and ``increment=1.0``, then the first press will travel down into the tip by - 3.5mm, the second by 4.5mm, and the third by 5.5mm). + 3.5 mm, the second by 4.5 mm, and the third by 5.5 mm). .. deprecated:: 2.14 Use the Opentrons App to change pipette pick-up settings. @@ -885,7 +881,7 @@ def drop_tip( Starting with API version 2.15, if the trash container is the default fixed trash, the API will instruct the pipettes to drop their tips in different locations within the trash container. Varying the tip drop location helps prevent tips from piling up - in a single location in the trash. + in a single location. The location in which to drop the tip can be manually specified with the ``location`` argument. The ``location`` argument can be specified in @@ -912,35 +908,8 @@ def drop_tip( If not specified, defaults to ``True`` on an OT-2. When ``home_after=False``, the pipette does not home its plunger. This can - save a few seconds, but may cause other problems. For example, you should only - set ``home_after=False`` if: - - * You're using a GEN2 pipette, not a GEN1 pipette. - * You've tested this parameter with your pipette and tips. - * You understand the risks described below. - - The ejector that pushes the tip off the end of the pipette is - driven by the plunger's stepper motor. Sometimes, the strain of - ejecting the tip can make that motor skip and fall out of sync - with where the robot thinks it is. - - GEN1 pipettes are especially vulnerable to this location sync problem. - You should never set ``home_after=False`` when using a GEN1 pipette. - - GEN2 pipettes can be affected by this the location sync problem, but less - frequently than GEN1 pipettes. As a best practice, always test your GEN2 pipette - with ``home_after=False`` before running your protocol. - - If you set ``home_after=False`` to disable homing the plunger, and - the motor happens to skip, you might encounter problems similar to these listed - below: - - * The run might halt with a "hard limit" error message. - * The pipette might aspirate or dispense the wrong volumes. - * The pipette might not fully drop subsequent tips. - - Homing the plunger fixes this motor skipping/location synchronization problem. - As a safety procedure, the robot normally homes the plunger after every tip drop. + save a few seconds, but is not recommended. Homing helps the robot track the + pipette's position. :returns: This instance. """ @@ -1403,7 +1372,7 @@ def speed(self) -> "PlungerSpeeds": @property # type: ignore @requires_version(2, 0) def flow_rate(self) -> "FlowRates": - """The speeds (in µL/s) configured for the pipette. See :ref:`new-plunger-flow-rates`. + """The speeds, in µL/s, configured for the pipette. See :ref:`new-plunger-flow-rates`. This is an object with attributes ``aspirate``, ``dispense``, and ``blow_out`` holding the flow rates for the corresponding operation. @@ -1418,7 +1387,7 @@ def flow_rate(self) -> "FlowRates": same values, setting one will override the other. For instance, to change the flow rate for aspiration on an instrument - you would do + you would do: .. code-block :: python @@ -1489,7 +1458,9 @@ def model(self) -> str: @requires_version(2, 0) def min_volume(self) -> float: """ - The minimum volume, in µL, that the pipette can hold. + The minimum volume, in µL, that the pipette can hold. This value may change + based on the :ref:`volume mode ` that the pipette + is currently configured for. """ return self._core.get_min_volume() @@ -1534,7 +1505,7 @@ def _has_tip(self) -> bool: def hw_pipette(self) -> PipetteDict: """View the information returned by the hardware API directly. - :raises: a :py:class:`.types.PipetteNotAttachedError` if the pipette is + :raises: :py:class:`.types.PipetteNotAttachedError` if the pipette is no longer attached (should not happen). """ return self._core.get_hardware_state() @@ -1570,7 +1541,7 @@ def well_bottom_clearance(self) -> "Clearances": will move this distance above the bottom of the well to aspirate or dispense. - To change, set the corresponding attribute. For instance, + To change, set the corresponding attribute. For instance: .. code-block:: python @@ -1616,9 +1587,12 @@ def configure_for_volume(self, volume: float) -> None: Changing a pipette's mode will reset its :ref:`flow rate `. - This function will raise an error if called when the pipette's tip contains liquid. It won't raise an error if a tip is not attached, but changing modes may affect which tips the pipette can subsequently pick up without raising an error. + This function will raise an error if called when the pipette's tip contains liquid. + It won't raise an error if a tip is not attached, but changing modes may affect which + tips the pipette can subsequently pick up without raising an error. - This function will also raise an error if ``volume`` is outside of the :ref:`minimum and maximum capacities ` of the pipette (e.g., setting ``volume=1`` for a Flex 1000 µL pipette). + This function will also raise an error if ``volume`` is outside of the :ref:`minimum + and maximum capacities ` of the pipette (e.g., setting ``volume=1`` for a Flex 1000 µL pipette). :param volume: The volume, in µL, that the pipette will prepare to handle. :type volume: float From fa6d0e81df28ac968f11a90067c0a67ff03543b3 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Wed, 25 Oct 2023 14:16:04 -0400 Subject: [PATCH 38/40] Revised intro --- .../protocol_api/instrument_context.py | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index c18559f2788..6c0eed8f5e9 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -55,18 +55,17 @@ class InstrumentContext(publisher.CommandPublisher): - """A context for a specific pipette or instrument. - - This can be used to call methods related to pipettes - moves or - aspirates or dispenses, or higher-level methods. + """ + The InstrumentContext class in the Opentrons Python API (PAPI) provides the objects, + attributes, and methods that allow you to use pipettes and other instruments in your + protocols. Similar to other class containers, InstrumentContext is temporary. + Class objects only exist when instantiated in your Python protocol. - Instances of this class bundle up state and config changes to a - pipette - for instance, changes to flow rates or trash containers. - Action methods (like :py:meth:`aspirate` or :py:meth:`distribute`) are - defined here for convenience. + This class also includes action methods (e.g., ``aspirate()`` and ``distribute()``). + We’ve included and defined many of these here for convenience. - In general, this class should not be instantiated directly; rather, - instances are returned from :py:meth:`ProtocolContext.load_instrument`. + Finally, objects in this class should not be instantiated directly. Instead, + instances are returned by :py:meth:`ProtocolContext.load_instrument`. .. versionadded:: 2.0 From 3f1c36a03b0a0992b74bf042e7f20360d1581717 Mon Sep 17 00:00:00 2001 From: Ed Cormany Date: Thu, 26 Oct 2023 15:40:09 -0400 Subject: [PATCH 39/40] batch of changes from final review --- .../protocol_api/instrument_context.py | 85 +++++++++++-------- 1 file changed, 51 insertions(+), 34 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 6c0eed8f5e9..0604eb759a5 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -56,10 +56,15 @@ class InstrumentContext(publisher.CommandPublisher): """ - The InstrumentContext class in the Opentrons Python API (PAPI) provides the objects, - attributes, and methods that allow you to use pipettes and other instruments in your - protocols. Similar to other class containers, InstrumentContext is temporary. - Class objects only exist when instantiated in your Python protocol. + The InstrumentContext class provides the objects, + attributes, and methods that allow you to use pipettes in your protocols. + + Methods generally fall into one of two categories. + + - They can change the state of the InstrumentContext object, such as how fast + it moves liquid or where it disposes of used tips). + - They can command the instrument to perform an action, like picking up tips, moving + to certain locations, and aspirating or dispensing liquid. This class also includes action methods (e.g., ``aspirate()`` and ``distribute()``). We’ve included and defined many of these here for convenience. @@ -153,9 +158,9 @@ def aspirate( rate: float = 1.0, ) -> InstrumentContext: """ - Draw liquid into a pipette tip. Includes parameters that control - aspiration volume, well location, tip position in a well,and pipette flow rate. - See :ref:`new-aspirate`. + Draw liquid into a pipette tip. + + See :ref:`new-aspirate` for more details and examples. :param volume: The volume to aspirate, measured in µL. If 0 or unspecified, defaults to the maximum volume for @@ -164,11 +169,11 @@ def aspirate( :param location: Tells the robot where to aspirate from. The location can be a :py:class:`.Well` or a :py:class:`.Location`. - - If the location is a ``well``, the robot will aspirate at or above - the center of the bottom of the well. The distance (in mm) from the - well bottom is specified by the :py:obj:`well_bottom_clearance.aspirate` object. + - If the location is a ``Well``, the robot will aspirate at or above + the bottom center of the well. The distance (in mm) from the + well bottom is specified by :py:obj:`well_bottom_clearance.aspirate`. - - If the location is a ``location`` (e.g., the result of :py:meth:`.Well.top` + - If the location is a ``Location`` (e.g., the result of :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the robot will aspirate from that specified position. - If the ``location`` is unspecified, the robot will aspirate from its current position. @@ -257,9 +262,9 @@ def dispense( push_out: Optional[float] = None, ) -> InstrumentContext: """ - Dispense liquid from a pipette tip. Includes parameters that control - dispense volume, well location, tip position in a well, and pipette - flow rate. See :ref:`new-dispense`. + Dispense liquid from a pipette tip. + + See :ref:`new-dispense` for more details and examples. :param volume: The volume to dispense, measured in µL. If 0 or unspecified, defaults to @@ -278,7 +283,7 @@ def dispense( object. - If the location is a ``location`` (e.g., the result of :py:meth:`.Well.top` or - :py:meth:`.Well.bottom`), the robot will dispense into the specified position. + :py:meth:`.Well.bottom`), the robot will dispense into the specified position. - If only a ``location`` is passed (e.g., ``(location=plate['A1'])``), all of the liquid aspirated into the pipette will be dispensed @@ -384,7 +389,8 @@ def mix( rate: float = 1.0, ) -> InstrumentContext: """ - Mixes a volume of liquid by repeatedly aspirating and dispensing it in a single location. + Mix a volume of liquid by repeatedly aspirating and dispensing it in a single location. + See :ref:`mix`. :param repetitions: Number of times to mix (default is 1). @@ -452,7 +458,7 @@ def blow_out( self, location: Optional[Union[types.Location, labware.Well]] = None ) -> InstrumentContext: """ - Blows an extra amount of air through a pipette's tip to clear it. + Blow an extra amount of air through a pipette's tip to clear it. If :py:attr:`dispense` is used to empty a pipette, usually a small amount of liquid remains in the tip. During @@ -465,7 +471,7 @@ def blow_out( :type location: :py:class:`.Well` or :py:class:`.Location` or None :raises RuntimeError: If no location is specified and location cache is - None. This should happen if ``blow_out`` is called + ``None``. This should happen if ``blow_out`` is called without first calling a method that takes a location (e.g., :py:meth:`.aspirate`, :py:meth:`dispense`) @@ -490,7 +496,7 @@ def blow_out( if isinstance(target, validation.WellTarget): if target.well.parent.is_tiprack: _log.warning( - "Blow_out being performed on a tip rack. " + "Blow_out being performed on a tiprack. " "Please re-check your code" ) move_to_location = target.location or target.well.top() @@ -545,12 +551,12 @@ def touch_tip( :param speed: The speed for touch tip motion, in mm/s. - Default: 60.0 mm/s - - Max: 80.0 mm/s - - Min: 1.0 mm/s + - Maximum: 80.0 mm/s + - Minimum: 1.0 mm/s :type speed: float :raises: ``UnexpectedTipRemovalError`` -- if no tip is attached to the pipette :raises RuntimeError: If no location is specified and location cache is - None. This should happen if ``touch_tip`` is called + ``None``. This should happen if ``touch_tip`` is called without first calling a method that takes a location (e.g., :py:meth:`.aspirate`, :py:meth:`dispense`) @@ -588,7 +594,7 @@ def touch_tip( return self if parent_labware.is_tiprack: _log.warning( - "Touch_tip being performed on a tip rack. Please re-check your code" + "Touch_tip being performed on a tiprack. Please re-check your code" ) if self.api_version < APIVersion(2, 4): @@ -611,9 +617,11 @@ def air_gap( self, volume: Optional[float] = None, height: Optional[float] = None ) -> InstrumentContext: """ - Draw air into the pipette's tip at the current location. See :ref:`air-gap`. + Draw air into the pipette's tip at the current well. + + See :ref:`air-gap`. - :param volume: The ``air_gap``, measured in µL. + :param volume: The amount of air, measured in µL. Calling ``air_gap()`` with no arguments uses the entire remaining volume in the pipette. :type volume: float @@ -871,11 +879,13 @@ def drop_tip( home_after: Optional[bool] = None, ) -> InstrumentContext: """ - Drop the current tip. See :ref:`pipette-drop-tip`. + Drop the current tip. + + See :ref:`pipette-drop-tip`. If no location is passed (e.g. ``pipette.drop_tip()``), the pipette will drop the attached tip into its default :py:attr:`trash_container`. For the Flex and OT-2 the - default slots for their in-deck trash containers are A3 and 12, respectively. + default slots for their trash containers are A3 and 12, respectively. Starting with API version 2.15, if the trash container is the default fixed trash, the API will instruct the pipettes to drop their tips in different locations within @@ -960,7 +970,9 @@ def drop_tip( @requires_version(2, 0) def home(self) -> InstrumentContext: - """Home the robot. See :ref:`utility-homing`. + """Home the robot. + + See :ref:`utility-homing`. :returns: This instance. """ @@ -1323,8 +1335,9 @@ def move_to( @requires_version(2, 0) def mount(self) -> str: """ - Return the name of the mount the pipette is attached to. The names are - ``left`` and ``right``. + Return the name of the mount the pipette is attached to. + + The possible names are ``left`` and ``right``. """ return self._core.get_mount().name.lower() @@ -1371,7 +1384,9 @@ def speed(self) -> "PlungerSpeeds": @property # type: ignore @requires_version(2, 0) def flow_rate(self) -> "FlowRates": - """The speeds, in µL/s, configured for the pipette. See :ref:`new-plunger-flow-rates`. + """The speeds, in µL/s, configured for the pipette. + + See :ref:`new-plunger-flow-rates`. This is an object with attributes ``aspirate``, ``dispense``, and ``blow_out`` holding the flow rates for the corresponding operation. @@ -1441,7 +1456,7 @@ def trash_container(self, trash: labware.Labware) -> None: @requires_version(2, 0) def name(self) -> str: """ - The name string for the pipette (e.g., ``p300_single``). + The name string for the pipette (e.g., ``"p300_single"``). """ return self._core.get_pipette_name() @@ -1512,7 +1527,9 @@ def hw_pipette(self) -> PipetteDict: @property # type: ignore @requires_version(2, 0) def channels(self) -> int: - """The number of channels on the pipette. See :ref:`new-pipette`.""" + """The number of channels on the pipette. + + See :ref:`new-pipette`.""" return self._core.get_channels() @property # type: ignore @@ -1584,7 +1601,7 @@ def configure_for_volume(self, volume: float) -> None: .. note :: - Changing a pipette's mode will reset its :ref:`flow rate `. + Changing a pipette's mode will reset its :ref:`flow rates `. This function will raise an error if called when the pipette's tip contains liquid. It won't raise an error if a tip is not attached, but changing modes may affect which From b7577721bbd29d9c3c6f3399422a67ecca5fa929 Mon Sep 17 00:00:00 2001 From: Joe Wojak Date: Thu, 26 Oct 2023 16:35:09 -0400 Subject: [PATCH 40/40] Restore intro sentence to line 58 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit and run Black. All done! ✨ 🍰 ✨ 1 file reformatted. --- .../protocol_api/instrument_context.py | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 0604eb759a5..aa02a21b780 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -55,16 +55,17 @@ class InstrumentContext(publisher.CommandPublisher): - """ + """A context for a specific pipette or instrument. + The InstrumentContext class provides the objects, - attributes, and methods that allow you to use pipettes in your protocols. - - Methods generally fall into one of two categories. - - - They can change the state of the InstrumentContext object, such as how fast - it moves liquid or where it disposes of used tips). + attributes, and methods that allow you to use pipettes in your protocols. + + Methods generally fall into one of two categories. + + - They can change the state of the InstrumentContext object, such as how fast + it moves liquid or where it disposes of used tips). - They can command the instrument to perform an action, like picking up tips, moving - to certain locations, and aspirating or dispensing liquid. + to certain locations, and aspirating or dispensing liquid. This class also includes action methods (e.g., ``aspirate()`` and ``distribute()``). We’ve included and defined many of these here for convenience. @@ -159,7 +160,7 @@ def aspirate( ) -> InstrumentContext: """ Draw liquid into a pipette tip. - + See :ref:`new-aspirate` for more details and examples. :param volume: The volume to aspirate, measured in µL. If 0 or @@ -390,7 +391,7 @@ def mix( ) -> InstrumentContext: """ Mix a volume of liquid by repeatedly aspirating and dispensing it in a single location. - + See :ref:`mix`. :param repetitions: Number of times to mix (default is 1).