frites.conn.conn_spec#

frites.conn.conn_spec(data, freqs=None, metric='coh', roi=None, times=None, sfreq=None, foi=None, sm_times=0.5, sm_freqs=1, sm_kernel='hanning', mode='morlet', n_cycles=7.0, mt_bandwidth=None, decim=1, kw_cwt={}, kw_mt={}, block_size=None, n_jobs=-1, verbose=None, dtype=<class 'numpy.float32'>, mean_trials=False, **kw_links)[source]#

Wavelet-based single-trial time-resolved spectral connectivity.

Parameters:

datanumpy:array_like

Electrophysiological data. Several input types are supported :

Standard NumPy arrays of shape (n_epochs, n_roi, n_times)

mne.Epochs

xarray.DataArray of shape (n_epochs, n_roi, n_times)

metricstr | “coh”

Which connectivity metric. Use either :

‘coh’ : Coherence

‘plv’ : Phase-Locking Value (PLV)

‘sxy’ : Cross-spectrum (complex). The output dtype is promoted to a complex type if needed. The phase convention is arg(sxy) = phase(source) - phase(target), sources and targets being the first and second region of each pair.

By default, the coherence is used.

Note

These are single-trial estimates: the temporal (sm_times) and frequency (sm_freqs) smoothing, and the tapers in ‘multitaper’ mode, are the only averaging involved. Without any of them the single-trial coherence and PLV are identically equal to one.

freqsnumpy:array_like

Array of central frequencies of shape (n_freqs,).

roinumpy:array_like | None

ROI names of a single subject. If the input is an xarray, the name of the ROI dimension can be provided

timesnumpy:array_like | None

Time vector array of shape (n_times,). If the input is an xarray, the name of the time dimension can be provided

sfreqfloat | None

Sampling frequency

foinumpy:array_like | None

Extract frequencies of interest. This parameters should be an array of shapes (n_foi, 2) defining where each band of interest start and finish.

sm_timesfloat | .5

Temporal smoothing in seconds. By default, a 500ms smoothing is used. The kernel length in samples is rounded (after decimation) and is at least one point (no smoothing).

sm_freqsint | 1

Number of points for frequency smoothing. By default, 1 is used which is equivalent to no smoothing

sm_kernel{‘square’, ‘hanning’}

Kernel type to use. Choose either ‘square’ or ‘hanning’. For the ‘hanning’ kernel, sm_times and sm_freqs are the number of non-zero taps.

mode{‘morlet’, ‘multitaper’}

Spectrum estimation mode can be either: ‘multitaper’ or ‘morlet’. In ‘multitaper’ mode the cross- and auto-spectra are averaged over the DPSS tapers (MNE uses floor(mt_bandwidth - 1) tapers).

n_cyclesnumpy:array_like | 7.

Number of cycles to use for each frequency. If a float or an integer is used, the same number of cycles is going to be used for all frequencies

mt_bandwidthnumpy:array_like | None

The bandwidth of the multitaper windowing function in Hz. Only used in ‘multitaper’ mode.

decimint | 1

To reduce memory usage, decimation factor after time-frequency decomposition. default 1 If int, returns tfr[…, ::decim]. If slice, returns tfr[…, decim].

kw_cwtdict | {}

Additional arguments sent to the mne-function

kw_mtdict | {}

Additional arguments sent to the mne-function

block_sizeint | None

Number of blocks of trials to process at once. This parameter can be use in order to decrease memory load. If None, all trials are used. If for example block_size=2, the number of trials are subdivided into two groups and each group is process one after the other.

n_jobsint | 1

Number of jobs to use for parallel computing (use -1 to use all jobs). The parallel loop is set at the pair level.

dtypenumpy dtype | np.float32

Output dtype. Promoted to np.complex64 for the complex ‘sxy’ metric when a real dtype is given.

mean_trialsbool | False

Average the connectivity across trials (output without the trials dimension).

kw_linksdict | {}

Additional arguments for selecting links to compute are passed to the function frites.conn.conn_links()

Returns:

connxarray.DataArray: DataArray of shape (n_trials, n_pairs, n_freqs, n_times)