spacr.figure_style

Resolve spaCR figure styles for display and export.

General settings define the shared appearance of every figure. Per-graph settings override only the values needed by a specific graph type. The style tables and export-colour helpers can be used without starting Qt or importing Matplotlib at module import time.

Classes

SavedFigureAppearance

Describe how a figure should be rendered during export.

Functions

apply(→ dict)	Apply a resolved spaCR style to Matplotlib.
chrome_of(→ str)	Resolve the color of a grid, spine, or box element.
contrast_ratio(→ Optional[float])	Calculate the WCAG contrast ratio between two colours.
export_colour(→ Optional[str])	Choose an export replacement colour for a figure element.
figure_save_mode(→ str)	Return the configured figure export mode.
illegible_colour_warning(→ str)	Format a warning for low-contrast data colours.
illegible_colours(→ list)	Find data colours with insufficient contrast against a background.
is_legible_on(→ bool)	Determine whether a colour meets a contrast threshold.
page_size(→ tuple)	Calculate figure dimensions for a named page shape.
palette_colours(→ list)	Return a palette as hexadecimal colour strings.
rc_params(→ dict)	Convert spaCR style settings to Matplotlib rcParams.
relative_luminance(→ Optional[float])	Calculate the WCAG relative luminance of a colour.
resolve(→ dict)	Resolve the effective style for a graph type.
saved_figure_appearance(→ SavedFigureAppearance)	Resolve the background and figure-element colours for export.
style_choices(→ tuple)	Return the allowed values for a closed-choice style setting.
theme_ink(→ Tuple[str, str])	Return figure-element colours for the active application theme.
to_rgb(→ Optional[tuple])	Convert a colour specification to RGB components.

Module Contents

class spacr.figure_style.SavedFigureAppearance

Bases: NamedTuple

Describe how a figure should be rendered during export.

Parameters:

• mode (str) – Active mode from SAVE_MODES.

• ground (str or None) – Export background, or None to retain or remove the current background according to mode.

• ink (str or None) – Replacement colour for low-contrast non-data elements, or None to preserve their colours.

• grid (str or None) – Replacement colour for low-contrast gridlines.

• transparent (bool) – Whether the figure writer should request a transparent background.

• flip (bool) – Whether low-contrast figure elements may be recoloured.

spacr.figure_style.apply(kind: str | None = None, general: Mapping[str, Any] | None = None, overrides: Mapping[str, Any] | None = None) → dict

Apply a resolved spaCR style to Matplotlib.

Matplotlib parameters and the colour cycle are updated when their optional dependencies are available. Styling failures are ignored so that figure generation can continue.

Parameters:

• kind (str, optional) – Graph type from GRAPH_KINDS.

• general (mapping of str to Any, optional) – User-defined general settings.

• overrides (mapping of str to mapping, optional) – User-defined settings keyed by graph type.

Returns:

dict – Fully resolved spaCR style, including settings that have no Matplotlib rcParam equivalent.

spacr.figure_style.chrome_of(style, element: str = 'grid') → str

Resolve the color of a grid, spine, or box element.

Parameters:

style – figure-style mapping containing chrome color overrides.

A nonempty element-specific value takes precedence over chrome_colour. An empty result indicates that the resolved figure ink color should be used.

spacr.figure_style.contrast_ratio(colour, other) → float | None

Calculate the WCAG contrast ratio between two colours.

Parameters:

• colour (Any) – First colour specification.

• other (Any) – Second colour specification.

Returns:

float or None – Contrast ratio from 1.0 to 21.0. None is returned when either colour is transparent or cannot be parsed.

spacr.figure_style.export_colour(current, kind: str, look=None) → str | None

Choose an export replacement colour for a figure element.

Data colours are always preserved. A dark background may be replaced in print mode; gridlines and other figure elements are replaced only when the active export mode allows it and their contrast is below the configured threshold.

Parameters:

• current (Any) – Current artist colour. Transparent and unrecognized values are left unchanged.

• kind ({'ground', 'grid', 'chrome', 'data'}) – Role of the artist in the figure.

• look (SavedFigureAppearance, optional) – Export appearance. If None, use saved_figure_appearance().

Returns:

str or None – Replacement colour, or None when the current colour should be preserved.

Examples

>>> look = saved_figure_appearance("print")
>>> export_colour("#FFFFFF", "chrome", look)
'#222222'
>>> export_colour("#222222", "chrome", look) is None
True
>>> export_colour("#FFFFFF", "data", look) is None
True

spacr.figure_style.figure_save_mode() → str

Return the configured figure export mode.

A valid SPACR_FIGURE_SAVE_MODE value takes precedence over the Qt preference store, which allows command-line and notebook workflows to choose a mode without starting the GUI. Missing or invalid environment values fall through to the stored preference; if no valid preference is available, the mode is 'print'.

Returns:

{‘print’, ‘screen’, ‘transparent’} – Active export mode.

spacr.figure_style.illegible_colour_warning(names) → str

Format a warning for low-contrast data colours.

Parameters:

names (iterable of str) – Colour names returned by illegible_colours().

