spectralbrain.viz.bayes#

Bayesian posterior visualisation for spectral morphometry.

Directly linked to spectralbrain.statistics.bayesian — every model class has a matching figure function. Also includes general Bayesian visualisation tools (ridgeline plots, ROPE decision diagrams, forest plots, prior–posterior overlays).

Figure types#

  1. Posterior distribution with HDI + ROPE (general)

  2. Forest plot (coefficients + credible intervals)

  3. Prior vs posterior overlay

  4. ROPE decision diagram (stacked bar)

  5. Ridgeline plot (multi-group, multi-panel)

  6. Horseshoe shrinkage path (HorseshoeRegression)

  7. BEST effect size posterior (BayesianGroupComparison)

  8. Site effects caterpillar (HierarchicalLinearModel)

  9. GP normative trajectory (GaussianProcessNormative)

  10. Connectome difference matrix (BayesianConnectome)

Functions

plot_best_posterior(trace, *[, rope, title, ...])

Three-panel BEST visualisation: Δμ, Δσ, effect size.

plot_connectome_posterior(edge_diff_matrix, *)

Posterior mean edge-difference matrix.

plot_forest(var_names, posteriors, *[, ...])

Forest plot — coefficients + credible intervals.

plot_gp_trajectory(ages_train, y_train, ...)

Gaussian Process age trajectory with uncertainty fans.

plot_horseshoe_coefficients(trace, *[, ...])

Horseshoe coefficient plot: forest + shrinkage heatmap.

plot_posterior(samples, *[, hdi_prob, rope, ...])

Posterior distribution with HDI band and optional ROPE.

plot_prior_posterior(prior_samples, ...[, ...])

Overlay prior and posterior distributions.

plot_ridgeline(data, *[, overlap, colors, ...])

Multi-panel ridgeline plot.

plot_rope_decision(posteriors[, rope, ...])

Stacked horizontal bar — P(below) | P(ROPE) | P(above).

plot_site_effects(trace, *[, site_names, ...])

Caterpillar plot of random intercepts per site.
spectralbrain.viz.bayes.plot_best_posterior(trace, *, rope=(-0.1, 0.1), title='BEST — Bayesian Group Comparison', save=None)[source]#

Three-panel BEST visualisation: Δμ, Δσ, effect size.

Parameters:

  • trace (arviz.InferenceData) – From BayesianGroupComparison.trace_.

  • rope ((lo, hi))

  • title (str)

  • save (str | PathLike | None)

Return type:

tuple[Figure, list[Axes]]

spectralbrain.viz.bayes.plot_connectome_posterior(edge_diff_matrix, *, labels=None, network_boundaries=None, cmap='RdBu_r', vmax=None, title='Bayesian Connectome — Edge Differences', ax=None, save=None)[source]#

Posterior mean edge-difference matrix.

Parameters:

  • edge_diff_matrix (ndarray, shape (R, R)) – From BayesianConnectome.edge_difference_matrix().

  • labels (list[str] | None)

  • network_boundaries (list[int] | None)

  • cmap (str)

  • vmax (float | None)

  • title (str)

  • ax (Axes | None)

  • save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.bayes.plot_forest(var_names, posteriors, *, hdi_prob=0.94, ref_val=0.0, colors=None, title='Forest Plot', xlabel='Coefficient', ax=None, save=None)[source]#

Forest plot — coefficients + credible intervals.

Parameters:

  • var_names (list of str) – Names of the variables / parameters.

  • posteriors (list of ndarray) – One posterior sample array per parameter.

  • hdi_prob (float)

  • ref_val (float) – Reference line (typically 0).

  • colors (list[str] | None)

  • title (str)

  • xlabel (str)

  • ax (Axes | None)

  • save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.bayes.plot_gp_trajectory(ages_train, y_train, ages_pred, y_pred_mean, y_pred_std, *, patient_ages=None, patient_values=None, patient_labels=None, ci_levels=(0.5, 0.9, 0.99), title='GP Normative Trajectory', xlabel='Age (years)', ylabel='Descriptor', ax=None, save=None)[source]#

Gaussian Process age trajectory with uncertainty fans.

Concentric bands show expanding uncertainty. Individual patients plotted as coloured dots with deviation annotation.

