From c4106bf9d3e42a17aa520364d438d15944923704 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Fri, 16 Aug 2024 01:00:06 -0400 Subject: [PATCH] review and edits --- api/docs/v2/basic_commands/liquids.rst | 20 +++++++++++----- api/docs/v2/pipettes/loading.rst | 20 ++++++++-------- .../protocol_api/instrument_context.py | 24 ++++++++++--------- .../protocol_api/protocol_context.py | 6 ++--- 4 files changed, 40 insertions(+), 30 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index 408183b8f59..9e2e4ff8782 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -263,13 +263,18 @@ This example aspirates enough air to fill the remaining volume in a pipette:: Detect Liquids ============== -The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pipette to check for liquid in a well plate or reservoir. It returns ``True`` if the pressure sensors in the pipette detect a liquid and ``False`` if the sensors do not. Detection takes place during aspiration, but aspiration isn't required to use ``detect_liquid_presence()``. This is a standalone method that can be called when you want the robot to record the presence or absence of a liquid. When ``detect_liquid_presence()`` finds an empty well it won't raise an error or stop your protocol. See also :ref:`lpd`. +The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pipette to check for liquid in a well. It returns ``True`` if the pressure sensors in the pipette detect a liquid and ``False`` if the sensors do not. + +Aspiration isn't required to use ``detect_liquid_presence()``. This is a standalone method that can be called when you want the robot to record the presence or absence of a liquid. When ``detect_liquid_presence()`` finds an empty well it won't raise an error or stop your protocol. + +A potential use of liquid detection is to try aspirating from another well if the first well is found to contain no liquid. .. code-block:: python - pipette.detect_liquid_presence(well) - -.. removed code sample. + if pipette.detect_liquid_presence(reservoir["A1"]): + pipette.aspirate(100, reservoir["A1"]) + else: + pipette.aspirate(100, reservoir["A2"]) .. versionadded:: 2.20 @@ -278,10 +283,13 @@ The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pip Require Liquids =============== -The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for and require liquid in a well plate or reservoir. It returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if the sensors do not. Detection takes place during aspiration, but aspiration isn't required to use ``require_liquid_presence()``. This is a standalone method that can be called when you want the robot to react to a missing liquid or empty well. When ``require_liquid_presence()`` finds an empty well, it raises an error and stops the protocol to let you resolve the problem. See also :ref:`lpd`. +The :py:meth:`.InstrumentContext.require_liquid_presence` method tells a Flex pipette to check for `and require` liquid in a well. + +Aspiration isn't required to use ``require_liquid_presence()``. This is a standalone method that can be called when you want the robot to react to a missing liquid or empty well. When ``require_liquid_presence()`` finds an empty well, it raises an error and pauses the protocol to let you resolve the problem. See also :ref:`lpd`. .. code-block:: python - pipette.require_liquid_presence(well) + pipette.require_liquid_presence(reservoir["A1"]) + pipette.aspirate(100, reservoir["A1"]) # only occurs if liquid found .. versionadded:: 2.20 diff --git a/api/docs/v2/pipettes/loading.rst b/api/docs/v2/pipettes/loading.rst index 4753a72f4a7..e97eb78592b 100644 --- a/api/docs/v2/pipettes/loading.rst +++ b/api/docs/v2/pipettes/loading.rst @@ -233,7 +233,7 @@ Liquid presence detection works with Flex 1-, 8-, and 96-channel pipettes only. Enabling Globally ----------------- -The easiest, and recommended, way to use liquid presence detection is by adding the optional Boolean argument, ``liquid_presence_detection=True`` to :py:meth:`.ProtocolContext.load_instrument` in your protocol. When ``True`` the robot will check for liquid on every aspiration. You can also turn this feature off and back on again later in a protocol. This example enables liquid presence detection on the 8-channel pipette used in the sample protocol at the top of the page. +To automatically use liquid presence detection, add the optional Boolean argument ``liquid_presence_detection=True`` to :py:meth:`.ProtocolContext.load_instrument` in your protocol. The robot will check for liquid on every aspiration. You can also turn this feature off and back on again later in a protocol. This example enables liquid presence detection on the 8-channel pipette used in the sample protocol at the top of the page. .. code-block:: python @@ -247,30 +247,30 @@ The easiest, and recommended, way to use liquid presence detection is by adding .. note:: Accurate liquid detection requires fresh, dry pipette tips. Protocols using this feature must discard used tips after an aspirate/dispense cycle and pick up new tips before the next cycle. The API will raise an error if liquid detection is active and your protocol attempts to reuse a pipette tip or if the robot thinks the tip is wet. -Let's take a look at how all this works. First, tell the robot to pick up a new, clean tip, aspirate 100 ul from a reservoir, and dispense that volume into a well plate. +Let's take a look at how all this works. First, tell the robot to pick up a clean tip, aspirate 100 µL from a reservoir, and dispense that volume into a well plate. .. code-block:: python - right.pick_up_tip(tiprack2) - right.aspirate(100, reservoir["A1"]) + right.pick_up_tip() + right.aspirate(100, reservoir["A1"]) # checks for liquid right.dispense(100, plate["A1"]) Liquid detection takes place prior to aspiration. Upon detecting a liquid, the pipette stops, raises itself above the liquid's surface, and then aspirates according to your protocol. Checking for a liquid adds time to your protocol run, so be aware of that before using it. If Flex doesn't detect liquid, it raises an error and stops the protocol until the problem is resolved. -However, aspiration isn't required for liquid level detection. Two standalone methods, :ref:`detect-liquid-presence` and :ref:`require-liquid-presence`, let you add liquid detection to a protocol with or without aspirating. The former checks for liquid and returns ``True`` if it finds liquid or ``False`` if it does not. It won't raise an error or stop a protocol. The latter checks for liquid and raises an error if it does not detect liquid. It will stop a protocol until the error is resolved. +However, aspiration isn't required for liquid level detection. Two standalone methods, :py:meth:`.detect_liquid_presence` and :py:meth:`.require_liquid_presence`, let you add liquid detection to a protocol with or without aspirating. Automatic detection is the same as calling ``require_liquid_presence()`` before every aspiration. See :ref:`detect-liquid-presence` and :ref:`require-liquid-presence` for details. .. versionadded:: 2.20 Activating and Deactivating --------------------------- -You can turn liquid presence detection off and on throughout a protocol. To turn it off, set ``pipette.liquid_presence_detection=False`` at the point in a protocol where it needs to be disabled, usually between picking up a new tip and aspirating a liquid. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's try this starting after picking up a new tip. +You can turn liquid presence detection off and on throughout a protocol. To turn it off, set ``pipette.liquid_presence_detection=False`` at the point in a protocol where it needs to be disabled, usually between picking up a new tip and aspirating a liquid. This overrides the global argument, ``liquid_presence_detection=True`` that we set on :py:meth:`~.ProtocolContext.load_instrument`. Let's try this after picking up a new tip. .. code-block:: python right.pick_up_tip() - right.liquid_presence_detection=False - right.aspirate(100, reservoir["A2"]) + right.liquid_presence_detection = False # Turns off liquid presence detection. + right.aspirate(100, reservoir["A2"]) # Aspirates immediately. From now on, the pipette will not check for liquid until you turn this feature back on. @@ -279,8 +279,8 @@ To reactivate, set ``liquid_presence_detection=True`` at the point later in the .. code-block:: python right.pick_up_tip() - right.liquid_presence_detection=True # Turns on liquid presence detection. - right.aspirate(100, reservoir["A3"]) # Detects liquid before aspirating. + right.liquid_presence_detection = True # Turns on liquid presence detection. + right.aspirate(100, reservoir["A3"]) # Detects liquid before aspirating. The robot will continue to check for liquid until this feature is disabled again, or an empty well is detected (and the robot raises an error), or the protocol completes. diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 5319b8f7ce4..7b3251cc3cf 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -1688,12 +1688,10 @@ def tip_racks(self, racks: List[labware.Labware]) -> None: @requires_version(2, 20) def liquid_presence_detection(self) -> bool: """ - Gets the global setting for liquid level detection. + Whether the pipette will perform automatic liquid presence detection. - When True, `liquid_probe` will be called before - aspirates and dispenses to bring the tip to the liquid level. - - The default value is False. + When ``True``, the pipette will check for liquid on every aspiration. + Defaults to ``False``. See :ref:`lpd`. """ return self._core.get_liquid_presence_detection() @@ -2120,10 +2118,12 @@ def configure_nozzle_layout( # noqa: C901 @requires_version(2, 20) def detect_liquid_presence(self, well: labware.Well) -> bool: - """Checks for liquid in a well and returns ``True`` if liquid is present and ``False`` if liquid is not present. Will not raise an error if it does not detect liquid. When simulating a protocol, the check always succeeds (returns ``True``). Works with Flex 1-, 8-, and 96-channel pipettes. See :ref:`lpd` and :ref:`detect-liquid-presence` - - If your protocol uses :ref:`partial tip pickup `, the pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid. - + """Checks for liquid in a well. + + Returns ``True`` if liquid is present and ``False`` if liquid is not present. Will not raise an error if it does not detect liquid. When simulating a protocol, the check always succeeds (returns ``True``). Works with Flex 1-, 8-, and 96-channel pipettes. See :ref:`detect-liquid-presence`. + + .. note:: + The pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid. """ loc = well.top() self._96_tip_config_valid() @@ -2131,10 +2131,12 @@ def detect_liquid_presence(self, well: labware.Well) -> bool: @requires_version(2, 20) def require_liquid_presence(self, well: labware.Well) -> None: - """Check for liquid in a well and raises an error if none is detected. When this method raises an error, Flex will offer the opportunity to enter recovery mode. In recovery mode, you can manually add liquid to resolve the error. When simulating a protocol, the check always succeeds (does not raise an error). Works with Flex 1-, 8-, and 96-channel pipettes. See :ref:`lpd` and :ref:`require-liquid-presence`. + """Check for liquid in a well and raises an error if none is detected. - If your protocol uses :ref:`partial tip pickup `, the pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid. + When this method raises an error, Flex will offer the opportunity to enter recovery mode. In recovery mode, you can manually add liquid to resolve the error. When simulating a protocol, the check always succeeds (does not raise an error). Works with Flex 1-, 8-, and 96-channel pipettes. See :ref:`lpd` and :ref:`require-liquid-presence`. + .. note:: + The pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid. """ loc = well.top() self._96_tip_config_valid() diff --git a/api/src/opentrons/protocol_api/protocol_context.py b/api/src/opentrons/protocol_api/protocol_context.py index 6f37aa678a1..ca2bc55874f 100644 --- a/api/src/opentrons/protocol_api/protocol_context.py +++ b/api/src/opentrons/protocol_api/protocol_context.py @@ -906,9 +906,9 @@ def load_instrument( control ` applications. You cannot replace an instrument in the middle of a protocol being run from the Opentrons App or touchscreen. - :param bool liquid_presence_detection: If ``True``, enable :ref:`liquid presence detection` for Flex 1-, 8-, or 96-channel pipettes. If your protocol uses :ref:`partial tip pickup `, the pressure sensors for the Flex 8-channel pipette are on channels A1 and H1. For the Flex 96-channel pipette, the pressure sensors are on channels A1 and H12. All other channels for these pipettes cannot detect the presence/absence of a liquid. - - .. versionadded:: 2.20 + :param bool liquid_presence_detection: If ``True``, enable automatic + :ref:`liquid presence detection ` for Flex 1-, 8-, or 96-channel pipettes. + .. versionadded:: 2.20 """ instrument_name = validation.ensure_lowercase_name(instrument_name) checked_instrument_name = validation.ensure_pipette_name(instrument_name)