spacr.qt.widgets.umap_figure_settings¶

Every Image UMAP setting, live-editable against the STATIC figure.

The live explorer has a settings window whose display options apply to the figure on screen. This module provides the equivalent for the screen – the ordinary, non-live figure the run leaves in spacr.qt.widgets.figure_queue.FigureQueue:

"the non live image UMAP figure settings should have all the image UMAP
 settings live editable (you should see changes in the graph directly)"

THE COST OF A SETTING IS NOT UNIFORM, and pretending it is would make the panel unusable. Three tiers, and every field declares which one it is in:

TIER_STYLE: settable on artists that already exist – dot size, dot colour, opacity, outline width. Microseconds; nothing is re-read from disk.
TIER_REDRAW: needs the figure replotted, but from the same embedding – image count, image zoom, figure size, which layers are drawn. Tenths of a second, because the thumbnails are re-read, so these are debounced.
TIER_RERUN: changes the embedding itself – n_neighbors, min_dist, the metric, the feature filter. There is no honest way to apply one of these to a finished figure: recomputing moves every point, and the arrangement the user was reading is the whole value of the projection. They are editable and propagated, and the panel says they land on the next run.

The tier is a fact about the artists and the data, not a policy, which is why it lives beside the field rather than in the caller.

Classes¶

`Field`	One editable Image UMAP setting.
`UmapFigureSettings`	Edit Image UMAP figure settings with debounced live application.

Functions¶

`apply_to_figure`(→ str)	Apply `values` to a finished Image UMAP figure.
`keys_for_tier`(→ Tuple[str, ...])	Every setting key in `tier`.
`live_keys`(→ Tuple[str, ...])	The settings that reach the figure already on screen.
`redraw_umap_figure`(→ bool)	Replot `fig` FROM THE SAME EMBEDDING with `values`.
`restyle_umap_figure`(→ bool)	Push the cheap settings onto the artists `fig` already carries.

Module Contents¶

class spacr.qt.widgets.umap_figure_settings.Field[source]¶

Bases: NamedTuple

One editable Image UMAP setting.

Parameters:

key – the settings key.
label – the label shown beside the editor.
kind – the editor type: "int", "float", "bool", "text" or "choice".
low – lower bound for a numeric editor (unused otherwise).
high – upper bound for a numeric editor (unused otherwise).
tier – what applying it takes: TIER_STYLE, TIER_REDRAW or TIER_RERUN.
choices – the options of a "choice" field.

class spacr.qt.widgets.umap_figure_settings.UmapFigureSettings(values: Dict[str, Any] | None = None, parent=None)[source]¶

Bases: PySide6.QtWidgets.QWidget

Edit Image UMAP figure settings with debounced live application.

Each change emits settings_changed with the complete settings dictionary after APPLY_DEBOUNCE_MS. The containing figure-settings window applies style and redraw tiers immediately; rerun-tier values are retained for the next embedding run. No separate Apply action is required.

Parameters:

values – the settings to open on. None opens on the defaults.
parent – parent widget.

Build the Image UMAP settings panel, grouped by when a change applies.

The three tiers are the point: settings that restyle the points already drawn, settings that redraw the graph from the same embedding so no point moves, and settings that only take effect on the next run.

Parameters:

values – the settings to open with; None entries fall back to the module defaults.
parent – parent widget, or None.

flush() → None[source]¶: Emit any pending change now instead of on the timer.

initial_values() → Dict[str, Any][source]¶: What the window opened on – what Cancel puts back.

live_values() → Dict[str, Any][source]¶: Only the half that reaches the figure already on screen.

values() → Dict[str, Any][source]¶: Every setting the window holds, keyed as the settings dict keys.

spacr.qt.widgets.umap_figure_settings.apply_to_figure(fig, payload: Dict[str, Any], values: Dict[str, Any], previous: Dict[str, Any] | None = None) → str[source]¶

Apply values to a finished Image UMAP figure.

Parameters:

fig – the matplotlib figure the Image UMAP was drawn into.
payload – the figure’s saved embedding payload, used for a redraw.
values – setting key to value; keys that differ from previous decide the work: any redraw-tier key replots, otherwise any style-tier key restyles.
previous – the values last applied; None treats every key as changed.

Returns:

"redraw", "style" or "" – what it actually had to do, so the caller can say whether the graph followed and can skip re-rasterising when nothing changed.

spacr.qt.widgets.umap_figure_settings.keys_for_tier(tier: str) → Tuple[str, ...][source]¶

Every setting key in tier.

Parameters:: tier – TIER_STYLE, TIER_REDRAW or TIER_RERUN; any other value gives an empty tuple.

spacr.qt.widgets.umap_figure_settings.live_keys() → Tuple[str, ...][source]¶: The settings that reach the figure already on screen.

spacr.qt.widgets.umap_figure_settings.redraw_umap_figure(fig, payload: Dict[str, Any], values: Dict[str, Any]) → bool[source]¶

Replot fig FROM THE SAME EMBEDDING with values.

The embedding in payload is read, never recomputed: this is what makes “live apply” honest on a projection. Every point keeps its coordinates and its neighbours; only what is drawn on top of them changes.

Parameters:

fig – the matplotlib figure; None returns False.
payload – dict holding embedding (array of shape (N, 2)), plot_labels or labels (one per point), and optionally records with image paths and theme_colors. A missing or mismatched embedding or labels returns False.
values – setting key to value; an unset key uses the shipped default.

Returns:

True when the figure was replotted.

spacr.qt.widgets.umap_figure_settings.restyle_umap_figure(fig, values: Dict[str, Any]) → bool[source]¶

Push the cheap settings onto the artists fig already carries.

Nothing is re-read and nothing is recomputed, so the points cannot move.

The original per-cluster face colours are stashed on the collection the first time a fixed colour is applied. Without that, switching the dot colour to red and back to cluster would leave every point red: the per-cluster colours were overwritten and there is nowhere left to read them from short of replotting.

Parameters:

fig – the matplotlib figure; None returns False.
values – setting key to value; only dot_size, point_alpha, outline_width and point_color are read, and a missing key is left alone.

Returns:

True when any artist was changed.

Nested helpers¶

redraw_umap_figure._get(key, fallback)¶

One figure setting, or the fallback when it is unset.

spacr/qt/widgets/umap_figure_settings.py:280