Plotters

pybasin.plotters.matplotlib_plotter.MatplotlibPlotter

Functions

init

__init__(bse: BasinStabilityEstimator)

Initialize the Plotter with a BasinStabilityEstimator instance.

Parameters:

Name	Type	Description	Default
`bse`	`BasinStabilityEstimator`	An instance of BasinStabilityEstimator.	required

save

save(dpi: int = 300) -> None

Save all pending figures to the output directory.

Figures are tracked when plot methods create new figures (i.e., when no ax parameter is passed). Call this after plotting to save all figures at once.

Parameters:

Name	Type	Description	Default
`dpi`	`int`	Resolution for saved images.	`300`

Raises:

Type	Description
`ValueError`	If `bse.output_dir` is not set or no figures pending.

show

show() -> None

Display all matplotlib figures.

Convenience wrapper around plt.show() so users don't need to import matplotlib separately.

plot_basin_stability_bars

plot_basin_stability_bars(ax: Axes | None = None) -> Axes

Plot basin stability values as a bar chart.

Parameters:

Name	Type	Description	Default
`ax`	`Axes \| None`	Matplotlib axes to plot on. If None, creates a new figure.	`None`

Returns:

Type	Description
`Axes`	The Axes object with the plot.

plot_state_space

plot_state_space(ax: Axes | None = None) -> Axes

Plot initial conditions in state space, colored by their attractor labels.

Parameters:

Name	Type	Description	Default
`ax`	`Axes \| None`	Matplotlib axes to plot on. If None, creates a new figure.	`None`

Returns:

Type	Description
`Axes`	The Axes object with the plot.

plot_feature_space

plot_feature_space(ax: Axes | None = None) -> Axes

Plot feature space with classifier results.

Parameters:

Name	Type	Description	Default
`ax`	`Axes \| None`	Matplotlib axes to plot on. If None, creates a new figure.	`None`

Returns:

Type	Description
`Axes`	The Axes object with the plot.

plot_bse_results

plot_bse_results() -> Figure

Generate diagnostic plots using the data stored in self.solution: 1. A bar plot of basin stability values. 2. A scatter plot of initial conditions (state space). 3. A scatter plot of the feature space with classifier results. 4. A placeholder plot for future use.

This method combines the individual plotting functions into a 2x2 grid. For individual plots, use plot_basin_stability_bars(), plot_state_space(), or plot_feature_space() directly.

Returns:

Type	Description
`Figure`	The Figure object with the 2x2 grid of plots.

plot_templates_phase_space

plot_templates_phase_space(
    x_var: int = 0,
    y_var: int = 1,
    z_var: int | None = None,
    time_range: tuple[float, float] = (700, 1000),
) -> Figure

Plot trajectories for the template initial conditions in 2D or 3D phase space.

Creates a CPU copy of the solver with 10x the original n_steps for smoother visualization. Caching is disabled to avoid polluting the cache with visualization-specific integrations.

Parameters:

Name	Type	Description	Default
`x_var`	`int`	State variable index for x-axis.	`0`
`y_var`	`int`	State variable index for y-axis.	`1`
`z_var`	`int \| None`	State variable index for z-axis (3D plot if provided).	`None`
`time_range`	`tuple[float, float]`	Time range (t_start, t_end) to plot.	`(700, 1000)`

plot_templates_trajectories

plot_templates_trajectories(
    plotted_var: int,
    y_limits: tuple[float, float]
    | dict[str, tuple[float, float]]
    | None = None,
    x_limits: tuple[float, float]
    | dict[str, tuple[float, float]]
    | None = None,
) -> Figure

Plot template trajectories as vertically stacked subplots.

Each trajectory gets its own row with independent y-axis scaling. This handles different amplitudes across attractors cleanly.

Creates a CPU copy of the solver with 10x the original n_steps for smoother visualization. Caching is disabled to avoid polluting the cache with visualization-specific integrations.

Parameters:

Name	Type	Description	Default
`plotted_var`	`int`	Index of the state variable to plot.	required
`y_limits`	`tuple[float, float] \| dict[str, tuple[float, float]] \| None`	Y-axis limits. Tuple applies to all, dict maps label to (y_min, y_max).	`None`
`x_limits`	`tuple[float, float] \| dict[str, tuple[float, float]] \| None`	X-axis limits. Tuple applies to all, dict maps label to (x_min, x_max).	`None`

pybasin.plotters.interactive_plotter.plotter.InteractivePlotter

