calibrain.UncertaintyEstimator

class calibrain.UncertaintyEstimator(nominal_coverages=None, logger=None)

Uncertainty estimator for fixed- and free-orientation source estimates.

Supported settings

1. Fixed orientation (EEG or MEG): - pointwise marginal credible interval membership - aggregated-mean marginal credible interval membership

2. Free orientation EEG: - pointwise 3D credible ellipsoid membership - aggregated-mean 3D credible ellipsoid membership

3. Free orientation MEG (reduced rank-2 model): - pointwise 2D credible ellipse membership in reduced coordinates - aggregated-mean 2D credible ellipse membership in reduced coordinates

Modeling convention

• posterior mean varies over time

• posterior covariance is static over time

• when aggregating by time-average, covariance is scaled by 1 / T

Important MEG convention

For MEG, the inverse model is assumed to be built on a reduced 2-orientation leadfield obtained source-wise via SVD or, preferably, taken directly from the extractor as Q_basis. Therefore:

• truth can be represented in reduced coordinates a_true with shape (N,2,T)

• if needed, truth can be lifted to local 3D via Q_basis -> shape (N,3,T)

• posterior mean is in reduced 2D coordinates, shape (N,2,T)

• posterior covariance is in reduced coordinates, shape (2N,2N)

Recommended usage

Use the extractor-provided basis:

V_tan = lf_free_meg[“Q_basis”]

instead of recomputing a new basis inside the uncertainty step.

Methods

aggregated_componentwise_interval_membership_free(...)	Temporally aggregated marginal (component-wise) CI membership.
aggregated_ellipse_membership_meg_free(...)	Aggregated 2D MEG credible ellipse membership in reduced coordinates.
aggregated_ellipsoid_membership_eeg_free(...)
aggregated_interval_membership(x_true, ...)
calibration_curve_componentwise_eeg_free_aggregated(...)	Aggregated marginal calibration curve for free-orientation EEG (K=3).
calibration_curve_componentwise_eeg_free_pointwise(...)	Pointwise marginal calibration curve for free-orientation EEG (K=3).
calibration_curve_componentwise_intervals_aggregated_free(...)	Calibration curve for marginal (component-wise) intervals (aggregated).
calibration_curve_componentwise_intervals_pointwise_free(...)	Calibration curve for marginal (component-wise) intervals (pointwise).
calibration_curve_componentwise_meg_free_aggregated(...)	Aggregated marginal calibration curve for reduced free-orientation MEG (K=2).
calibration_curve_componentwise_meg_free_pointwise(...)	Pointwise marginal calibration curve for reduced free-orientation MEG (K=2).
calibration_curve_ellipse_meg_free_aggregated(...)
calibration_curve_ellipse_meg_free_pointwise(...)
calibration_curve_ellipsoid_eeg_free_aggregated(...)
calibration_curve_ellipsoid_eeg_free_pointwise(...)
calibration_curve_intervals_aggregated(...)
calibration_curve_intervals_pointwise(...)
componentwise_variance_from_uncert(...[, ...])	Extract per-source per-component marginal variances as an (N,K) array.
credible_intervals_normal(mean, variance, ...)
lift_meg_2d_to_3d(x_2d, V_tan)	Lift reduced 2D MEG coordinates back to the retained local 3D basis.
plot_eeg_ellipsoid_membership_aggregated(...)
plot_eeg_ellipsoid_membership_pointwise(...)
plot_fixed_interval_membership_aggregated(...)
plot_fixed_interval_membership_pointwise(...)
plot_meg_ellipse_membership_aggregated(...)
plot_meg_ellipse_membership_pointwise(...[, ...])
pointwise_componentwise_interval_membership_free(...)	Pointwise marginal (component-wise) CI membership for free orientation.
pointwise_ellipse_membership_meg_free(...[, ...])	Direct 2D MEG credible ellipse membership in reduced coordinates.
pointwise_ellipsoid_membership_eeg_free(...)
pointwise_interval_membership(x_true, x_hat, ...)
posterior_variance_from_cov(posterior_cov, *)
precompute_meg_tangent_bases_svd(L_free_Mx3N)	Backward-compatible wrapper.
project_meg_3d_to_2d(x_3d, V_tan)	Project 3D MEG truth/estimate onto the local reduced 2D coordinates.
reduce_meg_leadfield_svd(L_free_Mx3N)	Fallback-only helper: build a source-wise SVD-reduced MEG leadfield.

