registry Module#

Theme registry and management for Episia.

This module maintains the global theme state and provides functions for getting/setting themes, retrieving color palettes, and registering custom themes.

Functions#

episia.viz.themes.registry.set_theme(theme)[source]#

Set the active Episia theme globally.

Applies the Matplotlib style if available silently skips if matplotlib.style is unavailable in the current environment.

Parameters:: theme (str) – One of ‘scientific’, ‘minimal’, ‘dark’, ‘colorblind’.
Raises:: ValueError – Unknown theme name.
Return type:: None

episia.viz.themes.registry.get_theme()[source]#

Return the currently active theme name.

Return type:: str

episia.viz.themes.registry.get_available_themes()[source]#

Return list of all available theme names.

Return type:: List[str]

episia.viz.themes.registry.get_palette(theme=None)[source]#

Return the colour palette for a given theme (or the active theme).

Parameters:: theme (str | None) – Theme name. Defaults to active theme.
Returns:: List of hex colour strings.
Return type:: List[str]

episia.viz.themes.registry.get_plotly_layout(theme=None)[source]#

Return a base Plotly layout dict for a given theme.

Intended for use inside plotly_plotter provides consistent background colours and font colours per theme.

Parameters:: theme (str | None) – Theme name. Defaults to active theme.
Returns:: Dict suitable for go.Figure(layout=…) or fig.update_layout().
Return type:: Dict[str, Any]

episia.viz.themes.registry.apply_mpl_theme(theme=None)[source]#

Apply Matplotlib style for the given (or active) theme.

Called automatically by MatplotlibPlotter before each plot. Can be called manually to affect any subsequent plt calls.

Parameters:: theme (str | None) – Theme name. Defaults to active theme.
Return type:: None

episia.viz.themes.registry.register_theme(name, palette, mplstyle_path=None, bg_paper='#ffffff', bg_plot='#ffffff', font_color='#222222')[source]#

Parameters:

name (str) – Theme identifier (must be unique).
palette (List[str]) – List of hex colour strings (min 4).
mplstyle_path (str | None) – Path to a .mplstyle file (optional).
bg_paper (str) – Plotly paper background colour.
bg_plot (str) – Plotly plot background colour.
font_color (str) – Default font colour for Plotly.

Raises:

ValueError – palette has fewer than 4 colours.

Return type:

None

Example:

register_theme(
    "xcept",
    palette=["#0d6efd", "#dc3545", "#198754", "#ffc107"],
    bg_paper="#f8f9fa",
)
set_theme("xcept")

Data#

episia.viz.themes.registry.AVAILABLE_THEMES: List[str] = ['scientific', 'minimal', 'dark', 'colorblind']#

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Built-in Themes#

Theme Name	Description	Use Case
`scientific`	Clean, high-contrast	Default, general purpose
`minimal`	No grid, maximum whitespace	Minimalist dashboards
`dark`	Dark background	Night mode, presentations
`colorblind`	Accessible palette	Colorblind-safe publications

Examples#

Basic theme usage:

from episia.viz.themes import set_theme, get_available_themes

# Check available themes
print(get_available_themes())
# ['scientific', 'minimal', 'dark', 'colorblind']

# Set theme globally
set_theme("dark")

# All subsequent plots will use dark theme
fig = plot_epicurve(result)  # Uses dark theme

# Get current theme
current = get_theme()
print(current)  # 'dark'

Getting color palettes:

from episia.viz.themes import get_palette

# Get palette for specific theme
colors = get_palette("colorblind")
print(colors)
# ['#0072B2', '#E69F00', '#56B4E9', '#009E73', '#F0E442', '#D55E00', ...]

# Use in custom plots
import matplotlib.pyplot as plt
for i, color in enumerate(colors[:3]):
    plt.plot(x, y[i], color=color)

Registering custom themes:

from episia.viz.themes import register_theme, set_theme

# Register institutional theme
register_theme(
    name="xcept_health",
    palette=["#0d6efd", "#dc3545", "#198754", "#ffc107", "#6c757d"],
    mplstyle_path="/path/to/custom.mplstyle",  # optional
    bg_paper="#f8f9fa",
    bg_plot="#ffffff",
    font_color="#212529"
)

# Use it immediately
set_theme("xcept_health")

Applying theme manually:

from episia.viz.themes import apply_mpl_theme

# Apply theme to current matplotlib session
apply_mpl_theme("scientific")

# All subsequent matplotlib commands use the theme
import matplotlib.pyplot as plt
plt.plot(x, y)  # Uses scientific theme styling

Plotly layout extraction:

from episia.viz.themes import get_plotly_layout

# Get base layout dict for theme
layout = get_plotly_layout("minimal")

# Use in custom Plotly figures
import plotly.graph_objects as go
fig = go.Figure(data=data, layout=layout)