Skip to content

Instruments

InstrumentContext

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, like 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.

Objects in this class should not be instantiated directly. Instead, instances are returned by ProtocolContext.load_instrument().

New in version 2.0

active_channels property v2.16 

active_channels

The number of channels the pipette will use to pick up tips.

By default, all channels on the pipette. Use configure_nozzle_layout() to set the pipette to use fewer channels.

air_gap v2.0 

air_gap(volume=None, height=None, in_place=None, rate=None, flow_rate=None)

Draw air into the pipette's tip at the current well.

See Air Gap.

Parameters:

  • volume (float, default: None ) –

    The amount of air, measured in µL. Calling air_gap() with no arguments uses the entire remaining volume in the pipette.

  • height (float, default: None ) –

    The height, in mm, to move above the current well before creating the air gap. The default is 5 mm above the current well. in_place (bool, optional): Air gap at the pipette's current position, without moving to some height above the well. If in_place is specified, height must be unset.

  • rate (float, default: None ) –

    A multiplier for the default flow rate of the pipette. Calculated as rate multiplied by flow_rate.aspirate. If neither rate nor flow_rate is specified, the pipette will aspirate at a rate of 1.0 * InstrumentContext.flow_rate.aspirate. See Pipette Flow Rates.

  • flow_rate (float, default: None ) –

    The rate, in µL/s, at which the pipette will draw in air.

Raises:

  • UnexpectedTipRemovalError –

    If no tip is attached to the pipette.

  • RuntimeError –

    If location cache is None and the air gap is not in_place. This would happen if air_gap() is called without first calling a method that takes a location (e.g., aspirate(), dispense()).

Returns:

Both volume and height are optional, but if you want to specify only height you must do it as a keyword argument: pipette.air_gap(height=2). If you call air_gap with a single, unnamed argument, it will always be interpreted as a volume.

Note

In API version 2.21 and earlier, this function was implemented as an aspirate, and dispensing into a well would add the air gap volume to the liquid tracked in the well. In API version 2.22 and later, air gap volume is not tracked as liquid when dispensing into a well.

Changed in version 2.22: No longer implemented as an aspirate.

Changed in version 2.24: Added the in_place option.

Changed in version 2.24: Adds the rate and flow_rate parameter. You can only define one or the other. If both are unspecified then rate is by default set to 1.0. Can air gap over a trash bin or waste chute.

aspirate v2.0 

aspirate(volume=None, location=None, rate=1.0, flow_rate=None, end_location=None, movement_delay=None)

Draw liquid into a pipette tip.

See Aspirate for more details and examples.

Parameters:

  • volume (int or float, default: None ) –

    The volume to aspirate, measured in µL. If unspecified, defaults to the maximum volume for the pipette and its currently attached tip.

    If aspirate() is called with a volume of precisely 0, its behavior depends on the API level of the protocol. On API levels below 2.16, it will behave the same as a volume of None/unspecified: aspirate until the pipette is full. On API levels at or above 2.16, no liquid will be aspirated.

  • location (Union[`Well`][opentrons.protocol_api.labware.Well], [`Location`][opentrons.types.Location], default: None ) –

    Tells the robot where to aspirate from. The location can be a Well or a Location.

    • 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 well_bottom_clearance.aspirate.

    • If the location is a Location (e.g., the result of Well.top() or Well.bottom()), the robot will aspirate from that specified position.

    • If the location is unspecified, the robot will aspirate from its current position.

  • rate (float, default: 1.0 ) –

    A multiplier for the default flow rate of the pipette. Calculated as rate multiplied by flow_rate.aspirate. If not specified, defaults to 1.0. See Pipette Flow Rates.

  • flow_rate (float, default: None ) –

    The absolute flow rate in µL/s. If flow_rate is specified, rate must not be set.

  • end_location (`Location`, default: None ) –

    Tells the robot to move between location and end_location while aspirating liquid. When this argument is used, the location and end_location must both be Location.

  • movement_delay (float, default: None ) –

    Delay the x/y/z movement during a dynamic aspirate. This option is only valid when using end_location. When this argument is used, the x/y/z movement will wait movement_delay seconds after the pipette starts to aspirate before moving. This may help when dispensing very viscous liquids that need to build up some pressure before liquid starts to flow.

Returns:

Note

If aspirate() is called with a single, unnamed argument, it will treat that argument as volume. If you want to call aspirate() with only location, specify it as a keyword argument: pipette.aspirate(location=plate['A1']).

Changed in version 2.24: Added the flow_rate parameter.

blow_out v2.0 

blow_out(location=None)

Blow an extra amount of air through a pipette's tip to clear it.

If 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 Blow Out.

Parameters:

  • location (Union[`Well`][opentrons.protocol_api.labware.Well], [`Location`][opentrons.types.Location], default: None ) –

    The blowout location. If no location is specified, the pipette will blow out from its current position.

    Changed in version 2.16: Accepts TrashBin and WasteChute values.

Raises:

  • RuntimeError –

    If no location is specified and the location cache is None. This should happen if blow_out() is called without first calling a method that takes a location, like aspirate() or dispense().

Returns:

Changed in version 2.24: location is no longer required if the pipette just moved to, dispensed, or blew out into a trash bin or waste chute.

channels property v2.0 

channels

The number of channels on the pipette.

Possible values are 1, 8, or 96.

See also type.

configure_for_volume v2.15 

configure_for_volume(volume)

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 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 very small volumes of liquid. Low-volume mode can only be set by calling configure_for_volume(). See Volume Modes.

Note

Changing a pipette's mode will reset its 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 tips the pipette can subsequently pick up without raising an error.

This function will also raise an error if volume is outside of the minimum and maximum capacities of the pipette (e.g., setting volume=1 for a Flex 1000 µL pipette).

