algorithms.cohere¶
Module: algorithms.cohere
¶
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 timeshiftindependent correlation between the timeseries (termed ‘coherence’), but can also be used in order to estimate the size of the timedelay (the phasedelay between the timeseries in a particular frequency band).
Functions¶

nitime.algorithms.cohere.
cache_fft
(time_series, ij, lb=0, ub=None, method=None, prefer_speed_over_memory=False, scale_by_freq=True)¶ 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
An ndarray with timeseries, where time is the last dimension
ij: list of tuples :
Each tuple in this variable should contain a pair of indices of the form (i,j). The resulting cache will contain the fft of timeseries in the rows indexed by the unique elements of the union of i and j
lb,ub: float :
Define a frequency band of interest, for which the fft will be cached
method: dict, optional :
See
get_spectra()
for details on how this is used. For this set of functions, ‘this_method’ has to be ‘welch’Returns: freqs, cache :
 where: cache =
{‘FFT_slices’:FFT_slices,’FFT_conj_slices’:FFT_conj_slices, ‘norm_val’:norm_val}
Notes
 For these functions, only the Welch windowed periodogram (‘welch’) is available.
 Detrending the input is not an option here, in order to save time on an empty function call.

nitime.algorithms.cohere.
cache_to_coherency
(cache, ij)¶ From a set of cached spectra, calculate the coherency relationships
Parameters: cache: dict :
the return value from
cache_fft()
ij: list :
a list of (i,j) tuples, the pairs of indices for which the crosscoherency is to be calculated
Returns: Cxy: dict :
coherence values between the timeseries ij. Indexing into this dict takes the form Cxy[i,j] in order to extract the coherency between timeseries i and timeseries j in the original input to
cache_fft()

nitime.algorithms.cohere.
cache_to_phase
(cache, ij)¶ From a set of cached set of windowed fft’s, calculate the frequencyband dependent phase for each of the channels in ij. Note that this returns the absolute phases of the timeseries, not the relative phases between them. In order to get relative phases, use cache_to_relative_phase
Parameters: cache : dict
The return value of
cache_fft()
ij: list :
A list of tuples of the form (i,j) for all the indices for which to calculate the phases
Returns: Phase : dict
The individual phases, keys are all the i and j in ij, such that Phase[i] gives you the phase for the timeseries i in the input to
cache_fft()

nitime.algorithms.cohere.
cache_to_psd
(cache, ij)¶ From a set of cached windowed fft, calculate the psd
Parameters: cache : dict
Return value from
cache_fft()
ij : list
A list of tuples of the form (i,j).
Returns: Pxx : dict
The phases for the intersection of (time_series[i],time_series[j]). The keys are the intersection of i,j values in the parameter ij

nitime.algorithms.cohere.
cache_to_relative_phase
(cache, ij)¶ From a set of cached set of windowed fft’s, calculate the frequencyband dependent relative phase for the combinations ij.
Parameters: cache: dict :
The return value from
cache_fft()
ij: list :
A list of tuples of the form (i,j), all the pairs of indices for which to calculate the relative phases
Returns: Phi_xy : dict
The relative phases between the timeseries i and j. Such that Phi_xy[i,j] is the phase from time_series[i] to time_series[j].

nitime.algorithms.cohere.
coherence
(time_series, csd_method=None)¶ Compute the coherence between the spectra of an ntuple of time_series.
Parameters of this function are in the time domain.
Parameters: time_series : float array
an array of different time series with time as the last dimension
csd_method : dict, optional
See
algorithms.spectral.get_spectra()
documentation for detailsReturns: f : float array
The central frequencies for the frequency bands for which the spectra are estimated
c : float array
This is a symmetric matrix with the coherencys of the signals. The coherency of signal i and signal j is in f[i][j].
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: 22737.

nitime.algorithms.cohere.
coherence_bavg
(time_series, lb=0, ub=None, csd_method=None)¶ Compute the bandaveraged coherence between the spectra of two time series.
Input to this function is in the time domain.
Parameters: time_series : float array
An array of time series, time as the last dimension.
lb, ub: float, optional :
The upper and lower bound on the frequency band to be used in averaging defaults to 1,max(f)
csd_method: dict, optional. :
See
get_spectra()
documentation for detailsReturns: c : float
This is an upperdiagonal array, where c[i][j] is the bandaveraged coherency between time_series[i] and time_series[j]

