abaquant.visualization.core

Import path: abaquant.visualization.core

Domain: Matplotlib and Plotly visualization helpers with shared themes.

Purpose

Global styling, backend selection, and export helpers for visualizations.

When to use it

Use these functions to inspect model behavior, portfolio allocations, market surfaces, credit assessments, calibrations, and dashboard outputs.

Public objects

  • class: VisualizationError — Raised when a visualization request cannot be produced or exported.

  • class: VisualizationTheme — Reusable presentation and export settings for all library plots.

  • function: get_visualization_theme — Return the immutable global visualization theme currently in effect.

  • function: configure_visualization — Set and return the global visualization theme.

  • function: reset_visualization_theme — Restore the built-in global visualization theme and return it.

  • function: visualization_theme — Temporarily apply a theme inside a ‘’with’’ block.

  • function: resolve_theme — Resolve one per-call theme, applying an optional backend override.

  • function: validate_backend — Validate one backend name, using the global theme when ‘’None’’.

  • function: require_matplotlib — Import Matplotlib lazily and raise an actionable error when missing.

  • function: require_plotly — Import Plotly lazily and raise an actionable error when missing.

  • function: matplotlib_axes — Create one styled Matplotlib figure and axes using ‘’theme’’.

  • function: style_matplotlib_axes — Apply typography, grid, and color-cycle settings to Matplotlib axes.

  • function: style_matplotlib_title — Set a consistently themed Matplotlib axes title.

  • function: style_plotly_figure — Apply global layout, typography, palette, and dimensions to Plotly figures.

  • function: save_figure — Persist one backend-native figure and return its resolved output path.

  • function: finalize_figure — Optionally export a figure according to explicit or global theme settings.

Detailed reference

Global styling, backend selection, and export helpers for visualizations.

The visualization layer is configured once through configure_visualization(). Every public visualize method resolves the active VisualizationTheme unless an explicit theme or backend is supplied. Figure creation never calls show; optional export is controlled through the active theme or a per-call save_path.

exception abaquant.visualization.core.VisualizationError

Bases: RuntimeError

Raised when a visualization request cannot be produced or exported.

class abaquant.visualization.core.VisualizationTheme(backend='matplotlib', color_sequence=('#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b'), background_color='white', paper_color='white', grid_color='#d9d9d9', font_family='DejaVu Sans', base_font_size=11.0, title_font_size=15.0, figure_size=(10.0, 6.0), dpi=120, line_width=2.0, marker_size=6.0, transparent=False, save_directory=None, save_format='png', auto_save=False, filename_prefix='abaquant')

Bases: object

Reusable presentation and export settings for all library plots.

Parameters:

  • backend ({"matplotlib", "plotly"}, default="matplotlib") – Backend used when individual visualize calls omit backend.

  • color_sequence (sequence of str, optional) – Ordered color palette used for lines, bars, and markers. CSS color names and hexadecimal color strings are accepted by both supported backends.

  • background_color (str, default="white") – Plot-area and canvas colors. paper_color applies to Plotly canvas; Matplotlib uses background_color for the figure face color.

  • paper_color (str, default="white") – Plot-area and canvas colors. paper_color applies to Plotly canvas; Matplotlib uses background_color for the figure face color.

  • grid_color (str, default="#d9d9d9") – Gridline color for Cartesian charts.

  • font_family (str, default="DejaVu Sans") – Preferred font family. Availability depends on the local rendering environment.

  • base_font_size (float, default=11.0) – Default axis, legend, and tick-label font size in points.

  • title_font_size (float, default=15.0) – Figure-title font size in points.

  • figure_size (tuple[float, float], default=(10.0, 6.0)) – Default figure width and height in inches for Matplotlib. Plotly uses the equivalent pixel dimensions derived from dpi.

  • dpi (int, default=120) – Raster resolution used by Matplotlib and as the conversion basis for Plotly layout dimensions.

  • line_width (float, default=2.0) – Default line width for line charts.

  • marker_size (float, default=6.0) – Default marker size for scatter and lattice charts.

  • transparent (bool, default=False) – Whether saved outputs should request transparent backgrounds where the selected backend and format support it.

  • save_directory (str or pathlib.Path, optional) – Directory used when auto_save=True and no explicit save_path is provided. Directories are created on demand.

  • save_format (str, default="png") – File format appended to generated filenames when no extension is given. Matplotlib supports its installed writers. Plotly static image export requires the optional kaleido package; html requires no extra renderer.

  • auto_save (bool, default=False) – Save every newly created visualization using save_directory and a generated file name. A missing save_directory raises an error.

  • filename_prefix (str, default="abaquant") – Prefix used for generated filenames.