Parameters:

  • volume (float) –

    The volume, in µL, that the pipette will prepare to handle.

configure_nozzle_layout v2.16 

configure_nozzle_layout(style, start=None, end=None, front_right=None, back_left=None, tip_racks=None)

Configure how many tips the 8-channel or 96-channel pipette will pick up.

Changing the nozzle layout will affect gantry movement for all subsequent pipetting actions that the pipette performs. It also alters the pipette's behavior for picking up tips. The pipette will continue to use the specified layout until this function is called again.

Note

When picking up fewer than 96 tips at once, the tip rack must not be placed in a tip rack adapter in the deck. If you try to pick up fewer than 96 tips from a tip rack that is in an adapter, the API will raise an error.

Parameters:

  • style (NozzleLayout or None) –

    The shape of the nozzle layout. You must import the layout constant in order to use it.

    • ALL resets the pipette to use all of its nozzles. Calling configure_nozzle_layout() with no arguments also resets the pipette.
    • COLUMN sets a 96-channel pipette to use 8 nozzles, aligned from front to back with respect to the deck. This corresponds to a column of wells on labware. For 8-channel pipettes, use ALL instead.
    • PARTIAL_COLUMN sets an 8-channel pipette to use 2--7 nozzles, aligned from front to back with respect to the deck. Not compatible with the 96-channel pipette.
    • ROW sets a 96-channel pipette to use 12 nozzles, aligned from left to right with respect to the deck. This corresponds to a row of wells on labware. Not compatible with 8-channel pipettes.
    • SINGLE sets the pipette to use 1 nozzle. This corresponds to a single well on labware.
  • start (str or None, default: None ) –

    The primary nozzle of the layout, which the robot uses to determine how it will move to different locations on the deck. The string should be of the same format used when identifying wells by name. Required unless setting style=ALL.

    Note

    If possible, don't use both start="A1" and start="A12" to pick up tips from the same rack. Doing so can affect positional accuracy.

    end (str or None): The nozzle at the end of a linear layout, which is used to determine how many tips will be picked up by a pipette. The string should be of the same format used when identifying wells by name. Required when setting style=PARTIAL_COLUMN.

  • tip_racks (List[Labware], default: None ) –

    Behaves the same as setting the tip_racks parameter of load_instrument(). If not specified, the new configuration resets tip_racks and you must specify the location every time you call pick_up_tip().

Changed in version 2.20: Added partial column, row, and single layouts.

consolidate v2.0 

consolidate(volume, source, dest, *args, **kwargs)

Move liquid from multiple source wells to a single destination well.

Parameters:

  • volume (Union[float, Sequence[float]]) –

    The amount, in µL, to aspirate from each source well.

  • source (List[Well]) –

    A list of wells to aspirate liquid from.

  • dest (Well) –

    A single well to dispense liquid into.

  • kwargs (Any, default: {} ) –

    See transfer() and the complex parameters page. Some parameters behave differently than when transferring. disposal_volume and mix_before are ignored.

Returns:

consolidate_with_liquid_class v2.24 

consolidate_with_liquid_class(liquid_class, volume, source, dest, new_tip='once', trash_location=None, return_tip=False, group_wells=True, keep_last_tip=None, tip_racks=None, tips=None)

Consolidate a particular type of liquid from a group of wells to one well.

Parameters:

  • liquid_class (LiquidClass) –

    The type of liquid to move. You must specify the liquid class, even if you have used Labware.load_liquid() to indicate what liquid the source contains.

  • volume (float) –

    The amount, in µL, to aspirate from each source well.

  • source (Union[Well, Sequence[Well], Sequence[Sequence[Well]]]) –

    A list of wells to aspirate liquid from.

  • dest (Union[Well, Sequence[Well], TrashBin, WasteChute]) –

    A single well, list of wells, trash bin, or waste chute to dispense liquid into. Multiple wells can only be given for multi-channel pipette configurations, and must be able to be dispensed to in a single dispense.

  • new_tip (str, default: 'once' ) –

    When to pick up and drop tips during the command. Defaults to "once".

    • "once": Use one tip for the entire command.
    • "always": Use a new tip after each aspirate and dispense, even when visiting the same source again.
    • "never": Do not pick up or drop tips at all.

    See Tip Handling for details.

  • trash_location (Union[Location, Well, TrashBin, WasteChute], default: None ) –

    A trash container, well, or other location to dispose of tips. Depending on the liquid class, the pipette may also blow out liquid here. If not specified, the pipette will dispose of tips in its trash_container.

  • return_tip (bool, default: False ) –

    Whether to drop used tips in their original locations in the tip rack, instead of the trash.

  • group_wells (bool, default: True ) –

    For multi-channel transfers only. If set to True, group together contiguous wells given into a single transfer step, taking into account the tip configuration. If False, target each well given with the primary nozzle. Defaults to True.

  • keep_last_tip (bool, default: None ) –

    When True, the pipette keeps the last tip used in the consolidate attached. When False, the last tip will be dropped or returned. If not set, behavior depends on the value of new_tip. new_tip="never" keeps the tip, and all other values of new_tip drop or return the tip.

  • tip_racks (List[Labware], default: None ) –

    A list of tip racks to pick up from for this command. If not provided, the pipette will pick up from its associated tip_racks. Providing this argument does not change the value of InstrumentContext.tip_racks.

  • tips (Union[Sequence[Well], Sequence[Sequence[Well]]], default: None ) –

    An ordered list of tips to use for the transfer. If the list contains fewer tips than needed to complete the transfer, the API will raise an error. The pipette will use only these tips even if tip_racks or the tip_racks parameter of this method is set.

New in version 2.25: Added the tip_racks parameter.

New in version 2.27: Added the tips parameter.

