spacr.figures.fast_render¶

Render generated regression figures from their interactive scenes.

For the plots listed in FAST_PANELS, render_panel() exports a provided FastPlot directly so the saved figure matches the visible tab. In auto mode, a call without a live widget uses the corresponding matplotlib panel. SPACR_FIGURE_RENDERER=pyqtgraph explicitly requests a new scene built from the coefficient table; matplotlib forces that renderer.

Output paths pass through spacr.plot.figure_path(), so file extensions follow the configured format. Matplotlib figures are published through spacr.figure_sink.publish and scene exports through spacr.figure_sink.publish_file; both routes add saved files to the gallery when a listener is present.

Classes¶

RenderedPanel

One generated figure: what drew it, where it went, and why.

Functions¶

`build_fast_plot`(key, frame, *[, alpha])	A live `FastPlot` for `key`, fed from `frame`.
`qt_application`()	The running `QApplication`, or None. NEVER creates one.
`render_panel`(→ RenderedPanel)	Write one generated panel, from the scene where there is one.
`renderer_for`(→ tuple)	`(renderer, reason)` for one panel. The decision, in one place.
`requested_renderer`(→ str)	The renderer the environment asks for, or `'auto'`.
`write_panels`(→ list)	Write every house-style panel into `dst`. Returns the records.

Module Contents¶

class spacr.figures.fast_render.RenderedPanel[source]¶

One generated figure: what drew it, where it went, and why.

renderer is RECORDED rather than assumed, because the answer varies per run and per machine and a user comparing a figure on screen against a figure in a folder has to be able to find out which one they are holding.

Parameters:

key – generated-panel key identifying the requested figure.
path – exported file path, or None when no file was written.
renderer – renderer selected for this result, whether it completed or reported a refusal.
drawn – whether the selected renderer successfully produced the panel; this does not by itself imply that a file was written.
reason – explanation for fallback or refusal, empty when unnecessary.

__bool__() → bool[source]¶

Return whether the panel was drawn and has an output path.

Returns:: True only for a drawn panel with a non-empty path.

spacr.figures.fast_render.build_fast_plot(key: str, frame, *, alpha: float = 0.05)[source]¶

A live FastPlot for key, fed from frame.

THE COLUMNS ARE RESOLVED BY spacr.figures.panels, not here. A second opinion about which column is the effect and which rows are hypotheses is precisely the disagreement this module exists to end, and effect_column / p_column / q_column / tested are the generated side’s single statement of it.

Parameters:

key – generated-panel key with an entry in FAST_PANELS.
frame – coefficient table used to populate the interactive plot.

Returns:

the widget, or None when this table cannot support the panel.

Raises:

KeyError – on a key with no interactive twin.

spacr.figures.fast_render.qt_application()[source]¶

The running QApplication, or None. NEVER creates one.

Deliberately does not import PySide6 unless it is already imported. Importing Qt pulls a GUI toolkit into a notebook that asked for a regression, so the question “is there a GUI?” has to be answerable without answering it in the affirmative by accident.

spacr.figures.fast_render.render_panel(key: str, frame=None, path=None, *, plot=None, fmt: str | None = None, renderer: str | None = None, alpha: float = 0.05, announce: bool = True) → RenderedPanel[source]¶

Write one generated panel, from the scene where there is one.

Parameters:

key – a key of FAST_PANELS (equivalently of spacr.figures.panels.SHEET_ORDER).
frame – the coefficient table. Needed only when no plot is given and for the matplotlib fallback.
path – destination. Its extension is REPLACED by the figure-format preference unless fmt forces one, so the name always names what was actually written.
plot – a live FastPlot to render. THIS IS THE POINT OF THE MODULE: given the widget the user is looking at, the file IS that widget rather than a second drawing of its data.
renderer – force one of RENDERERS.
announce – put the file in the gallery as well as on disk .

Returns:

a RenderedPanel, always. A panel that could not be drawn comes back with drawn=False and a reason rather than raising – losing a fit over a picture is the worst trade here.

spacr.figures.fast_render.renderer_for(key: str, force: str | None = None) → tuple[source]¶

(renderer, reason) for one panel. The decision, in one place.

Parameters:

key – generated-panel key. Only keys in FAST_PANELS have an interactive twin; every other key is assigned to matplotlib.
force – one of RENDERERS, overriding the environment and the auto rule.

Returns:

('pyqtgraph'|'matplotlib', reason). The reason is never empty for matplotlib, because “why is this not the screen’s renderer” is exactly the question a user asks of a figure that does not match a tab.

spacr.figures.fast_render.requested_renderer() → str[source]¶

The renderer the environment asks for, or 'auto'.

An unrecognised value is 'auto' rather than an error: a run must not lose its figures over a misspelt environment variable, which is the rule spacr.figure_style.figure_save_mode() already follows for the save mode.

spacr.figures.fast_render.write_panels(frame, dst, *, keys: Sequence[str] = SHEET_ORDER, plots=None, fmt: str | None = None, renderer: str | None = None, alpha: float = 0.05, verbose: bool = True) → list[source]¶

Write every house-style panel into dst. Returns the records.

Parameters:

frame – coefficient/results table used to build panels that have no live plot and by any matplotlib fallback.
dst – output directory, created when absent; each panel key becomes the destination file stem within it.
plots – {key: live FastPlot} for the panels that are on screen. Anything absent is built from the frame.
verbose – print one line naming the renderer that drew them, so a user who finds a figure that does not match a tab can see why in the run’s log rather than by inspecting the file.