spacr.figures.sheet

The whole regression as one publication-ready figure.

Not a gallery of separate pictures at separate sizes. One sheet, laid out the way a journal figure is: 6-12 panels, bold upper-case letters top-left, reading order matching the argument, related panels adjacent and sharing scales, and more white space between groups than within them – which is the only hierarchy cue the published figures use.

READING ORDER IS THE ARGUMENT, and it is why the panel order is fixed rather than alphabetical or whatever the dict happened to hold:

A volcano what the screen found B strongest effects which genes, and how sure C effect distribution what the effects look like as a whole D control separation whether the assay worked at all E guide agreement whether the calls are corroborated F p-value distribution whether the correction means anything G q-q whether the model was entitled to say it

A reader who stops after B has the result. One who reads to G knows whether to believe it. A sheet ordered any other way asks them to take the result on trust and audit it afterwards, which is not how anyone reads a figure.

Classes

Sheet

A rendered sheet and everything needed to write its legend.

Functions

attach(→ None)	Hang a panel's name, data and groups on its figure.
build_panel(key, frame, *[, target, figsize])	One panel on its own figure, for the grid view and for saving.
build_sheet(→ Sheet)	Draw every panel this table supports, as one figure.

Module Contents

class spacr.figures.sheet.Sheet

A rendered sheet and everything needed to write its legend.

Parameters:

• figure – Matplotlib figure containing the rendered multi-panel grid.

• panels – successfully rendered panel records in figure-reading order; their sequence supplies legend letters and captions.

• skipped – panel records omitted from the grid, retaining their titles and failure reasons for the legend.

legend() → str

The figure legend, panel by panel.

Generated from the panels themselves rather than written twice: a legend maintained by hand beside the code that draws the figure is a legend that describes last month’s figure.

spacr.figures.sheet.attach(figure, panel) → None

Hang a panel’s name, data and groups on its figure.

THE FIGURE HAS TO CARRY THEM because that is all the export sees. A user right-clicks a picture in the queue and asks to save it; nothing at that point knows which frame it came from or what was compared, unless the figure itself does.

Private attributes on a matplotlib Figure rather than a wrapper object, because the figure is handed through the Qt bridge, the queue, a spill file and back, and a wrapper would be lost at the first of those.

Parameters:

• figure – Matplotlib figure that will carry the export metadata.

• panel – panel metadata to attach; None leaves the figure unchanged.

spacr.figures.sheet.build_panel(key: str, frame, *, target: str | None = None, figsize=(3.4, 2.6), **kwargs)

One panel on its own figure, for the grid view and for saving.

Parameters:

• key – panel name from spacr.figures.panels.REGISTRY.

• frame – coefficient table consumed by the selected panel.

Returns:

(figure, Panel).

spacr.figures.sheet.build_sheet(frame, *, width: str = 'double', target: str | None = None, order: Sequence[str] = SHEET_ORDER, alpha: float = 0.05, effect_threshold: float | None = None, highlight: str | None = None) → Sheet

Draw every panel this table supports, as one figure.

Parameters:

• frame – the coefficient table.

• width – 'single', 'double' or 'full'.

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

• highlight – a gene to ring on the volcano, so the sheet can follow the selection in the GUI.

Returns:

a Sheet.

Panels whose data is absent are SKIPPED AND NAMED, never drawn as an empty frame. A blank box in a figure sheet reads as a panel that failed, which is worse than a gap and much worse than a sentence saying why.