current_tip_source_well v2.25 

current_tip_source_well()

Returns the tip rack well the current tip has been picked up from.

If there is no tip currently on the pipette, this will return None.

current_volume property v2.0 

current_volume

The current amount of liquid held in the pipette, measured in µL.

default_speed property v2.0 writable 

default_speed

The speed at which the robot's gantry moves in mm/s.

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 of the move_to() method. See Gantry Speed.

detect_liquid_presence v2.20 

detect_liquid_presence(well)

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 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.

dispense v2.0 

dispense(volume=None, location=None, rate=1.0, push_out=None, flow_rate=None, end_location=None, movement_delay=None)

Dispense liquid from a pipette tip.

See Dispense for more details and examples.

Parameters:

  • volume (int or float, default: None ) –

    The volume to dispense, measured in µL.

    • If unspecified or None, dispense the current_volume.

    • If 0, the behavior of dispense() depends on the API level of the protocol. In API version 2.16 and earlier, dispense all liquid in the pipette (same as unspecified or None). In API version 2.17 and later, dispense no liquid.

    • If greater than current_volume, the behavior of dispense() depends on the API level of the protocol. In API version 2.16 and earlier, dispense all liquid in the pipette. In API version 2.17 and later, raise an error.

  • location (Optional[Union[Location, Well, TrashBin, WasteChute]], default: None ) –

    Tells the robot where to dispense liquid held in the pipette. The location can be a Well, Location, TrashBin, or WasteChute.

    • If a Well, the pipette will dispense at or above the bottom center of the well. The distance (in mm) from the well bottom is specified by well_bottom_clearance.dispense.

    • If a Location (e.g., the result of Well.top() or Well.bottom()), the pipette will dispense at that specified position.

    • If a trash container, the pipette will dispense at a location relative to its center and the trash container's top center. See Position Relative to Trash Containers for details.

    • If unspecified, the pipette will dispense at its current position.

    If only a location is passed (e.g., pipette.dispense(location=plate['A1'])), all of the liquid aspirated into the pipette will be dispensed (the amount is accessible through current_volume).

    Changed in version 2.16: Accepts TrashBin and WasteChute values.

  • rate (float, default: 1.0 ) –

    How quickly a pipette dispenses liquid. The speed in µL/s is calculated as rate multiplied by flow_rate.dispense. If not specified, defaults to 1.0. See Pipette Flow Rates.

  • push_out (float, default: None ) –

    Continue past the plunger bottom to help ensure all liquid leaves the tip. Measured in µL. The default value is None.

    When not specified or set to None, the plunger moves by a non-zero default amount.

    For a table of default values, see Push Out After Dispense.

  • flow_rate (float, default: None ) –

    The absolute flow rate in µL/s. If flow_rate is specified, rate must not be set.

  • end_location (`Location`, default: None ) –

    Tells the robot to move between location and end_location while dispensing liquid held in the pipette. When this argument is used, the location and end_location must both be a Location.

  • movement_delay (float, default: None ) –

    Delay the x/y/z movement during a dynamic dispense. This option is only valid when using end_location. When this argument is used, the x/y/z movement will wait movement_delay seconds after the pipette starts to dispense before moving. This may help when dispensing very viscous liquids that need to build up some pressure before liquid starts to flow.

Returns:

Note

If dispense() is called with a single, unnamed argument, it will treat that argument as volume. If you want to call dispense() with only location, specify it as a keyword argument: pipette.dispense(location=plate['A1']).

New in version 2.15: Added the push_out parameter.

Changed in version 2.17: Behavior of the volume parameter.

New in version 2.24: Added the flow_rate parameter.

Changed in version 2.24: location is no longer required if the pipette just moved to, dispensed, or blew out into a trash bin or waste chute.

distribute v2.0 

distribute(volume, source, dest, *args, **kwargs)

Move a volume of liquid from one source to multiple destinations.

Parameters:

  • volume (Union[float, Sequence[float]]) –

    The amount, in µL, to dispense into each destination well.

  • source (Well) –

    A single well to aspirate liquid from.

  • dest (List[Well]) –

    A list of wells to dispense liquid into.

  • kwargs (Any, default: {} ) –

    See transfer() and the complex parameters page. Some parameters behave differently than when transferring.

    • disposal_volume: Aspirates additional liquid to improve the accuracy of each dispense. Defaults to the minimum volume of the pipette. See Disposal Volume for details.

    • mix_after: Ignored.

Returns:

distribute_with_liquid_class v2.24 

distribute_with_liquid_class(liquid_class, volume, source, dest, new_tip='once', trash_location=None, return_tip=False, group_wells=True, keep_last_tip=None, tip_racks=None, tips=None)

Distribute a particular type of liquid from one well to a group of wells.