Returns:

str – Warning text, or an empty string when names is empty.

spacr.figure_style.illegible_colours(colours, ground=PRINT_GROUND, floor: float | None = None) → list

Find data colours with insufficient contrast against a background.

Parameters:

• colours (iterable of colour specifications) – Colours accepted by to_rgb(). Unrecognized values and numeric RGBA entries with alpha below 0.5 are ignored.

• ground (Any, default=PRINT_GROUND) – Background colour used for the contrast calculation.

• floor (float, optional) – Minimum accepted contrast ratio. If None, use DATA_CONTRAST_FLOOR.

Returns:

list of str – Sorted, deduplicated colours in #RRGGBB format.

Notes

This function reports low-contrast data colours but does not replace them, because colour may encode a result or category.

spacr.figure_style.is_legible_on(colour, ground, floor: float = CHROME_CONTRAST_FLOOR) → bool

Determine whether a colour meets a contrast threshold.

Parameters:

• colour (Any) – Foreground colour specification.

• ground (Any) – Background colour specification.

• floor (float, default=CHROME_CONTRAST_FLOOR) – Minimum accepted WCAG contrast ratio.

Returns:

bool – True when the ratio meets floor. Unrecognized and transparent colours are treated as legible so they are not recoloured.

spacr.figure_style.page_size(shape: str, width: float) → tuple

Calculate figure dimensions for a named page shape.

Parameters:

• shape ({"square", "portrait", "landscape", "wide"}) – Aspect-ratio preset.

• width (float) – Figure width in inches.

Returns:

tuple of float – (width, height) in inches.

Raises:

KeyError – If shape has no fixed ratio, including "custom".

spacr.figure_style.palette_colours(name: str | None) → list

Return a palette as hexadecimal colour strings.

Named seaborn palettes are used when they resolve successfully; otherwise, spaCR’s built-in palette is used. An empty name, or failure to load either source, returns an empty list so callers can preserve the current colour cycle.

Parameters:

name – Palette name from STYLE_CHOICES["palette"], or None.

Returns:

The resolved sequence of hexadecimal colours.

spacr.figure_style.rc_params(style: Mapping[str, Any]) → dict

Convert spaCR style settings to Matplotlib rcParams.

Settings without an equivalent Matplotlib parameter, such as per_row and label_top_n, are omitted.

Parameters:

style (mapping of str to Any) – Resolved or partial spaCR figure style.

Returns:

dict – Matplotlib parameter names and values derived from style.

spacr.figure_style.relative_luminance(colour) → float | None

Calculate the WCAG relative luminance of a colour.

Parameters:

colour (Any) – Colour specification accepted by to_rgb().

Returns:

float or None – Relative luminance in the interval [0, 1], or None when the colour is transparent or cannot be parsed.

spacr.figure_style.resolve(kind: str | None = None, general: Mapping[str, Any] | None = None, overrides: Mapping[str, Any] | None = None) → dict

Resolve the effective style for a graph type.

Settings are merged in this order: general defaults, user-defined general settings, graph-type defaults, and user-defined graph-type overrides. Entries whose value is None do not replace an earlier value.

Parameters:

• kind (str, optional) – Graph type from GRAPH_KINDS. If None, only the general layers are applied.

• general (mapping of str to Any, optional) – User-defined general settings.

• overrides (mapping of str to mapping, optional) – User-defined settings keyed by graph type.

Returns:

dict – Merged style settings. Unknown graph types inherit only the general layers and any matching entry in overrides.

spacr.figure_style.saved_figure_appearance(mode: str | None = None) → SavedFigureAppearance

Resolve the background and figure-element colours for export.

Parameters:

mode ({'print', 'screen', 'transparent'}, optional) – Export mode. If None, use figure_save_mode(). Invalid values fall back to 'print'.

Returns:

SavedFigureAppearance – Rendering instructions shared by the Matplotlib and pyqtgraph export paths. Data colours are outside this appearance and remain unchanged.

spacr.figure_style.style_choices(name: str) → tuple

Return the allowed values for a closed-choice style setting.

Parameters:

name (str) – Style key from GENERAL_DEFAULTS or GRAPH_DEFAULTS.

Returns:

tuple – Allowed values. An empty tuple indicates that the setting is free-form or unknown.

spacr.figure_style.theme_ink() → Tuple[str, str]

Return figure-element colours for the active application theme.

Returns:

• ink (str) – Colour for labels, ticks, spines, and annotations.

• grid (str) – Colour for gridlines.

Notes

Light themes use PRINT_INK and PRINT_GRID. Dark themes use DARK_INK and DARK_GRID. The light-theme pair is returned when the Qt preference store is unavailable.

spacr.figure_style.to_rgb(colour) → tuple | None

Convert a colour specification to RGB components.

Parameters:

colour (Any) – Hexadecimal, named, RGB, or RGBA colour specification.

Returns:

tuple of float or None – Three RGB components. Hexadecimal and Matplotlib colour inputs are normalized to the interval [0, 1]; numeric sequences are returned as floats. None is returned for transparent or unrecognized colours.