superstats.diagnostics.plots.prior_samples#

Prior sample visualization helpers.

Functions

plot_joint_prior(local_params, hyper_params, ...)

Plot joint prior diagnostics combining hyperparameter distributions, shared parameter histograms, and time-varying trajectories.

plot_time_invariant_prior(hyper_params, ...)

Plot time-invariant parameter distributions.

plot_time_varying_prior(local_params[, ...])

Plot time-varying parameter trajectories with marginal KDE.
superstats.diagnostics.plots.prior_samples.plot_joint_prior(local_params, hyper_params, shared_params, param_bounds=None, mixture_names=None, hyper_param_groups=None, marginal=True, color='#356673', title_fontsize=22, tick_fontsize=16, alpha=0.5, figsize=None)[source]#

Plot joint prior diagnostics combining hyperparameter distributions, shared parameter histograms, and time-varying trajectories.

Parameters:
local_paramsdict of np.ndarray, each of shape (num_trajectories, num_steps)

Mapping from parameter name to an array of trajectories. Every StochasticTransition parameter is unconditionally added here by JointPrior.sample, so together with shared_params this is the authoritative set of row names.

hyper_paramsdict of np.ndarray

Mapping from hyperparameter name to an array of samples. Keys are f”{param_name}_{hyper_key}”.

shared_paramsdict of np.ndarray

Mapping from parameter name to an array of shared parameter samples.

param_boundsdict or None, optional, default: None

Mapping from parameter name to (lower, upper) y-axis limits.

mixture_namesdict or None, optional, default: None

Mapping from parameter name to a list of component names for mixture weight parameters.

hyper_param_groupsdict or None, optional, default: None

Mapping from each parameter name to the exact list of hyper_params keys it owns. Required to correctly separate rows when one parameter name is a prefix of another at an underscore boundary (e.g. “v_1” and “v_1_2”), since str.startswith cannot disambiguate that case from key strings alone. When provided (e.g. by JointPrior.plot_joint_prior), this is used instead of prefix matching. If omitted, falls back to prefix matching, which can misassign hyperparameters in the presence of such name collisions.

marginalbool, optional, default: True

Whether to draw a marginal KDE panel beside each trajectory panel.

colorstr, optional, default: BASE_COLOR

Base plotting color for KDEs and trajectories.

title_fontsizeint, optional, default: 22

The font size of the panel titles (parameter names).

tick_fontsizeint, optional, default: 16

The font size of the axis tick labels.

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

The opacity of individual trajectories.

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 plottable parameters are found across local_params, hyper_params, and shared_params.

Parameters:
Return type:

Figure

superstats.diagnostics.plots.prior_samples.plot_time_invariant_prior(hyper_params, shared_params, mixture_names=None, color='#356673', num_cols=2, title_fontsize=22, label_fontsize=18, tick_fontsize=16, figsize=None)[source]#

Plot time-invariant parameter distributions.

Parameters:
hyper_paramsdict of np.ndarray

Mapping from parameter name to an array of hyperparameter samples.

shared_paramsdict of np.ndarray

Mapping from parameter name to an array of shared parameter samples.

mixture_namesdict or None, optional, default: None

Mapping from parameter name to a list of component names for mixture weight parameters.

colorstr, optional, default: BASE_COLOR

Base color for non-mixture histograms.

num_colsint, optional, default: 2

Number of subplot columns.

title_fontsizeint, optional, default: 22

The font size of the panel titles.

label_fontsizeint, optional, default: 18

The font size of the axis labels.

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 both hyper_params and shared_params are empty.

Parameters:
Return type:

Figure

superstats.diagnostics.plots.prior_samples.plot_time_varying_prior(local_params, param_bounds=None, num_cols=2, marginal=True, alpha=0.5, color='#356673', title_fontsize=22, label_fontsize=18, tick_fontsize=16, figsize=None)[source]#

Plot time-varying parameter trajectories with marginal KDE.

Parameters:
local_paramsdict of np.ndarray, each of shape (num_trajectories, num_steps)

Mapping from parameter name to an array of trajectories.

param_boundsdict or None, optional, default: None

Mapping from parameter name to (lower, upper) y-axis limits.

num_colsint, optional, default: 2

Number of subplot columns.

marginalbool, optional, default: True

Whether to draw a marginal KDE panel beside each trajectory panel.

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

The opacity of individual trajectories.

colorstr, optional, default: BASE_COLOR

Line color for individual trajectories and marginal KDE.

title_fontsizeint, optional, default: 22

The font size of the panel titles.

label_fontsizeint, optional, default: 18

The font size of the axis labels.

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 local_params is empty.

Parameters:
Return type:

Figure