Parameters:

  • liquid_class (LiquidClass) –

    The type of liquid to move. You must specify the liquid class, even if you have used Labware.load_liquid() to indicate what liquid the source contains.

  • volume (float) –

    The amount, in µL, to dispense to each destination.

  • source (Union[Well, Sequence[Well]]) –

    A single well for the pipette to target, or a group of wells to target in a single aspirate for a multi-channel pipette.

  • dest (Sequence[Well]) –

    A list of wells to dispense liquid into.

  • new_tip (str, default: 'once' ) –

    When to pick up and drop tips during the command. Defaults to "once".

    • "once": Use one tip for the entire command.
    • "always": Use a new tip before each aspirate.
    • "never": Do not pick up or drop tips at all.

    See Tip Handling.

  • trash_location (Union[Location, Well, TrashBin, WasteChute], default: None ) –

    A trash container, well, or other location to dispose of tips. Depending on the liquid class, the pipette may also blow out liquid here. If not specified, the pipette will dispose of tips in its trash_container.

  • return_tip (bool, default: False ) –

    Whether to drop used tips in their original locations in the tip rack, instead of the trash.

  • group_wells (bool, default: True ) –

    For multi-channel transfers only. If set to True, group together contiguous wells given into a single transfer step, taking into account the tip configuration. If False, target each well given with the primary nozzle. Defaults to True.

  • keep_last_tip (bool, default: None ) –

    When True, the pipette keeps the last tip used in the distribute attached. When False, the last tip will be dropped or returned. If not set, behavior depends on the value of new_tip. new_tip="never" keeps the tip, and all other values of new_tip drop or return the tip.

  • tip_racks (List[Labware], default: None ) –

    A list of tip racks to pick up from for this command. If not provided, the pipette will pick up from its associated tip_racks. Providing this argument does not change the value of InstrumentContext.tip_racks.

  • tips (Union[Sequence[Well], Sequence[Sequence[Well]]], default: None ) –

    An ordered list of tips to use for the transfer. If the list contains fewer tips than needed to complete the transfer, the API will raise an error. The pipette will use only these tips even if tip_racks or the tip_racks parameter of this method is set.

New in version 2.25: Added the tip_racks parameter.

New in version 2.27: Added the tips parameter.

drop_tip v2.0 

drop_tip(location=None, home_after=None)

Drop the current tip.

See Dropping a Tip for examples.

If no location is passed (e.g. pipette.drop_tip()), the pipette will drop the attached tip into its trash_container.

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:

  • As a Well. This uses a default location relative to the well. This style of call can be used to make the robot drop a tip into labware like a well plate or a reservoir. For example, pipette.drop_tip(location=reservoir["A1"]).
  • As a Location. For example, to drop a tip from an unusually large height above the tip rack, you could call pipette.drop_tip(tip_rack["A1"].top(z=10)).
  • As a TrashBin. This uses a default location relative to the TrashBin object. For example, pipette.drop_tip(location=trash_bin).
  • As a WasteChute. This uses a default location relative to the WasteChute object. For example, pipette.drop_tip(location=waste_chute).

Changed in version 2.16: Accepts TrashBin and WasteChute values.

In API versions 2.15 to 2.17, if location is a TrashBin or not specified, the API will instruct the pipette to drop tips in different locations within the bin. Varying the tip drop location helps prevent tips from piling up in a single location.

Changed in version 2.18: The API will only vary the tip drop location if location is not specified. Specifying a TrashBin as the location behaves the same as specifying TrashBin.top, which is a fixed position.

Parameters:

  • location (Optional[Union[Location, Well, TrashBin, WasteChute]], default: None ) –

    Where to drop the tip.

  • home_after (Optional[bool], default: None ) –

    Whether to home the pipette's plunger after dropping the tip. If not specified, defaults to True on an OT-2.

    When False, the pipette does not home its plunger. This can save a few seconds, but is not recommended. Homing helps the robot track the pipette's position.

Returns:

dynamic_mix v2.27 

dynamic_mix(aspirate_start_location, dispense_start_location, repetitions=1, volume=None, aspirate_end_location=None, dispense_end_location=None, rate=1.0, aspirate_flow_rate=None, dispense_flow_rate=None, aspirate_delay=None, dispense_delay=None, final_push_out=None, movement_delay=None)

Mix a volume of liquid by repeatedly aspirating and dispensing it in multiple locations.

See Dynamic Mix for examples.

Parameters:

  • repetitions (int, default: 1 ) –

    Number of times to mix (default is 1).

  • volume (float, default: None ) –

    The volume to mix, measured in µL. If unspecified, defaults to the maximum volume for the pipette and its attached tip.

    If mix() is called with a volume of precisely 0, its behavior depends on the API level of the protocol. On API levels below 2.16, it will behave the same as a volume of None/unspecified: mix the full working volume of the pipette. On API levels at or above 2.16, no liquid will be mixed.

  • aspirate_start_location (Location) –

    The location where the pipette will aspirate from.

  • aspirate_end_location (Location, default: None ) –

    If this argument is supplied, the pipette will move between aspirate_start_location and aspirate_end_location while performing the aspirate.

  • dispense_start_location (Location) –

    The location where the pipette will dispense to.

  • dispense_end_location (Location, default: None ) –

    If this argument is supplied, the pipette will move between dispense_start_location and dispense_end_location while performing the dispense.

  • rate (float, default: 1.0 ) –

    How quickly the pipette aspirates and dispenses liquid while mixing. The aspiration flow rate is calculated as rate multiplied by flow_rate.aspirate. The dispensing flow rate is calculated as rate multiplied by flow_rate.dispense. See new plunger flow rates.

  • aspirate_flow_rate (float, default: None ) –

    The absolute flow rate for each aspirate in the mix, in µL/s. If this is specified, rate must not be set.

  • dispense_flow_rate (float, default: None ) –

    The absolute flow rate for each dispense in the mix, in µL/s. If this is specified, rate must not be set.

  • aspirate_delay (float, default: None ) –

    How long to wait after each aspirate in the mix, in seconds.

  • dispense_delay (float, default: None ) –

    How long to wait after each dispense in the mix, in seconds.

  • final_push_out (float, default: None ) –

    How much volume to push out after the final mix repetition. The pipette will not push out after earlier repetitions. If not specified or None, the pipette will push out the default non-zero amount. See push out dispense.

  • movement_delay (float, default: None ) –

    Delay the x/y/z movement during a dynamic mix. This option is only valid when using aspirate_end_location or dispense_end_location. When this argument is used, the x/y/z movement will wait movement_delay seconds after the pipette starts to aspirate/dispense before moving. This may help when mixing very viscous liquids that need to build up some pressure before liquid starts to flow.

