connectivityanalysis#

syncopy.connectivityanalysis(data, method='coh', keeptrials=False, output='abs', foi=None, foilim=None, pad='maxperlen', channelcmb=None, polyremoval=0, tapsmofrq=None, nTaper=None, taper='hann', taper_opt=None, jackknife=False, parallel=None, select=None, **kwargs)[source]#

Perform connectivity analysis of Syncopy SpectralData OR directly AnalogData objects

In case the input is an AnalogData object, a (multi-)tapered Fourier analysis is performed implicitly to arrive at the cross spectral densities needed for coherence, ppc and Granger causality estimates. Relevant parameters are the same as for freqanalysis() with method='mtmfft':

(‘foi’, ‘foilim’, ‘pad’, ‘tapsmofrq’, ‘nTaper’, ‘taper’, ‘taper_opt’, ‘polyremoval’)

If the input is already in the spectral domain, so data is of class SpectralData, no additional modification of the spectra is performed, and all parameters above to control the spectral estimation have no effect.

Usage Summary

List of available analysis methods and respective distinct options:

“coh”(Multi-) tapered coherency estimate

Compute the normalized cross spectral densities between channel combinations

output : one of (‘abs’, ‘pow’, ‘complex’, ‘angle’, ‘imag’ or ‘real’)
channelcmb: [senders, receivers], two sequences encoding channel names/indices
jackknife: set to True to compute the variance via jackknife resampling

Spectral analysis (input is AnalogData):

taper : one of availableTapers
tapsmofrq : spectral smoothing box for slepian tapers (in Hz)
nTaper : (optional) number of orthogonal tapers for slepian tapers
pad: either pad to an absolute length in seconds or set to ‘nextpow2’

“csd”(‘Multi-) tapered cross spectra

Computes the cross spectral estimates between channel combinations

output is fixed: complex cross spectra

channelcmb: [senders, receivers], two sequences encoding channel names/indices
keeptrials: set to False to get single-trial cross-spectra

Spectral analysis (input is AnalogData):

taper : one of availableTapers
tapsmofrq : spectral smoothing box for slepian tapers (in Hz)
nTaper : (optional) number of orthogonal tapers for slepian tapers
pad: either pad to an absolute length in seconds or set to ‘nextpow2’

“ppc”Pairwise phase consistency, see [Vinck2010]

Computes the PPC phase locking index for channel combinations.

NOTE: Computations for all channel pairs can be slow, it is recommended to use the channelcmb parameter to compute only desired channel pairs, as this can lead to a significant speed up.

output is fixed : real ppc spectrum

channelcmb: [senders, receivers], two sequences encoding channel names/indices

Spectral analysis (input is AnalogData):

taper : one of availableTapers
tapsmofrq : spectral smoothing box for slepian tapers (in Hz)
nTaper : (optional) number of orthogonal tapers for slepian tapers
pad: either pad to an absolute length in seconds or set to ‘nextpow2’

“granger”Spectral Granger-Geweke causality following [Dhamala2008]

Computes linear causality estimates between channel combinations.

WARNING: When inputting SpectralData directly, it is very important that the previous spy.freqanalysis was done without foi/foilim specification as Granger causality needs all attainable frequencies (0, f_Nyquist)! It is possible to compute many channel pairs at once (default behavior), but this can be numerically unstable. The recommended way is to use the channelcmb parameter, which triggers pair-wise computation.

channelcmb: [senders, receivers], two sequences encoding channel names/indices
jackknife: set to True to compute the variance via jackknife resampling

Spectral analysis (input is AnalogData):

taper : one of availableTapers
tapsmofrq : spectral smoothing box for slepian tapers (in Hz)
nTaper : (optional, not recommended) number of slepian tapers
pad: either pad to an absolute length in seconds or set to ‘nextpow2’

After the computation, information about the convergence and potential regularization of the cross-spectral densities can be obtained by inspecting the .info property of the resulting :class:~`syncopy.CrossSpectralData` object. Keys of that info-dict are: `{'converged', 'max rel. err', 'reg. factor', 'initial cond. num'}`.

“corr”Cross-correlations

Computes the one sided (positive lags) cross-correlations between all channel combinations of AnalogData. The maximal lag is half the trial lengths.

keeptrials : set to True for single trial cross-correlations

The parameters listed below can be provided as is or a via a cfg configuration ‘structure’, see Notes for details.

Parameters:

data (~syncopy.AnalogData) – A non-empty Syncopy SpectralData or AnalogData object
method (str) – Connectivity estimation method, one of 'coh'`, 'corr', 'granger', 'csd', 'ppc'
output (str) – Relevant for coherence estimation (method='coh') Use 'pow' for absolute squared coherence, 'abs' for absolute value of coherence , 'complex' for the complex valued coherency or 'angle', 'imag' or 'real' to extract the phase difference, imaginary or real part of the coherency respectively.
keeptrials (bool) – Relevant only for cross-correlations (method='corr') and cross spectra (method='csd'). If True single-trial cross-correlations/cross-spectra are returned.
foi (array-like or None) – Frequencies of interest (Hz) for output. If desired frequencies cannot be matched exactly, the closest possible frequencies are used. If foi is None or foi = "all", all attainable frequencies (i.e., zero to Nyquist / 2) are selected.
foilim (array-like [fmin, fmax] or None or "all") – Frequency-window [fmin, fmax] (in Hz) of interest. The foi array will be constructed in 1Hz steps from fmin to fmax (inclusive).
pad ('maxperlen', float or 'nextpow2' -) – For the default 'maxperlen', no padding is performed in case of equal length trials, while trials of varying lengths are padded to match the longest trial. If pad is a number all trials are padded so that pad indicates the absolute length of all trials after padding (in seconds). For instance pad = 2 pads all trials to an absolute length of 2000 samples, if and only if the longest trial contains at maximum 2000 samples and the samplerate is 1kHz. If pad is 'nextpow2' all trials are padded to the nearest power of two (in samples) of the longest trial.
channelcmb ([senders, receivers], list of array like, optional) – Two sequences senders and receivers encoding channel names or indices. such that connectivity measure gets computed only for those (senders x receivers) channel combinations. Only supported for spectral measures 'coh', 'csd', 'ppc', 'granger' and requires SpectralData as input data type.
tapsmofrq (float or None) – Only valid if method is 'coh', 'csd' or 'granger' and input data is a AnalogData. Enables multi-tapering and sets the amount of spectral smoothing with slepian tapers in Hz.
nTaper (int or None) – Only valid if method is 'coh' or 'granger' and tapsmofrq is set. Number of orthogonal tapers to use for multi-tapering. It is not recommended to set the number of tapers manually! Leave at None for the optimal number to be set automatically.
taper (str or None, optional) – Only valid if method is 'coh', 'csd' or 'granger' and input data is a AnalogData. Windowing function, one of availableTapers For multi-tapering with slepian tapers use tapsmofrq directly.
taper_opt (dict or None) – Only valid if method is 'coh', 'csd' or 'granger' and input data is a AnalogData. Dictionary with keys for additional taper parameters. For example kaiser() has the additional parameter ‘beta’. For multi-tapering set tapsmofrq directly.
jackknife (bool, optional) – Set to True to compute the variance via jackknife resampling, only available (and meaningful) for methods coh and granger
parallel (None or bool) – If None (recommended), processing is automatically performed in parallel (i.e., concurrently across trials/channel-groups), provided a dask parallel processing client is running and available. Parallel processing can be manually disabled by setting parallel to False. If parallel is True but no parallel processing client is running, computing will be performed sequentially.
select (dict or StructDict or str) – In-place selection of subset of input data for processing. Please refer to syncopy.selectdata() for further usage details.

Returns:

out – The analyis result with dims [‘time’, ‘freq’, ‘channel_i’, channel_j’]. The out may contain additional metadata, based on the method used to compute it:

For method=’granger’, the out.info property contains the keys listed and explained in metadata_keys.
if jackknife=True, out.jack_var and out.jack_bias contain the jackknife variance and bias

Return type:

~syncopy.CrossSpectralData

Examples

In the following adata is an instance of AnalogData

Calculate the coherence between all channels with 2Hz spectral smoothing, and plot the results for two combinations between 30Hz and 90Hz:

>>> coh = spy.connectivityanalysis(adata, method='coh', tapsmofrq=2)
>>> coh.singlepanelplot(channel_i=0, channel_j=1, frequency=[30,90])
>>> coh.singlepanelplot(channel_i=1, channel_j=2, frequency=[30,90])

Compute the cross-correlation between channel 8 and 12 and plot the results for the first 200ms:

>>> cfg = spy.StructDict()
>>> cfg.method = 'corr'
>>> cfg.select = {'channel': ['channel8', 'channel12']}
>>> corr = spy.connectivityanalysis(adata, cfg)
>>> corr.singlepanelplot(channel_i='channel8', channel_j='channel12', latency=[0, 0.2])

Estimate Granger causality only between channel pairs (0->3), (0->4), (2->3) and (2->4)

First compute a SpectralData with complex dtype and no frequency limitations (so no foi/foilim setting):

>>> spec = spy.freqanalysis(adata, output='complex')

Then the connectivity analysis:

>>> cfg = spy.StructDict()
>>> cfg.method = 'granger'
>>> cfg.channelcmb = [[0, 2], [3, 4]]  # [senders, receivers]
>>> granger = spy.connectivityanalysis(spec, cfg)

Plot the (2->4) results between 15Hz and 60Hz:

>>> granger.singlepanelplot(channel_i='channel3', channel_j='channel5', frequency=[15, 60])

Notes

This function can be either called providing its input arguments directly or via a cfg configuration ‘structure’. For instance, the following function calls are equivalent

>>> spy.connectivityanalysis(data, method=...)
>>> cfg = spy.StructDict()
>>> cfg.method = ...
>>> spy.connectivityanalysis(cfg, data)
>>> cfg.data = data
>>> spy.connectivityanalysis(cfg)

Please refer to Syncopy for FieldTrip Users for further details.

[Dhamala2008]

Dhamala, Mukeshwar, Govindan Rangarajan, and Mingzhou Ding. “Analyzing information flow in brain networks with nonparametric Granger causality.” Neuroimage 41.2 (2008): 354-362.

[Vinck2010]

Vinck, Martin, et al. “The pairwise phase consistency: a bias-free measure of rhythmic neuronal synchronization.” Neuroimage 51.1 (2010): 112-122.

connectivityanalysis

Contents

connectivityanalysis#