Coherency is an analogue of correlation, calculated in the frequency domain. This is a useful quantity for describing a system of oscillators coupled with delay. This is because the coherency captures not only the magnitude of the time-shift-independent correlation between the time-series (termed ‘coherence’), but can also be used in order to estimate the size of the time-delay (the phase-delay between the time-series in a particular frequency band).
This library contains the following functions:
XXX
compute and cache the windowed FFTs of the time_series, in such a way that computing the psd and csd of any combination of them can be done quickly.
Parameters : | time_series : float array
ij: list of tuples :
lb,ub: float :
method: dict, optional :
|
---|---|
Returns : | freqs, cache :
|
Notes
From a set of cached spectra, calculate the coherency relationships
Parameters : | cache: dict :
ij: list :
|
---|---|
Returns : | Cxy: dict :
|
From a set of cached set of windowed fft’s, calculate the frequency-band dependent phase for each of the channels in ij. Note that this returns the absolute phases of the time-series, not the relative phases between them. In order to get relative phases, use cache_to_relative_phase
Parameters : | cache : dict
ij: list :
|
---|---|
Returns : | Phase : dict
|
From a set of cached windowed fft, calculate the psd
Parameters : | cache : dict
ij : list
|
---|---|
Returns : | Pxx : dict
|
From a set of cached set of windowed fft’s, calculate the frequency-band dependent relative phase for the combinations ij.
Parameters : | cache: dict :
ij: list :
|
---|---|
Returns : | Phi_xy : dict
|
Compute the coherence between the spectra of an n-tuple of time_series.
Parameters of this function are in the time domain.
Parameters : | time_series: float array :
csd_method: dict, optional :
|
---|---|
Returns : | f : float array
c : float array
|
Notes
This is an implementation of equation (2) of Sun (2005):
Coh_{xy}(\lambda) = |{R_{xy}(\lambda)}|^2 = \frac{|{f_{xy}(\lambda)}|^2}{f_{xx}(\lambda) \cdot f_{yy}(\lambda)}
F.T. Sun and L.M. Miller and M. D’Esposito (2005). Measuring temporal dynamics of functional networks using phase spectrum of fMRI data. Neuroimage, 28: 227-37.
Compute the band-averaged coherence between the spectra of two time series.
Input to this function is in the time domain.
Parameters : | time_series : float array
lb, ub: float, optional :
csd_method: dict, optional. :
|
---|---|
Returns : | c : float
|
Compute the band-specific partial coherence between the spectra of two time series.
The partial coherence is the part of the coherence between x and y, which cannot be attributed to a common cause, r.
Input to this function is in the time domain.
Parameters : | time_series: float array :
r: float array :
csd_method: dict, optional :
|
---|---|
Returns : | f: array, :
c: float array :
|
Notes
This is an implementation of equation (2) of Sun (2004):
Coh_{xy|r} = \frac{|{R_{xy}(\lambda) - R_{xr}(\lambda) R_{ry}(\lambda)}|^2}{(1-|{R_{xr}}|^2)(1-|{R_{ry}}|^2)}
F.T. Sun and L.M. Miller and M. D’Esposito (2004). Measuring interregional functional connectivity using coherence and partial coherence analyses of fMRI data Neuroimage, 21: 647-58.
Compute the band-specific partial coherence between the spectra of two time series. See partial_coherence().
Input to this function is in the frequency domain.
Parameters : | fxy : float array
fyy, fxx : float array
fxr, fry : float array
|
---|---|
Returns : | float :
|
Same as coherence, except regularized in order to overcome numerical imprecisions
Parameters : | time_series: n-d float array :
epsilon: float :
alpha: float :
csd_method: dict, optional. :
|
---|---|
Returns : | frequencies, coherence : |
Notes
The regularization scheme is as follows:
C_{x,y} = \frac{(\alpha f_{xx} + \epsilon)^2} {\alpha^{2}((f_{xx}+\epsilon)(f_{yy}+\epsilon))}
Compute the coherence between the spectra of two time series.
Parameters of this function are in the frequency domain.
Parameters : | fxy : array
fyy, fxx : array
|
---|---|
Returns : | float : a frequency-band-dependent measure of the linear association
|
See also
Compute the coherency between the spectra of n-tuple of time series. Input to this function is in the time domain
Parameters : | time_series: n*t float array :
csd_method: dict, optional. :
|
---|---|
Returns : | f : float array
c : float array
|
Notes
This is an implementation of equation (1) of Sun (2005):
R_{xy} (\lambda) = \frac{f_{xy}(\lambda)} {\sqrt{f_{xx} (\lambda) \cdot f_{yy}(\lambda)}}
F.T. Sun and L.M. Miller and M. D’Esposito (2005). Measuring temporal dynamics of functional networks using phase spectrum of fMRI data. Neuroimage, 28: 227-37.
Compute the band-averaged coherency between the spectra of two time series.
Input to this function is in the time domain.
Parameters : | time_series: n*t float array :
lb, ub: float, optional :
csd_method: dict, optional. :
|
---|---|
Returns : | c: float array :
|
Notes
This is an implementation of equation (A4) of Sun(2005):
\bar{Coh_{xy}} (\bar{\lambda}) = \frac{\left|{\sum_\lambda{\hat{f_{xy}}}}\right|^2} {\sum_\lambda{\hat{f_{xx}}}\cdot sum_\lambda{\hat{f_{yy}}}}
F.T. Sun and L.M. Miller and M. D’Esposito (2005). Measuring temporal dynamics of functional networks using phase spectrum of fMRI data. Neuroimage, 28: 227-37.
The temporal delay calculated from the coherency phase spectrum.
Parameters : | time_series: float array :
lb, ub: float :
csd_method : dict, optional.
|
---|---|
Returns : | f : float array
p : float array
|
Compute the phase spectrum of the cross-spectrum between two time series.
The parameters of this function are in the time domain.
Parameters : | time_series: n*t float array : The time series, with t, time, as the last dimension : |
---|---|
Returns : | f: mid frequencies of the bands : p: an array with the pairwise phase spectrum between the time : series, where p[i][j] is the phase spectrum between time series[i] and : time_series[j] : |
Notes
This is an implementation of equation (3) of Sun et al. (2005) [Sun2005]:
\phi(\lambda) = arg [R_{xy} (\lambda)] = arg [f_{xy} (\lambda)]
F.T. Sun and L.M. Miller and M. D’Esposito (2005). Measuring temporal dynamics of functional networks using phase spectrum of fMRI data. Neuroimage, 28: 227-37.
Compute a regularized measure of the coherence.
Regularization may be needed in order to overcome numerical imprecisions
Parameters : | time_series: float array :
epsilon: float :
alpha: float :
csd_method: dict, optional. :
|
---|---|
Returns : | f: float array :
c: float array :
|
Notes
The regularization scheme is as follows:
Coh_{xy}^R = \frac{(\alpha f_{xx} + \epsilon) ^2} {\alpha^{2}(f_{xx}+\epsilon)(f_{yy}+\epsilon)}
Compute the coherency between the spectra of two time series.
Input to this function is in the frequency domain.
Parameters : | fxy : float array
fyy,fxx : float array
|
---|---|
Returns : | complex array :
|
See also
Calculate the spectral decomposition of the correlation.
Parameters : | x1,x2: ndarray :
Fs: float, optional :
norm: bool, optional :
|
---|---|
Returns : | f: ndarray :
ccn: ndarray :
|
Notes
This method is described in full in: D Cordes, V M Haughton, K Arfanakis, G J Wendt, P A Turski, C H Moritz, M A Quigley, M E Meyerand (2000). Mapping functionally related regions of brain with functional connectivity MR imaging. AJNR American journal of neuroradiology 21:1636-44