Raises:

  • UnexpectedTipRemovalError –

    If no tip is attached to the pipette.

Returns:

Note

All the arguments of mix() are optional. However, if you omit one of them, all subsequent arguments must be passed as keyword arguments. For instance, pipette.mix(1, location=wellplate['A1']) is a valid call, but pipette.mix(1, wellplate['A1']) is not.

flow_rate property v2.0 

flow_rate

The speeds, in µL/s, configured for the pipette.

See Pipette Flow Rates.

This is an object with attributes aspirate, dispense, and blow_out holding the flow rate for the corresponding operation.

Note

Setting values of speed, which is deprecated, will override the values in flow_rate.

get_minimum_liquid_sense_height v2.21 

get_minimum_liquid_sense_height()

Get the minimum allowed height for liquid-level detection.

has_tip property v2.7 

has_tip

Whether this instrument has a tip attached or not.

The value of this property is determined logically by the API, not by detecting the physical presence of a tip. This is the case even on Flex, which has sensors to detect tip attachment.

home v2.0 

home()

Home the robot.

See Homing.

Returns:

home_plunger v2.0 

home_plunger()

Home the plunger associated with this mount.

Returns:

hw_pipette property v2.0 

hw_pipette

View the information returned by the hardware API directly.

Raises:

  • `types.PipetteNotAttachedError` –

    If the pipette is no longer attached (should not happen).

liquid_presence_detection property v2.20 writable 

liquid_presence_detection

Whether the pipette will perform automatic liquid presence detection.

When True, the pipette will check for liquid on every aspiration. Defaults to False. See Liquid Presence Detection.

max_volume property v2.0 

max_volume

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 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.

measure_liquid_height v2.20 

measure_liquid_height(well)

Check the height of the liquid within a well.

Returns:

  • LiquidTrackingType –

    The height, in mm, of the liquid from the bottom of the well.

min_volume property v2.0 

min_volume

The minimum volume, in µL, that the pipette can hold. This value may change based on the volume mode that the pipette is currently configured for.

mix v2.0 

mix(repetitions=1, volume=None, location=None, rate=1.0, aspirate_flow_rate=None, dispense_flow_rate=None, aspirate_delay=None, dispense_delay=None, final_push_out=None)

Mix a volume of liquid by repeatedly aspirating and dispensing it in a single location.

See Mix for examples.

Parameters:

  • repetitions (int, default: 1 ) –

    Number of times to mix (default is 1).

  • volume (float, default: None ) –

    The volume to mix, measured in µL. If unspecified, defaults to the maximum volume for the pipette and its attached tip.

    If mix() is called with a volume of precisely 0, its behavior depends on the API level of the protocol. On API levels below 2.16, it will behave the same as a volume of None/unspecified: mix the full working volume of the pipette. On API levels at or above 2.16, no liquid will be mixed.

  • location (Union[`Well`][opentrons.protocol_api.labware.Well], [`Location`][opentrons.types.Location], default: None ) –

    The location where the pipette will mix. If unspecified, the pipette will mix at its current position.

  • rate (float, default: 1.0 ) –

    How quickly the pipette aspirates and dispenses liquid while mixing. The aspiration flow rate is calculated as rate multiplied by flow_rate.aspirate. The dispensing flow rate is calculated as rate multiplied by flow_rate.dispense. See Pipette Flow Rates.

  • aspirate_flow_rate (float, default: None ) –

    The absolute flow rate for each aspirate in the mix, in µL/s. If this is specified, rate must not be set.

  • dispense_flow_rate (float, default: None ) –

    The absolute flow rate for each dispense in the mix, in µL/s. If this is specified, rate must not be set.

  • aspirate_delay (float, default: None ) –

    How long to wait after each aspirate in the mix, in seconds.

  • dispense_delay (float, default: None ) –

    How long to wait after each dispense in the mix, in seconds.

  • final_push_out (float, default: None ) –

    How much volume to push out after the final mix repetition. The pipette will not push out after earlier repetitions. If not specified or None, the pipette will push out the default non-zero amount. See Push Out After Dispense.

Raises:

  • UnexpectedTipRemovalError –

    If no tip is attached to the pipette.

Returns:

Note

All the arguments of mix() are optional. However, if you omit one of them, all subsequent arguments must be passed as keyword arguments. For instance, pipette.mix(1, location=wellplate['A1']) is a valid call, but pipette.mix(1, wellplate['A1']) is not.

Changed in version 2.21: Does not repeatedly check for liquid presence.

New in version 2.24: Added the aspirate_flow_rate, dispense_flow_rate, aspirate_delay, dispense_delay, and final_push_out parameters.

model property v2.0 

model

The model string for the pipette (e.g., 'p300_single_v1.3')

mount property v2.0 

mount

Return the name of the mount the pipette is attached to.

The possible names are "left" and "right".

move_to v2.0 

move_to(location, force_direct=False, minimum_z_height=None, speed=None, publish=True)

Move the instrument.

See Move To for examples.

Parameters:

  • location (Union[`Location`][opentrons.types.Location], [`TrashBin`][opentrons.protocol_api.TrashBin], [`WasteChute`][opentrons.protocol_api.WasteChute]) –

    Where to move to.

    Changed in version 2.16: Accepts TrashBin and WasteChute values.

  • force_direct (bool, default: False ) –

    If True, move directly to the destination without arc motion.

    Warning

    Forcing direct motion can cause the pipette to crash into labware, modules, or other objects on the deck.

  • minimum_z_height (float, default: None ) –

    An amount, measured in mm, to raise the mid-arc height. The mid-arc height can't be lowered.

  • speed (float, default: None ) –

    The speed at which to move. By default, InstrumentContext.default_speed. This controls the straight linear speed of the motion. To limit individual axis speeds, use ProtocolContext.max_speeds.

  • publish (bool, default: True ) –

    Whether to list this function call in the run preview. Default is True.

