Utils

utils

Utility functions (pure numerical helpers, no plotting, no I/O).

Functions

acceptance_rate_from_accepted

acceptance_rate_from_accepted(accepted)

Compute acceptance rate from explicit acceptance flags.

Parameters:

Name	Type	Description	Default
accepted	ArrayLike	Boolean array-like of shape (n_steps,) indicating whether each proposal was accepted.	required

Returns:

Type	Description
acceptance_rate	Mean of the acceptance indicators.

Raises:

Type	Description
ValueError	If accepted is not one-dimensional.

extract_samples

extract_samples(chain, *, chain_key)

Extract parameter samples from a tinyDA chain object.

This is a small compatibility helper that converts the object returned by tinyDA.sample(...) into a plain NumPy array.

Expected tinyDA structure

This function assumes that chain[chain_key] is an iterable of links, where each link exposes a .parameters attribute (a 1D parameter vector).

Parameters:

Name	Type	Description	Default
chain	dict[str, Any]	Object returned by tinyDA.sample. In practice this behaves like a dictionary that maps chain keys (e.g. "chain_0" or "chain_coarse_0") to sequences of chain links.	required
chain_key	str	Key identifying which chain to extract.	required

Returns:

Type	Description
samples	Sample matrix of shape (n_steps, n_dim) where: n_steps is the number of MCMC iterations stored in the chain, n_dim is the parameter dimension.

Raises:

Type	Description
KeyError	If chain_key is not present in the chain object.
TypeError	If the links do not expose a .parameters attribute or cannot be iterated.

Notes

This function performs no thinning or burn-in removal. Those should be done at the MCMCChain level (see MCMCChain.burn_in).

hf_call_fraction

hf_call_fraction(used_hf)

Compute the fraction of steps that used the high-fidelity (HF) model.

Parameters:

Name	Type	Description	Default
used_hf	ArrayLike	Boolean array-like of shape (n_steps,) where True indicates an HF evaluation occurred at that step.	required

Returns:

Type	Description
hf_fraction	Mean of the HF-usage indicators.

Raises:

Type	Description
ValueError	If used_hf is not one-dimensional.

mean_subchain_length

mean_subchain_length(subchain_length)

Compute the mean subchain length (subsampling rate) over a history.

Parameters:

Name	Type	Description	Default
subchain_length	ArrayLike	Array-like subchain length history.	required

Returns:

Type	Description
mean_length	Mean of the provided subchain lengths.

Raises:

Type	Description
ValueError	If subchain_length is not one-dimensional.

move_fraction_from_samples

move_fraction_from_samples(samples)

Compute the fraction of steps where the state changes.

This is a fallback diagnostic used when explicit acceptance flags are not available from the sampler. It measures how often consecutive states differ.

Parameters:

Name	Type	Description	Default
samples	ArrayLike	Sample matrix of shape (n_steps, n_dim).	required

Returns:

Type	Description
move_fraction	Fraction of steps (between 0 and 1) for which the parameter vector changes compared to the previous step. Returns 0.0 if fewer than two samples are given.

Raises:

Type	Description
ValueError	If samples is not a 2D array.

Notes

• This is not guaranteed to equal the true Metropolis acceptance rate. For instance, deterministic updates, rounding, or other sampler internals may cause differences.
• The first sample has no "previous step" and is not counted.

posterior_rmse

posterior_rmse(samples, theta_true, *, burn_in=0)

Compute a simple posterior error metric against a reference parameter.

The reported value is the mean Euclidean distance between each sample and a provided reference parameter vector theta_true, after discarding burn-in.

Parameters:

Name	Type	Description	Default
samples	ArrayLike	Sample matrix of shape (n_steps, n_dim).	required
theta_true	ArrayLike	Reference parameter vector of shape (n_dim,).	required
burn_in	int	Number of initial samples to discard before computing the statistic.	0

Returns:

Type	Description
rmse	Mean Euclidean distance from samples to theta_true (after burn-in).

Raises:

Type	Description
ValueError	If shapes are inconsistent or burn_in is outside [0, n_steps].

Notes

Despite the name, this is not an RMSE in observation space; it is a parameter-space distance statistic that is sometimes convenient in toy problems with known truth.

coverage

coverage(y_true, y_hat, y_std, *, z)

Compute empirical coverage of predictive intervals.

This function measures the fraction of entries of y_true that fall inside the symmetric predictive interval

.. math::

[\hat y - z\,\sigma,\; \hat y + z\,\sigma],

where z is a chosen normal quantile (e.g. z≈1.96 for an approximate 95% interval under a Gaussian assumption).

Parameters:

Name	Type	Description	Default
y_true	ArrayLike	Reference (ground-truth) values.	required
y_hat	ArrayLike	Predictive mean values.	required
y_std	ArrayLike	Predictive standard deviations (must be non-negative).	required
z	float	Interval half-width multiplier. Must be non-negative.	required

Returns:

Type	Description
coverage	Fraction of entries that satisfy y_true ∈ [y_hat - z*y_std, y_hat + z*y_std].

Raises:

Type	Description
ValueError	If shapes are inconsistent, if y_std contains negative values, or if z < 0.

Notes

• This is an empirical coverage computed over all entries (and therefore over time points for trajectory outputs).
• Coverage is meaningful only if y_std corresponds to uncertainty on the same quantity as y_hat (same units and alignment).

rmse

rmse(y_hat, y_true)

Compute the root-mean-square error (RMSE).

Parameters:

Name	Type	Description	Default
y_hat	ArrayLike	Predicted values.	required
y_true	ArrayLike	Reference (ground-truth) values. Must have the same shape as y_hat.	required

Returns:

Type	Description
rmse	Root-mean-square error: .. math:: \mathrm{RMSE}(\hat y, y) = \sqrt{\frac{1}{n}\sum_{i=1}^{n}(\hat y_i - y_i)^2}.

Raises:

Type	Description
ValueError	If y_hat and y_true have different shapes.

Notes

This metric is computed elementwise and then averaged over all entries. For trajectory outputs, this corresponds to an average over time points.