Source code for autoprotocol.util

Module containing utility functions

    :copyright: 2021 by The Autoprotocol Development Team, see AUTHORS
        for more details.
    :license: BSD, see LICENSE for more details


from .constants import SBS_FORMAT_SHAPES
from .unit import Unit, UnitStringError, UnitValueError

[docs]def is_valid_well(well): """Checks if an input is of type Well, WellGroup or list of type Well. Example Usage: .. code-block:: python if not is_valid_well(source): raise TypeError("Source must be of type Well, list of Wells, or " "WellGroup.") Parameters ---------- well : Well or WellGroup or list(Well) Parameter to validate is type Well, WellGroup, list of Wells. Returns ------- bool Returns True if param is of type Well, WellGroup or list of type Well. """ from autoprotocol.container import Well, WellGroup if not isinstance(well, (Well, WellGroup, list)): return False if isinstance(well, list): if not all(isinstance(well, Well) for well in well): return False return True
[docs]def parse_unit(unit, accepted_unit=None): """ Parses and checks unit provided and ensures its of valid type and dimensionality. Note that this also checks against the dimensionality of the `accepted_unit`. I.e. `parse_unit("1:s", "minute")` will return True. Raises type errors if the Unit provided is invalid. Parameters ---------- unit: Unit or str Input to be checked accepted_unit: Unit or str or list(Unit) or list(str), optional Dimensionality of unit should match against the accepted unit(s). Examples -------- .. code-block:: python parse_unit("1:ul", "1:ml") parse_unit("1:ul", "ml") parse_unit("1:ul", ["ml", "kg"]) Returns ------- Unit Parsed and checked unit Raises ------ TypeError Error when input does not match expected type or dimensionality """ if not isinstance(unit, Unit): try: unit = Unit(unit) except (UnitStringError, UnitValueError) as e: raise TypeError(f"{unit} is not of type Unit/str") from e if accepted_unit is not None: # Note: This is hacky. We should formalize the concept of base Units # in AP-Py def parse_base_unit(base_unit): if not isinstance(base_unit, Unit): if isinstance(base_unit, str): if ":" not in base_unit: base_unit = "1:" + base_unit return Unit(base_unit) if isinstance(accepted_unit, list): accepted_unit = [parse_base_unit(a_u) for a_u in accepted_unit] else: accepted_unit = [parse_base_unit(accepted_unit)] if all([unit.dimensionality != a_u.dimensionality for a_u in accepted_unit]): raise TypeError( f"{unit} is not of the expected dimensionality " f"{accepted_unit}" ) return unit
def _validate_as_instance(item, target_type): """ Validates that the item is an instance of the target_type and if not, checks whether the item is the Parameters ---------- item : target_type target_type : type Returns ------- target_type the item as an instance of the target type Raises ------ TypeError if the passed item isn't either target_type or an instance thereof """ if not isinstance(item, target_type): try: item = _validate_as_instance(item(), target_type) except TypeError as e: raise TypeError(f"{item} can't be parsed as a {target_type}.") from e return item def _check_container_type_with_shape(container_type, shape): """ Checks whether the selected origin and shape pair are valid Parameters ---------- container_type : ContainerType the origin of the liquid handling operation. for multi channel operations this is the top left well of the stamp. for single channel operations this is the source well. shape : dict the shape of the transfer. used to determine the shape format of multichannel liquid handling operations see Raises ------ ValueError invalid combination of container and shape specified """ from .instruction import Instruction shape =**shape) format_rows = SBS_FORMAT_SHAPES[shape["format"]]["rows"] format_columns = SBS_FORMAT_SHAPES[shape["format"]]["columns"] is_single = shape["rows"] == shape["columns"] == 1 if container_type.is_tube and not is_single: raise ValueError( f"Tube container_type {container_type} was specified with multi " f"channel transfer shape {shape}, but tubes only support single " f"channel liquid handling." ) container_wells = container_type.well_count if container_wells == 24: rows_one_or_even = shape["rows"] == 1 or shape["rows"] % 2 == 0 columns_one_or_even = shape["columns"] == 1 or shape["columns"] % 2 == 0 if not (rows_one_or_even and columns_one_or_even): raise ValueError( f"24 well container_type {container_type.container_type} was " f"specified, but multi channel transfers in 24 well " f"containers must have row and column counts either equal to " f"1 or divisible by 2, but {shape} was specified." ) if ( shape["format"] == "SBS384" and container_wells < 384 and "sbs384_compatible" not in container_type.capabilities ): raise ValueError( f"SBS384 transfers can only be executed in 384 well plates, but " f"container_type: {container_type} has {container_wells} wells." f"If the container_type is compatible with less than 384 wells, make sure to include: sbs384_compatible in the container_type's capabilities list" ) # check for valid multi channel shapes max_rows = shape["rows"] == format_rows max_columns = shape["columns"] == format_columns is_full = max_rows and max_columns is_selective = (max_rows or max_columns) and not (max_rows and max_columns) if is_single or is_full: pass elif is_selective: if shape["format"] != "SBS96": raise ValueError( f"{shape['format']} formatted transfers require rows: " f"{format_rows} and columns: {format_columns}, but {shape} was " f"specified." ) else: raise ValueError( f"Invalid transfer shape passed: only individual wells or full " f"rows/columns can be transferred. For {shape['format']} format " f"a full row consists of {format_columns} columns and a full " f"column consists of {format_rows} rows, but {shape} was specified." ) def _validate_liha_shape(device: str, shape: dict) -> None: """Validates LiHa shape for liquid handle dispense. Args: device (str): The LiHa device name. Currently supported devices are "x_mantis" and "x_tempest_chip". shape (dict): A dictionary containing the number of rows and columns for the LiHa shape. For example, {"rows": 8, "columns": 1}. Raises: ValueError: If the provided device name is not one of the supported devices or if the provided shape is not valid for the specified device. Example: >>> _validate_liha_shape("x_mantis", {"rows": 1, "columns": 1}) None """ accepted_shape = {} if device == "x_mantis": accepted_shape.update({"rows": 1, "columns": 1}) elif device == "x_tempest_chip": accepted_shape.update({"rows": 8, "columns": 1}) else: raise ValueError( f"Device {device} is not in list of accepted devices " f"[x_mantis, x_tempest_chip]" ) if shape != accepted_shape: raise ValueError( f"Input LiHa shape: {shape}. " f"Should be {accepted_shape} for device {device}." )