spacr.figures.panels

Regression result and diagnostic panels.

Each panel function draws into a supplied Matplotlib axes and returns a Panel record containing its caption, input requirements, and plotted data. The shared registry lets reports and the desktop interface discover the same available panels without duplicating plotting rules.

Classes

Panel

Metadata describing a rendered or unavailable figure panel.

Functions

available(→ Dict[str, bool])

Which panels this table can support, without drawing anything.

control_separation(→ Panel)

Plot coefficient distributions for the available control classes.

control_threshold(frame[, multiplier])

A symmetric effect-size cut, measured from the CONTROL guides.

effect_column(→ Optional[str])

The fitted effect column, whatever this backend called it.

effect_distribution(→ Panel)

Where the screen's effects sit, and where the controls sit in them.

effect_rank(→ Panel)

Plot the largest fitted effects with available confidence intervals.

guide_agreement(→ Panel)

Per gene: do its own guides push the same way?

label_series(frame)

A readable name per row, with no holes.

p_column(→ Optional[str])

The raw p-value column, whatever this backend calls it.

p_histogram(→ Panel)

The single most informative check that a correction means anything.

q_column(→ Optional[str])

The multiple-testing-corrected p, if the fit produced one.

qq_plot(→ Panel)

Observed against expected p, and the inflation factor.

statistic_column(→ Optional[str])

The test statistic, which differs by backend.

tested(→ numpy.ndarray)

Rows that are hypotheses, via the repo's single statement of it.

volcano(→ Panel)

Plot fitted effect size against statistical significance.

Module Contents

class spacr.figures.panels.Panel[source]

Metadata describing a rendered or unavailable figure panel.

Parameters:

  • key – stable registry key identifying the panel.

  • title – short display title used on the figure sheet.

  • caption – figure-legend sentence describing the comparison, sample size, and significance convention used by the rendered panel.

  • drawn – whether the panel was rendered successfully.

  • reason – actionable explanation when drawn is false.

  • needs – source-column names required before the panel can be rendered.

  • data – rows actually rendered after any panel-specific filtering.

  • groups – labelled comparison groups, or None when the panel defines no group comparison.

spacr.figures.panels.available(frame) → Dict[str, bool][source]

Which panels this table can support, without drawing anything.

Parameters:

frame – coefficient table to check against every registered panel.

spacr.figures.panels.control_separation(ax, frame) → Panel[source]

Plot coefficient distributions for the available control classes.

Each coefficient is shown as a point and each class median as a horizontal line, preserving the within-class spread used to assess assay separation.

Parameters:
Returns:

Panel – Rendering metadata and grouped values used by downstream statistics.

spacr.figures.panels.control_threshold(frame, multiplier=3.0)[source]

A symmetric effect-size cut, measured from the CONTROL guides.

(where, value) – the rule that produced it and the number, or (reason, None) when neither rule could be applied.

THE CUT WAS NEVER VISIBLE, which is the complaint: it defaulted to None, so a volcano drew its significance line and nothing else. A p-value says an effect is distinguishable from zero; with a thousand wells that includes effects too small to care about, and the cut is what separates “detectable” from “worth following up”.

Controls first because it is the defensible one to write in a methods section – the spread of guides that target nothing IS the null. Measured on this screen the two agree closely (0.83 against 0.84), but a screen with a strong signal pulls the all-guide MAD up while leaving the controls where they are, and then only one of them is still a null.

sigma is MAD x 1.4826, which is the consistent estimator for a normal and, unlike the standard deviation, is not inflated by the outliers a screen exists to find.

spacr.figures.panels.effect_column(frame) → str | None[source]

The fitted effect column, whatever this backend called it.

spaCR writes coefficient; a statsmodels summary carries coef. Both are the same quantity and both have to plot.

Parameters:

frame – coefficient table whose columns are inspected.

spacr.figures.panels.effect_distribution(ax, frame) → Panel[source]

Where the screen’s effects sit, and where the controls sit in them.

Parameters:

  • ax – Matplotlib axes on which to draw the histogram.

  • frame – coefficient table containing the tested effects.

spacr.figures.panels.effect_rank(ax, frame, *, alpha=0.05, top=14) → Panel[source]

