science_jubilee.tools.Pipette#

Attributes#

logger

Exceptions#

`ToolConfigurationError`	Raise this error if there is something wrong with how the tool is configured
`ToolStateError`	Raise this error if the tool is in the wrong state to perform such a command.

Classes#

`Labware`	A class representing a basic laboratory labware made up of a set of wells/pipette tips.
`Location`	A location to target as a motion.
`Well`	A class representing a well of a labware.
`Tool`
`Pipette`	A class representation of an Opentrons OT2 pipette.
`TipTracker`	A class to track the usage of pipette tips and their location in the tiprack

Functions#

`requires_active_tool`(func)	Decorator to ensure that a tool cannot complete an action unless it is the
`tip_check`(func)	Decorator to check if the pipette has a tip attached before performing an action.

Module Contents#

class science_jubilee.tools.Pipette.Labware(labware_filename: str, offset: Tuple[float] = None, order: str = 'rows', path: str = os.path.join(os.path.dirname(__file__), 'labware_definition'))[source]#

Bases: WellSet

A class representing a basic laboratory labware made up of a set of wells/pipette tips.

Parameters:

labware_filename (str) – The name of the config .json
offset (Tuple[float], optional) – Coordinates to use to offset all the wells in a labware for easier handling of coordinates. For example this is called by the :method:`Deck.load_labware` when assignign a labware to a deck slot, defaults to None
order (str, optional) – Option to order the wells of a labware either by row or columns, defaults to ‘rows’
path (str, optional) – Path to the folder containing the configuration .json files for the labware, defaults to the ‘labware_definition/’ in the science_jubilee/labware directory.

__repr__()[source]#: Displayed representation of a Labware object indicating the type of labware and its name. Additionally, it will show the :attribute:`Deck.slots` number if the labware has been already assigned to it.

_create_rows_and_columns()[source]#

Creates a dictionary of Row and Column and Well objects from the data in the config .json file.

Returns:: A dictionary of Row and Column and Well objects
Return type:: Row, Column, Well

get_row(row_id: str) → Row[source]#

Fucntions to fetch the Well.name of the indicated row.

Parameters:: row_id (str) – The name of a row of the labware, usually indicated by a capital letter (e.g., A, B, etc.)
Returns:: A list of Well objects diplayed by their :attribute:`Well.name`
Return type:: Row

get_column(col_id: int) → Column[source]#

Fucntions to fetch the Well.name of the indicated column.

Parameters:: col_id (str) – The name of a column of the labware, usually indicated by an integer number (e.g., 1, 2, etc.)
Returns:: A list of Well objects diplayed by their :attribute:`Well.name`
Return type:: Column

property shape#

Returns the shape of the labware as a tuple of (rows, columns)

Returns:: A tuple of (rows, columns)
Return type:: Tuple[int, int]

property ordering: List[List[str]]#

Returns the ordering of the wells in the labware as a list of lists. Each list represents a row of the labware.

Returns:: A list of lists of Well.name objects
Return type:: List[List[str]]

property brand: dict#

Returns the brand of the labware as a strin

Returns:: A string with the brand of the labware
Return type:: str

metadata() → dict[source]#

Returns the metadata of the labware as a dictionary

The metadata of a labware will generally contain the display name, the type of labware, and the units of volume. These can also be found as attributes of the Labware object.

Returns:: A dictionary with the metadata of the labware
Return type:: dict

property display_name#

Returns the display name of the labware as a string

Returns:: A string with the display name of the labware
Return type:: str

property labware_type#

Returns the type of labware as a string

The type fo labware will generally either be a tiprack, wellplate, reservoir, etc.

Returns:: A string with the type of labware
Return type:: str

property volume_units#

Returns the units of volume of the labware as a string

The volume units will be either uL or mL.

Returns:: A string with the units of volume of the labware
Return type:: str

property dimensions: dict#

Returns the dimensions of the labware as a dictionary

Returns:: A dictionary with the x,y, and z dimensions of the labware
Return type:: dict

parameters() → dict[source]#

Returns the parameters describing certain features of the labware as a dictionary

The parameters genereally include whether the shape of the labware is regular or irregular, if it is a tiprack, and other Opentrons specific parameters as we are using their ‘Custom Labware Page’ to generate the .json config files.

