phenotypic.util.decode_well_position#

phenotypic.util.decode_well_position(well, n_rows: int = 8, order: str = 'column') → ndarray[source]#

Decode microplate well identifiers to 0-based linear indices.

Supports scalar strings, Python lists, NumPy arrays, Pandas Series, and Polars Series as input. Output is always a NumPy int32 array of the same length, or a scalar int32 for scalar input. The well position is distinct from the GRID labels. These are in relation to the actual original well plate, and may have an offset in comparison to the GRID positions from a GridImage

Row encoding follows the ANSI/SBS microplate convention: single letters A-Z map to rows 0-25; double letters AA-AZ to 26-51, etc. This covers 96-well (A-H), 384-well (A-P), and 1536-well (A-AF) formats.

Column-major index formula: (col - 1) * n_rows + row_idx (0-based).

Parameters:

  • well – Well label(s) of the form <letter(s)><digits>, e.g. "A1", "B11", "AA3". Case-insensitive. Leading/trailing whitespace is stripped. Accepts str, list[str], np.ndarray, pandas.Series, or polars.Series.

  • n_rows (int) – Number of rows in the plate. Defaults to 8 (96-well). Use 16 for 384-well, 32 for 1536-well.

  • order (str) – Linear indexing order. "column" (default) uses column-major (Fortran) order. "row" is reserved but not yet implemented.

Returns:

np.ndarray of dtype int32 containing 0-based linear indices. Invalid or unparseable labels produce -1. Returns a scalar int32 when a single string is passed.

Raises:

NotImplementedError – If order="row" is requested.

Return type:

ndarray

Examples

>>> decode_well_position("A1")
array(0, dtype=int32)
>>> decode_well_position(["A1", "B1", "A2"], n_rows=8)
array([ 0,  1,  8], dtype=int32)
>>> decode_well_position(["A11", "H12"], n_rows=8)
array([80, 95], dtype=int32)
On this page

This Page