name property v2.0 

name

The name string for the pipette.

From API version 2.15 to 2.22, this property returned an internal name for Flex pipettes. (e.g., "p1000_single_flex").

In API version 2.23 and later, this property returns the Python Protocol API load name of Flex pipettes (e.g., "flex_1channel_1000").

pick_up_tip v2.0 

pick_up_tip(location=None, presses=None, increment=None, prep_after=None)

Pick up a tip for the pipette to run liquid-handling commands.

See Picking Up a Tip.

If no location is passed, the pipette will pick up the next available tip in its tip_racks list. Within each tip rack, tips will be picked up in the order specified by the labware definition and wells(). To adjust where the sequence starts, use starting_tip.

The exact position for tip pickup accounts for the length of the tip and how much the tip overlaps with the pipette nozzle. These measurements are fixed values on Flex, and are based on the results of tip length calibration on OT-2.

Note

API version 2.19 updates the tip overlap values for Flex. When updating a protocol from 2.18 (or lower) to 2.19 (or higher), pipette performance should improve without additional changes to your protocol. Nevertheless, it is good practice after updating to do the following:

  • Run Labware Position Check.
  • Perform a dry run of your protocol.
  • If tip position is slightly higher than expected, adjust the location parameter of pipetting actions to achieve the desired result.

Parameters:

  • location (Union[`Well`][opentrons.protocol_api.labware.Well], [`Labware`][opentrons.protocol_api.labware.Labware], [`Location`][opentrons.types.Location], default: None ) –

    The location from which to pick up a tip. The location argument can be specified in several ways:

    • As a Well. For example, pipette.pick_up_tip(tiprack.wells()[0]) will always pick up the first tip in tiprack, even if the rack is not a member of tip_racks.

    • As a labware. pipette.pick_up_tip(tiprack) will pick up the next available tip in tiprack, even if the rack is not a member of tip_racks.

    • As a Location. Use this to make fine adjustments to the pickup location. For example, to tell the robot to start its pick up tip routine 1 mm closer to the top of the well in the tip rack, call pipette.pick_up_tip(tiprack["A1"].top(z=-1)).

  • presses (int, default: None ) –

    The number of times to lower and then raise the pipette 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 a dry run).

    Deprecated in version 2.14: Use the Opentrons App to change pipette pick-up settings.

  • increment (float, default: None ) –

    The additional distance to travel on each successive press. For example, if presses=3 and increment=1.0, then the first press will travel down into the tip by 3.5 mm, the second by 4.5 mm, and the third by 5.5 mm).

    Deprecated in version 2.14: Use the Opentrons App to change pipette pick-up settings.

  • prep_after (bool, default: None ) –

    Whether the pipette plunger should prepare itself to aspirate immediately after picking up a tip.

    If True, the pipette will move its plunger position to bottom in preparation for any following calls to aspirate().

    If False, the pipette will prepare its plunger later, during the next call to aspirate(). This is accomplished by moving the tip to the top of the well, and positioning the plunger outside any potential liquids.

    Warning

    This is provided for compatibility with older Python Protocol API behavior. You should normally leave this unset.

    Setting prep_after=False may create an unintended pipette movement, when the pipette automatically moves the tip to the top of the well to prepare the plunger.

Returns:

New in version 2.13: Adds the prep_after argument. In version 2.12 and earlier, the plunger can't prepare itself for aspiration during pick_up_tip(), and will instead always prepare during aspirate(). Version 2.12 and earlier will raise an APIVersionError if a value is set for prep_after.

Changed in version 2.19: Uses new values for how much a tip overlaps with the pipette nozzle.

prepare_to_aspirate v2.16 

prepare_to_aspirate()

Prepare a pipette for aspiration.

Before a pipette can aspirate into an empty tip, the plunger must be in its bottom position. After dropping a tip or blowing out, the plunger will be in a different position. This function moves the plunger to the bottom position, regardless of its current position, to make sure that the pipette is ready to aspirate.

You rarely need to call this function. The API automatically prepares the pipette for aspiration as part of other commands:

  • After picking up a tip with pick_up_tip().
  • When calling aspirate(), if the pipette isn't already prepared. If the pipette is in a well, it will move out of the well, move the plunger, and then move back.

Use prepare_to_aspirate() when you need to control exactly when the plunger motion will happen. A common use case is a pre-wetting routine, which requires preparing for aspiration, moving into a well, and then aspirating without leaving the well:

pipette.move_to(well.bottom(z=2))
protocol.delay(5)
pipette.mix(10, 10)
pipette.move_to(well.top(z=5))
pipette.blow_out()
pipette.prepare_to_aspirate()
pipette.move_to(well.bottom(z=2))
protocol.delay(5)
pipette.aspirate(10, well.bottom(z=2))

The call to prepare_to_aspirate() means that the plunger will be in the bottom position before the call to aspirate(). Since it doesn't need to prepare again, it will not move up out of the well to move the plunger. It will aspirate in place.

require_liquid_presence v2.20 

require_liquid_presence(well)

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 detect_liquid_presence() and 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.

reset_tipracks v2.0 

reset_tipracks()

Reload all tips in each tip rack and reset the starting tip.

resin_tip_dispense v2.23 

resin_tip_dispense(location, volume=None, rate=None)

Push liquid out of resin tips that are currently sealed to a pipette.

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