Returns:: A dictionary with the parameters of the labware
Return type:: dict

property is_tip_rack#

Returns a boolean indicating if the labware is a tiprack

Returns:: True if the labware is a tiprack, False otherwise
Return type:: bool

property load_name#

Returns the name of the labware as a string

Returns:: A string with the name of the labware
Return type:: str

property tip_length#

Returns the length of the tip of the labware as a float if the labware is a tiprack, otherwise returns None

Returns:: A float with the length of the tip of the labware or None otherwise
Return type:: float

property tip_overlap#

Returns the overlap of the tip of the labware as a float if the labware is a tiprack, otherwise returns None

Returns:: A float with the overlap of the tip of the labware or None otherwise
Return type:: float

property offset#

Returns the offset of the labware as a tuple of floats

Returns:: A tuple of floats with the offset of the labware
Return type:: Tuple[float]

add_slot(slot_)[source]#

Add name of deck slot after labware has been loaded

Parameters:: slot (str) – The name of the deck slot

withWellOrder(order) → list[source]#

Reorders the wells by rows or by columns. Automatically updates the :attribute:`Labware.wells`

Parameters:: order (str) – The order in which to reorder the wells. Can be either ‘rows’ or ‘columns’
Returns:: A list of Well objects diplayed by their :attribute:`Well.name`
Return type:: list

_translate_point(well: Well, theta: float, x_space: float, y_space: float, upper_left: Tuple[float])[source]#

Helper function to translate the coordinates of a well by a given angle theta.

Parameters:

well (Well) – A Well object
theta (float) – The angle by which to translate the coordinates of the well

Returns:

The new x and y coordinates of the well

Return type:

float, float

static _nominal_coordinates(well: Well, x_space: float, y_space: float)[source]#: Helper function to calculate the nominal coordinates of a well in a labware based on its row and column index.

manual_offset(corner_wells: List[Tuple[float]], save: bool = False)[source]#

Allows the user to manually offset the coordinates of the labware based on three corner wells.

Adapted from https://github.com/machineagency/sonication_station labware calibration procedure.

Parameters:

offset (Tuple[float]) – A list containing tuples of floats
save (bool, optional) – Option to save the manual offset to the original config .json file, defaults to False

Returns:

An updated Labware object with the new coordinates of the wells

Return type:

Labware

load_manualOffset(apply: bool = True)[source]#

Loads the manual offset of a labware from its config .json file for a specific slot

Parameters:: apply (bool, optional) – Option to apply the manual offset to the labware or return values, defaults to False
Returns:: A list of tuples containing the manual offset of the labware
Return type:: List[Tuple[float]]

static _getxyz(location: Well | Tuple | Location)[source]#

Helper function to extract the x, y, z coordinates of a location object.

Parameters:: location (Union[Well, Tuple, Location]) – The location object to extract the coordinates from. This can either be a Well, a :tuple: of x, y, z coordinates, or a Location object
Raises:: ValueError – If the location is not a Well, a tuple, or a Location object
Returns:: The x, y, z coordinates of the location
Return type:: float, float, float

class science_jubilee.tools.Pipette.Location(point: Point, labware: Well | Labware)[source]#

A location to target as a motion.

The location contains a Point and possibly an associated Labware or Well instance.

property point: Point#

The coordinates (x,y,z) of a Well or a Labware

Returns:: A tuple of coordinates (x,y,z)
Return type:: Point

property labware#

The :class:`Well` object associated with the coordinates (x,y,z)

Returns:: A Well object
Return type:: Well

__iter__() → Iterable[Point | Well | Labware][source]#

Iterable interface to support unpacking of Location objects.

Returns:: An interable of Location objects
Return type:: Iterable[Union[Point, Well, Labware]]

__eq__(other: object) → bool[source]#

Comparison between two Location objects.

Parameters:: other (Location) – A Location object
Returns:: True if the two Location objects are equal, False otherwise
Return type:: bool

__repr__() → str[source]#

Returns a string representation of the Location object.

Returns:: A string representation of the Location object
Return type:: str

class science_jubilee.tools.Pipette.Well[source]#

A class representing a well of a labware.

Each Well is associated with a specific name, depth, total liquid volume, shape, diameter, x, y, and z dimension, y-dimension, as well as its coordinates and any applied offset

