mne.time_frequency.CrossSpectralDensity

class mne.time_frequency.CrossSpectralDensity(data, ch_names, frequencies, n_fft, tmin=None, tmax=None, projs=None)

Cross-spectral density.

Given a list of time series, the CSD matrix denotes for each pair of time series, the cross-spectral density. This matrix is symmetric and internally stored as a vector.

This object can store multiple CSD matrices: one for each frequency. Use .get_data(freq) to obtain an CSD matrix as an ndarray.

Parameters

datandarray, shape ((n_channels**2 + n_channels) // 2, n_frequencies)

For each frequency, the cross-spectral density matrix in vector format.

ch_nameslist of str

List of string names for each channel.

frequenciesfloat | list of float | list of list of float

Frequency or frequencies for which the CSD matrix was calculated. When averaging across frequencies (see the CrossSpectralDensity.mean() function), this will be a list of lists that contains for each frequency bin, the frequencies that were averaged. Frequencies should always be sorted.

n_fftint

The number of FFT points or samples that have been used in the computation of this CSD.

tminfloat | None

Start of the time window for which CSD was calculated in seconds. Can be None (the default) to indicate no timing information is available.

tmaxfloat | None

End of the time window for which CSD was calculated in seconds. Can be None (the default) to indicate no timing information is available.

projslist of Projection | None

List of projectors to apply to timeseries data when using this CSD object to compute a DICS beamformer. Defaults to None, which means no projectors will be applied.

See also

csd_fourier

csd_multitaper

csd_morlet

csd_array_fourier

csd_array_multitaper

csd_array_morlet

Attributes

n_channels

Number of time series defined in this CSD object.

Methods

__getitem__(sel)	Subselect frequencies.
__hash__(/)	Return hash(self).
__len__()	Return number of frequencies.
copy()	Return copy of the CrossSpectralDensity object.
get_data([frequency, index, as_cov])	Get the CSD matrix for a given frequency as NumPy array.
mean([fmin, fmax])	Calculate the mean CSD in the given frequency range(s).
pick_channels(ch_names[, ordered])	Pick channels from this cross-spectral density matrix.
pick_frequency([freq, index])	Get a CrossSpectralDensity object with only the given frequency.
plot([info, mode, colorbar, cmap, n_cols, show])	Plot CSD matrices.
save(fname)	Save the CSD to an HDF5 file.
sum([fmin, fmax])	Calculate the sum CSD in the given frequency range(s).

__getitem__(sel)

Subselect frequencies.

Parameters

selndarray

Array of frequency indices to subselect.

Returns

csdinstance of CrossSpectralDensity

A new CSD instance with the subset of frequencies.

__len__()

Return number of frequencies.

Returns

n_freqsint

The number of frequencies.

copy()

Return copy of the CrossSpectralDensity object.

Returns

copyinstance of CrossSpectralDensity

A copy of the object.

get_data(frequency=None, index=None, as_cov=False)

Get the CSD matrix for a given frequency as NumPy array.

If there is only one matrix defined in the CSD object, calling this method without any parameters will return it. If multiple matrices are defined, use either the frequency or index parameter to select one.

Parameters

frequencyfloat | None

Return the CSD matrix for a specific frequency. Only available when no averaging across frequencies has been done.

indexint | None

Return the CSD matrix for the frequency or frequency-bin with the given index.

as_covbool

Whether to return the data as a numpy array (False, the default), or pack it in a mne.Covariance object (True).

New in version 0.20.

Returns

csdndarray, shape (n_channels, n_channels) | instance of Covariance

The CSD matrix corresponding to the requested frequency.

See also

pick_frequency

mean(fmin=None, fmax=None)

Calculate the mean CSD in the given frequency range(s).

Parameters

fminfloat | list of float | None

Lower bound of the frequency range in Hertz. Defaults to the lowest frequency available. When a list of frequencies is given, these are used as the lower bounds (inclusive) of frequency bins and the mean is taken for each bin.

fmaxfloat | list of float | None

Upper bound of the frequency range in Hertz. Defaults to the highest frequency available. When a list of frequencies is given, these are used as the upper bounds (inclusive) of frequency bins and the mean is taken for each bin.

Returns

csdinstance of CrossSpectralDensity

The CSD matrix, averaged across the given frequency range(s).

Examples using mean:

Compute a cross-spectral density (CSD) matrix

Compute source power using DICS beamformer

property n_channels

Number of time series defined in this CSD object.

pick_channels(ch_names, ordered=False)

Pick channels from this cross-spectral density matrix.

Parameters

ch_nameslist of str

List of channels to keep. All other channels are dropped.

orderedbool

If True (default False), ensure that the order of the channels matches the order of ch_names.

Returns

csdinstance of CrossSpectralDensity.

The modified cross-spectral density object.

Notes

Operates in-place.

New in version 0.20.0.

pick_frequency(freq=None, index=None)

Get a CrossSpectralDensity object with only the given frequency.

Parameters

freqfloat | None

Return the CSD matrix for a specific frequency. Only available when no averaging across frequencies has been done.

indexint | None

Return the CSD matrix for the frequency or frequency-bin with the given index.

Returns

csdinstance of CrossSpectralDensity

A CSD object containing a single CSD matrix that corresponds to the requested frequency or frequency-bin.

See also

get_data

plot(info=None, mode='csd', colorbar=True, cmap='viridis', n_cols=None, show=True)

Plot CSD matrices.

A sub-plot is created for each frequency. If an info object is passed to the function, different channel types are plotted in different figures.

Parameters

infomne.Info | None

The mne.Info object with information about the sensors and methods of measurement. Used to split the figure by channel-type, if provided. By default, the CSD matrix is plotted as a whole.

mode‘csd’ | ‘coh’

Whether to plot the cross-spectral density (‘csd’, the default), or the coherence (‘coh’) between the channels.

colorbarbool

Whether to show a colorbar. Defaults to True.

cmapstr | None

The matplotlib colormap to use. Defaults to None, which means the colormap will default to matplotlib’s default.

n_colsint | None

CSD matrices are plotted in a grid. This parameter controls how many matrix to plot side by side before starting a new row. By default, a number will be chosen to make the grid as square as possible.

showbool

Whether to show the figure. Defaults to True.

Returns

figlist of Figure

The figures created by this function.

save(fname)

Save the CSD to an HDF5 file.

Parameters

fnamestr

The name of the file to save the CSD to. The extension ‘.h5’ will be appended if the given filename doesn’t have it already.

See also

read_csd

For reading CSD objects from a file.

sum(fmin=None, fmax=None)

Calculate the sum CSD in the given frequency range(s).

If the exact given frequencies are not available, the nearest frequencies will be chosen.

Parameters

fminfloat | list of float | None

Lower bound of the frequency range in Hertz. Defaults to the lowest frequency available. When a list of frequencies is given, these are used as the lower bounds (inclusive) of frequency bins and the sum is taken for each bin.

fmaxfloat | list of float | None

Upper bound of the frequency range in Hertz. Defaults to the highest frequency available. When a list of frequencies is given, these are used as the upper bounds (inclusive) of frequency bins and the sum is taken for each bin.

Returns

csdinstance of CrossSpectralDensity

The CSD matrix, summed across the given frequency range(s).

Examples using mne.time_frequency.CrossSpectralDensity

DICS for power mapping

Compute a cross-spectral density (CSD) matrix

Compute source power using DICS beamformer

previous

mne.time_frequency.EpochsTFR

next

mne.time_frequency.csd_fourier