spacr.well_spec

Parse plate rows, columns, and wells through one validated vocabulary.

Supported forms include rows such as r1, columns such as c1, and individual wells such as A01 or r1_c1. Every token is checked against the selected plate layout so an invalid or out-of-range selection fails with a useful message instead of silently selecting no wells.

Exceptions

WellSpecError

Raised when a well specification is invalid for its plate layout.

Functions

control_block_wells(→ list)	Return the wells named by the three control-block settings.
parse(→ Set[Tuple[int, int]])	Resolve a mixed well specification to unique one-based coordinates.
parse_one(→ Set[Tuple[int, int]])	Resolve one row, column, or well token to one-based coordinates.
row_label(→ str)	Convert a one-based row number to a plate-map label.
row_number(→ int)	Convert a plate-map row label to its one-based row number.
shape(→ Tuple[int, int])	Return the row and column count for a supported plate layout.
to_text(→ str)	Serialize selected coordinates using compact supported tokens.
well_label(→ str)	Return the plate-map label for a one-based row and column.

Module Contents

exception spacr.well_spec.WellSpecError

Bases: ValueError

Raised when a well specification is invalid for its plate layout.

Initialize self. See help(type(self)) for accurate signature.

spacr.well_spec.control_block_wells(settings) → list

Return the wells named by the three control-block settings.

Parameters:

settings – the run’s settings mapping.

Returns:

well/row/column names, in the order the blocks are declared, with duplicates removed and order otherwise preserved.

Pure-control wells are excluded from regression because each contains a guide fixed by design rather than a random draw from the screened library. A strong control left in the model can otherwise become a high-leverage observation for a gene under test.

spacr.well_spec.parse(text, layout: int = DEFAULT_LAYOUT) → Set[Tuple[int, int]]

Resolve a mixed well specification to unique one-based coordinates.

Parameters:

text – delimited string or iterable of row, column, and well tokens.

The value "r1, c1, A01" selects the union of the named row, column, and individual well.

spacr.well_spec.parse_one(text: str, layout: int = DEFAULT_LAYOUT) → Set[Tuple[int, int]]

Resolve one row, column, or well token to one-based coordinates.

Parameters:

text – single row, column, or well token to resolve.

Raises:

WellSpecError – If the token is malformed or outside the selected layout. The error identifies both the token and plate dimensions.

spacr.well_spec.row_label(row: int) → str

Convert a one-based row number to a plate-map label.

Parameters:

row – one-based plate row number.

spacr.well_spec.row_number(label: str) → int

Convert a plate-map row label to its one-based row number.

Parameters:

label – alphabetic plate-map row label.

spacr.well_spec.shape(layout: int = DEFAULT_LAYOUT) → Tuple[int, int]

Return the row and column count for a supported plate layout.

Raises:

WellSpecError – If layout is not one of the supported well counts.

spacr.well_spec.to_text(cells: Iterable[Tuple[int, int]], layout: int = DEFAULT_LAYOUT) → str

Serialize selected coordinates using compact supported tokens.

Parameters:

cells – iterable of one-based (row, column) coordinates.

Complete rows and columns become rN and cN tokens. Remaining coordinates are written as individual well labels, ensuring the result can be parsed again without introducing an unsupported range syntax.

spacr.well_spec.well_label(row: int, column: int) → str

Return the plate-map label for a one-based row and column.

Parameters:

• row – one-based plate row number.

• column – one-based plate column number.