__init__(nominal_coverages=None, logger=None)

static posterior_variance_from_cov(posterior_cov, *, min_var=0.0)

Return type:

ndarray

credible_intervals_normal(mean, variance, nominal_coverage)

Return type:

Tuple[ndarray, ndarray]

pointwise_interval_membership(x_true, x_hat, posterior_var, nominal_coverage)

Return type:

Dict[str, Any]

aggregated_interval_membership(x_true, x_hat, posterior_var, nominal_coverage)

Return type:

Dict[str, Any]

calibration_curve_intervals_pointwise(x_true, x_hat, posterior_var)

Return type:

Dict[str, Any]

calibration_curve_intervals_aggregated(x_true, x_hat, posterior_var)

Return type:

Dict[str, Any]

pointwise_ellipsoid_membership_eeg_free(x_true, x_hat, posterior_cov, nominal_coverage, *, psd_repair_blocks=False, block_epsilon=1e-12)

Return type:

Dict[str, Any]

aggregated_ellipsoid_membership_eeg_free(x_true, x_hat, posterior_cov, nominal_coverage, *, psd_repair_blocks=False, block_epsilon=1e-12)

Return type:

Dict[str, Any]

calibration_curve_ellipsoid_eeg_free_pointwise(x_true, x_hat, posterior_cov, *, psd_repair_blocks=False, block_epsilon=1e-12)

Return type:

Dict[str, Any]

calibration_curve_ellipsoid_eeg_free_aggregated(x_true, x_hat, posterior_cov, *, psd_repair_blocks=False, block_epsilon=1e-12)

Return type:

Dict[str, Any]

static componentwise_variance_from_uncert(posterior_uncert, *, n_sources, n_orient, min_var=1e-12)

Extract per-source per-component marginal variances as an (N,K) array.

Supports: - full covariance: (K*N, K*N), uses diag(…) and reshapes to (N,K) - block covariance: (N, K, K), uses diagonal blocks directly

This utility underpins the interval_type=”marginal” diagnostic for free orientation, where directions/components are not evaluated separately but pooled (see calibration_curve_componentwise_intervals_*).

Return type:

ndarray

pointwise_componentwise_interval_membership_free(x_true, x_hat, posterior_uncert, nominal_coverage, *, n_orient, min_var=1e-12)

Pointwise marginal (component-wise) CI membership for free orientation.

This implements the “direction-aggregated marginal” diagnostic from _temp/Component_CI_R1.py: :rtype: Dict[str, Any]

• Build scalar normal credible intervals per retained component using only marginal variances (diagonal of the covariance).

• Pool interval membership over sources, components, and time.

Important

Directions/components are not evaluated separately. They are pooled because local coordinate systems are arbitrary (EEG xyz axes depend on coordinate choice; MEG reduced components are voxel-dependent).

aggregated_componentwise_interval_membership_free(x_true, x_hat, posterior_uncert, nominal_coverage, *, n_orient, min_var=1e-12)

Temporally aggregated marginal (component-wise) CI membership.

This corresponds to building the diagnostic on time-averaged signals: :rtype: Dict[str, Any]

• Aggregate x_true/x_hat over time (mean over T).

• Scale marginal variances by 1/T (variance of the mean).

• Build scalar CIs per component and pool membership over sources and components.

calibration_curve_componentwise_intervals_pointwise_free(x_true, x_hat, posterior_uncert, *, n_orient, min_var=1e-12)

