spacr.figures.plates

Small-multiple heatmaps for plate-layout measurements.

All plates for one measurement share a color scale and are arranged in a compact grid with square wells. Missing wells remain distinct from measured zeros and are excluded from color-limit estimation. Styling is scoped through spacr.figures.style.figure_style() so drawing a plate does not change global Matplotlib settings.

Functions

build_plates(frame, variable, *[, grouping, min_max, ...])	Every plate of a screen as one figure, on one colour scale.
draw_plate(→ None)	One plate into one axes, with square wells and no gridlines.
full_plate_grid(→ Tuple[int, int])	Return the smallest standard plate shape containing every measured well.
plate_figure_name(→ str)	Return the file name for a plate panel, built from its variable.
plate_names(→ List[str])	Return distinct nonempty plate identifiers in first-occurrence order.
plate_ramp([target])	Create the sequential blue color map used for plate measurements.
score_ramp([target])	Create the diverging color map used for signed plate scores.
shared_limits(→ Tuple[float, float])	Return one (low, high) colour range for all plates' measured wells.
small_multiple_layout(→ Tuple[int, int])	Rows and columns of plates that put the composite nearest square.
well_matrices(frame, variable, *[, grouping, ...])	One matrix per plate, on a shared grid, with absent wells as nan.

Module Contents

spacr.figures.plates.build_plates(frame, variable: str, *, grouping: str = 'mean', min_max='allq', min_count=0, cmap=None, target: str | None = None, width: float = WIDTH, plates: Sequence[str] | None = None, limits: Tuple[float, float] | None = None, outline: str | None = None)

Every plate of a screen as one figure, on one colour scale.

Parameters:

• frame – long-format frame with a prc column and variable.

• variable – the measurement to aggregate per well.

• grouping – 'mean', 'sum' or 'count'.

• min_count – minimum number of rows required for a well to be drawn.

• min_max – colour-scale spec, as spacr.plot.generate_plate_heatmap() defines it – but applied once, over every plate together.

• cmap – a colormap to override the house ramp. None uses plate_ramp(), which is what the style asks for.

• target – 'screen' or 'print'; defaults to the user’s own figure preference.

• width – figure width in inches. The height is derived from it, so that the wells come out square.

• plates – draw only these plates, in this order.

• limits – an explicit (vmin, vmax), overriding min_max. To draw one plate per figure on a common scale, compute shared_limits() over every plate once and pass the same pair to each figure.

• outline – a column of frame; every well whose mean of it is above zero gets a square outline in the ink colour. A hit call drawn on the score it was called from, without a second figure.

Returns:

(figure, Panel). With no matrix the panel has drawn=False plus its missing requirements and reason. Otherwise its caption records the actual aggregation, well counts, and shared limits.

spacr.figures.plates.draw_plate(ax, matrix: numpy.ndarray, *, vmin: float, vmax: float, cmap, ink: str, name: str = '', row_labels=None, column_labels=None) → None

One plate into one axes, with square wells and no gridlines.

Parameters:

• ax – matplotlib axes that receives the wash, image, ticks and title.

• matrix – (n_rows, n_columns), nan where no well was measured.

• vmin – lower endpoint shared by the plate’s colour normalisation.

• vmax – upper endpoint shared by the plate’s colour normalisation.

• cmap – matplotlib colormap (or registered colormap name) used for measured wells.

• ink – colour used for ticks, labels, spines and the plate wash.

• name – optional plate title; false values leave the title unset.

• row_labels – True to draw the row letters, False to leave the axis bare (an inner plate of the small multiple shares the outer one’s).

• column_labels – truthy to draw column numbers; false values leave the axis bare when an outer plate already supplies them.

Returns:

None; artists are added to ax in place.

spacr.figures.plates.full_plate_grid(rows: Sequence[int], columns: Sequence[int]) → Tuple[int, int]

Return the smallest standard plate shape containing every measured well.

Pivoting only the wells that carry data drops entirely unused columns, so a screen that never used columns 1-3 (such as the tsg101 screen) would draw its first measured column against the left spine and shift every edge effect by the missing positions.

Parameters:

• rows – measured 1-based plate row indices.

• columns – measured 1-based plate column indices.

Returns:

(n_rows, n_columns) of the smallest standard format that contains every measured well, or the bounding box when the wells fit no standard plate (a partial or non-standard layout).

spacr.figures.plates.plate_figure_name(variable: str, prefix: str = 'plate_heatmap', suffix: str = '.pdf') → str

