Labware (inherits from WellSet)

Description

Represents a basic laboratory labware consisting of multiple wells (or tips). Provides access to labware geometry, metadata, volume information, and supports both digital and manual calibration workflows. Handles labware loaded from configuration .json files.

Constructor

Labware(
    labware_filename: str,
    offset: Tuple[float] = None,
    order: str = "rows",
    path: str = default_path,
)

Loads a labware object from a JSON configuration file and initializes its wells, rows, and columns.

Parameter	Type	Description
labware_filename	str	Name of the JSON file specifying labware layout.
offset	Tuple[float] (optional)	Offset to apply to all wells after loading.
order	str (optional)	Ordering of wells: 'rows' or 'columns' (default is 'rows').
path	str (optional)	Path to the folder containing the configuration files.

Properties

Property	Type	Description
shape	Tuple[int, int]	Number of rows and columns.
ordering	List[List[str]]	Well IDs organized by rows.
brand	str	Brand of the labware (e.g., Falcon, Generic).
display_name	str	User-friendly name for display purposes.
labware_type	str	Type of labware (e.g., "wellplate", "tiprack").
volume_units	str	Units for volume (e.g., "uL" or "mL").
dimensions	Dict[str, float]	Physical dimensions (x, y, z sizes).
offset	Tuple[float]	Global offset applied to all wells (settable).
is_tip_rack	bool	Whether the labware is a tiprack.
load_name	str	Internal load name of the labware (used for matching configs).
tip_length	float	Length of the pipette tips (only if tiprack).
tip_overlap	float	Tip overlap value (only if tiprack).

Methods

Method	Returns	Description
get_row(row_id: str)	Row	Retrieves a row of wells by row ID (e.g., 'A').
get_column(col_id: int)	Column	Retrieves a column of wells by column number.
metadata()	dict	Returns additional metadata for the labware.
parameters()	dict	Returns configuration parameters like tiprack status.
add_slot(slot_: int)	None	Associates the labware with a specific deck slot.
withWellOrder(order: str)	list	Reorders the wells by rows or columns.
apply_offset(offset: Tuple[float])	None	Applies a new offset to all wells.
manual_offset(corner_wells: List[Tuple[float]], save: bool = False)	None	Applies manual calibration based on three corner wells.
load_manualOffset(apply: bool = True)	List[Tuple[float]] or None	Loads saved manual offset from the configuration file.
repr()	str	Display information (e.g., "wellplate: falcon_96_wellplate_360ul_flat on slot 1").
_getxyz(location)	Tuple[float, float, float]	Helper to extract x, y, z from a Well, Location, or raw coordinates.

Short Example

# Load a labware from config
labware = Labware("falcon_96_wellplate_360ul_flat")

# Check its dimensions
print(labware.shape)

# Access a specific row and column
row_A = labware.get_row("A")
col_1 = labware.get_column(1)

# Apply a manual offset (after loading to a deck slot)
labware.add_slot(1)
corner_wells = [(10.0, 10.0), (110.0, 10.0), (110.0, 80.0)]
labware.manual_offset(corner_wells)

Important Notes

• Loading labware automatically creates well, row, and column structures for easy access.
• Offsets can be applied dynamically after loading (e.g., deck alignment adjustments).
• Manual offsetting requires the labware to be already assigned to a slot.
• manual_offset() assumes three corner wells (upper left, upper right, bottom right) are provided for calibration.
• If the labware is a tiprack, wells are initialized with has_tip=True and clean_tip=True.
• Config files are editable to save updated manual offsets persistently.