Returns:: A Well object with various information about the geometry of the well and its position in the labware
Return type:: Well

name: str#

depth: float#

totalLiquidVolume: float#

shape: str#

diameter: float = None#

xDimension: float = None#

yDimension: float = None#

x: float#

y: float#

z: float#

offset: Tuple[float] = None#

slot: int = None#

has_tip: bool = False#

clean_tip: bool = False#

labware_name: str = None#

property x#

Offsets the x-position of the each well with respect to the deck-slot coordinates

Returns:: The x-coordinate of the well
Return type:: float

property y#

Offsets the y-position of the each well with respect to the deck-slot coordinates

Returns:: The y-coordinate of the well
Return type:: float

property z#

Offsets the z-position of each well with respect to the deck-slot coordinates

Returns:: The z-coordinate of the well
Return type:: float

apply_offset(offset: Tuple[float])[source]#

Allows the user to offset the coordinates of the well with respect to the deck-slot coordinates

Parameters:: offset (Tuple[float]) – A tuple of floats with the new offset of the well

property top_#

Defines the top-most point of the well

Returns:: The z-coordinate of the top of the well
Return type:: float

property bottom_#

Defines the bottom-most point of the well

Returns:: The z-coordinate of the bottom of the well
Return type:: float

bottom(z: float, check=False)[source]#

Allows the user to dinamically indicate a new Z location relative to the bottom of the well.

Parameters:

z (float) – the distance in mm to offset the coordinates from the bottom of the well. Should be +
check (bool, optional) – the ‘z’ parameters can either be + or -. If negative, an assert error is raised to avoid collision with the labware. However, there might be instances of custom labware where the bottom of the well is purposely set as higher during the generation of its config .json file., defaults to False

Returns:

A Location which contains information about the new coordinates generated and the Well object

Return type:

Location

top(z: float)[source]#

Allows the user to dinamically indicate a new Z location relative to the top of the well.

Parameters:: z (float) – the distance in mm to offset the coordinates from the top of the well.Can be either + or -
Returns:: A Location which contains information about the new coordinates generated and the Well object.
Return type:: Location

__repr__()[source]#

Displayed representation of a Well object indicating its name and its coordinates

Returns:: A string representation of the name and coordinates of a well
Return type:: str

set_has_tip(value: bool)[source]#

Set the value of the has_tip attribute.

Parameters:: value (bool) – The new value for the has_tip attribute

set_clean_tip(value: bool)[source]#

Returns the value of the clean_tip attribute.

Parameters:: value (bool) – The new value for the clean_tip attribute

class science_jubilee.tools.Pipette.Tool(index, name, **kwargs)[source]#

post_load()[source]#: Run any code after tool has been associated with the machine.

exception science_jubilee.tools.Pipette.ToolConfigurationError[source]#

Bases: Exception

Raise this error if there is something wrong with how the tool is configured

exception science_jubilee.tools.Pipette.ToolStateError[source]#

Bases: Exception

Raise this error if the tool is in the wrong state to perform such a command.

science_jubilee.tools.Pipette.requires_active_tool(func)[source]#: Decorator to ensure that a tool cannot complete an action unless it is the current active tool.

science_jubilee.tools.Pipette.logger[source]#

science_jubilee.tools.Pipette.tip_check(func)[source]#: Decorator to check if the pipette has a tip attached before performing an action.

class science_jubilee.tools.Pipette.Pipette(index, name, brand, model, max_volume, min_volume, zero_position, blowout_position, drop_tip_position, mm_to_ul)[source]#

Bases: science_jubilee.tools.Tool.Tool

A class representation of an Opentrons OT2 pipette.

classmethod from_config(index, name, config_file: str, path: str = os.path.join(os.path.dirname(__file__), 'configs'))[source]#

Initialize the pipette object from a config file

Parameters:

index (int) – The tool index of the pipette on the machine
name (str) – The tool name
config_file (str) – The name of the config file containign the pipette parameters
path – The path to the labware configuration .json files for the labware, defaults to the ‘labware_definition/’ in the science_jubilee/labware directory.

Returns:

A Pipette object

Return type:

Pipette

post_load()[source]#: Prime the Pipette after loading it onto the Machine sot hat it is ready to use

