spectral_connectivity.statistics.coherence_fisher_z_transform#

coherence_fisher_z_transform(coherency1: ndarray[tuple[int, ...], dtype[complexfloating]] | complex, n_obs1: int, coherency2: ndarray[tuple[int, ...], dtype[complexfloating]] | complex = 0, n_obs2: int = 0) → ndarray[tuple[int, ...], dtype[floating]][source]#

Transform coherence magnitude to approximately normal distribution.

Applies Fisher’s z-transformation to coherence magnitudes, which approximately normalizes the distribution for statistical testing. Can compute single-sample test against zero or two-sample test.

Parameters:

  • coherency1 (NDArray[complexfloating] or complex, shape (...,)) – Complex coherency values between signals. A scalar is accepted and gives a scalar (0-d) result.

  • n_obs1 (int) – Number of observations for coherency1 (n_tapers * n_trials).

  • coherency2 (NDArray[complexfloating] or float, default=0) – Second coherency for comparison. If 0, tests against null hypothesis.

  • n_obs2 (int, default=0) – Number of observations for coherency2 (n_tapers * n_trials).

Returns:

fisher_z_transform – Z-scores for statistical testing. If coherency2=0, tests coherency1 against zero. Otherwise, tests difference coherency1 - coherency2.

Return type:

NDArray[floating], shape (…,)

Examples

>>> import numpy as np
>>> # Compare two coherences (the intended two-sample use).
>>> coh1 = np.array([0.5 + 0.2j, 0.3 + 0.1j])
>>> coh2 = np.array([0.3 + 0.15j, 0.4 + 0.05j])
>>> diff_z = coherence_fisher_z_transform(coh1, 100, coh2, 120)
>>>
>>> # To test a single coherence against ZERO, use the exact null instead:
>>> from spectral_connectivity.statistics import coherence_significance_pvalue
>>> coherence = np.array([0.1 + 0.05j, 0.3 + 0.2j, 0.8 + 0.1j])
>>> p_values = coherence_significance_pvalue(coherence, n_observations=100)

Notes

The transformation uses bias correction based on the number of observations to improve the normal approximation for small sample sizes.

The Fisher approximation is derived around a non-zero operating point. To test a single coherence against zero coherence, prefer coherence_significance_pvalue(), which uses the exact null distribution; the Fisher one-sample form (the coherency2=0, n_obs2=0 default) is miscalibrated at that boundary and over-rejects the null.