Interactive web-based plotter for basin stability visualization.

Uses Dash with Mantine components for a modern UI and Plotly for interactive visualizations. Each page owns its controls, plot, and callbacks.

Attributes:

Name	Type	Description
`bse`	`BasinStabilityEstimator`	BasinStabilityEstimator instance with computed results.
`state_labels`		Optional mapping of state indices to custom labels.
`app`	`Dash \| None`	Dash application instance.

Functions

init

__init__(
    bse: BasinStabilityEstimator | BasinStabilityStudy,
    state_labels: dict[int, str] | None = None,
    options: InteractivePlotterOptions | None = None,
)

Initialize the Plotter.

Parameters:

Name	Type	Description	Default
`bse`	`BasinStabilityEstimator \| BasinStabilityStudy`	BasinStabilityEstimator or BasinStabilityStudy instance.	required
`state_labels`	`dict[int, str] \| None`	Optional dict mapping state indices to labels, e.g., {0: "θ", 1: "ω"} for a pendulum system.	`None`
`options`	`InteractivePlotterOptions \| None`	Optional configuration for default control values.	`None`

run

run(port: int = 8050, debug: bool = False) -> None

Launch the interactive plotter as a standalone Dash server.

Parameters:

Name	Type	Description	Default
`port`	`int`	Port to run the server on (default: 8050).	`8050`
`debug`	`bool`	Enable Dash debug mode (default: False).	`False`

pybasin.matplotlib_study_plotter.MatplotlibStudyPlotter

Matplotlib-based plotter for parameter study basin stability results.

Supports multi-parameter studies by grouping results along one chosen parameter (x-axis) while producing separate curves for each combination of the remaining parameters. When parameters is not passed, one figure is produced per studied parameter.

Attributes:

Name	Type	Description
`bs_study`		BasinStabilityStudy instance with computed results.

Functions

init

__init__(bs_study: BasinStabilityStudy)

Initialize the plotter with a BasinStabilityStudy instance.

Parameters:

Name	Type	Description	Default
`bs_study`	`BasinStabilityStudy`	An instance of BasinStabilityStudy.	required

save

save(dpi: int = 300) -> None

Save all pending figures to the output directory.

Figures are tracked when plot methods create new figures. Call this after plotting to save all figures at once.

Parameters:

Name	Type	Description	Default
`dpi`	`int`	Resolution for saved images.	`300`

Raises:

Type	Description
`ValueError`	If `bs_study.output_dir` is not set or no figures pending.

show

show() -> None

Display all matplotlib figures.

Convenience wrapper around plt.show() so users don't need to import matplotlib separately.

plot_parameter_stability

plot_parameter_stability(
    interval: Literal["linear", "log"] = "linear",
    parameters: list[str] | None = None,
) -> list[Figure]

Plot basin stability values against parameter variation.

Produces one figure per parameter. Colors represent attractors so that downstream recolor_figure calls reassign thesis-palette colors correctly. For multi-parameter studies, line style and marker vary per group (combination of the other parameters).

Parameters:

Name	Type	Description	Default
`interval`	`Literal['linear', 'log']`	x-axis scale — `'linear'` or `'log'`.	`'linear'`
`parameters`	`list[str] \| None`	Which studied parameters to plot. `None` plots all.	`None`

Returns:

Type	Description
`list[Figure]`	List of matplotlib Figure objects (one per parameter).

plot_orbit_diagram

plot_orbit_diagram(
    dof: list[int] | None = None,
    interval: Literal["linear", "log"] = "linear",
    parameters: list[str] | None = None,
) -> list[Figure]

Plot orbit diagrams showing attractor amplitude levels over parameter variation.

Produces one figure per parameter. For each attractor at each parameter value, displays the peak amplitudes detected from steady-state trajectories. Period-N orbits appear as N distinct amplitude bands.

Requires compute_orbit_data when creating the BasinStabilityStudy.

Parameters:

Name	Type	Description	Default
`interval`	`Literal['linear', 'log']`	x-axis scale — `'linear'` or `'log'`.	`'linear'`
`dof`	`list[int] \| None`	List of state indices to plot. If None, uses the DOFs from orbit_data.	`None`
`parameters`	`list[str] \| None`	Which studied parameters to plot. `None` plots all.	`None`

Returns:

Type	Description
`list[Figure]`	List of matplotlib Figure objects (one per parameter).

Raises:

Type	Description
`ValueError`	If orbit_data was not computed during the study.