Return the file name for a plate panel, built from its variable.

This does not use spacr.schema.escape_filename_component(), which escapes the key separator (log_pred would be written as log%5Fpred); in a file name the underscore is kept. Unicode alphanumerics and -_. in variable are retained; every other character is replaced with an underscore.

Parameters:

• variable – measurement name to include in the file name.

• prefix – filename prefix, used verbatim.

• suffix – filename suffix, including any extension, used verbatim.

Returns:

prefix, a sanitized nonempty variable component, and suffix joined into one filename.

spacr.figures.plates.plate_names(frame) → List[str]

Return distinct nonempty plate identifiers in first-occurrence order.

prc keys are parsed from the right: the final tokens are row and column, while every preceding token belongs to the plate identifier. This preserves plate identifiers that contain underscores.

Screens whose keys are the plain three-token form are unaffected: the plate is still the first token because there is nothing in front of it.

Parameters:

frame – long-format table whose prc values identify wells.

Returns:

Plate identifiers parsed from the right. Keys with fewer than three underscore-delimited tokens are retained verbatim.

spacr.figures.plates.plate_ramp(target: str = 'screen')

Create the sequential blue color map used for plate measurements.

Parameters:

target (str, default="screen") – "print" selects the print ramp. Every other value selects the screen ramp, which avoids the darkest print color so high values remain distinct from a dark interface background.

Returns:

matplotlib.colors.Colormap – Color map with a transparent bad-value color for unmeasured wells.

spacr.figures.plates.score_ramp(target: str = 'screen')

Create the diverging color map used for signed plate scores.

A hit score (SSMD, robust z, B-score) is signed about the negative control, which is what a diverging map is for. The ends are the house down and up colours (spacr.figures.style.ROLES), so a well scored below the control reads rust and one above it green, the same as on a volcano.

Parameters:

target – "print" centres on a near-white; every other value on the light grey of the screen plate ramp.

Returns:

A color map with a transparent bad-value color.

spacr.figures.plates.shared_limits(matrices: Sequence[numpy.ndarray], min_max='allq') → Tuple[float, float]

Return one (low, high) colour range for all plates’ measured wells.

Plate heatmaps are read by comparing plates; independent scales would give one colour a different value on each plate and hide batch effects.

Parameters:

• matrices – per-plate value matrices; non-finite wells are excluded from the shared scale.

• min_max – A two-float sequence selects those quantiles; a two-item sequence containing a non-float supplies absolute endpoints. 'allq' selects the 2nd and 98th percentiles, while every other value selects the finite extrema.

Returns:

(low, high) shared by every matrix. An empty finite pool returns (0.0, 1.0); equal endpoints are widened by 1e-6.

spacr.figures.plates.small_multiple_layout(count: int, plate_aspect: float, target: float = TARGET_ASPECT) → Tuple[int, int]

Rows and columns of plates that put the composite nearest square.

Four plates in a row is 4 x 1.5 = a 6:1 composite; four in a 2 x 2 is 1.5:1. Both hold the same picture; only one of them fills a tile.

Parameters:

• count – number of plates to place. A non-positive count has no grid and returns (0, 0).

• plate_aspect – one plate’s width over its height, in wells. For a positive count, this and target must be positive; unsupported nonpositive ratios may propagate arithmetic domain or division errors.

• target – the positive composite width-over-height to aim at.

Returns:

(rows, columns).

spacr.figures.plates.well_matrices(frame, variable: str, *, grouping: str = 'mean', min_count=0, plates: Sequence[str] | None = None)

One matrix per plate, on a shared grid, with absent wells as nan.

Wraps spacr.plot.generate_plate_heatmap() – which is where the prc parsing, the letter walk past row P and the min_count filter live – and reverses its .fillna(0). A well with no rows and a well that measured zero are the same cell afterwards, so the count map is fetched alongside the value map and a well with a count of zero is masked back out.

A well with rows but nothing numeric in any of them is masked too. The count map counts rows, and the aggregation coerces the variable with errors='coerce', so such a well aggregates to NaN and is filled with the same invented zero one step further in.

Parameters:

• frame – long-format frame with a prc column.

• variable – the measurement column to aggregate.

• grouping – 'mean', 'sum' or 'count'.

• min_count – wells with fewer rows than this are dropped, and then read as absent rather than as zero.

• plates – return only these plates, in this order.

Returns:

(names, matrices, (n_rows, n_columns)) with equally many names and matrices on the smallest fitting standard plate grid. Absent or unreadable wells and wells below min_count are nan.