spectral_connectivity.statistics.jackknife_confidence_interval#

jackknife_confidence_interval(estimate: ndarray[tuple[int, ...], dtype[floating]], leave_one_out: ndarray[tuple[int, ...], dtype[floating]], *, confidence_level: float = 0.95, transformation: Literal['identity', 'log', 'fisher', 'fisher_squared', 'circular'] = 'identity', _saturated_by_construction: ndarray[tuple[int, ...], dtype[bool]] | bool = False) → JackknifeResult[source]#

Summarize leave-one-out replicates with a jackknife confidence interval.

Parameters:

  • estimate (array, shape (...)) – Full-sample estimate of a real-valued measure.

  • leave_one_out (array, shape (n_observations, ...)) – Replicates with one observation omitted each, stacked on the first axis; the remaining axes must match estimate.

  • confidence_level (float, default=0.95) – Two-sided coverage of the interval, in (0, 1). The critical value is the Student t quantile with n_observations - 1 degrees of freedom, the standard choice for a jackknife variance estimated from n_observations replicates [1] [2]; a normal quantile under-covers when there are few replicates (about 0.88 instead of 0.95 at five).

  • transformation ({"identity", "log", "fisher", "fisher_squared", "circular"}) – Scale on which the interval is formed. Log is appropriate for positive spectra, Fisher’s atanh for magnitude coherence in [-1, 1], fisher_squared (atanh(sqrt(.))) for magnitude-squared coherence in [0, 1], and circular for angles in radians.

Returns:

Estimate, bias-corrected estimate, standard error, and confidence bounds, all on the original scale and with the shape of estimate. The standard error is converted back with the local delta method.

Return type:

JackknifeResult

Notes

For "circular" the replicates are unwrapped onto the branch nearest the estimate, the interval is formed on that linear scale, and the bounds are wrapped back to (-pi, pi]. A bound that wraps past +/-pi leaves lower > upper; the interval is then [lower, pi] U (-pi, upper]. The circular standard error itself is not wrapped, so it can exceed pi; when the half-width is at least pi the interval covers the whole circle, the phase is not resolved, and the bounds are reported as (-pi, pi) with a UserWarning.

The interval describes the size of a measure; it is not a test that the measure differs from 0. In Monte Carlo simulation with independent complex-Gaussian observations and 95% nominal intervals, fisher_squared covers the true magnitude-squared coherence 94-95% of the time when the true |coherence| is 0.3-0.8, but when the true coherence is 0 it excludes 0 in 11-15% of datasets at 5 to 100 observations, and more observations do not help. (An estimate of exactly 0, which requires an exactly cancelling cross-spectrum, gets a standard error of 0, since the delta-method derivative vanishes there.) To test for nonzero coherence use the exact zero-coherence null, coherence_significance_pvalue(). "circular" intervals under-cover when the phase is poorly determined (77-88% coverage at a true |coherence| of 0.1). See spectral_connectivity.connectivity.Connectivity.jackknife() for the per-measure figures.

References

[1]

Thomson, D. J., & Chave, A. D. (1991). Jackknifed error estimates for spectra, coherences, and transfer functions. In Advances in Spectrum Analysis and Array Processing.

[2]

Efron, B., & Tibshirani, R. J. (1993). An Introduction to the Bootstrap. Chapman & Hall.