"""
This module contains components for liquid handler IDSs.
A liquid handler is an automated laboratory instrument designed for the precise
manipulation and distribution of liquid volumes. It operates using a set of programmed
instructions to aspirate (draw up) and dispense (release) liquid samples with high
accuracy. Liquid handlers are instrumental in various scientific disciplines, such as
genomics, drug discovery, and analytical chemistry, where handling precise quantities
of liquids is crucial.
Liquid handlers employ robotic arms equipped with specialized tools, such as pipettes
or probes, to perform various liquid-handling tasks. The system is typically programmed
with specific protocols that dictate the volumes to be aspirated or dispensed, as well
as the locations within well plates or other containers. The precision of liquid
handlers is attributed to their ability to control factors like pipette speed,
immersion depth, and dispensing rate. This level of precision is crucial in applications
such as high-throughput screening, where numerous samples need consistent and accurate
handling for reliable experimental outcomes. The automation provided by liquid handlers
significantly enhances efficiency in laboratories, minimizing human error and
facilitating complex liquid manipulations at a scale unattainable through manual
methods.
Two significant aspects of data usage patterns in liquid handlers include sample/liquid
transfers tracking and consumables usage tracking.
Sample tracking involves monitoring the movement and status of liquid samples throughout
the liquid handling process. It helps track each sample from its original well position
to the final destination well, along with all the intermediate wells it moves through
throughout the process. It enables researchers to trace the history and handling of each
sample, facilitates reproducibility and ensures the reliability of experimental results
and provides a record for quality control and audit purposes.
Consumables usage tracking involves monitoring the usage of the liquid handler's
physical components, including pipettes, tips, and other accessories. It provides a
detailed history of the types of pipettes and tips used, along with the frequency of
their usage and unload events, enables precise tracking of consumables, such as pipette
tips, facilitating inventory management, helps prevent contamination by tracking the
usage of disposable components and supports compliance with regulatory requirements by
maintaining thorough records of instrument performance and consumable usage.
Typically, a specific instrument IDS can have more fields than the ones present in
these models. For example, if the instrument pipetting step has additional attributes,
such as a pod name for example, this field can be added by inheriting from the
PipettingStep class:
.. code-block:: python
class CustomPipettingStep(PipettingStep):
pod_name: Nullable[str]
"""
from typing import List
from ts_ids_core.annotations import Nullable
from ts_ids_core.base.ids_element import IdsElement
from ts_ids_core.base.ids_field import IdsField
from ts_ids_core.schema import Holder, Location, RawValueUnit, Sample, Time
[docs]
class LiquidHandlerHolder(Holder):
"""Liquid handler holder with associated deck position"""
vendor: Nullable[str] = IdsField(description="Vendor of the holder")
deck_position: Nullable[str] = IdsField(
description="Position of the holder on a deck"
)
[docs]
class LiquidHandlerLocation(Location):
"""Liquid handler location in a liquid handler holder"""
barcode: Nullable[str] = IdsField(
description="Barcode associated with a tube location in a tube rack"
)
holder: LiquidHandlerHolder = IdsField(
description="Information about the holder to which the location belongs to"
)
[docs]
class LiquidHandlerSample(Sample):
"""Properties of a liquid handler sample at a specific location"""
location: LiquidHandlerLocation = IdsField(
description="Liquid handler sample location properties"
)
liquid_class: Nullable[str] = IdsField(
description="The broad category or group of the liquid sample, such as solvent,"
" buffer, or reagent."
)
liquid_type: Nullable[str] = IdsField(
description="The specific instance or formulation of the liquid sample within "
"its liquid class"
)
[docs]
class Tip(IdsElement):
"""Properties of a tip used in a pipetting step"""
id_: Nullable[str] = IdsField(alias="id", description="Identifier for the tip")
type_: Nullable[str] = IdsField(
alias="type", description="Type or model of the tip"
)
vendor: Nullable[str] = IdsField(description="Vendor of the tip")
number: Nullable[int] = IdsField(description="Index of the current tip")
[docs]
class PipettingStep(IdsElement):
"""Pipetting step component
A pipetting step is a single aspirate or dispense event performed by a tip-based liquid handler.
It is part of a liquid transfer operation, which can consist of multiple pipetting steps.
This class should almost always be used as part of a LiquidTransfer object and not on its own.
"""
time: Time = IdsField(description="The time when the pipetting step occurs")
operation_type: Nullable[str] = IdsField(
description="Pipetting step operation type, such as 'Aspirate' or 'Dispense'"
)
device_name: Nullable[str] = IdsField(
description="Device used for performing the pipetting step, such as a flexible "
"channel arm or a multi-channel arm"
)
volume: RawValueUnit = IdsField(
description="The liquid volume aspirated or dispensed during the pipetting step"
)
flow_rate: RawValueUnit = IdsField(
description="The flow rate at which the liquid is aspirated or dispensed during"
" the pipetting step"
)
[docs]
class LiquidTransfer(IdsElement):
"""Liquid transfer component"""
id_: Nullable[str] = IdsField(
alias="id", description="Unique identifier for the liquid transfer operation"
)
time: Time = IdsField(
description="The time when the liquid transfer starts and ends "
"and the duration of the transfer. Although the pipetting steps have their own "
"timestamps, the liquid transfer time is here to provide query convenience."
)
transfer_mechanism: Nullable[str] = IdsField(
description="The mechanism used for the liquid transfer, such as 'pipette' or "
"'acoustic'"
)
tip: Tip = IdsField(
description="Information about the tip used for the liquid transfer step"
)
sample: LiquidHandlerSample = IdsField(
description="Information about the liquid handler sample being transferred"
)
source: LiquidHandlerLocation = IdsField(description="source location")
destination: LiquidHandlerLocation = IdsField(description="destination location")
volume: RawValueUnit = IdsField(
description="The volume of liquid being transferred"
)
pipetting_steps: List[PipettingStep] = IdsField(
description="List of pipetting steps involved in the liquid transfer"
)
[docs]
class TipEvent(IdsElement):
"""Tip load/unload event"""
time: Time = IdsField(
description="Timestamp indicating when the tip load/unload event occurred"
)
tip_type: Nullable[str] = IdsField(
description="Type or model of the loaded/unloaded tip"
)
tip_count: Nullable[int] = IdsField(
description="Number of tips loaded/unloaded during the event"
)
holder: LiquidHandlerHolder = IdsField(
description="Information about the holder to which the tips are loaded/unloaded"
)
[docs]
class TipUsage(IdsElement):
"""Tip usage component"""
tip_type: Nullable[str] = IdsField(
description="Type or model of the tip for which usage statistics are recorded"
)
tip_events: List[TipEvent] = IdsField(
description="List of individual tip load/unload events"
)
total_tip_events: Nullable[int] = IdsField(
description="Total count of tip load/unload events for the specified tip type"
)
total_tips: Nullable[int] = IdsField(
description="Total count of tips loaded/unloaded for the specified tip type"
)