# 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’

  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 cross-coherency is to be calculated

  Returns:

    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

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

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

  Returns:

    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

  Returns:

    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

  Returns:

    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

  Returns:

    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

  Returns:

    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

  Returns:

    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

  Returns:

    float : a frequency-band-dependent measure of the linear association

    > between the two time series

  See also

  `coherence()`

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

  Returns:

    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

  Returns:

    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()`

  Returns:

    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 :

  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.

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

  Returns:

    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

  Returns:

    complex array :

    > the frequency-band-dependent coherency

  See also

  `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

  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:1636-44