Calibration curve for marginal (component-wise) intervals (pointwise).

Return type:

Dict[str, Any]

Summary

Builds scalar normal credible intervals per component (using only marginal variances) and pools membership over sources, components, and time. This is the interval_type=”marginal” diagnostic for free orientation.

Shapes

• EEG free: n_orient=3, x_true/x_hat are (N,3,T)

• Reduced MEG free: n_orient=2, x_true/x_hat are (N,2,T)

• posterior_uncert: either full (K*N,K*N) or per-source blocks (N,K,K)

Important

Components are not evaluated separately (pooled), because local coordinate labels are arbitrary.

calibration_curve_componentwise_intervals_aggregated_free(x_true, x_hat, posterior_uncert, *, n_orient, min_var=1e-12)

Calibration curve for marginal (component-wise) intervals (aggregated).

Return type:

Dict[str, Any]

Summary

Temporally aggregated version of the interval_type=”marginal” free diagnostic:

1. average x_true/x_hat over time,

2. scale marginal variances by 1/T,

3. build scalar CIs per component,

4. pool membership over sources and components.

This is the mode used by workflows/calibration.py.

Important

Components are pooled (no direction-wise curves), because local coordinate systems are arbitrary.

calibration_curve_componentwise_eeg_free_pointwise(x_true, x_hat, posterior_uncert, *, min_var=1e-12)

Pointwise marginal calibration curve for free-orientation EEG (K=3).

Expected shapes: - x_true, x_hat: (N,3,T) - posterior_uncert: (3N,3N) or per-source blocks (N,3,3)

Return type:

Dict[str, Any]

calibration_curve_componentwise_eeg_free_aggregated(x_true, x_hat, posterior_uncert, *, min_var=1e-12)

Aggregated marginal calibration curve for free-orientation EEG (K=3).

Expected shapes: - x_true, x_hat: (N,3,T) - posterior_uncert: (3N,3N) or per-source blocks (N,3,3)

Return type:

Dict[str, Any]

calibration_curve_componentwise_meg_free_pointwise(x_true_2d, x_hat_2d, posterior_uncert_2d, *, min_var=1e-12)

Pointwise marginal calibration curve for reduced free-orientation MEG (K=2).

Expected shapes: - x_true_2d, x_hat_2d: (N,2,T) - posterior_uncert_2d: (2N,2N) or per-source blocks (N,2,2)

Return type:

Dict[str, Any]

Notes

This diagnostic operates directly in reduced 2D coefficient coordinates: no 2D->3D lifting and no 3D->2D projection is performed here.

calibration_curve_componentwise_meg_free_aggregated(x_true_2d, x_hat_2d, posterior_uncert_2d, *, min_var=1e-12)

Aggregated marginal calibration curve for reduced free-orientation MEG (K=2).

Expected shapes: - x_true_2d, x_hat_2d: (N,2,T) - posterior_uncert_2d: (2N,2N) or per-source blocks (N,2,2)

Return type:

Dict[str, Any]

Notes

This diagnostic operates directly in reduced 2D coefficient coordinates: no 2D->3D lifting and no 3D->2D projection is performed here.

reduce_meg_leadfield_svd(L_free_Mx3N)

Fallback-only helper: build a source-wise SVD-reduced MEG leadfield.

For each source i:

L_i = U_i S_i V_i^T, with L_i in R^{M x 3}

keep the first two right singular vectors V_i(:, :2), and define

L_i_reduced = L_i @ V_i(:, :2) in R^{M x 2}

Recommended usage

In the current pipeline, prefer the extractor-provided basis

Q_basis = lf_free_meg[“Q_basis”]

rather than recomputing a new basis here.

returns:

• L_meg_Mx2N: reduced global leadfield, shape (M, 2N)

• V_tan: source-wise 3D->2D basis, shape (N, 3, 2)

• singular_values: shape (N, 2)

