Skip to content

Commit 3ffad55

Browse files
shlokaminshlokamin
authored
docs(api): update transfer documentation (#7014)
Update transfer documentation to account for disposal volume kwarg overriding source blowout location.
1 parent 91c5b22 commit 3ffad55

File tree

2 files changed

+95
-14
lines changed

2 files changed

+95
-14
lines changed

‎api/docs/v2/new_complex_commands.rst

Lines changed: 89 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -102,14 +102,21 @@ Parameters for the complex liquid handling are listed here in order of operation
102102
+--------------------------------+------------------------------------------------------+----------------------------+------------------------------------+------------------------------------+
103103
| ``air_gap`` | Volume in µL | 0 | 0 | 0 |
104104
+--------------------------------+------------------------------------------------------+----------------------------+------------------------------------+------------------------------------+
105-
| ``blow_out`` | ``True`` or ``False``, if true blow out at dispense | ``False`` | ``False`` | ``False`` |
105+
| ``blow_out`` | ``True`` or ``False``, if true and no location | ``False`` | ``False`` | ``False`` |
106+
| | specified it will blow out in the trash. | | | |
107+
| | | | | |
108+
| | **Note**: | | | |
109+
| | 1. If the pipette tip is empty, and no location is | | | |
110+
| | specified, the pipette will blow out in the trash. | | | |
111+
| | 2. If the pipette tip is not empty, and no | | | |
112+
| | location is specified, the pipette will blow out | | | |
113+
| | into the source well. | | | |
106114
+--------------------------------+------------------------------------------------------+----------------------------+------------------------------------+------------------------------------+
107-
| ``blowout_location`` | ``trash``, ``source well``, ``destination well`` | If pipette empty, blowout | If pipette empty, blowout | If pipette empty, blowout |
108-
| | | into trash, otherwise | into trash, otherwise | into trash, otherwise |
109-
| | | blowout into source well | blowout into source well | blowout into source well |
110-
| | | If ``blow_out`` is false | If ``blow_out`` is false | If ``blowout`` is false |
111-
| | | ``blowout_location`` will | ``blowout_location`` will | ``blowout_location`` will |
112-
| | | be ignored | be ignored | be ignored |
115+
| ``blowout_location`` | ``trash``, ``source well``, ``destination well`` | There is no location by | There is no location by | There is no location by |
116+
| | | default. Please see | default. Please see ``blow_out`` | default. Please see ``blow_out`` |
117+
| | **Note**: If ``blow_out`` is set to ``False`` this | ``blow_out`` above for | above for default behavior. | above for default behavior. |
118+
| | parameter will be ignored. | default behavior. | | |
119+
| | | | | |
113120
+--------------------------------+------------------------------------------------------+----------------------------+------------------------------------+------------------------------------+
114121
| ``trash`` | ``True`` or ``False``, if false return tip to tiprack| ``True`` | ``True`` | ``True`` |
115122
+--------------------------------+------------------------------------------------------+----------------------------+------------------------------------+------------------------------------+
@@ -727,7 +734,7 @@ will have the steps...
727734
``blow_out``
728735
------------
729736

730-
A :ref:`blow-out` can be performed after every dispense that leaves the tip empty by setting ``blow_out=True``.
737+
A :ref:`blow-out` into the trash can be performed after every dispense that leaves the tip empty by setting ``blow_out=True``.
731738

732739
.. code-block:: python
733740
@@ -751,6 +758,80 @@ will have the steps...
751758
752759
.. versionadded:: 2.0
753760

761+
The robot will automatically dispense any left over liquid that is *not* from using ``disposal_volume`` into
762+
the source well of your transfer function.
763+
764+
.. code-block:: python
765+
766+
pipette.pick_up_tip()
767+
pipette.aspirate(10, plate['A1'])
768+
pipette.transfer(
769+
100,
770+
plate['A1'],
771+
plate['A2'],
772+
blow_out=True, # blow out droplets into the source well (A1 of "plate")
773+
new_tip='never')
774+
775+
.. versionadded:: 2.8
776+
777+
778+
``blowout_location``
779+
--------------------
780+
781+
Starting in Python API Version 2.8 and above, you can specify the well type you would like your pipette to blow out in.
782+
Specifying a location will override any defaults from the ``blow_out`` argument.
783+
784+
The code below is the same default behavior you would see utilizing ``blow_out=True`` only. It will blow out for
785+
every transfer into the trash.
786+
787+
.. code-block:: python
788+
789+
pipette.transfer(
790+
100,
791+
plate['A1'],
792+
plate['A2'],
793+
blow_out=True,
794+
blowout_location='trash') # blow out droplets into the trash
795+
796+
.. versionadded:: 2.8
797+
798+
The same is true even if you have extra liquid left in your tip shown below.
799+
800+
.. code-block:: python
801+
802+
pipette.pick_up_tip()
803+
pipette.aspirate(10, plate['A1'])
804+
pipette.transfer(
805+
100,
806+
plate['A1'],
807+
plate['A2'],
808+
blow_out=True,
809+
blowout_location='trash', # blow out droplets into the trash
810+
new_tip='never')
811+
812+
.. versionadded:: 2.8
813+
814+
If you wish to blow out in the source or destination well you can do so by specifying the location as either ``source well`` or ``destination well``.
815+
For example, to blow out in the destination well you can do the following:
816+
817+
.. code-block:: python
818+
819+
pipette.transfer(
820+
100,
821+
plate['A1'],
822+
plate.wells(),
823+
blow_out=True,
824+
blowout_location='destination well') # blow out droplets into each destination well (this will blow out in wells `A1`, `B1`, `C1`..etc)
825+
826+
.. versionadded:: 2.8
827+
828+
829+
.. note::
830+
831+
You *must* specify ``blow_out=True`` in order to utilize the new argument ``blowout_location``
832+
833+
834+
754835
``mix_before``, ``mix_after``
755836
-----------------------------
756837

‎api/src/opentrons/protocol_api/instrument_context.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1017,13 +1017,13 @@ def transfer(self,
10171017
- 'destintation well': blowout excess liquid into destination
10181018
well
10191019
- 'trash': blowout excess liquid into the trash
1020-
If no `blow_out_location` specified and there is liquid left in
1021-
the pipette, a :py:meth:`blow_out` will occur into the source
1022-
well
1020+
If no `blow_out_location` specified, no `disposal_volume`
1021+
specified, and the pipette contains liquid,
1022+
a :py:meth:`blow_out` will occur into the source well
10231023
1024-
If no `blow_out_location` specified and there is no liquid
1025-
left in
1026-
the pipette, a :py:meth:`blow_out` will occur into the trash
1024+
If no `blow_out_location` specified and either
1025+
`disposal_volume` is specified or the pipette is empty,
1026+
a :py:meth:`blow_out` will occur into the trash
10271027
10281028
If `blow_out` is set to `False`, this parameter will be ignored
10291029

0 commit comments

Comments
 (0)