mne_connectivity.decoding.CoherencyDecomposition

class mne_connectivity.decoding.CoherencyDecomposition(info, method, indices, mode='multitaper', fmin=None, fmax=None, mt_bandwidth=None, mt_adaptive=False, mt_low_bias=True, cwt_freqs=None, cwt_n_cycles=7, n_components=None, rank=None, n_jobs=1, verbose=None)

Decompose connectivity sources using multivariate coherency-based methods.

Parameters:

infomne.Info

Information about the data which will be decomposed and transformed, such as that coming from an mne.Epochs object. The number of channels must match the subsequent input data.

methodstr

The multivariate method to use for the decomposition. Can be:

• "cacoh" - Canonical Coherency (CaCoh) [1]

• "mic" - Maximised Imaginary part of Coherency (MIC) [2]

indicestuple of array

A tuple of two arrays, containing the indices of the seed and target channels in the input data, respectively. The indices of only a single connection (i.e. between one group of seeds and one group of targets) is supported.

modestr (default “multitaper”)

The cross-spectral density computation method. Can be "multitaper", "fourier", or "cwt_morlet".

fminint | float | None (default None)

The lowest frequency of interest in Hz. Must not be None and only used if mode in ["multitaper", "fourier"].

fmaxint | float | None (default None)

The highest frequency of interest in Hz. Must not be None and only used if mode in ["multitaper", "fourier"].

mt_bandwidthint | float | None (default None)

The bandwidth of the multitaper windowing function in Hz to use when computing the cross-spectral density. Only used if mode="multitaper".

mt_adaptivebool (default False)

Whether to use adaptive weights when combining the tapered spectra in the cross-spectral density. Only used if mode="multitaper".

mt_low_biasbool (default True)

Whether to use tapers with over 90 percent spectral concentration within the bandwidth when computing the cross-spectral density. Only used if mode="multitaper".

cwt_freqsarray of int or float | None (default None)

The frequencies of interest in Hz. Must not be None and only used if mode="cwt_morlet".

cwt_n_cyclesint | float | array of int or float (default 7)

The number of cycles to use when constructing the Morlet wavelets. Fixed number or one per frequency. Only used if mode=cwt_morlet.

n_componentsint | None (default None)

The number of connectivity components (sources) to extract from the data. If None, the number of components equal to the minimum rank of the seeds and targets is extracted (see the rank parameter). If an int, the number of components must be <= the minimum rank of the seeds and targets. E.g. if the seed channels had a rank of 5 and the target channels had a rank of 3, n_components must be <= 3.

ranktuple of int | None (default None)

A tuple of two ints, containing the degree of rank subspace projection to apply to the seed and target data, respectively, before filters are fit. If None, the rank of the seed and target data is used. If a tuple of ints, the entries must be <= the rank of the seed and target data. The minimum rank of the seeds and targets determines the maximum number of connectivity components (sources) which can be extracted from the data (see the n_components parameter). Specifying ranks below that of the data may reduce the degree of overfitting when computing the filters.

n_jobsint

The number of jobs to run in parallel (default 1). Requires the joblib package.

verbosebool, str, int, or None

If not None, override default verbose level (see mne.verbose() for more info). If used, it should be passed as a keyword-argument only.

Notes

The multivariate methods maximise connectivity between a set of seed and target signals in a frequency-resolved manner. The maximisation of connectivity involves fitting spatial filters to the cross-spectral density of the seed and target data, alongside which spatial patterns of the contributions to connectivity can be computed [3].

Once fit, the filters can be used to transform data into the underlying connectivity components. Connectivity can be computed on this transformed data using the bivariate coherency-based methods of the mne_connectivity.spectral_connectivity_epochs and mne_connectivity.spectral_connectivity_time functions. These bivariate methods are:

• "cohy" and "coh" for CaCoh [1]

• "imcoh" for MIC [2]

