utils

Utility functions for visualizers module.

This module provides helper functions for common visualizers tasks, including backend-agnostic style translation and figure manipulation.

pysatl_cpd.analysis.visualization.utils.normalize_backend(value)[source]

Normalise a backend enum or string to DrawBackend.

Parameters:

value (DrawBackend | str) – Backend as enum or string.

Return type:

DrawBackend

Raises:

ValueError – If the string does not match any known backend.

pysatl_cpd.analysis.visualization.utils.is_plotly_figure(figure)[source]

Check whether a figure is a Plotly Figure.

Parameters:

figure (Figure | Figure) – Figure to check.

Return type:

TypeGuard[Figure]

pysatl_cpd.analysis.visualization.utils.is_matplotlib_figure(figure)[source]

Check whether a figure is a Matplotlib Figure.

Parameters:

figure (Figure | Figure) – Figure to check.

Return type:

TypeGuard[Figure]

pysatl_cpd.analysis.visualization.utils.is_plotly_axes(axes)[source]

Check whether axes is a Plotly subplot position tuple.

Parameters:

axes (Axes | tuple[int, int]) – Axes to check.

Return type:

TypeGuard[tuple[int, int]]

pysatl_cpd.analysis.visualization.utils.is_matplotlib_axes(axes)[source]

Check whether axes is a Matplotlib Axes object.

Parameters:

axes (Axes | tuple[int, int]) – Axes to check.

Return type:

TypeGuard[Axes]

pysatl_cpd.analysis.visualization.utils.is_plotly_mapping(mapping)[source]

Check whether mapping contains Plotly subplot positions.

Parameters:

mapping (dict[str, Axes] | dict[str, tuple[int, int]]) – Axes mapping to check.

Return type:

TypeGuard[dict[str, tuple[int, int]]]

pysatl_cpd.analysis.visualization.utils.is_matplotlib_mapping(mapping)[source]

Check whether mapping contains Matplotlib Axes objects.

Parameters:

mapping (dict[str, Axes] | dict[str, tuple[int, int]]) – Axes mapping to check.

Return type:

TypeGuard[dict[str, Axes]]

pysatl_cpd.analysis.visualization.utils.get_plotly_subplot_annotation_index(figure, row, col)[source]

Get the annotation index for a subplot in a Plotly figure.

This function calculates the correct annotation index for subplot titles in Plotly figures with arbitrary grid layouts using row-major ordering.

Parameters:

  • figure (Figure) – The Plotly figure containing subplots

  • row (int) – Subplot row position (1-indexed)

  • col (int) – Subplot column position (1-indexed)

Returns:

Annotation index in figure.layout.annotations for the subplot title

Return type:

int

Examples

>>> import plotly.graph_objects as go
>>> fig = go.Figure()
>>> fig = make_subplots(rows=2, cols=2)
>>> # Top-left subplot (1,1) -> index 0
>>> get_plotly_subplot_annotation_index(fig, 1, 1)
0
>>> # Bottom-right subplot (2,2) -> index 3
>>> get_plotly_subplot_annotation_index(fig, 2, 2)
3
pysatl_cpd.analysis.visualization.utils.translate_linestyle(linestyle)[source]

Translate linestyle strings from Plotly to Matplotlib format.

Parameters:

linestyle (str) – Linestyle string in source format (Plotly).

Returns:

Linestyle string in target format.

Return type:

str

Raises:

ValueError – If linestyle is not recognized.

Examples

>>> translate_linestyle("dash")
'--'
>>> translate_linestyle("dashdot")
'-.'
pysatl_cpd.analysis.visualization.utils.to_plotly_color(color)[source]

Convert a Matplotlib-style color to a Plotly-compatible color.

Return type:

str | None

Parameters:

color (str | None)

pysatl_cpd.analysis.visualization.utils.to_plotly_dash(linestyle)[source]

Convert a Matplotlib linestyle to Plotly dash style.

Return type:

str | None

Parameters:

linestyle (str | None)

pysatl_cpd.analysis.visualization.utils.to_plotly_marker(marker)[source]

Convert a Matplotlib marker to a Plotly marker symbol.

Return type:

str | None

Parameters:

marker (str | None)

pysatl_cpd.analysis.visualization.utils.resolve_legend_visibility(spec, *, allow_legend=True)[source]

Return whether a visual element should participate in the legend.

Return type:

bool

Parameters:
pysatl_cpd.analysis.visualization.utils.resolve_legend_label(spec)[source]

Return the effective legend label for a visual element.

Return type:

str | None

Parameters:

spec (LineSpec | FillSpec | FilledLineSpec)

pysatl_cpd.analysis.visualization.utils.resolve_legend_group(spec)[source]

Return the effective Plotly legend group for a visual element.

Return type:

str | None

Parameters:

spec (LineSpec | FillSpec | FilledLineSpec)

