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])	The plate the measured wells sit on, not the box that bounds them.
plate_figure_name(→ str)	The file a plate panel is written to: named for what it draws.
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])	One colour scale for every plate, over the wells that exist.
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 at the same time.

• 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. THIS IS WHAT MAKES ONE-PLATE-PER-FIGURE SAFE: a caller that wants a plate to a tile computes shared_limits() over every plate once and passes the same pair to each figure, so splitting the small multiple up does not silently give each plate its own scale again.

• 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]

The plate the measured wells sit on, not the box that bounds them.

THE EDGE HAS TO BE THE EDGE. Pivoting only the wells that carry data drops an entirely unused column, so a screen that never used columns 1-3 – which the tsg101 screen does not – drew its first measured column hard against the left spine. Every edge effect then reads one plate position out, and an edge effect is the artefact a plate heatmap exists to show.

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

The file a plate panel is written to: named for what it draws.

NOT spacr.schema.escape_filename_component(), which escapes the key separator – log_pred would be written as log%5Fpred. This is a file name and not a key: an underscore is exactly what belongs in it. 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 – which is every one this module has been run on – 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]

One colour scale for every plate, over the wells that exist.

SHARED IS THE POINT. A plate heatmap is read by comparing plates; four independent scales make the same colour mean four different numbers and turn a batch effect into an invisible one.

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 undoes the one thing it does that a picture must not inherit: 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.