spectral_connectivity.statistics.coherence_fisher_z_transform#

coherence_fisher_z_transform(coherency1: ndarray[tuple[int, ...], dtype[complexfloating]], n_obs1: int, coherency2: ndarray[tuple[int, ...], dtype[complexfloating]] | float = 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], shape (...,)) – Complex coherency values between signals.

  • 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
>>> # Test single coherence against zero
>>> coherence = np.array([0.1 + 0.05j, 0.3 + 0.2j, 0.8 + 0.1j])
>>> z_scores = coherence_fisher_z_transform(coherence, n_obs1=100)
>>>
>>> # Compare two coherences
>>> 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)

Notes

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