The common way to use this function is as follows:

  1. Seal resin tips to the pipette using resin_tip_seal().

  2. Use resin_tip_dispense() to displace an experimentally derived volume at an experimentally derived rate to create an experimentally derived target pressure inside the pipette.

  3. Use delay() to wait an experimentally derived amount of time for the pressure inside the pipette to push liquid into and through the resin tip and out the other side.

  4. As liquid passes through the resin tip, the pressure inside the pipette will fall. If not all liquid has been dispensed from the resin tip, repeat steps 2 and 3.

  5. Unseal resin tips from the pipette using resin_tip_unseal().

Flex pipette pressure sensors will raise an overpressure when a differential pressure inside the pipette chamber above sensor limits is detected. You may need to disable the pressure sensor to create the required pressure profile.

Warning

Building excessive pressure inside the pipette chamber (significantly above the sensor limit) with the pressure sensors disabled can damage the pipette.

Parameters:

  • location (Location) –

    Tells the robot where to dispense.

  • volume (float, default: None ) –

    The volume that the plunger should displace, in µL. Does not directly relate to the volume of liquid that will be dispensed.

  • rate (float, default: None ) –

    How quickly the plunger moves to displace the commanded volume, in µL/s. This rate does not directly relate to the flow rate of liquid out of the resin tip. Defaults to 10.0 µL/s.

resin_tip_seal v2.23 

resin_tip_seal(location)

Seal resin tips onto the pipette.

The location provided should contain resin tips. The pipette will attach itself to the resin tips but does not check any tip presence sensors. Before the pipette seals to the tips, the plunger will rise to the top of its working range so that it can perform a resin_tip_dispense() immediately.

Parameters:

  • location (Location) –

    A location containing resin tips, must be a Labware or a Well.

resin_tip_unseal v2.23 

resin_tip_unseal(location)

Release resin tips from the pipette.

The location provided should be a valid location to drop resin tips.

Parameters:

  • location (Location) –

    A location that can accept tips.

return_height property v2.2 

return_height

The height to return a tip to its tip rack.

Returns:

  • float –

    A scaling factor to apply to the tip length. During drop_tip(), this factor is multiplied by the tip length to get the distance from the top of the well to drop the tip.

return_tip v2.0 

return_tip(home_after=None)

Drop the currently attached tip in its original location in the tip rack.

Returning a tip does not reset tip tracking, so Well.has_tip will remain False for the destination.

Returns:

Parameters:

  • home_after (Optional[bool], default: None ) –

    See the home_after parameter of drop_tip().

speed property v2.0 

speed

The speeds (in mm/s) configured for the pipette plunger.

This is an object with attributes aspirate, dispense, and blow_out holding the plunger speeds for the corresponding operation.

Note

Setting values of flow_rate will override the values in speed.

Removed in version 2.14: This property has been removed because it's fundamentally misaligned with the step-wise nature of a pipette's plunger speed configuration. Use flow_rate instead.

starting_tip property v2.0 writable 

starting_tip

Which well of a tip rack the pipette should start at when automatically choosing tips to pick up.

See pick_up_tip().

Note

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 InstrumentContext.pick_up_tip() with no argument. This is fixed for all API levels as of robot software version 7.0.0.

tip_racks property v2.0 writable 

tip_racks

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 pick_up_tip() without arguments. See Picking Up a Tip.

touch_tip v2.0 

touch_tip(location=None, radius=1.0, v_offset=-1.0, speed=60.0, mm_from_edge=_Unset())

Touch the pipette tip to the sides of a well, with the intent of removing leftover droplets.

See Touch Tip for more details and examples.

Parameters:

  • location (Union[`Well`][opentrons.protocol_api.labware.Well], None, default: None ) –

    If no location is passed, the pipette will touch its tip at the edges of the current well.

  • radius (float, default: 1.0 ) –

    How far to move, as a proportion of the target well's radius. When radius=1.0, the pipette tip will move all the way to the edge of the target well. When radius=0.5, it will move to 50% of the well's radius. Default is 1.0 (100%).

  • v_offset (float, default: -1.0 ) –

    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.

  • speed (float, default: 60.0 ) –

    The speed for touch tip motion, in mm/s.

    • Default: 60.0 mm/s
    • Maximum: 80.0 mm/s
    • Minimum: 1.0 mm/s
  • mm_from_edge (float, default: _Unset() ) –

    How far to move inside the well, as a distance from the well's edge. When mm_from_edge=0, the pipette will move to the target well's edge to touch the tip. When mm_from_edge=1, the pipette will move to 1 mm from the target well's edge to touch the tip. Values lower than 0 will press the tip harder into the target well's walls; higher values will touch the well more lightly, or not at all. mm_from_edge and radius are mutually exclusive: to use mm_from_edge, radius must be unspecified (left to its default value of 1.0).

Raises:

  • UnexpectedTipRemovalError –

    If no tip is attached to the pipette.

  • RuntimeError –

    If no location is specified and the location cache is None. This should happen if touch_tip() is called without first calling a method that takes a location, like aspirate() or dispense().

  • ValueError –

    If both mm_from_edge and radius are specified.

Returns:

Changed in version 2.24: Added the mm_from_edge parameter.

transfer v2.0 

transfer(volume, source, dest, trash=True, **kwargs)

Move liquid from one well or group of wells to another.

Transfer is a higher-level command, incorporating other InstrumentContext commands, like aspirate() and dispense(). It makes writing a protocol easier at the cost of specificity. See Complex Commands for details on how transfer and other complex commands perform their component steps.

Parameters:

  • volume (Union[float, Sequence[float]]) –

    The amount, in µL, to aspirate from each source and dispense to each destination. If volume is a list, each amount will be used for the source and destination at the matching index. A list item of 0 will skip the corresponding wells entirely. See List of Volumes for details and examples.

  • source (AdvancedLiquidHandling) –

    A single well or a list of wells to aspirate liquid from.

  • dest (AdvancedLiquidHandling) –

    A single well or a list of wells to dispense liquid into.