Plot the largest fitted effects with available confidence intervals.

Parameters:

  • ax (matplotlib.axes.Axes) – Axes to draw into.

  • frame (pandas.DataFrame) – Coefficient table.

  • alpha (float, default=0.05) – Adjusted-p-value threshold used to color called coefficients.

  • top (int, default=14) – Maximum number of coefficients to display.

Returns:

Panel – Rendering metadata and the columns required by the panel.

spacr.figures.panels.guide_agreement(ax, frame) → Panel[source]

Per gene: do its own guides push the same way?

The one thing a volcano structurally cannot show. A gene called by one guide out of six is the commonest way a pooled screen makes a confident artefact, and it is the same dot as a gene whose guides agree.

Parameters:

  • ax – Matplotlib axes on which to draw guide concordance.

  • frame – per-guide coefficient table with parseable feature terms.

spacr.figures.panels.label_series(frame)[source]

A readable name per row, with no holes.

gene is NaN on the per-guide rows and grna is NaN on the per-gene rows, so either column alone labels half the volcano “nan” – which is what a first pass at this actually drew. Coalesce them, and fall back to the design term with its boilerplate stripped.

spacr.figures.panels.p_column(frame) → str | None[source]

The raw p-value column, whatever this backend calls it.

Parameters:

frame – coefficient table whose columns are inspected.

spacr.figures.panels.p_histogram(ax, frame, *, bins=40) → Panel[source]

The single most informative check that a correction means anything.

Under the null p is uniform. Flat with a spike at zero is a screen with real hits; a slope, a hump in the middle or a spike at one is a model that is wrong, and no amount of FDR fixes it.

Parameters:

  • ax – Matplotlib axes on which to draw the histogram.

  • frame – coefficient table containing the tested p-values.

spacr.figures.panels.q_column(frame) → str | None[source]

The multiple-testing-corrected p, if the fit produced one.

Its ABSENCE is meaningful and is not an error: the penalised backends have no p-value to correct, and a run asked for multiple_testing_method = 'none' deliberately has none either. A panel that finds no q falls back to the raw p and says which one it drew.

Parameters:

frame – coefficient table whose columns are inspected.

spacr.figures.panels.qq_plot(ax, frame) → Panel[source]

Observed against expected p, and the inflation factor.

A screen whose points leave the diagonal early has either real signal or a mis-specified model, and lambda says which is more likely.

Parameters:

  • ax – Matplotlib axes on which to draw the q-q plot.

  • frame – coefficient table containing the tested p-values.

spacr.figures.panels.statistic_column(frame) → str | None[source]

The test statistic, which differs by backend.

OLS and RLM report t value; GLM, Poisson and the mixed model report z value; the penalised backends report neither and give a selection frequency instead. Every one of those tables has to display.

Parameters:

frame – coefficient table whose columns are inspected.

spacr.figures.panels.tested(frame) → numpy.ndarray[source]

Rows that are hypotheses, via the repo’s single statement of it.

spacr.figures.panels.volcano(ax, frame, *, alpha=0.05, effect_threshold='auto', highlight=None, label_top=8, colour_by=None, baseline_kind=None, baseline_name=None, compartment=None) → Panel[source]

Plot fitted effect size against statistical significance.

Parameters:

  • ax (matplotlib.axes.Axes) – Axes to draw into.

  • frame (pandas.DataFrame) – Coefficient table containing effect and p- or q-value columns.

  • alpha (float, default=0.05) – Significance threshold.

  • effect_threshold (float, "auto", or None, default="auto") – Minimum absolute effect. "auto" estimates a threshold from the control-guide spread.

  • highlight (str or None, default=None) – Coefficient label to outline.

  • label_top (int, default=8) – Maximum number of called coefficients to label.

  • colour_by (str or None, default=None) – Reserved for compatibility; currently ignored.

  • baseline_kind (str or None, default=None) – Effect baseline understood by spacr.baseline. The default is zero.

  • baseline_name (str or None, default=None) – Optional name used to describe the selected baseline.

  • compartment (str or None, default=None) – TAGM/LOPIT compartment to highlight against the remaining points.

Returns:

Panel – Rendering metadata, including the coefficient rows that were drawn.