The approach taken here is to optimise the connectivity in a given frequency band. Frequency bin-wise optimisation is offered in the multivariate coherency-based methods of the mne_connectivity.spectral_connectivity_epochs and mne_connectivity.spectral_connectivity_time functions.

References

[1] (1,2)

Carmen Vidaurre, Guido Nolte, Ingmar E.J. de Vries, M. Gómez, Tjeerd W. Boonstra, K.-R. Müller, Arno Villringer, and Vadim V. Nikulin. Canonical maximization of coherence: a novel tool for investigation of neuronal interactions between two datasets. NeuroImage, 201:116009, 2019. doi:10.1016/j.neuroimage.2019.116009.

[2] (1,2)

Arne Ewald, Laura Marzetti, Filippo Zappasodi, Frank C. Meinecke, and Guido Nolte. Estimating true brain connectivity from EEG/MEG data invariant to linear and static transformations in sensor space. NeuroImage, 60(1):476–488, 2012. doi:10.1016/j.neuroimage.2011.11.084.

[3]

Stefan Haufe, Frank Meinecke, Kai Görgen, Sven Dähne, John-Dylan Haynes, Benjamin Blankertz, and Felix Bießmann. On the interpretation of weight vectors of linear models in multivariate neuroimaging. NeuroImage, 87:96–110, 2014. doi:10.1016/j.neuroimage.2013.10.067.

Attributes:

filters_tuple of array, shape=(n_signals, n_components)

A tuple of two arrays containing the spatial filters for transforming the seed and target data, respectively.

patterns_tuple of array, shape=(n_components, n_signals)

A tuple of two arrays containing the spatial patterns corresponding to the spatial filters for the seed and target data, respectively.

Methods

fit(X[, y])	Compute connectivity decomposition filters for epoched data.
fit_transform(X[, y])	Fit filters to data, then transform and return it.
get_params([deep])	Get parameters for this estimator.
get_transformed_indices()	Get indices for the transformed data.
set_params(**params)	Set the parameters of this estimator.
transform(X)	Decompose data into connectivity sources using the fitted filters.

fit(X, y=None)

Compute connectivity decomposition filters for epoched data.

Parameters:

Xarray, shape=(n_epochs, n_signals, n_times)

The input data which the connectivity decomposition filters should be fit to.

yNone

Ignored; exists for compatibility with scikit-learn pipelines.

Returns:

selfinstance of CoherencyDecomposition

The modified class instance.

fit_transform(X, y=None, **fit_params)

Fit filters to data, then transform and return it.

Parameters:

Xarray, shape=(n_epochs, n_signals, n_times)

The input data which the connectivity decomposition filters should be fit to and subsequently transformed.

yNone

Ignored; exists for compatibility with scikit-learn pipelines.

**fit_paramsdict

Additional fitting parameters passed to the fit method. Not used for this class.

Returns:

X_transformedarray, shape=(n_epochs, n_components*2, n_times)

The transformed data. The first n_components channels are the transformed seeds, and the last n_components channels are the transformed targets.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deepbool, optional

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict

Parameter names mapped to their values.

get_transformed_indices()

Get indices for the transformed data.

Returns:

indices_transformedtuple of array

Indices of seeds and targets in the transformed data with the form (seeds, targets) to be used when passing the data to spectral_connectivity_epochs and spectral_connectivity_time. Entries of the indices are arranged such that connectivity would be computed between the first seed component and first target component, second seed component and second target component, etc…

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict

Parameters.

Returns:

instinstance

The object.

transform(X)

Decompose data into connectivity sources using the fitted filters.

Parameters:

Xarray, shape=((n_epochs, ) n_signals, n_times)

The data to be transformed by the connectivity decomposition filters.

Returns:

X_transformedarray, shape=((n_epochs, ) n_components*2, n_times)

The transformed data. The first n_components channels are the transformed seeds, and the last n_components channels are the transformed targets.

Examples using mne_connectivity.decoding.CoherencyDecomposition

Multivariate decomposition for efficient connectivity analysis

Multivariate decomposition for efficient connectivity analysis