vol2move(vol)[source]#

Converts desired volume in uL to a movement of the pipette motor axis

Parameters:: vol (float) – The desired amount of liquid expressed in uL
Returns:: The corresponding motor movement in mm
Return type:: float

prime(s=2500)[source]#

Moves the plunger to the low-point on the pipette motor axis to prepare for further commands Note::This position should not engage the pipette tip plunger

Parameters:: s (int) – The speed of the plunger movement in mm/min

_aspirate(vol: float, s: int = 2000)[source]#

Moves the plunger upwards to aspirate liquid into the pipette tip

Parameters:

vol (float) – The volume of liquid to aspirate in uL
s (int) – The speed of the plunger movement in mm/min

aspirate(vol: float, location: science_jubilee.labware.Labware.Well | Tuple | science_jubilee.labware.Labware.Location, s: int = 2000)[source]#

Moves the pipette to the specified location and aspirates the desired volume of liquid

Parameters:

vol (float) – The volume of liquid to aspirate in uL
location (Union[Well, Tuple, Location]) – The location from where to aspirate the liquid from.
s (int, optional) – The speed of the plunger movement in mm/min, defaults to 2000

Raises:

ToolStateError – If the pipette does not have a tip attached

_dispense(vol: float, s: int = 2000)[source]#

Moves the plunger downwards to dispense liquid out of the pipette tip

Parameters:

vol (float) – The volume of liquid to dispense in uL
s (int) – The speed of the plunger movement in mm/min

Note:: Ideally the user does not call this functions directly, but instead uses the :method:`dispense` method

dispense(vol: float, location: science_jubilee.labware.Labware.Well | Tuple | science_jubilee.labware.Labware.Location, s: int = 2000)[source]#

Moves the pipette to the specified location and dispenses the desired volume of liquid

Parameters:

vol (float) – The volume of liquid to dispense in uL
location (Union[Well, Tuple, Location]) – The location to dispense the liquid into.
s (int, optional) – The speed of the plunger movement in mm/min, defaults to 2000

Raises:

ToolStateError – If the pipette does not have a tip attached

transfer(vol: float | list[float], source_well: science_jubilee.labware.Labware.Well | Tuple | science_jubilee.labware.Labware.Location, destination_well: science_jubilee.labware.Labware.Well | Tuple | science_jubilee.labware.Labware.Location, s: int = 3000, blowout=None, mix_before: tuple = None, mix_after: tuple = None, air_gap: float = 0, new_tip: str = 'always')[source]#

Transfers the desired volume of liquid from the source well to the destination well

This is a combination of the :method:`aspirate` and :method:`dispense` steps.

Parameters:

vol (float) – The volume of liquid to transfer in uL
source_well (Union[Well, Tuple, Location]) – The location from where to aspirate the liquid from.
destination_well (Union[Well, Tuple, Location]) – The location to dispense the liquid into.
s (int, optional) – The speed of the plunger movement in mm/min, defaults to 3000
blowout (Union[Well, Tuple, Location], optional) – The location to blowout any remainign liquid in the pipette tip
mix_before (tuple, optional) – The number of times to mix before dispensing and the volume to mix
mix_after (tuple, optional) – The number of times to mix after dispensing and the volume to mix
new_tip (str, optional) – Whether or not to use a new tip for the transfer. Can be ‘always’, ‘never’, or ‘once’
air_gap (float, optional) – The volume of air to aspirate after aspirating the liquid, defaults to None

Note:: :param new_tip: still not implemented at the moment (2023-11-16)

_create_volume_list(volume, total_xfers)[source]#

Creates a list of volumes to transfer

Parameters:

volume (Union[float, list[float]]) – The volume of liquid to transfer
total_xfers (int) – The total number of transfer steps to perform

Returns:

A list of volumes to transfer

Note: This function was taken from the Opentrons API and modified to work with the Pipette class of Science_Jubilee

static _extend_source_target_lists(sources: List[science_jubilee.labware.Labware.Well | science_jubilee.labware.Labware.Location], targets: List[science_jubilee.labware.Labware.Well | science_jubilee.labware.Labware.Location])[source]#

Extend source or target list to match the length of the other

Parameters:

sources (List[Union[Well, Location]]) – The list of source wells
targets (List[Union[Well, Location]]) – The list of target wells

Returns:

The extended source and target lists

Return type:

Tuple[List[Union[Well, Location]], List[Union[Well, Location]]]

Note: This function was taken from the Opentrons API and modified to work with the Pipette class of Science_Jubilee

static _expand_for_volume_contraints(volumes: Iterator[float], targets: Iterator, max_volume: float)[source]#

Expands the volumes and targets to ensure that the volume does not exceed the maximum volume of the pipette

Parameters:

volumes (Iterator[float]) – An iterator of the volumes to transfer
targets (Iterator) – An iterator of the targets to transfer the volumes to
max_volume (float) – The maximum volume of the pipette in uL

Returns:

An iterator of the volumes and targets to transfer

Return type:

Iterator

Note: This function was taken from the Opentrons API and modified to work with the Pipette class of Science_Jubilee

blowout(s: int = 6000)[source]#

Blows out any remaining liquid in the pipette tip

Parameters:: s (int, optional) – The speed of the plunger movement in mm/min, defaults to 3000

air_gap(vol)[source]#

Moves the plunger upwards to aspirate air into the pipette tip

Parameters:: vol (float) – The volume of air to aspirate in uL

mix(vol: float, n: int, s: int = 5500)[source]#

Mixes liquid by alternating aspirate and dispense steps for the specified number of times

Parameters:

vol (float) – The volume of liquid to mix in uL
n (int) – The number of times to mix
s (int, optional) – The speed of the plunger movement in mm/min, defaults to 5000

stir(n_times: int = 1, height: float = None)[source]#

Stirs the liquid in the current well by moving the pipette tip in a circular motion

Parameters:

n_times (int, optional) – The number of times to stir the liquid, defaults to 1
height (float, optional) – The z-coordinate to move the tip to during the stir step, defaults to None

Raises:

ToolStateError – If the pipette does not have a tip attached before stirring or if the pipette is not in a well

update_z_offset(tip: bool = None)[source]#

Shift the z-offset of the tool to account for the tip length

Parameters:: tip (bool, optional) – Parameter to indicated whether to add or remove the tip offset, defaults to None

add_tiprack(tiprack: science_jubilee.labware.Labware.Labware | list)[source]#

Associate a tiprack with the pipette tool

Parameters:: tiprack (Union[Labware, list]) – The tiprack to associate with the pipette

_pickup_tip(z)[source]#

Moves the Jubilee Z-axis upwards to pick up a pipette tip and stops once the tip sensor is triggered

Parameters:: z (float) – The z-coordinate to move the pipette to
Raises:: ToolStateError – If the pipette already has a tip attached

pickup_tip(tip_: science_jubilee.labware.Labware.Well | Tuple = None)[source]#

Moves the pipette to the specified location and picks up a tip

This function can either take a specific tip or if not specified, will pick up the next available tip in the tiprack associated with the pipette.

Parameters:: tip (Union[Well, Tuple], optional) – The location of the pipette tip to pick up, defaults to None

return_tip(location: science_jubilee.labware.Labware.Well = None)[source]#

Returns the pipette tip to the either the specified location or to where the tip was picked up from

Parameters:: location (Well, optional) – The location to return the tip to, defaults to None (i.e. return to where the tip was picked up from)

_drop_tip()[source]#

Moves the plunger to eject the pipette tip

Raises:: ToolConfigurationError – If the pipette does not have a tip attached

drop_tip(location: science_jubilee.labware.Labware.Well | Tuple = None)[source]#

Moves the pipette to the specified location and drops the pipette tip

Parameters:: location (Union[Well, tuple]) – The location to drop the tip into

class science_jubilee.tools.Pipette.TipTracker(tips, start_well=None)[source]#

A class to track the usage of pipette tips and their location in the tiprack

Parameters:

tips (list[Well]) – The list of tips in the tiprack
start_well (Well, optional) – The starting well to begin tracking the tips from, defaults to None

Note: This function was taken from the Opentrons API and modified to work with the Pipette class of Science_Jubilee

next_tip(start_well=None)[source]#

use_tip(tip_well)[source]#

previous_tip()[source]#

return_tip(well=None)[source]#

assign_tip_to_stock(tip_well, stock_well)[source]#