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

Return which registered panels can be drawn, using a discarded figure.

control_separation(→ Panel)

Plot coefficient distributions for the available control classes.

control_threshold(frame[, multiplier])

Return a symmetric effect-size cut estimated from the control guides.

effect_column(→ Optional[str])

Return the name of the fitted-effect column, or None if absent.

effect_distribution(→ Panel)

Plot a histogram of tested effects with zero and ±3σ (MAD) lines.

effect_rank(→ Panel)

Plot the largest fitted effects with available confidence intervals.

guide_agreement(→ Panel)

Plot, per gene, the fraction of its guides that agree in effect sign.

label_series(frame)

Return a non-missing display label for every row.

p_column(→ Optional[str])

Return the name of the raw p-value column, or None if absent.

p_histogram(→ Panel)

Plot a histogram of raw p-values with the uniform expectation and π₀.

q_column(→ Optional[str])

Return the name of the corrected p-value column, or None if absent.

qq_plot(→ Panel)

Plot observed against expected p-values and the inflation factor λ.

statistic_column(→ Optional[str])

Return the name of the test-statistic column, or None if absent.

tested(→ numpy.ndarray)

Mask of tested-hypothesis rows, from spacr.hits.tested_family().

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]

Return which registered panels can be drawn, using a discarded figure.

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]

Return a symmetric effect-size cut estimated from the control guides.

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

A p-value states that an effect is distinguishable from zero; with a thousand wells that includes very small effects. The effect-size cut separates detectable effects from those large enough to follow up, and is drawn on the volcano beside the significance line.

The control guides are used first, because the spread of guides that target nothing is the null distribution. With fewer than MIN_CONTROLS finite controls, or zero control spread, the MAD of all finite coefficients is used instead. On the reference screen the two agree closely (0.83 against 0.84), but a strong signal raises the all-guide MAD while the control MAD is unchanged.

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]

Return the name of the fitted-effect column, or None if absent.

spaCR writes coefficient; a statsmodels summary carries coef. Both hold the same quantity and both are accepted, as are effect and estimate.

Parameters:

frame – coefficient table whose columns are inspected.

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

Plot a histogram of tested effects with zero and ±3σ (MAD) lines.

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]

Plot, per gene, the fraction of its guides that agree in effect sign.

A volcano cannot show this. A gene called by one guide out of six is a common source of false hits in pooled screens, and on a volcano it looks the same as a gene whose guides agree. Genes with a single guide are highlighted.

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]

Return a non-missing display label for every row.

gene is NaN on the per-guide rows and grna is NaN on the per-gene rows, so either column alone would label half the volcano “nan”. The two are coalesced, with the design term (its fraction:gene[...] wrapper stripped) as the fallback, and the row position when no label column exists.

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

Return the name of the raw p-value column, or None if absent.

Parameters:

frame – coefficient table whose columns are inspected.

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

Plot a histogram of raw p-values with the uniform expectation and π₀.

Under the null, p-values are uniform. A flat histogram with a spike near zero indicates real hits; a slope, a central hump or a spike near one indicates a mis-specified model, which FDR correction does not fix.

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]

Return the name of the corrected p-value column, or None if absent.

A missing column is not an error: the penalised backends have no p-value to correct, and a run with multiple_testing_method = 'none' has none either. A panel that finds no q-value falls back to the raw p-value and states which one it drew.

Parameters:

frame – coefficient table whose columns are inspected.

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

Plot observed against expected p-values and the inflation factor λ.

Points that leave the diagonal early indicate either real signal or a mis-specified model; λ near 1 indicates a calibrated null, and a large λ indicates systematic inflation rather than a few hits.

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]

Return the name of the test-statistic column, or None if absent.

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. All of these column names are recognised.

Parameters:

frame – coefficient table whose columns are inspected.

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

Mask of tested-hypothesis rows, from spacr.hits.tested_family().

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.