superstats.diagnostics.plots.posterior_samples#

Posterior sample visualization helpers.

Functions

plot_time_invariant_posterior(estimates[, ...])

Plot time-invariant parameter posteriors.

plot_time_varying_posterior(estimates[, ...])

Plot time-varying parameter posteriors.
superstats.diagnostics.plots.posterior_samples.plot_time_invariant_posterior(estimates, targets=None, variable_keys=None, variable_names=None, aggregation=None, mixture_names=None, num_cols=2, color='#356673', title_fontsize=22, label_fontsize=18, tick_fontsize=16, figsize=None)[source]#

Plot time-invariant parameter posteriors.

Parameters:
estimatesMapping[str, np.ndarray] or np.ndarray

Posterior samples. If a dict, values of shape (num_datasets, num_post_samples, num_steps, num_components), keyed by variable. If an array, shape (num_datasets, num_post_samples, num_steps, num_params) directly - treated as single-component parameters; mixture grouping is not inferable from array input.

targetsMapping[str, np.ndarray], np.ndarray, or None, optional, default: None

Ground-truth values, matching the input type of estimates. If a dict, values of shape (num_datasets, num_components). If an array, shape (num_datasets, num_params) directly. If given, drawn as black dashed vertical lines. When aggregation is None, one solid line per panel marks that panel’s specific dataset’s true value. When aggregation is given, the per-dataset true values are collapsed with aggregation and a single solid line is drawn per panel.

variable_keyssequence of str or None, optional, default: None

Which variables to select and plot, and in what order, when estimates is a dict. By default, all keys, in dict insertion order. Ignored for array input.

variable_namessequence of str or None, optional, default: None

Display names (used for panel labels/titles), in the same order as variable_keys (or the array’s last axis). Defaults to variable_keys for dict input, or param_0, param_1, … for array input.

aggregationcallable() or None, optional, default: None

Controls both the posterior layout and the target summary. If None: one panel per (dataset, parameter) pair; rows=params, cols=datasets, param name as row label, dataset index as column title; targets (if given) are shown per dataset. If a callable (e.g. np.mean, np.median): posterior samples are pooled across datasets into one panel per parameter, arranged in a num_cols-column grid; targets (if given) are collapsed across datasets with aggregation into a single reference value per panel.

mixture_namesdict or None, optional, default: None

Mapping from base parameter name (e.g. “a”, without any “_mixture_weights” suffix) to a list of component names. Defaults to “component 0”, “component 1”, … when not supplied. Only applies to dict input with multi-component values.

num_colsint, optional, default: 2

Number of subplot columns when aggregation is not None.

colorstr, optional, default: BASE_COLOR

Base color for non-mixture parameters.

title_fontsizeint, optional, default: 22

The font size of the panel titles.

label_fontsizeint, optional, default: 18

The font size of the row labels (param names, non-pooled layout only).

tick_fontsizeint, optional, default: 16

The font size of the axis tick labels.

figsizetuple of two floats or None, optional, default: None

Explicit figure size in inches. If None, the default layout size is used.

Returns:
figplt.Figure - the figure instance for optional saving
Raises:
ValueError

If no variables are found to plot (empty variable_keys, whether resolved by default or passed explicitly), or if variable_names doesn’t match the number of variables for array input.

Parameters:
Return type:

Figure

superstats.diagnostics.plots.posterior_samples.plot_time_varying_posterior(estimates, targets=None, variable_keys=None, variable_names=None, aggregation=None, aggregate_strategy='full_uncertainty', uncertainty_fun='95ci', smoothing=None, smoothing_window=5, marginal=True, num_cols=2, alpha=0.5, color='#356673', title_fontsize=22, label_fontsize=18, tick_fontsize=16, figsize=None)[source]#

Plot time-varying parameter posteriors.

Parameters:
estimatesMapping[str, np.ndarray] or np.ndarray

Posterior samples. If a dict, values of shape (num_datasets, num_post_samples, num_steps, 1), keyed by variable. If an array, shape (num_datasets, num_post_samples, num_steps, num_params) directly.

targetsMapping[str, np.ndarray], np.ndarray, or None, optional, default: None

Ground-truth trajectories, matching the input type of estimates. If a dict, values of shape (num_datasets, num_steps, 1). If an array, shape (num_datasets, num_steps, num_params) directly. If given, drawn as a black dashed line on top of each panel: the raw per-dataset trajectory when aggregation is None, or aggregated across datasets (using aggregation) when aggregation is not None. Smoothed with the same smoothing settings as the posterior trajectories, for a fair visual comparison.

variable_keyssequence of str or None, optional, default: None

Which variables to select and plot, and in what order, when estimates/targets are dicts. By default, all keys, in dict insertion order. Ignored for array input.

variable_namessequence of str or None, optional, default: None

Display names (used for panel labels/titles), in the same order as variable_keys (or the array’s last axis). Defaults to variable_keys for dict input, or param_0, param_1, … for array input.

aggregationcallable() or None, optional, default: None

None: one panel per (param, dataset). callable: one panel per param, aggregated across datasets. Called as aggregation(trajectories, axis=0) and must return a (T,) center. The same function aggregates targets across datasets when both targets and aggregation are given.

aggregate_strategy{“full_uncertainty”, “no_epistemic”}, optional, default: “full_uncertainty”

Only used when aggregation is not None. “full_uncertainty”: flatten datasets and posterior samples, then summarize. “no_epistemic”: median across posterior samples per dataset first, then aggregate.

uncertainty_fun{“std”, “95ci”, “mad”, “95hdi”} or callable() or None, optional, default: “95ci”

Band drawn around the center line. A callable receives (N, T) trajectories and must return (lo, hi), each of shape (T,).

smoothing{“sma”, “ema”} or None, optional, default: None

Applied to each trajectory (and to targets, if given) before computing the center, uncertainty, and marginal.

smoothing_windowint, optional, default: 5

Window size for sma, or span parameter for ema.

marginalbool, optional, default: True

Attach a marginal KDE panel to the right of each trajectory axis. The KDE is computed on the same array used for the uncertainty band.

num_colsint, optional, default: 2

Number of subplot columns when aggregation is not None.

colorstr, optional, default: BASE_COLOR

Line and band color.

alphafloat in [0, 1], optional, default: 0.5

Alpha for the uncertainty band.

title_fontsizeint, optional, default: 22

The font size of the panel titles.

label_fontsizeint, optional, default: 18

The font size of the axis label texts.

tick_fontsizeint, optional, default: 16

The font size of the axis tick labels.

figsizetuple of two floats or None, optional, default: None

Explicit figure size in inches. If None, the default layout size is used.

Returns:
figplt.Figure - the figure instance for optional saving
Raises:
ValueError

If estimates/targets are inconsistent (mismatched dict keys, or a variable_names length mismatch for array input), or if aggregate_strategy, or uncertainty_fun when given as a string, is not one of the recognized values.

Parameters:
Return type:

Figure