abaquant.visualization.core.get_visualization_theme()

Return the immutable global visualization theme currently in effect.

Return type:

VisualizationTheme

abaquant.visualization.core.configure_visualization(theme=None, /, **overrides)

Set and return the global visualization theme.

Parameters:

  • theme (VisualizationTheme, optional) – Complete baseline theme. When omitted, the current theme is used as the baseline.

  • **overrides – Named VisualizationTheme fields to replace on the baseline.

Returns:

Newly active immutable theme.

Return type:

VisualizationTheme

abaquant.visualization.core.reset_visualization_theme()

Restore the built-in global visualization theme and return it.

Return type:

VisualizationTheme

abaquant.visualization.core.visualization_theme(theme=None, /, **overrides)

Temporarily apply a theme inside a with block.

The previous global theme is restored even when plotting raises an error.

Parameters:
Return type:

Iterator[VisualizationTheme]

abaquant.visualization.core.resolve_theme(theme=None, backend=None)

Resolve one per-call theme, applying an optional backend override.

Parameters:
Return type:

VisualizationTheme

abaquant.visualization.core.validate_backend(backend)

Validate one backend name, using the global theme when None.

Parameters:

backend (str | None)

Return type:

Literal[‘matplotlib’, ‘plotly’]

abaquant.visualization.core.require_matplotlib()

Import Matplotlib lazily and raise an actionable error when missing.

abaquant.visualization.core.require_plotly()

Import Plotly lazily and raise an actionable error when missing.

abaquant.visualization.core.matplotlib_axes(pyplot, theme)

Create one styled Matplotlib figure and axes using theme.

Parameters:

theme (VisualizationTheme)

abaquant.visualization.core.style_matplotlib_axes(axes, theme, *, grid_axis='both')

Apply typography, grid, and color-cycle settings to Matplotlib axes.

Parameters:
Return type:

None

abaquant.visualization.core.style_matplotlib_title(axes, title, theme)

Set a consistently themed Matplotlib axes title.

Parameters:
Return type:

None

abaquant.visualization.core.style_plotly_figure(figure, theme, *, title=None, xaxis_title=None, yaxis_title=None)

Apply global layout, typography, palette, and dimensions to Plotly figures.

Parameters:

  • theme (VisualizationTheme)

  • title (str | None)

  • xaxis_title (str | None)

  • yaxis_title (str | None)

abaquant.visualization.core.save_figure(figure, *, backend=None, path=None, filename=None, theme=None, default_name='visualization')

Persist one backend-native figure and return its resolved output path.

Explicit path takes precedence. Otherwise, the theme’s save_directory and save_format define the destination.

Parameters:

  • backend (Literal['matplotlib', 'plotly'] | None)

  • path (str | Path | None)

  • filename (str | None)

  • theme (VisualizationTheme | None)

  • default_name (str)

Return type:

Path

abaquant.visualization.core.finalize_figure(figure, *, backend=None, theme=None, save_path=None, filename=None, default_name='visualization')

Optionally export a figure according to explicit or global theme settings.

Parameters:

  • backend (Literal['matplotlib', 'plotly'] | None)

  • theme (VisualizationTheme | None)

  • save_path (str | Path | None)

  • filename (str | None)

  • default_name (str)