science_jubilee.tools.Pipette ============================= .. py:module:: science_jubilee.tools.Pipette Attributes ---------- .. autoapisummary:: science_jubilee.tools.Pipette.logger Exceptions ---------- .. autoapisummary:: science_jubilee.tools.Pipette.ToolConfigurationError science_jubilee.tools.Pipette.ToolStateError Classes ------- .. autoapisummary:: science_jubilee.tools.Pipette.Labware science_jubilee.tools.Pipette.Location science_jubilee.tools.Pipette.Well science_jubilee.tools.Pipette.Tool science_jubilee.tools.Pipette.Pipette science_jubilee.tools.Pipette.TipTracker Functions --------- .. autoapisummary:: science_jubilee.tools.Pipette.requires_active_tool science_jubilee.tools.Pipette.tip_check Module Contents --------------- .. py:class:: Labware(labware_filename: str, offset: Tuple[float] = None, order: str = 'rows', path: str = os.path.join(os.path.dirname(__file__), 'labware_definition')) Bases: :py:obj:`WellSet` A class representing a basic laboratory labware made up of a set of wells/pipette tips. :param labware_filename: The name of the config `.json` :type labware_filename: str :param offset: 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 :type offset: Tuple[float], optional :param order: Option to order the wells of a labware either by `row` or `columns`, defaults to 'rows' :type order: str, optional :param path: Path to the folder containing the configuration `.json` files for the labware, defaults to the 'labware_definition/' in the science_jubilee/labware directory. :type path: str, optional .. py:method:: __repr__() Displayed representation of a :class:`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. .. py:method:: _create_rows_and_columns() Creates a dictionary of :class:`Row` and :class:`Column` and :class:`Well` objects from the data in the config `.json` file. :return: A dictionary of :class:`Row` and :class:`Column` and :class:`Well` objects :rtype: :class:`Row`, :class:`Column`, :class:`Well` .. py:method:: get_row(row_id: str) -> Row Fucntions to fetch the :class:`Well.name` of the indicated row. :param row_id: The name of a row of the labware, usually indicated by a capital letter (e.g., A, B, etc.) :type row_id: str :return: A list of :class:`Well` objects diplayed by their :attribute:`Well.name` :rtype: :class:`Row` .. py:method:: get_column(col_id: int) -> Column Fucntions to fetch the :class:`Well.name` of the indicated column. :param col_id: The name of a column of the labware, usually indicated by an integer number (e.g., 1, 2, etc.) :type col_id: str :return: A list of :class:`Well` objects diplayed by their :attribute:`Well.name` :rtype: :class:`Column` .. py:property:: shape Returns the shape of the labware as a tuple of (rows, columns) :return: A tuple of (rows, columns) :rtype: Tuple[int, int] .. py:property:: ordering :type: 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. :return: A list of lists of :class:`Well.name` objects :rtype: List[List[str]] .. py:property:: brand :type: dict Returns the brand of the labware as a strin :return: A string with the brand of the labware :rtype: str .. py:method:: metadata() -> dict 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 :class:`Labware` object. :return: A dictionary with the metadata of the labware :rtype: dict .. py:property:: display_name Returns the display name of the labware as a string :return: A string with the display name of the labware :rtype: str .. py:property:: labware_type Returns the type of labware as a string The type fo labware will generally either be a tiprack, wellplate, reservoir, etc. :return: A string with the type of labware :rtype: str .. py:property:: volume_units Returns the units of volume of the labware as a string The volume units will be either uL or mL. :return: A string with the units of volume of the labware :rtype: str .. py:property:: dimensions :type: dict Returns the dimensions of the labware as a dictionary :return: A dictionary with the x,y, and z dimensions of the labware :rtype: dict .. py:method:: parameters() -> dict 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. :return: A dictionary with the parameters of the labware :rtype: dict .. py:property:: is_tip_rack Returns a boolean indicating if the labware is a tiprack :return: True if the labware is a tiprack, False otherwise :rtype: bool .. py:property:: load_name Returns the name of the labware as a string :return: A string with the name of the labware :rtype: str .. py:property:: tip_length Returns the length of the tip of the labware as a float if the labware is a tiprack, otherwise returns None :return: A float with the length of the tip of the labware or None otherwise :rtype: float .. py:property:: tip_overlap Returns the overlap of the tip of the labware as a float if the labware is a tiprack, otherwise returns None :return: A float with the overlap of the tip of the labware or None otherwise :rtype: float .. py:property:: offset Returns the offset of the labware as a tuple of floats :return: A tuple of floats with the offset of the labware :rtype: Tuple[float] .. py:method:: add_slot(slot_) Add name of deck slot after labware has been loaded :param slot_: The name of the deck slot :type slot_: str .. py:method:: withWellOrder(order) -> list Reorders the wells by rows or by columns. Automatically updates the :attribute:`Labware.wells` :param order: The order in which to reorder the wells. Can be either 'rows' or 'columns' :type order: str :return: A list of :class:`Well` objects diplayed by their :attribute:`Well.name` :rtype: list .. py:method:: _translate_point(well: Well, theta: float, x_space: float, y_space: float, upper_left: Tuple[float]) Helper function to translate the coordinates of a well by a given angle theta. :param well: A :class:`Well` object :type well: :class:`Well` :param theta: The angle by which to translate the coordinates of the well :type theta: float :return: The new x and y coordinates of the well :rtype: float, float .. py:method:: _nominal_coordinates(well: Well, x_space: float, y_space: float) :staticmethod: Helper function to calculate the nominal coordinates of a well in a labware based on its row and column index. .. py:method:: manual_offset(corner_wells: List[Tuple[float]], save: bool = False) 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. :param offset: A list containing tuples of floats :type offset: Tuple[float] :param save: Option to save the manual offset to the original config `.json` file, defaults to False :type save: bool, optional :return: An updated :class:`Labware` object with the new coordinates of the wells :rtype: :class:`Labware` .. py:method:: load_manualOffset(apply: bool = True) Loads the manual offset of a labware from its config `.json` file for a specific slot :param apply: Option to apply the manual offset to the labware or return values, defaults to False :type apply: bool, optional :return: A list of tuples containing the manual offset of the labware :rtype: List[Tuple[float]] .. py:method:: _getxyz(location: Union[Well, Tuple, Location]) :staticmethod: Helper function to extract the x, y, z coordinates of a location object. :param location: The location object to extract the coordinates from. This can either be a :class:`Well`, a :tuple: of x, y, z coordinates, or a :class:`Location` object :type location: Union[Well, Tuple, Location] :raises ValueError: If the location is not a :class:`Well`, a :class:`tuple`, or a :class:`Location` object :return: The x, y, z coordinates of the location :rtype: float, float, float .. py:class:: Location(point: Point, labware: Union[Well, Labware]) A location to target as a motion. The location contains a :class:`Point` and possibly an associated :class:`Labware` or :class:`Well` instance. .. py:property:: point :type: Point The coordinates (x,y,z) of a Well or a Labware :return: A tuple of coordinates (x,y,z) :rtype: :class:`Point` .. py:property:: labware The :class:`Well` object associated with the coordinates (x,y,z) :return: A :class:`Well` object :rtype: :class:`Well` .. py:method:: __iter__() -> Iterable[Union[Point, Well, Labware]] Iterable interface to support unpacking of :class:`Location` objects. :return: An interable of :class:`Location` objects :rtype: Iterable[Union[Point, Well, Labware]] .. py:method:: __eq__(other: object) -> bool Comparison between two :class:`Location` objects. :param other: A :class:`Location` object :type other: :class:`Location` :return: True if the two :class:`Location` objects are equal, False otherwise :rtype: bool .. py:method:: __repr__() -> str Returns a string representation of the :class:`Location` object. :return: A string representation of the :class:`Location` object :rtype: str .. py:class:: Well 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 :return: A :class:`Well` object with various information about the geometry of the well and its position in the labware :rtype: :class:`Well` .. py:attribute:: name :type: str .. py:attribute:: depth :type: float .. py:attribute:: totalLiquidVolume :type: float .. py:attribute:: shape :type: str .. py:attribute:: diameter :type: float :value: None .. py:attribute:: xDimension :type: float :value: None .. py:attribute:: yDimension :type: float :value: None .. py:attribute:: x :type: float .. py:attribute:: y :type: float .. py:attribute:: z :type: float .. py:attribute:: offset :type: Tuple[float] :value: None .. py:attribute:: slot :type: int :value: None .. py:attribute:: has_tip :type: bool :value: False .. py:attribute:: clean_tip :type: bool :value: False .. py:attribute:: labware_name :type: str :value: None .. py:property:: x Offsets the x-position of the each well with respect to the deck-slot coordinates :return: The x-coordinate of the well :rtype: float .. py:property:: y Offsets the y-position of the each well with respect to the deck-slot coordinates :return: The y-coordinate of the well :rtype: float .. py:property:: z Offsets the z-position of each well with respect to the deck-slot coordinates :return: The z-coordinate of the well :rtype: float .. py:method:: apply_offset(offset: Tuple[float]) Allows the user to offset the coordinates of the well with respect to the deck-slot coordinates :param offset: A tuple of floats with the new offset of the well :type offset: Tuple[float] .. py:property:: top_ Defines the top-most point of the well :return: The z-coordinate of the top of the well :rtype: float .. py:property:: bottom_ Defines the bottom-most point of the well :return: The z-coordinate of the bottom of the well :rtype: float .. py:method:: bottom(z: float, check=False) Allows the user to dinamically indicate a new Z location relative to the bottom of the well. :param z: the distance in mm to offset the coordinates from the bottom of the well. Should be + :type z: float :param check: 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 :type check: bool, optional :return: A :class:`Location` which contains information about the new coordinates generated and the :class:`Well` object :rtype: :class:`Location` .. py:method:: top(z: float) Allows the user to dinamically indicate a new Z location relative to the top of the well. :param z: the distance in mm to offset the coordinates from the top of the well.Can be either + or - :type z: float :return: A :class:`Location` which contains information about the new coordinates generated and the :class:`Well` object. :rtype: :class:`Location` .. py:method:: __repr__() Displayed representation of a :class:`Well` object indicating its name and its coordinates :return: A string representation of the name and coordinates of a well :rtype: str .. py:method:: set_has_tip(value: bool) Set the value of the `has_tip` attribute. :param value: The new value for the `has_tip` attribute :type value: bool .. py:method:: set_clean_tip(value: bool) Returns the value of the `clean_tip` attribute. :param value: The new value for the `clean_tip` attribute :type value: bool .. py:class:: Tool(index, name, **kwargs) .. py:method:: post_load() Run any code after tool has been associated with the machine. .. py:exception:: ToolConfigurationError Bases: :py:obj:`Exception` Raise this error if there is something wrong with how the tool is configured .. py:exception:: ToolStateError Bases: :py:obj:`Exception` Raise this error if the tool is in the wrong state to perform such a command. .. py:function:: requires_active_tool(func) Decorator to ensure that a tool cannot complete an action unless it is the current active tool. .. py:data:: logger .. py:function:: tip_check(func) Decorator to check if the pipette has a tip attached before performing an action. .. py:class:: Pipette(index, name, brand, model, max_volume, min_volume, zero_position, blowout_position, drop_tip_position, mm_to_ul) Bases: :py:obj:`science_jubilee.tools.Tool.Tool` A class representation of an Opentrons OT2 pipette. .. py:method:: from_config(index, name, config_file: str, path: str = os.path.join(os.path.dirname(__file__), 'configs')) :classmethod: Initialize the pipette object from a config file :param index: The tool index of the pipette on the machine :type index: int :param name: The tool name :type name: str :param config_file: The name of the config file containign the pipette parameters :type config_file: str :param 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 :class:`Pipette` object :rtype: :class:`Pipette` .. py:method:: post_load() Prime the Pipette after loading it onto the Machine sot hat it is ready to use .. py:method:: vol2move(vol) Converts desired volume in uL to a movement of the pipette motor axis :param vol: The desired amount of liquid expressed in uL :type vol: float :return: The corresponding motor movement in mm :rtype: float .. py:method:: prime(s=2500) 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 :param s: The speed of the plunger movement in mm/min :type s: int .. py:method:: _aspirate(vol: float, s: int = 2000) Moves the plunger upwards to aspirate liquid into the pipette tip :param vol: The volume of liquid to aspirate in uL :type vol: float :param s: The speed of the plunger movement in mm/min :type s: int .. py:method:: aspirate(vol: float, location: Union[science_jubilee.labware.Labware.Well, Tuple, science_jubilee.labware.Labware.Location], s: int = 2000) Moves the pipette to the specified location and aspirates the desired volume of liquid :param vol: The volume of liquid to aspirate in uL :type vol: float :param location: The location from where to aspirate the liquid from. :type location: Union[Well, Tuple, Location] :param s: The speed of the plunger movement in mm/min, defaults to 2000 :type s: int, optional :raises ToolStateError: If the pipette does not have a tip attached .. py:method:: _dispense(vol: float, s: int = 2000) Moves the plunger downwards to dispense liquid out of the pipette tip :param vol: The volume of liquid to dispense in uL :type vol: float :param s: The speed of the plunger movement in mm/min :type s: int Note:: Ideally the user does not call this functions directly, but instead uses the :method:`dispense` method .. py:method:: dispense(vol: float, location: Union[science_jubilee.labware.Labware.Well, Tuple, science_jubilee.labware.Labware.Location], s: int = 2000) Moves the pipette to the specified location and dispenses the desired volume of liquid :param vol: The volume of liquid to dispense in uL :type vol: float :param location: The location to dispense the liquid into. :type location: Union[Well, Tuple, Location] :param s: The speed of the plunger movement in mm/min, defaults to 2000 :type s: int, optional :raises ToolStateError: If the pipette does not have a tip attached .. py:method:: transfer(vol: Union[float, list[float]], source_well: Union[science_jubilee.labware.Labware.Well, Tuple, science_jubilee.labware.Labware.Location], destination_well: Union[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') 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. :param vol: The volume of liquid to transfer in uL :type vol: float :param source_well: The location from where to aspirate the liquid from. :type source_well: Union[Well, Tuple, Location] :param destination_well: The location to dispense the liquid into. :type destination_well: Union[Well, Tuple, Location] :param s: The speed of the plunger movement in mm/min, defaults to 3000 :type s: int, optional :param blowout: The location to blowout any remainign liquid in the pipette tip :type blowout: Union[Well, Tuple, Location], optional :param mix_before: The number of times to mix before dispensing and the volume to mix :type mix_before: tuple, optional :param mix_after: The number of times to mix after dispensing and the volume to mix :type mix_after: tuple, optional :param new_tip: Whether or not to use a new tip for the transfer. Can be 'always', 'never', or 'once' :type new_tip: str, optional :param air_gap: The volume of air to aspirate after aspirating the liquid, defaults to None :type air_gap: float, optional Note:: :param new_tip: still not implemented at the moment (2023-11-16) .. py:method:: _create_volume_list(volume, total_xfers) Creates a list of volumes to transfer :param volume: The volume of liquid to transfer :type volume: Union[float, list[float]] :param total_xfers: The total number of transfer steps to perform :type total_xfers: int :return: 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 .. py:method:: _extend_source_target_lists(sources: List[Union[science_jubilee.labware.Labware.Well, science_jubilee.labware.Labware.Location]], targets: List[Union[science_jubilee.labware.Labware.Well, science_jubilee.labware.Labware.Location]]) :staticmethod: Extend source or target list to match the length of the other :param sources: The list of source wells :type sources: List[Union[Well, Location]] :param targets: The list of target wells :type targets: List[Union[Well, Location]] :return: The extended source and target lists :rtype: 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 .. py:method:: _expand_for_volume_contraints(volumes: Iterator[float], targets: Iterator, max_volume: float) :staticmethod: Expands the volumes and targets to ensure that the volume does not exceed the maximum volume of the pipette :param volumes: An iterator of the volumes to transfer :type volumes: Iterator[float] :param targets: An iterator of the targets to transfer the volumes to :type targets: Iterator :param max_volume: The maximum volume of the pipette in uL :type max_volume: float :return: An iterator of the volumes and targets to transfer :rtype: Iterator Note: This function was taken from the Opentrons API and modified to work with the Pipette class of Science_Jubilee .. py:method:: blowout(s: int = 6000) Blows out any remaining liquid in the pipette tip :param s: The speed of the plunger movement in mm/min, defaults to 3000 :type s: int, optional .. py:method:: air_gap(vol) Moves the plunger upwards to aspirate air into the pipette tip :param vol: The volume of air to aspirate in uL :type vol: float .. py:method:: mix(vol: float, n: int, s: int = 5500) Mixes liquid by alternating aspirate and dispense steps for the specified number of times :param vol: The volume of liquid to mix in uL :type vol: float :param n: The number of times to mix :type n: int :param s: The speed of the plunger movement in mm/min, defaults to 5000 :type s: int, optional .. py:method:: stir(n_times: int = 1, height: float = None) Stirs the liquid in the current well by moving the pipette tip in a circular motion :param n_times: The number of times to stir the liquid, defaults to 1 :type n_times: int, optional :param height: The z-coordinate to move the tip to during the stir step, defaults to None :type height: float, optional :raises ToolStateError: If the pipette does not have a tip attached before stirring or if the pipette is not in a well .. py:method:: update_z_offset(tip: bool = None) Shift the z-offset of the tool to account for the tip length :param tip: Parameter to indicated whether to add or remove the tip offset, defaults to None :type tip: bool, optional .. py:method:: add_tiprack(tiprack: Union[science_jubilee.labware.Labware.Labware, list]) Associate a tiprack with the pipette tool :param tiprack: The tiprack to associate with the pipette :type tiprack: Union[Labware, list] .. py:method:: _pickup_tip(z) Moves the Jubilee Z-axis upwards to pick up a pipette tip and stops once the tip sensor is triggered :param z: The z-coordinate to move the pipette to :type z: float :raises ToolStateError: If the pipette already has a tip attached .. py:method:: pickup_tip(tip_: Union[science_jubilee.labware.Labware.Well, Tuple] = None) 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. :param tip_: The location of the pipette tip to pick up, defaults to None :type tip_: Union[Well, Tuple], optional .. py:method:: return_tip(location: science_jubilee.labware.Labware.Well = None) Returns the pipette tip to the either the specified location or to where the tip was picked up from :param location: The location to return the tip to, defaults to None (i.e. return to where the tip was picked up from) :type location: :class:`Well`, optional .. py:method:: _drop_tip() Moves the plunger to eject the pipette tip :raises ToolConfigurationError: If the pipette does not have a tip attached .. py:method:: drop_tip(location: Union[science_jubilee.labware.Labware.Well, Tuple] = None) Moves the pipette to the specified location and drops the pipette tip :param location: The location to drop the tip into :type location: Union[:class:`Well`, tuple] .. py:class:: TipTracker(tips, start_well=None) A class to track the usage of pipette tips and their location in the tiprack :param tips: The list of tips in the tiprack :type tips: list[:class:`Well`] :param start_well: The starting well to begin tracking the tips from, defaults to None :type start_well: :class:`Well`, optional Note: This function was taken from the Opentrons API and modified to work with the Pipette class of Science_Jubilee .. py:method:: next_tip(start_well=None) .. py:method:: use_tip(tip_well) .. py:method:: previous_tip() .. py:method:: return_tip(well=None) .. py:method:: assign_tip_to_stock(tip_well, stock_well)