spacr.volcano_style

Workflow inputs and outputs

Volcano Explorer

Open a saved regression result and inspect effect sizes, adjusted significance and individual hit records.

Open: Regression → Volcano Explorer.

Inputs and outputs below include conditional alternatives. The guidance and handoff notes say which route applies.

Inputs

• Regression results and hits — Selected run results folder: coefficient/result CSVs, hit tables, settings and diagnostic figures.

Outputs

• Figures and table exports — The output location chosen by the tool; exports describe the selected data and filters.

Before this module

• Regression: Inspect saved effects and adjusted significance.

API reference.

Module tutorial.

The complete appearance of a volcano plot, as data rather than arguments.

VolcanoStyle holds every setting the interactive explorer exposes, so one object can be handed to the renderer, saved beside a figure, reloaded, and replayed to reproduce a plot exactly. The renderer is a plain function of (results, style) with no Qt in it, which is what lets the same code draw the headless PDF written by a pipeline run and the live canvas the user clicks on – they cannot drift, because there is only one of them.

Splitting the style out this way is also what makes “export exactly what I am looking at” true: the export path re-renders from the same object at a different size and dpi rather than screenshotting the widget.

Classes

VolcanoStyle

All volcano-plot settings. Defaults reproduce the pipeline plot.

Functions

localizations_present(→ list)	Return the compartments present in results, most common first.
page_ground(style, *[, screen])	Resolve the background colour for a volcano-plot render.
point_details(→ dict)	Return the data row and plotted coordinates of one point.
point_localizations(results, style)	Each row's LOPIT compartment as an array of names, '' where unknown.
render_volcano(results, style, *[, figure, save_path, ...])	Draw the volcano described by style and return (figure, axes).
validate_style(→ dict)	Validate volcano-plot style fields without stopping at the first error.

Module Contents

class spacr.volcano_style.VolcanoStyle

Bases: spacr.style_base.FigureStyle

All volcano-plot settings. Defaults reproduce the pipeline plot.

General settings are inherited: axes, type, grid, legend, spines and the page come from spacr.style_base.FigureStyle, so “font size” is one setting in spaCR rather than one per figure, and a house style saved on a volcano can be applied to any other figure that shares those names. This class adds the volcano-specific settings: the columns, the thresholds, the marks and the labelling.

classmethod from_dict(values: dict) → VolcanoStyle

Build from a dict, ignoring keys this version does not know.

Forwards-compatible on purpose: a style saved by a newer spaCR still loads here, minus the settings that did not exist yet.

Parameters:

values – serialized style fields; unknown names are ignored.

classmethod load(path) → VolcanoStyle

Load a JSON style from a filesystem path.

Parameters:

path – path-like JSON source previously written by save().

save(path) → str

Write this style as JSON and return its filesystem path.

Parameters:

path – path-like destination to create or replace.

to_dict() → dict

Return every style field as a recursively copied plain mapping.

spacr.volcano_style.localizations_present(results: pandas.DataFrame, style: VolcanoStyle, minimum: int | None = None) → list

Return the compartments present in results, most common first.

Only compartments with at least minimum localized rows (default spacr.localisation.MIN_GENES, the threshold spacr.localisation.present() applies) are listed, not every compartment in the reference table, so the menu offers no choice that would colour no point.

Parameters:

• results – result rows whose genes or guides are localized.

• style – style selecting the localization or fallback label column.

spacr.volcano_style.page_ground(style: VolcanoStyle, *, screen: bool = False)

Resolve the background colour for a volcano-plot render.

An explicit background_color applies to screen and file output. If it is unset, screen rendering uses screen_background and file rendering preserves the figure’s existing transparency.

Parameters:

• style – Volcano-plot style settings.

• screen – Resolve for interactive screen display.

Returns:

A matplotlib colour value, or None to preserve the current figure background.

spacr.volcano_style.point_details(results: pandas.DataFrame, index: int, style: VolcanoStyle) → dict

Return the data row and plotted coordinates of one point.

Returns every column of the row, plus the derived plotted coordinates, so the panel can show both what was plotted and what it came from.

Parameters:

• results – result frame in the same row order as the plotted points.

• index – positional row index of the selected point.

• style – style selecting the plotted x and y columns and transform.

spacr.volcano_style.point_localizations(results: pandas.DataFrame, style: VolcanoStyle)

Each row’s LOPIT compartment as an array of names, '' where unknown.

spacr.localisation.of() resolves genes encoded in bracketed regression terms such as fraction:grna[233460_1]. Explorer tables may instead contain bare accessions or guide identifiers such as TGGT1_233460 or 233460_1. This function accepts both forms and queries the bundled localization table first with the normalized accession and then, when applicable, with its terminal gene number.

Parameters:

• results – result rows containing a usable gene or guide column.

• style – style whose localization and label columns guide lookup.

Returns:

a numpy array of compartment names, or None when no column of results can name a gene or no localization table is bundled; the volcano is then drawn without compartment colouring.

spacr.volcano_style.render_volcano(results: pandas.DataFrame, style: VolcanoStyle, *, figure=None, save_path=None, screen: bool = False)

Draw the volcano described by style and return (figure, axes).

Parameters:

• results – coefficient table supplying the effect, significance and annotation columns named by style.

• style – complete volcano appearance and data-mapping specification, including cut-offs, labels, colours and figure geometry.

• figure – draw into this figure instead of creating one, so a live canvas can be redrawn in place.

• save_path – also write the figure here. The extension chooses the format; .pdf stays vector.

• screen – this render is going onto a screen someone is reading, not into a file. It is the one bit that tells VolcanoStyle.screen_background from VolcanoStyle.background_color – see page_ground(). A renderer that could not tell them apart would have to choose between an unreadable canvas and an exported figure carrying a white rectangle onto every page it is placed on.

spacr.volcano_style.validate_style(results: pandas.DataFrame, style: VolcanoStyle) → dict

Validate volcano-plot style fields without stopping at the first error.

Parameters:

• results – Results table used to validate referenced column names.

• style – Style configuration to validate.

Returns:

Mapping from invalid field names to explanatory messages. An empty mapping indicates that the style can be rendered.