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