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 directlyAnalogData
objectsIn 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 forfreqanalysis()
withmethod='mtmfft'
:(‘foi’, ‘foilim’, ‘pad’, ‘tapsmofrq’, ‘nTaper’, ‘taper’, ‘taper_opt’, ‘polyremoval’)
If the input is already in the spectral domain, so
data
is of classSpectralData
, 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
orAnalogData
objectmethod (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
isNone
orfoi = "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. Ifpad
is a number all trials are padded so thatpad
indicates the absolute length of all trials after padding (in seconds). For instancepad = 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. Ifpad
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
andreceivers
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 requiresSpectralData
as input data type.tapsmofrq (float or None) – Only valid if
method
is'coh'
,'csd'
or'granger'
and input data is aAnalogData
. 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'
andtapsmofrq
is set. Number of orthogonal tapers to use for multi-tapering. It is not recommended to set the number of tapers manually! Leave atNone
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 aAnalogData
. Windowing function, one ofavailableTapers
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 aAnalogData
. Dictionary with keys for additional taper parameters. For examplekaiser()
has the additional parameter ‘beta’. For multi-tapering settapsmofrq
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 tosyncopy.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.