Parameters:

  • ages_train (ndarray, shape (n,))

  • y_train (ndarray, shape (n,))

  • ages_pred (ndarray, shape (m,))

  • y_pred_mean (ndarray, shape (m,))

  • y_pred_std (ndarray, shape (m,))

  • patient_ages (ndarray, optional)

  • patient_values (ndarray, optional)

  • patient_labels (list of str, optional)

  • ci_levels (tuple of float) – Confidence bands (inner to outer).

  • title (str)

  • xlabel (str)

  • ylabel (str)

  • ax (Axes | None)

  • save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.bayes.plot_horseshoe_coefficients(trace, *, var_names=None, hdi_prob=0.94, title='Horseshoe Regression — Feature Selection', save=None)[source]#

Horseshoe coefficient plot: forest + shrinkage heatmap.

Left panel: forest plot of β posteriors. Right panel: local shrinkage (κ = 1/(1+λ²)) — darker = more shrunk.

Parameters:

  • trace (arviz.InferenceData) – From HorseshoeRegression.trace_.

  • var_names (list of str, optional) – Names for each feature / coefficient.

  • hdi_prob (float)

  • title (str)

  • save (str | PathLike | None)

Return type:

tuple[Figure, tuple[Axes, Axes]]

spectralbrain.viz.bayes.plot_posterior(samples, *, hdi_prob=0.94, rope=None, ref_val=None, color='#4477AA', xlabel='Parameter', title='', ax=None, save=None)[source]#

Posterior distribution with HDI band and optional ROPE.

Parameters:

  • samples (ndarray, shape (n,))

  • hdi_prob (float) – Highest Density Interval probability mass.

  • rope ((lo, hi), optional) – Region Of Practical Equivalence — shaded in grey.

  • ref_val (float, optional) – Reference value (vertical dashed line, e.g. 0).

  • color (str)

  • xlabel (str)

  • title (str)

  • ax (Axes | None)

  • save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.bayes.plot_prior_posterior(prior_samples, posterior_samples, *, xlabel='Parameter', title='Prior → Posterior', ax=None, save=None)[source]#

Overlay prior and posterior distributions.

Parameters:
Return type:

tuple[Figure, Axes]

spectralbrain.viz.bayes.plot_ridgeline(data, *, overlap=0.6, colors=None, xlabel='Value', title='', figsize=None, save=None, formats=None)[source]#

Multi-panel ridgeline plot.

Each panel corresponds to one feature. Within each panel, overlapping KDE distributions are stacked vertically by group.

Parameters:

  • data (dict of {feature_name: {group_name: samples}}) – Outer dict = panels (features). Inner dict = ridges within each panel (groups).

  • overlap (float) – Vertical overlap between ridges (0 = no overlap, 1 = full).

  • colors (list of str, optional) – Colours per group.

  • xlabel (str)

  • title (str)

  • figsize ((w, h), optional)

  • save (str | PathLike | None)

  • formats (str | list[str] | None)

Returns:

fig, axes

Return type:

tuple[Figure, list[Axes]]

Examples

>>> plot_ridgeline({
...     "HKS": {"Control": ctrl_hks, "MTLE-L": mtle_l_hks, "MTLE-R": mtle_r_hks},
...     "WKS": {"Control": ctrl_wks, "MTLE-L": mtle_l_wks, "MTLE-R": mtle_r_wks},
... }, overlap=0.7, save="ridgeline.png")
spectralbrain.viz.bayes.plot_rope_decision(posteriors, rope=(-0.1, 0.1), *, title='ROPE Decision', xlabel='Probability', ax=None, save=None)[source]#

Stacked horizontal bar — P(below) | P(ROPE) | P(above).

Parameters:

  • posteriors (dict of {label: samples})

  • rope ((lo, hi))

  • title (str)

  • xlabel (str)

  • ax (Axes | None)

  • save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.bayes.plot_site_effects(trace, *, site_names=None, title='Hierarchical Model — Site Random Effects', save=None)[source]#

Caterpillar plot of random intercepts per site.

Parameters:

  • trace (arviz.InferenceData) – From HierarchicalLinearModel.trace_.

  • site_names (list of str, optional)

  • title (str)

  • save (str | PathLike | None)

Return type:

tuple[Figure, Axes]