nitime.algorithms.cohere.
coherence_partial
(time_series, r, csd_method=None)¶ Compute the bandspecific 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 :
An array of timeseries, with time as the last dimension.
r: float array :
This array represents the temporal sequence of the common cause to be partialed out, sampled at the same rate as time_series
csd_method: dict, optional :
See
get_spectra()
documentation for detailsReturns: f: array, :
The midfrequencies of the frequency bands in the spectral decomposition
c: float array :
The frequency dependent partial coherence between time_series i and time_series j in c[i][j] and in c[j][i], with r partialed out
Notes
This is an implementation of equation (2) of Sun (2004):
\[Coh_{xyr} = \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: 64758.

nitime.algorithms.cohere.
coherence_partial_spec
(fxy, fxx, fyy, fxr, fry, frr)¶ Compute the bandspecific 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
The crossspectrum of the time series
fyy, fxx : float array
The spectra of the signals
fxr, fry : float array
The crossspectra of the signals with the event
Returns: float :
the bandaveraged coherency

nitime.algorithms.cohere.
coherence_regularized
(time_series, epsilon, alpha, csd_method=None)¶ Same as coherence, except regularized in order to overcome numerical imprecisions
Parameters: time_series: nd float array :
The time series data for which the regularized coherence is calculated
epsilon: float :
Small regularization parameter. Should be much smaller than any meaningful value of coherence you might encounter
alpha: float :
large regularization parameter. Should be much larger than any meaningful value of coherence you might encounter (preferably much larger than 1).
csd_method: dict, optional. :
See
get_spectra()
documentation for detailsReturns: f: float array :
The central frequencies for the frequency bands for which the spectra are estimated
c: nd array :
This is a symmetric matrix with the coherencys of the signals. The coherency of signal i and signal j is in f[i][j].
Notes
The regularization scheme is as follows:
\[C_{x,y} = \frac{(\alpha f_{xx} + \epsilon)^2} {\alpha^{2}((f_{xx}+\epsilon)(f_{yy}+\epsilon))}\]

nitime.algorithms.cohere.
coherence_spec
(fxy, fxx, fyy)¶ Compute the coherence between the spectra of two time series.
Parameters of this function are in the frequency domain.
Parameters: fxy : array
The crossspectrum of the time series
fyy, fxx : array
The spectra of the signals
Returns: float : a frequencybanddependent measure of the linear association
between the two time series
See also

nitime.algorithms.cohere.
coherency
(time_series, csd_method=None)¶ Compute the coherency between the spectra of ntuple of time series. Input to this function is in the time domain
Parameters: time_series : n*t float array
an array of n different time series of length t each
csd_method : dict, optional.
See
get_spectra()
documentation for detailsReturns: f : float array
The central frequencies for the frequency bands for which the spectra are estimated
c : float array
This is a symmetric matrix with the coherencys of the signals. The coherency of signal i and signal j is in f[i][j]. Note that f[i][j] = f[j][i].conj()
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: 22737.

nitime.algorithms.cohere.
coherency_bavg
(time_series, lb=0, ub=None, csd_method=None)¶ Compute the bandaveraged coherency between the spectra of two time series.
Input to this function is in the time domain.
Parameters: time_series: n*t float array :
an array of n different time series of length t each
lb, ub: float, optional :
the upper and lower bound on the frequency band to be used in averaging defaults to 1,max(f)
csd_method: dict, optional. :
See
get_spectra()
documentation for detailsReturns: c: float array :
This is an upperdiagonal array, where c[i][j] is the bandaveraged coherency between time_series[i] and time_series[j]
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: 22737.

nitime.algorithms.cohere.
coherency_phase_delay
(time_series, lb=0, ub=None, csd_method=None)¶ The temporal delay calculated from the coherency phase spectrum.
Parameters: time_series: float array :
The timeseries data for which the delay is calculated.
lb, ub: float :
Frequency boundaries (in Hz), for the domain over which the delays are calculated. Defaults to 0max(f)
csd_method : dict, optional.
See
get_spectra()
Returns: f : float array
The midfrequencies for the frequency bands over which the calculation is done.
p : float array
Pairwise temporal delays between timeseries (in seconds).

nitime.algorithms.cohere.
coherency_phase_spectrum
(time_series, csd_method=None)¶ Compute the phase spectrum of the crossspectrum 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: 22737.

nitime.algorithms.cohere.
coherency_regularized
(time_series, epsilon, alpha, csd_method=None)¶ Compute a regularized measure of the coherence.
Regularization may be needed in order to overcome numerical imprecisions
Parameters: time_series: float array :
The time series data for which the regularized coherence is calculated. Time as the last dimension.
epsilon: float :
Small regularization parameter. Should be much smaller than any meaningful value of coherence you might encounter
alpha: float :
Large regularization parameter. Should be much larger than any meaningful value of coherence you might encounter (preferably much larger than 1).
csd_method: dict, optional. :
See
get_spectra()
documentation for detailsReturns: f: float array :
The central frequencies for the frequency bands for which the spectra are estimated
c: float array :
This is a symmetric matrix with the coherencys of the signals. The coherency of signal i and signal j is in f[i][j]. Note that f[i][j] = f[j][i].conj()
Notes
The regularization scheme is as follows:
\[Coh_{xy}^R = \frac{(\alpha f_{xx} + \epsilon) ^2} {\alpha^{2}(f_{xx}+\epsilon)(f_{yy}+\epsilon)}\]

nitime.algorithms.cohere.
coherency_spec
(fxy, fxx, fyy)¶ Compute the coherency between the spectra of two time series.
Input to this function is in the frequency domain.
Parameters: fxy : float array
The crossspectrum of the time series
fyy,fxx : float array
The spectra of the signals
Returns: complex array :
the frequencybanddependent coherency
See also

nitime.algorithms.cohere.
correlation_spectrum
(x1, x2, Fs=6.283185307179586, norm=False)¶ Calculate the spectral decomposition of the correlation.
Parameters: x1,x2: ndarray :
Two arrays to be correlated. Same dimensions
Fs: float, optional :
Sampling rate in Hz. If provided, an array of frequencies will be returned.Defaults to 2
norm: bool, optional :
When this is true, the spectrum is normalized to sum to 1
Returns: f: ndarray :
ndarray with the frequencies
ccn: ndarray :
The spectral decomposition of the correlation
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:163644