spacr.style_base

Shared figure-style values and rendering conventions.

Figure-specific style dataclasses inherit FigureStyle so common controls have the same name and can be copied between plots. Renderers use the signature render(data, style, *, figure=None, save_path=None) and return (figure, axes). Passing figure redraws an existing canvas; passing save_path also writes the result with spaCR’s export settings.

Classes

FigureStyle

Appearance settings shared by every spaCR figure.

Functions

apply_page(→ None)

Apply shared axes, typography, grid, spine, and page settings.

font_names(→ List[str])

The families to ask matplotlib for, best first, face REGISTERED.

font_rc(→ Dict[str, Any])

The Matplotlib font parameters a style asks for.

style_kind(→ str)

Return a stable figure kind derived from a style class name.

write(→ str)

Write a styled figure with spaCR's standard export pipeline.

Module Contents

class spacr.style_base.FigureStyle[source]

Appearance settings shared by every spaCR figure.

Plot-specific options, such as an effect-size threshold or a colour-by column, belong on the corresponding subclass. Keeping only portable values here allows a saved house style to be applied across plot types.

Parameters:

  • x_label – horizontal-axis label supplied to the renderer; empty permits renderer-specific or default behavior.

  • y_label – vertical-axis label supplied to the renderer; empty permits renderer-specific or default behavior.

  • title – figure title; empty suppresses the shared title operation.

  • x_scale – Matplotlib horizontal scale from SCALES.

  • y_scale – Matplotlib vertical scale from SCALES.

  • x_lim – explicit horizontal (minimum, maximum) limits, or None for data-derived limits.

  • y_lim – explicit vertical (minimum, maximum) limits, or None.

  • invert_x – whether to reverse the horizontal axis after limits apply.

  • invert_y – whether to reverse the vertical axis after limits apply.

  • font_family – font-family preference available to renderers that support a figure-wide family. Defaults to the face spaCR ships; see font_names().

  • font_size – base text size available for plot-specific prose.

  • title_font_size – title size in points.

  • label_font_size – axis-label size in points.

  • tick_font_size – tick-label size in points.

  • font_weight – shared Matplotlib text weight.

  • figure_width – figure-canvas width in inches for live and saved use.

  • figure_height – figure-canvas height in inches for live and saved use.

  • dpi – dots per inch used for raster output.

  • grid – whether the selected grid is visible.

  • grid_axis – axes receiving grid lines: "x", "y", "both", or "none".

  • grid_color – Matplotlib-compatible grid-line color.

  • grid_width – grid-line width in points.

  • hide_top_right_spines – whether to remove the top and right frame lines.

  • legend – whether renderers with keyed marks should draw a legend.

  • legend_location – Matplotlib legend placement from SHARED_CHOICES.

  • background_color – named page and axes color; "none" delegates the background choice to the renderer.

  • transparent – whether exported figure backgrounds are transparent.

as_dict() → Dict[str, Any][source]

Every field by name. Portable between styles that share them.

shared_with(other: FigureStyle) → Dict[str, Any][source]

The fields BOTH styles have, so one can be applied to the other.

Parameters:

other – figure-style dataclass whose shared field names define the returned values.

What makes a house style a house style: a font size and a grid chosen on a volcano should reach the comparison figure beside it, while the volcano’s effect-size threshold must not follow it there.

spacr.style_base.apply_page(figure, axes, style: FigureStyle) → None[source]

Apply shared axes, typography, grid, spine, and page settings.

Parameters:

  • figure – Matplotlib figure whose page appearance is updated.

  • axes – Matplotlib axes whose presentation is updated.

  • style – shared figure-style settings to apply.

Call this after drawing plot-specific marks. It changes figure and axes presentation only; it does not add or remove data marks. The title, the axis labels and the tick labels are put into the style’s family – font_names() – so a renderer that draws outside a font rc_context still gets the face spaCR ships rather than DejaVu Sans.

spacr.style_base.font_names(style: FigureStyle) → List[str][source]

The families to ask matplotlib for, best first, face REGISTERED.

Parameters:

style – figure style whose font_family is the first choice.

Returns:

a family list suitable for font.family, a FontProperties or matplotlib.text.Text.set_fontfamily(). A generic family is returned alone, because matplotlib resolves it through its own list.

Naming a family is not the same as having it. Matplotlib answers a name it cannot find by falling back – silently, bar a findfont warning – to DejaVu Sans, so a style saying “Open Sans” on a machine where Open Sans was never installed drew in DejaVu Sans and looked nothing like the interface around it. This REGISTERS the faces spaCR ships before naming them, which is what makes the name resolve on that machine, and puts FONT_FAMILY last so a chosen family the machine lacks lands on the house face instead of DejaVu Sans.

Nothing is listed after FONT_FAMILY: it is registered from a file in the package, so it always resolves, and an unreachable name in the list would only make matplotlib warn once per drawn string about a font it was never going to use.

spacr.style_base.font_rc(style: FigureStyle) → Dict[str, Any][source]

The Matplotlib font parameters a style asks for.

Parameters:

style – figure style supplying family, size and weight.

Returns:

rcParams entries to draw inside, as matplotlib.rc_context takes them.

Hand this to rc_context rather than assembling font.* by hand: the family arrives as the resolvable list font_names() builds, with the bundled face already registered.

spacr.style_base.style_kind(style: Any) → str[source]

Return a stable figure kind derived from a style class name.

Parameters:

style – style instance whose class name identifies the figure kind.

For example, VolcanoStyle becomes "volcano". Deriving the value prevents independently declared names from colliding and keeps this headless helper independent of the Qt plotting widgets.

spacr.style_base.write(figure, save_path, style: FigureStyle) → str[source]

Write a styled figure with spaCR’s standard export pipeline.

Parameters:

  • figure – drawn Matplotlib figure to export.

  • save_path – destination path; its suffix selects the format.

  • style – figure-style export settings, including DPI and transparency.

The extension in save_path selects the format. Raster outputs use the style’s DPI; font embedding, paper repainting, transparency, and bounding box behavior are delegated to spacr.plot.save_figure().