Transfer accepts a number of optional parameters that give you greater control over the exact steps it performs. See Complex Liquid Handling Parameters or the links under each argument's entry below for additional details and examples.

Other Parameters:

  • new_tip (str) –

    When to pick up and drop tips during the command. Defaults to "once".

    • "once": Use one tip for the entire command.
    • "always": Use a new tip for each set of aspirate and dispense steps.
    • "never": Do not pick up or drop tips at all.

    See Tip Handling for details.

  • trash (bool) –

    If True (default), the pipette will drop tips in its trash_container. If False, the pipette will return tips to their tip rack.

    See Trash Tips for details.

  • touch_tip (bool) –

    If True, perform a touch_tip() following each aspirate() and dispense(). Defaults to False.

    See Touch Tip for details.

  • blow_out (bool) –

    If True, a blow_out() will occur following each dispense(), but only if the pipette has no liquid left in it. If False (default), the pipette will not blow out liquid.

    See Blow Out for details.

  • blowout_location (str) –

    Accepts one of three string values: "trash", "source well", or "destination well".

    If blow_out is False (its default), this parameter is ignored.

    If blow_out is True and this parameter is not set:

    • Blow out into the trash, if the pipette is empty or only contains the disposal volume.
    • Blow out into the source well, if the pipette otherwise contains liquid.
  • mix_before (tuple) –

    Perform a mix() before each aspirate() during the transfer. The first value of the tuple is the number of repetitions, and the second value is the amount of liquid to mix in µL.

    See Mix Before for details.

  • mix_after (tuple) –

    Perform a mix() after each dispense() during the transfer. The first value of the tuple is the number of repetitions, and the second value is the amount of liquid to mix in µL.

    See Mix After for details.

  • disposal_volume (float) –

    Transfer ignores the numeric value of this parameter. If set, the pipette will not aspirate additional liquid, but it will perform a very small blow out after each dispense.

    See Disposal Volume for details.

Returns:

transfer_with_liquid_class v2.24 

transfer_with_liquid_class(liquid_class, volume, source, dest, new_tip='once', trash_location=None, return_tip=False, group_wells=True, keep_last_tip=None, tip_racks=None, tips=None)

Move a particular type of liquid from one well or group of wells to another.

Parameters:

  • liquid_class (LiquidClass) –

    The type of liquid to move. You must specify the liquid class, even if you have used Labware.load_liquid() to indicate what liquid the source contains.

  • volume (float) –

    The amount, in µL, to aspirate from each source and dispense to each destination.

  • source (Union[Well, Sequence[Well], Sequence[Sequence[Well]]]) –

    A single well or a list of wells to aspirate liquid from.

  • dest (Union[Well, Sequence[Well], TrashBin, WasteChute]) –

    A single well, list of wells, trash bin, or waste chute to dispense liquid into.

  • new_tip (str, default: 'once' ) –

    When to pick up and drop tips during the command. Defaults to "once".

    • "once": Use one tip for the entire command.
    • "always": Use a new tip for each set of aspirate and dispense steps.
    • "per source": Use one tip for each source well, even if tip refilling is required.
    • "per destination": Use one tip for each destination well, even if tip refilling is required.
    • "never": Do not pick up or drop tips at all.

    See Tip Handling for details.

  • trash_location (Union[Location, Well, TrashBin, WasteChute], default: None ) –

    A trash container, well, or other location to dispose of tips. Depending on the liquid class, the pipette may also blow out liquid here. If not specified, the pipette will dispose of tips in its trash_container.

  • return_tip (bool, default: False ) –

    Whether to drop used tips in their original locations in the tip rack, instead of the trash.

  • group_wells (bool, default: True ) –

    For multi-channel transfers only. If set to True, group together contiguous wells given into a single transfer step, taking into account the tip configuration. If False, target each well given with the primary nozzle. Defaults to True.

  • keep_last_tip (bool, default: None ) –

    When True, the pipette keeps the last tip used in the transfer attached. When False, the last tip will be dropped or returned. If not set, behavior depends on the value of new_tip. new_tip="never" keeps the tip, and all other values of new_tip drop or return the tip.

  • tip_racks (List[Labware], default: None ) –

    A list of tip racks to pick up from for this command. If not provided, the pipette will pick up from its associated tip_racks. Providing this argument does not change the value of InstrumentContext.tip_racks.

  • tips (Union[Sequence[Well], Sequence[Sequence[Well]]], default: None ) –

    An ordered list of tips to use for the transfer. If the list contains fewer tips than needed to complete the transfer, the API will raise an error. The pipette will use only these tips even if InstrumentContext.tip_racks or the tip_racks parameter of this method is set.

New in version 2.25: Added the tip_racks parameter.

New in version 2.27: Added the tips parameter.

trash_container property v2.0 writable 

trash_container

The trash container associated with this pipette.

This is the property used to determine where to drop tips and blow out liquids when calling drop_tip() or blow_out() without arguments.

You can set this to a Labware, TrashBin, or WasteChute.

The default value depends on the robot type and API version:

Changed in version 2.16: Added support for TrashBin and WasteChute objects.

type property v2.0 

type

'single' if this is a 1-channel pipette, or 'multi' otherwise.

See also channels, which can distinguish between 8-channel and 96-channel pipettes.

well_bottom_clearance property v2.0 

well_bottom_clearance

The distance above the bottom of a well to aspirate or dispense.

This is an object with attributes aspirate and dispense, describing the default height of the corresponding operation. The default is 1.0 mm for both aspirate and dispense.

When aspirate() or dispense() is given a Well rather than a full Location, the robot will move this distance above the bottom of the well to aspirate or dispense.

To change, set the corresponding attribute:

pipette.well_bottom_clearance.aspirate = 2