Diagnostics

diagnostics

Plotting utilities for diagnostics.

All functions return matplotlib (fig, ax) objects and never call plt.show().

Functions

plot_chain_2d

plot_chain_2d(samples, *, used_hf=None, theta_true=None, title=None, names=('θ₁', 'θ₂'), show=False)

Scatter plot of a 2D chain, optionally highlighting HF steps.

Parameters:

Name	Type	Description	Default
`samples`	`ArrayLike`	Sample array of shape `(n_steps, 2)`.	required
`used_hf`	`ArrayLike \| None`	Optional boolean array of shape `(n_steps,)` indicating whether HF was used at each step. If provided, surrogate-only steps and HF steps are plotted with different markers.	`None`
`theta_true`	`ArrayLike \| None`	Optional reference parameter of shape `(2,)` to overlay as a marker.	`None`
`title`	`str \| None`	Optional title.	`None`
`names`	`tuple[str, str]`	Axis labels for the two parameters.	`('θ₁', 'θ₂')`
`show`	`bool`	If True, call `plt.show()` before returning.	`False`

Returns:

Type	Description
`(fig, ax)`	Matplotlib figure and axes.

plot_cumulative_hf_fraction

plot_cumulative_hf_fraction(used_hf, *, burn_in=0, labels=None, title='High-fidelity usage over iterations', show=False)

Plot cumulative HF usage fraction over iterations.

Given a boolean series used_hf indicating whether the high-fidelity (HF) model was used at each MCMC step, this function plots the cumulative HF fraction.

The function supports plotting multiple runs by passing a sequence of arrays.

Parameters:

Name	Type	Description	Default
`used_hf`	`ArrayLike \| Sequence[ArrayLike]`	Either a single boolean array of shape `(n_steps,)` or a sequence of such arrays. True indicates that the HF model was used at that step.	required
`burn_in`	`int`	Number of initial steps to discard before computing the cumulative fraction. Must be non-negative.	`0`
`labels`	`Sequence[str] \| None`	Optional labels for each series when `used_hf` is a sequence. If provided, its length must match the number of series.	`None`
`title`	`str`	Title for the plot.	`'High-fidelity usage over iterations'`
`show`	`bool`	If True, call `plt.show()` before returning. For MkDocs/Jupyter usage, leaving this False is recommended.	`False`

Returns:

Type	Description
`(fig, ax or None)`	Returns `(fig, ax)` if at least one series contains data after burn-in. Returns `None` if nothing can be plotted (e.g. all series empty after burn-in).

Raises:

Type	Description
`ValueError`	If `burn_in` is negative or if `labels` has the wrong length.

Notes

In active-learning runs, HF usage flags are typically recorded by ActiveMCMCModel.log.used_hf and attached to the chain extras.

See Also

plot_subchain_length_history Visualise how the adaptive subchain length changes over time.

plot_subchain_length_history

plot_subchain_length_history(subchain_length, *, title='Adaptive subchain length history', show=False)

Plot the adaptive subchain length history.

Parameters:

Name	Type	Description	Default
`subchain_length`	`ArrayLike`	1D integer array of subchain lengths. Values must be positive.	required
`title`	`str`	Plot title.	`'Adaptive subchain length history'`
`show`	`bool`	If True, call `plt.show()` before returning.	`False`

Returns:

Type	Description
`(fig, ax or None)`	Returns `(fig, ax)` if `subchain_length` is non-empty, otherwise `None`.

Raises:

Type	Description
`ValueError`	If any subchain length is non-positive.

See Also

AdaptiveSubchainState.subchain_history Field where the adaptive policy records the subchain length per coarse call.

plot_surrogate_error_history

plot_surrogate_error_history(errors, *, target=None, title='Surrogate accuracy over time', show=False)

Plot surrogate-HF discrepancy over fine evaluations.

Parameters:

Name	Type	Description	Default
`errors`	`ArrayLike`	1D array of non-negative error values (e.g. RMSE between LF mean and HF output) recorded at fine evaluations.	required
`target`	`float \| None`	Optional target error level. If provided, a horizontal reference line is drawn.	`None`
`title`	`str`	Plot title.	`'Surrogate accuracy over time'`
`show`	`bool`	If True, call `plt.show()` before returning.	`False`

Returns:

Type	Description
`(fig, ax or None)`	Returns `(fig, ax)` if `errors` is non-empty, otherwise `None`.

Raises:

Type	Description
`ValueError`	If any error is negative or if `target` is negative.

See Also

AdaptiveSubchainState.hf_errors Error history recorded by the adaptive policy.

plot_pod_energy

plot_pod_energy(Y, *, r_max=50, center=True, thresholds=(0.9, 0.95, 0.99), show=False)

Plot per-mode and cumulative POD energy curves.

The function produces two figures:

Per-mode energy fraction (log scale)
Cumulative energy with reference threshold lines

This is typically used as a quick diagnostic for selecting a POD rank.

Parameters:

Name	Type	Description	Default
`Y`	`ArrayLike`	Snapshot matrix of shape `(n_snapshots, n_obs)`.	required
`r_max`	`int`	Maximum number of modes to display. Must be positive.	`50`
`center`	`bool`	Whether to mean-center the snapshots before SVD. See `pod_energy_from_snapshots`.	`True`
`thresholds`	`tuple[float, ...]`	Cumulative energy thresholds to mark on the cumulative plot. Each value must be in `(0, 1]`. For each threshold `th`, the plot shows the smallest rank `r` such that cumulative energy is at least `th`.	`(0.9, 0.95, 0.99)`
`show`	`bool`	If True, call `plt.show()` before returning. For MkDocs/Jupyter usage, leaving this False is recommended.	`False`

Returns:

Type	Description
`((fig_energy, ax_energy), (fig_cum, ax_cum))`	Two `(fig, ax)` pairs: per-mode energy and cumulative energy.

Raises:

Type	Description
`ValueError`	If `r_max <= 0`, if `Y` is not 2D, or if any threshold is not in `(0, 1]`.

Notes

The per-mode plot is shown on a log scale because POD spectra often decay quickly.

pod_energy_from_snapshots

pod_energy_from_snapshots(Y, *, center=True)

Compute POD energy fractions from a snapshot matrix.

This helper computes the singular values of the snapshot matrix and returns:

the per-mode energy fraction, and
the cumulative energy fraction,

which are often used to choose a POD rank.

Parameters:

Name	Type	Description	Default
`Y`	`ArrayLike`	Snapshot matrix with shape `(n_snapshots, n_obs)` where each row is one snapshot/trajectory in observation space.	required
`center`	`bool`	If True, subtract the column-wise mean before computing the SVD. Centering is usually recommended for POD/PCA-style decompositions.	`True`

Returns:

Type	Description
`energy_fraction`	1D array where `energy_fraction[i]` is the fraction of total energy explained by mode `i` (0-indexed). Sums to 1 (up to numerical error).
`cumulative_energy`	1D array of cumulative sums of `energy_fraction`.

Raises:

Type	Description
`ValueError`	If `Y` is not two-dimensional.

Notes

The energy is computed from squared singular values:

lambda_i = s_i^2
energy_fraction_i = lambda_i / sum(lambda_j)

plot_error_vs_uncertainty

plot_error_vs_uncertainty(mean_std, rmse_vals, *, title=None, show=False)

Plot RMSE against predicted uncertainty.

This diagnostic is a quick calibration check: if the model's predictive uncertainty is informative, larger predicted standard deviations should typically correspond to larger realised errors.

Parameters:

Name	Type	Description	Default
`mean_std`	`ArrayLike`	1D array of "typical" predictive standard deviations per test point, e.g. the mean of the pointwise predictive std across the observation grid.	required
`rmse_vals`	`ArrayLike`	1D array of realised errors (RMSE) per test point.	required
`title`	`str \| None`	Optional plot title.	`None`
`show`	`bool`	If True, call `plt.show()` before returning.	`False`

Returns:

Type	Description
`(fig, ax)`	Matplotlib figure and axes.

Raises:

Type	Description
`ValueError`	If `mean_std` and `rmse_vals` do not have the same shape.

plot_prediction_at_theta

plot_prediction_at_theta(model, theta, t, y_obs, *, y_true=None, title=None, z=2.0, show=False)

Plot a predictive mean with an uncertainty band at a fixed parameter value.

This function is primarily intended for documentation and quick diagnostics: it visualises (i) observed data, (ii) the model's predictive mean, and (iii) a pointwise uncertainty band based on the model's predictive variance.

Parameters:

Name	Type	Description	Default
`model`	`PredictMeanVar`	Any object implementing `predict` with mean and variance output. The model must provide `predict(theta) -> (mean, variance)` in observation space.	required
`theta`	`ArrayLike`	Parameter vector at which the prediction is evaluated.	required
`t`	`ArrayLike`	1D grid for the observation/prediction (e.g. time). Must have the same length as the predicted mean and observation vectors.	required
`y_obs`	`ArrayLike`	Observed data vector aligned with `t`. This is typically the noisy observation.	required
`y_true`	`ArrayLike \| None`	Optional "true" profile aligned with `t` (e.g. the noiseless HF output) for reference.	`None`
`title`	`str \| None`	Optional plot title.	`None`
`z`	`float`	Width of the uncertainty band in standard deviations. The band is drawn as `mean ± z * std`, where `std = sqrt(variance)`.	`2.0`
`show`	`bool`	If True, call `plt.show()` before returning. In library usage and documentation builds, leaving this False is recommended (MkDocs/Jupyter will render the figure).	`False`

Returns:

Type	Description
`(fig, ax)`	Matplotlib figure and axes. The caller may further customise or save them.

Raises:

Type	Description
`ValueError`	If `t`, `y_obs`, `mean`, and `variance` do not have the same 1D shape, or if `variance` contains negative entries.

See Also

plot_error_vs_uncertainty Scatter plot assessing whether predicted uncertainty correlates with error.