# analysis.coherence

## Module: `analysis.coherence`

Inheritance diagram for `nitime.analysis.coherence`:

## Classes

### `CoherenceAnalyzer`

class nitime.analysis.coherence.CoherenceAnalyzer(input=None, method=None, unwrap_phases=False)

  Bases: `BaseAnalyzer`

  Analyzer object for coherence/coherency analysis

  __init__(input=None, method=None, unwrap_phases=False)
    Parameters:

      input : TimeSeries object

      > Containing the data to analyze.

      method : dict, optional,

      > This is the method used for spectral analysis of the signal for the coherence calculation. See `algorithms.get_spectra()` documentation for details.

      unwrap_phases : bool, optional

      > Whether to unwrap the phases. This should be True if you assume that the time-delay is the same for all the frequency bands. See _[Sun2005] for details. Default : False

    Examples

        >>> import nitime.timeseries as ts
        >>> t1 = ts.TimeSeries(data = np.arange(0,1024,1).reshape(2,512),
        ...                                 sampling_rate=np.pi)
        >>> c1 = CoherenceAnalyzer(t1)
        >>> c1.method['Fs']
        3.1415926535... Hz
        >>> c1.method['this_method']
        'welch'
        >>> c1.coherence[0,1]
        array([0.9024, 0.9027, 0.9652, 0.9433, 0.9297, 0.9213, 0.9161, 0.9126,
               0.9102, 0.9085, 0.9072, 0.9063, 0.9055, 0.905 , 0.9045, 0.9041,
               0.9038, 0.9036, 0.9034, 0.9032, 0.9031, 0.9029, 0.9028, 0.9027,
               0.9027, 0.9026, 0.9026, 0.9025, 0.9025, 0.9025, 0.9025, 0.9026,
               1.    ])
        >>> c1.phase[0,1]
        array([ 0.    , -0.035 , -0.4839, -0.4073, -0.3373, -0.2828, -0.241 ,
               -0.2085, -0.1826, -0.1615, -0.144 , -0.1292, -0.1164, -0.1054,
               -0.0956, -0.0869, -0.0791, -0.072 , -0.0656, -0.0596, -0.0541,
               -0.0489, -0.0441, -0.0396, -0.0353, -0.0314, -0.0277, -0.0244,
               -0.0216, -0.0197, -0.0198, -0.028 ,  0.    ])

  coherence()

    The coherence between the different channels in the input TimeSeries object

  coherence_partial()

    The partial coherence between data[i] and data[j], given data[k], as a function of frequency band

  coherency()

    The standard output for this kind of analyzer is the coherency

  delay()

    The delay in seconds between the two time series

  frequencies()

    The central frequencies in the bands

  phase()

    The frequency-dependent phase relationship between all the pairwise combinations of time-series in the data

  spectrum()

    The spectra of each of the channels and cross-spectra between different channels in the input TimeSeries object

### `MTCoherenceAnalyzer`

class nitime.analysis.coherence.MTCoherenceAnalyzer(input=None, bandwidth=None, alpha=0.05, adaptive=True)

  Bases: `BaseAnalyzer`

  Analyzer for multi-taper coherence analysis, including jack-knife estimate of confidence interval

  __init__(input=None, bandwidth=None, alpha=0.05, adaptive=True)

    Initializer function for the MTCoherenceAnalyzer

    Parameters:

      input : TimeSeries object

      bandwidth : float,

      > The bandwidth of the windowing function will determine the number tapers to use. This parameters represents trade-off between frequency resolution (lower main lobe bandwidth for the taper) and variance reduction (higher bandwidth and number of averaged estimates). Per default will be set to 4 times the fundamental frequency, such that NW=4

      alpha : float, default =0.05

      > This is the alpha used to construct a confidence interval around the multi-taper csd estimate, based on a jack-knife estimate of the variance [Thompson2007].

      adaptive : bool, default to True

      > Whether to set the weights for the tapered spectra according to the adaptive algorithm (Thompson, 2007).

    Notes

    Thompson, DJ (2007) Jackknifing multitaper spectrum estimates. IEEE Signal Processing Magazing. 24: 20-30

  coherence()
  confidence_interval()

    The size of the 1-alpha confidence interval

  df()
  eigs()
  frequencies()
  spectra()
  tapers()
  weights()

### `SeedCoherenceAnalyzer`

class nitime.analysis.coherence.SeedCoherenceAnalyzer(seed_time_series=None, target_time_series=None, method=None, lb=0, ub=None, prefer_speed_over_memory=True, scale_by_freq=True)

  Bases: `object`

  This analyzer takes two time-series. The first is designated as a time-series of seeds. The other is designated as a time-series of targets. The analyzer performs a coherence analysis between each of the channels in the seed time-series and all of the channels in the target time-series.

  __init__(seed_time_series=None, target_time_series=None, method=None, lb=0, ub=None, prefer_speed_over_memory=True, scale_by_freq=True)

    The constructor for the SeedCoherenceAnalyzer

    Parameters:

      seed_time_series: a time-series object :

      target_time_series: a time-series object :

      lb,ub: float,optional, default: lb=0, ub=None (max frequency) :

      > define a frequency band of interest

      prefer_speed_over_memory: Boolean, optional, default=True :

      > Makes things go a bit faster, if you have enough memory

  coherence()

    The coherence between each of the channels of the seed time series and all the channels of the target time-series.

  coherency()
  delay()

    The delay in seconds between the two time series

  frequencies()

    Get the central frequencies for the frequency bands, given the method of estimating the spectrum

  relative_phases()

    The frequency-band dependent relative phase between the two time-series

  target_cache()

### `SparseCoherenceAnalyzer`

class nitime.analysis.coherence.SparseCoherenceAnalyzer(time_series=None, ij=(0, 0), method=None, lb=0, ub=None, prefer_speed_over_memory=True, scale_by_freq=True)

  Bases: `BaseAnalyzer`

  This analyzer is intended for analysis of large sets of data, in which possibly only a subset of combinations of time-series needs to be compared. The constructor for this class receives as input not only a time-series object, but also a list of tuples with index combinations (i,j) for the combinations. Importantly, this class implements only the mlab csd function and cannot use other methods of spectral estimation

  __init__(time_series=None, ij=(0, 0), method=None, lb=0, ub=None, prefer_speed_over_memory=True, scale_by_freq=True)

    The constructor for the SparseCoherenceAnalyzer

    Parameters:

      time_series : a time-series object

      ij : a list of tuples, each containing a pair of indices.

      > 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,optional, default: lb=0, ub=None (max frequency)

      > define a frequency band of interest

      prefer_speed_over_memory: Boolean, optional, default=True :

      > Does exactly what the name implies. If you have enough memory

      method : optional, dict

      > The method for spectral estimation (see `algorithms.get_spectra()`)

  cache()

    Caches the fft windows required by the other methods of the SparseCoherenceAnalyzer. Calculate only once and reuse

  coherence()

    The coherence values for the output

  coherency()

    The default behavior is to calculate the cache, extract it and then output the coherency

  delay()

    The delay in seconds between the two time series

  frequencies()

    Get the central frequencies for the frequency bands, given the method of estimating the spectrum

  phases()

    The frequency-band dependent phases of the spectra of each of the time -series i,j in the analyzer

  relative_phases()

    The frequency-band dependent relative phase between the two time-series

  spectrum()

    get the spectrum for the collection of time-series in this analyzer