spectral_connectivity.statistics.coherence_significance_pvalue#

coherence_significance_pvalue(coherency: ndarray[tuple[int, ...], dtype[complexfloating]], n_observations: int) → ndarray[tuple[int, ...], dtype[floating]][source]#

P-value for testing squared coherence magnitude against zero.

Tests the null hypothesis that the true coherence is zero. Under this null, for n independent complex-Gaussian observations the magnitude-squared coherence estimate follows a Beta(1, n - 1) distribution, so the upper-tail probability is P(|C|^2 >= c) = (1 - c)^(n - 1).

This exact boundary distribution should be used instead of the Fisher z-transform (coherence_fisher_z_transform()) when testing against zero coherence: the Fisher approximation is derived around a non-zero operating point and is badly miscalibrated at coherence == 0 (it over-rejects the null by 3-4x, e.g. ~16-22% actual rejection at a nominal 5% level).

Parameters:

  • coherency (NDArray[complexfloating], shape (...,)) – Complex coherency values between signals.

  • n_observations (int) – Number of independent observations used to estimate the coherency (n_tapers * n_trials).

Returns:

p_values – Upper-tail p-values for the test of zero coherence.

Return type:

NDArray[floating], shape (…,)

References

[1]

Hannan, E. J. (1970). Multiple Time Series. Wiley. (Null distribution of magnitude-squared coherence.)

[2]

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