pysatl_cpd.analysis.visualization.utils.get_matplotlib_legend_label(spec, *, allow_legend=True)[source]

Return the label to pass to Matplotlib, or None.

Return type:

str | None

Parameters:
pysatl_cpd.analysis.visualization.utils.get_plotly_legend_kwargs(spec, *, allow_legend=True, primary_trace=True)[source]

Return Plotly legend kwargs for a logical visual element.

Return type:

dict[str, Any]

Parameters:
pysatl_cpd.analysis.visualization.utils.line_spec_to_mpl_kwargs(spec)[source]

Convert a shared line spec to Matplotlib line kwargs.

Return type:

dict[str, Any]

Parameters:

spec (LineSpec)

pysatl_cpd.analysis.visualization.utils.line_spec_to_plotly_trace_kwargs(spec)[source]

Convert a shared line spec to Plotly trace kwargs.

Return type:

dict[str, Any]

Parameters:

spec (LineSpec)

pysatl_cpd.analysis.visualization.utils.fill_spec_to_mpl_kwargs(spec)[source]

Convert a shared fill spec to Matplotlib fill kwargs.

Return type:

dict[str, Any]

Parameters:

spec (FillSpec)

pysatl_cpd.analysis.visualization.utils.fill_spec_to_plotly_trace_kwargs(spec)[source]

Convert a shared fill spec to Plotly trace kwargs.

Return type:

dict[str, Any]

Parameters:

spec (FillSpec)

pysatl_cpd.analysis.visualization.utils.filled_line_spec_to_mpl_line_kwargs(spec)[source]

Convert a filled line spec to Matplotlib line kwargs.

Return type:

dict[str, Any]

Parameters:

spec (FilledLineSpec)

pysatl_cpd.analysis.visualization.utils.filled_line_spec_to_mpl_fill_kwargs(spec)[source]

Convert a filled line spec to Matplotlib fill kwargs.

Return type:

dict[str, Any]

Parameters:

spec (FilledLineSpec)

pysatl_cpd.analysis.visualization.utils.rgba_color(color, alpha)[source]

Return an rgba Plotly color string for a line/fill color.

Return type:

str

Parameters:
pysatl_cpd.analysis.visualization.utils.filled_line_spec_to_plotly_trace_kwargs(spec)[source]

Convert a filled line spec to Plotly trace kwargs.

Return type:

dict[str, Any]

Parameters:

spec (FilledLineSpec)

pysatl_cpd.analysis.visualization.utils.apply_matplotlib_plot_spec(ax, spec, *, grid_alpha=0.3)[source]

Apply plot metadata from a shared plot spec to Matplotlib axes.

Return type:

None

Parameters:
pysatl_cpd.analysis.visualization.utils.apply_matplotlib_twin_plot_spec(ax, spec)[source]

Apply twin-axis metadata from a shared plot spec to Matplotlib axes.

Return type:

None

Parameters:
pysatl_cpd.analysis.visualization.utils.apply_plotly_plot_spec(figure, row, col, spec, *, grid_width=1, grid_color='lightgray')[source]

Apply plot metadata from a shared plot spec to a Plotly subplot.

Return type:

None

Parameters:
pysatl_cpd.analysis.visualization.utils.apply_plotly_twin_plot_spec(figure, row, col, spec)[source]

Apply twin-axis metadata from a shared plot spec to a Plotly subplot.

Return type:

None

Parameters:
pysatl_cpd.analysis.visualization.utils.get_subplot_y_limits(fig, axes)[source]

Extract min and max y-values from actual data traces for a Plotly subplot.

This function analyzes all traces associated with a specific subplot and computes the data range, adding a small padding to ensure comfortable viewing margins.

Parameters:

  • fig (Figure) – Plotly figure containing the subplot.

  • axes (tuple[int, int]) – Subplot position as a tuple (row, column). Row and column indices are 1-based as used in Plotly’s subplot addressing.

Returns:

(y_min, y_max) representing the recommended y-axis limits for the subplot, with padding applied. Returns (0.0, 1.0) if no data found.

Return type:

tuple[float, float]

Raises:

ValueError – If no finite y values are found in the subplot traces.

Notes

The function uses a hack with dynamic attributes to track whether padding has already been applied for a given subplot. Padding is applied only once per subplot to avoid recursive expansion.

The y-axis mapping is determined using Plotly’s internal _grid_ref structure. If not available, a fallback mapping based on row number is used.

Examples

>>> import plotly.graph_objects as go
>>> fig = go.Figure()
>>> fig.add_trace(go.Scatter(x=[0,1,2], y=[5,10,15]), row=1, col=1)
>>> y_min, y_max = get_subplot_y_limits(fig, (1, 1))
>>> print(f"{y_min:.2f}, {y_max:.2f}")
4.75, 15.25