# 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 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).

## 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 time-series, 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 time-series 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’ 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 cross-coherency is to be calculated Cxy: dict : coherence values between the time-series ij. Indexing into this dict takes the form Cxy[i,j] in order to extract the coherency between time-series i and time-series 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 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 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 Phase : dict The individual phases, keys are all the i and j in ij, such that Phase[i] gives you the phase for the time-series 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). 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 frequency-band 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 Phi_xy : dict The relative phases between the time-series 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 n-tuple 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 details 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: 227-37.

nitime.algorithms.cohere.coherence_bavg(time_series, lb=0, ub=None, csd_method=None)

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 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 details c : float This is an upper-diagonal array, where c[i][j] is the band-averaged coherency between time_series[i] and time_series[j]
nitime.algorithms.cohere.coherence_partial(time_series, r, csd_method=None)

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 : An array of time-series, 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 details f: array, : The mid-frequencies 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_{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.

nitime.algorithms.cohere.coherence_partial_spec(fxy, fxx, fyy, fxr, fry, frr)

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 The cross-spectrum of the time series fyy, fxx : float array The spectra of the signals fxr, fry : float array The cross-spectra of the signals with the event float : the band-averaged 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: n-d 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 details f: float array : The central frequencies for the frequency bands for which the spectra are estimated c: n-d 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 cross-spectrum of the time series fyy, fxx : array The spectra of the signals float : a frequency-band-dependent measure of the linear association between the two time series
nitime.algorithms.cohere.coherency(time_series, csd_method=None)

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 an array of n different time series of length t each csd_method : dict, optional. See get_spectra() documentation for details 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: 227-37.

nitime.algorithms.cohere.coherency_bavg(time_series, lb=0, ub=None, csd_method=None)

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 : 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 details c: float array : This is an upper-diagonal array, where c[i][j] is the band-averaged 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: 227-37.

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 time-series 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 0-max(f) csd_method : dict, optional. See get_spectra() f : float array The mid-frequencies for the frequency bands over which the calculation is done. p : float array Pairwise temporal delays between time-series (in seconds).
nitime.algorithms.cohere.coherency_phase_spectrum(time_series, csd_method=None)

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 : 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.

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 details 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 cross-spectrum of the time series fyy,fxx : float array The spectra of the signals complex array : the frequency-band-dependent coherency
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 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:1636-44