connectivityanalysis
connectivityanalysis#
- syncopy.connectivityanalysis(data, method='coh', keeptrials=False, output='abs', foi=None, foilim=None, pad='maxperlen', polyremoval=0, tapsmofrq=None, nTaper=None, taper='hann', taper_opt=None, 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 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 all channel combinations
output : one of (‘abs’, ‘pow’, ‘complex’, ‘angle’, ‘imag’ or ‘real’)
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 spectral density estimate
Computes the cross spectral estimates between all channel combinations
output : complex spectrum
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’
- “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
- “granger”Spectral Granger-Geweke causality
Computes linear causality estimates between all 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)!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'}`
.
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'
output (str) – Relevant for cross-spectral density 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 for cross-correlations (
method='corr'
). If True single-trial cross-correlations 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.tapsmofrq (float or None) – Only valid if
method
is'coh'
or'granger'
. 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'
or'granger'
. Windowing function, one ofavailableTapers
For multi-tapering with slepian tapers use tapsmofrq directly.taper_opt (dict or None) – Dictionary with keys for additional taper parameters. For example
kaiser()
has the additional parameter ‘beta’. For multi-tapering settapsmofrq
directly.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
.
- 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, foilim=[30,90]) >>> coh.singlepanelplot(channel_i=1, channel_j=2, foilim=[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', toilim=[0, 0.2])
Estimate Granger causality between the same channels (re-using the cfg from above):
>>> cfg.method = 'granger' >>> granger = spy.connectivityanalysis(adata, cfg)
Plot the results between 15Hz and 30Hz:
>>> granger.singlepanelplot(channel_i='channel8', channel_j='channel12', foilim=[15, 25])