rtype:

dict with

precompute_meg_tangent_bases_svd(L_free_Mx3N)

Backward-compatible wrapper.

Returns source-wise local 3x2 reduction bases from the original free leadfield. Prefer passing the extractor basis directly whenever possible.

Return type:

ndarray

static project_meg_3d_to_2d(x_3d, V_tan)

Project 3D MEG truth/estimate onto the local reduced 2D coordinates.

Parameters:

• x_3d ((N,3,T) or (N,3))

• V_tan ((N,3,2))

Returns:

x_2d

Return type:

(N,2,T) or (N,2)

static lift_meg_2d_to_3d(x_2d, V_tan)

Lift reduced 2D MEG coordinates back to the retained local 3D basis.

Parameters:

• x_2d ((N,2,T) or (N,2))

• V_tan ((N,3,2))

Returns:

x_3d_lifted

Return type:

(N,3,T) or (N,3)

pointwise_ellipse_membership_meg_free(x_true_3d, x_hat_2d, posterior_cov_2d, nominal_coverage, *, V_tan=None, L_free_Mx3N=None, psd_repair_blocks=False, block_epsilon=1e-12)

Direct 2D MEG credible ellipse membership in reduced coordinates.

Return type:

Dict[str, Any]

Truth is provided in 3D and projected to reduced coordinates:

x_true_2d = V_tan^T x_true_3d

Posterior mean and covariance are assumed to already come from the reduced 2D MEG inverse model.

Recommended usage

Pass V_tan=Q_basis from the leadfield extractor to avoid recomputing a potentially sign-flipped basis.

aggregated_ellipse_membership_meg_free(x_true_3d, x_hat_2d, posterior_cov_2d, nominal_coverage, *, V_tan=None, L_free_Mx3N=None, psd_repair_blocks=False, block_epsilon=1e-12)

Aggregated 2D MEG credible ellipse membership in reduced coordinates.

Return type:

Dict[str, Any]

Recommended usage

Pass V_tan=Q_basis from the leadfield extractor.

calibration_curve_ellipse_meg_free_pointwise(x_true_3d, x_hat_2d, posterior_cov_2d, *, V_tan=None, L_free_Mx3N=None, psd_repair_blocks=False, block_epsilon=1e-12)

Return type:

Dict[str, Any]

calibration_curve_ellipse_meg_free_aggregated(x_true_3d, x_hat_2d, posterior_cov_2d, *, V_tan=None, L_free_Mx3N=None, psd_repair_blocks=False, block_epsilon=1e-12)

Return type:

Dict[str, Any]

plot_fixed_interval_membership_pointwise(x_true, x_hat, posterior_var, src_idx, nominal_coverage=0.95, *, times=None, figsize=(9.0, 4.0))

Return type:

None

plot_fixed_interval_membership_aggregated(diag_fixed, src_idx, *, nominal_coverage=0.95, figsize=(7.0, 2.2))

Return type:

None

plot_eeg_ellipsoid_membership_pointwise(x_hat, x_true, posterior_cov, src_idx, time_idx, nominal_coverage=0.95, *, psd_repair_blocks=False, block_epsilon=1e-12, figsize=(8.0, 6.0), elev=22.0, azim=-58.0)

Return type:

None

plot_eeg_ellipsoid_membership_aggregated(diag_eeg, src_idx, *, figsize=(8.0, 6.0), elev=22.0, azim=-58.0)

Return type:

None

plot_meg_ellipse_membership_pointwise(x_true_3d, x_hat_2d, posterior_cov_2d, src_idx, time_idx, nominal_coverage=0.95, *, V_tan=None, L_free_Mx3N=None, psd_repair_blocks=False, block_epsilon=1e-12, figsize=(6.5, 6.0))

Return type:

None

plot_meg_ellipse_membership_aggregated(diag_meg, src_idx, *, nominal_coverage=0.95, figsize=(6.5, 6.0))

Return type:

None