Note

Click here to download the full example code

Compute a cross-spectral density (CSD) matrix

A cross-spectral density (CSD) matrix is similar to a covariance matrix, but in the time-frequency domain. It is the first step towards computing sensor-to-sensor coherence or a DICS beamformer.

This script demonstrates the three methods that MNE-Python provides to compute the CSD:

  1. Using short-term Fourier transform: mne.time_frequency.csd_fourier()

  2. Using a multitaper approach: mne.time_frequency.csd_multitaper()

  3. Using Morlet wavelets: mne.time_frequency.csd_morlet()

# Author: Marijn van Vliet <w.m.vanvliet@gmail.com>
# License: BSD (3-clause)
from matplotlib import pyplot as plt

import mne
from mne.datasets import sample
from mne.time_frequency import csd_fourier, csd_multitaper, csd_morlet

print(__doc__)

In the following example, the computation of the CSD matrices can be performed using multiple cores. Set n_jobs to a value >1 to select the number of cores to use.

n_jobs = 1

Loading the sample dataset.

data_path = sample.data_path()
fname_raw = data_path + '/MEG/sample/sample_audvis_raw.fif'
fname_event = data_path + '/MEG/sample/sample_audvis_raw-eve.fif'
raw = mne.io.read_raw_fif(fname_raw)
events = mne.read_events(fname_event)

Out:

Opening raw data file /home/circleci/mne_data/MNE-sample-data/MEG/sample/sample_audvis_raw.fif...
    Read a total of 3 projection items:
        PCA-v1 (1 x 102)  idle
        PCA-v2 (1 x 102)  idle
        PCA-v3 (1 x 102)  idle
    Range : 25800 ... 192599 =     42.956 ...   320.670 secs
Ready.

By default, CSD matrices are computed using all MEG/EEG channels. When interpreting a CSD matrix with mixed sensor types, be aware that the measurement units, and thus the scalings, differ across sensors. In this example, for speed and clarity, we select a single channel type: gradiometers.

picks = mne.pick_types(raw.info, meg='grad')

# Make some epochs, based on events with trigger code 1
epochs = mne.Epochs(raw, events, event_id=1, tmin=-0.2, tmax=1,
                    picks=picks, baseline=(None, 0),
                    reject=dict(grad=4000e-13), preload=True)

Out:

Not setting metadata
Not setting metadata
72 matching events found
Setting baseline interval to [-0.19979521315838786, 0.0] sec
Applying baseline correction (mode: mean)
3 projection items activated
Loading data for 72 events and 722 original time points ...
0 bad epochs dropped

Computing CSD matrices using short-term Fourier transform and (adaptive) multitapers is straightforward:

csd_fft = csd_fourier(epochs, fmin=15, fmax=20, n_jobs=n_jobs)
csd_mt = csd_multitaper(epochs, fmin=15, fmax=20, adaptive=True, n_jobs=n_jobs)

Out:

Removing projector <Projection | PCA-v1, active : True, n_channels : 102>
Removing projector <Projection | PCA-v2, active : True, n_channels : 102>
Removing projector <Projection | PCA-v3, active : True, n_channels : 102>
Computing cross-spectral density from epochs...

  0%|          | CSD epoch blocks : 0/72 [00:00<?,       ?it/s]
  1%|1         | CSD epoch blocks : 1/72 [00:00<00:02,   35.49it/s]
  3%|2         | CSD epoch blocks : 2/72 [00:00<00:01,   38.80it/s]
  4%|4         | CSD epoch blocks : 3/72 [00:00<00:01,   44.37it/s]
  7%|6         | CSD epoch blocks : 5/72 [00:00<00:01,   51.81it/s]
 10%|9         | CSD epoch blocks : 7/72 [00:00<00:01,   56.30it/s]
 12%|#2        | CSD epoch blocks : 9/72 [00:00<00:01,   58.74it/s]
 15%|#5        | CSD epoch blocks : 11/72 [00:00<00:01,   60.12it/s]
 18%|#8        | CSD epoch blocks : 13/72 [00:00<00:00,   61.69it/s]
 21%|##        | CSD epoch blocks : 15/72 [00:00<00:00,   62.84it/s]
 24%|##3       | CSD epoch blocks : 17/72 [00:00<00:00,   63.23it/s]
 26%|##6       | CSD epoch blocks : 19/72 [00:00<00:00,   63.84it/s]
 29%|##9       | CSD epoch blocks : 21/72 [00:00<00:00,   64.52it/s]
 32%|###1      | CSD epoch blocks : 23/72 [00:00<00:00,   64.74it/s]
 35%|###4      | CSD epoch blocks : 25/72 [00:00<00:00,   64.91it/s]
 38%|###7      | CSD epoch blocks : 27/72 [00:00<00:00,   65.34it/s]
 40%|####      | CSD epoch blocks : 29/72 [00:00<00:00,   65.60it/s]
 43%|####3     | CSD epoch blocks : 31/72 [00:00<00:00,   65.63it/s]
 46%|####5     | CSD epoch blocks : 33/72 [00:00<00:00,   65.77it/s]
 49%|####8     | CSD epoch blocks : 35/72 [00:00<00:00,   66.07it/s]
 51%|#####1    | CSD epoch blocks : 37/72 [00:00<00:00,   66.02it/s]
 54%|#####4    | CSD epoch blocks : 39/72 [00:00<00:00,   66.18it/s]
 57%|#####6    | CSD epoch blocks : 41/72 [00:00<00:00,   66.46it/s]
 60%|#####9    | CSD epoch blocks : 43/72 [00:00<00:00,   66.55it/s]
 62%|######2   | CSD epoch blocks : 45/72 [00:00<00:00,   66.56it/s]
 65%|######5   | CSD epoch blocks : 47/72 [00:00<00:00,   66.77it/s]
 68%|######8   | CSD epoch blocks : 49/72 [00:00<00:00,   66.96it/s]
 71%|#######   | CSD epoch blocks : 51/72 [00:00<00:00,   66.66it/s]
 74%|#######3  | CSD epoch blocks : 53/72 [00:00<00:00,   66.65it/s]
 76%|#######6  | CSD epoch blocks : 55/72 [00:00<00:00,   66.42it/s]
 78%|#######7  | CSD epoch blocks : 56/72 [00:00<00:00,   66.12it/s]
 81%|########  | CSD epoch blocks : 58/72 [00:00<00:00,   66.15it/s]
 83%|########3 | CSD epoch blocks : 60/72 [00:00<00:00,   66.26it/s]
 86%|########6 | CSD epoch blocks : 62/72 [00:00<00:00,   66.16it/s]
 89%|########8 | CSD epoch blocks : 64/72 [00:00<00:00,   66.03it/s]
 92%|#########1| CSD epoch blocks : 66/72 [00:01<00:00,   66.12it/s]
 94%|#########4| CSD epoch blocks : 68/72 [00:01<00:00,   66.37it/s]
 97%|#########7| CSD epoch blocks : 70/72 [00:01<00:00,   66.27it/s]
100%|##########| CSD epoch blocks : 72/72 [00:01<00:00,   66.23it/s]
100%|##########| CSD epoch blocks : 72/72 [00:01<00:00,   65.66it/s]
[done]
Removing projector <Projection | PCA-v1, active : True, n_channels : 102>
Removing projector <Projection | PCA-v2, active : True, n_channels : 102>
Removing projector <Projection | PCA-v3, active : True, n_channels : 102>
    Using multitaper spectrum estimation with 7 DPSS windows
Computing cross-spectral density from epochs...

  0%|          | CSD epoch blocks : 0/72 [00:00<?,       ?it/s]
  1%|1         | CSD epoch blocks : 1/72 [00:00<00:13,    5.34it/s]
  3%|2         | CSD epoch blocks : 2/72 [00:00<00:10,    6.40it/s]
  4%|4         | CSD epoch blocks : 3/72 [00:00<00:09,    6.97it/s]
  6%|5         | CSD epoch blocks : 4/72 [00:00<00:09,    6.88it/s]
  7%|6         | CSD epoch blocks : 5/72 [00:00<00:09,    7.08it/s]
  8%|8         | CSD epoch blocks : 6/72 [00:00<00:09,    7.26it/s]
 10%|9         | CSD epoch blocks : 7/72 [00:00<00:08,    7.35it/s]
 11%|#1        | CSD epoch blocks : 8/72 [00:01<00:08,    7.22it/s]
 12%|#2        | CSD epoch blocks : 9/72 [00:01<00:08,    7.34it/s]
 14%|#3        | CSD epoch blocks : 10/72 [00:01<00:08,    7.42it/s]
 15%|#5        | CSD epoch blocks : 11/72 [00:01<00:08,    7.51it/s]
 17%|#6        | CSD epoch blocks : 12/72 [00:01<00:07,    7.58it/s]
 18%|#8        | CSD epoch blocks : 13/72 [00:01<00:07,    7.64it/s]
 19%|#9        | CSD epoch blocks : 14/72 [00:01<00:07,    7.68it/s]
 21%|##        | CSD epoch blocks : 15/72 [00:01<00:07,    7.73it/s]
 22%|##2       | CSD epoch blocks : 16/72 [00:02<00:07,    7.72it/s]
 24%|##3       | CSD epoch blocks : 17/72 [00:02<00:07,    7.76it/s]
 25%|##5       | CSD epoch blocks : 18/72 [00:02<00:06,    7.77it/s]
 26%|##6       | CSD epoch blocks : 19/72 [00:02<00:06,    7.80it/s]
 28%|##7       | CSD epoch blocks : 20/72 [00:02<00:06,    7.83it/s]
 29%|##9       | CSD epoch blocks : 21/72 [00:02<00:06,    7.85it/s]
 31%|###       | CSD epoch blocks : 22/72 [00:02<00:06,    7.88it/s]
 32%|###1      | CSD epoch blocks : 23/72 [00:02<00:06,    7.90it/s]
 33%|###3      | CSD epoch blocks : 24/72 [00:03<00:06,    7.92it/s]
 35%|###4      | CSD epoch blocks : 25/72 [00:03<00:05,    7.92it/s]
 36%|###6      | CSD epoch blocks : 26/72 [00:03<00:05,    7.94it/s]
 38%|###7      | CSD epoch blocks : 27/72 [00:03<00:05,    7.95it/s]
 39%|###8      | CSD epoch blocks : 28/72 [00:03<00:05,    7.92it/s]
 40%|####      | CSD epoch blocks : 29/72 [00:03<00:05,    7.94it/s]
 42%|####1     | CSD epoch blocks : 30/72 [00:03<00:05,    7.92it/s]
 43%|####3     | CSD epoch blocks : 31/72 [00:03<00:05,    7.93it/s]
 44%|####4     | CSD epoch blocks : 32/72 [00:04<00:05,    7.94it/s]
 46%|####5     | CSD epoch blocks : 33/72 [00:04<00:04,    7.94it/s]
 47%|####7     | CSD epoch blocks : 34/72 [00:04<00:04,    7.96it/s]
 49%|####8     | CSD epoch blocks : 35/72 [00:04<00:04,    7.96it/s]
 50%|#####     | CSD epoch blocks : 36/72 [00:04<00:04,    7.97it/s]
 51%|#####1    | CSD epoch blocks : 37/72 [00:04<00:04,    7.98it/s]
 53%|#####2    | CSD epoch blocks : 38/72 [00:04<00:04,    7.99it/s]
 54%|#####4    | CSD epoch blocks : 39/72 [00:04<00:04,    8.00it/s]
 56%|#####5    | CSD epoch blocks : 40/72 [00:05<00:03,    8.01it/s]
 57%|#####6    | CSD epoch blocks : 41/72 [00:05<00:03,    8.01it/s]
 58%|#####8    | CSD epoch blocks : 42/72 [00:05<00:03,    8.02it/s]
 60%|#####9    | CSD epoch blocks : 43/72 [00:05<00:03,    8.03it/s]
 61%|######1   | CSD epoch blocks : 44/72 [00:05<00:03,    8.04it/s]
 62%|######2   | CSD epoch blocks : 45/72 [00:05<00:03,    8.03it/s]
 64%|######3   | CSD epoch blocks : 46/72 [00:05<00:03,    8.04it/s]
 65%|######5   | CSD epoch blocks : 47/72 [00:05<00:03,    8.03it/s]
 67%|######6   | CSD epoch blocks : 48/72 [00:06<00:02,    8.04it/s]
 68%|######8   | CSD epoch blocks : 49/72 [00:06<00:02,    8.05it/s]
 69%|######9   | CSD epoch blocks : 50/72 [00:06<00:02,    8.05it/s]
 71%|#######   | CSD epoch blocks : 51/72 [00:06<00:02,    8.05it/s]
 72%|#######2  | CSD epoch blocks : 52/72 [00:06<00:02,    8.05it/s]
 74%|#######3  | CSD epoch blocks : 53/72 [00:06<00:02,    8.01it/s]
 75%|#######5  | CSD epoch blocks : 54/72 [00:06<00:02,    7.95it/s]
 76%|#######6  | CSD epoch blocks : 55/72 [00:06<00:02,    7.92it/s]
 78%|#######7  | CSD epoch blocks : 56/72 [00:07<00:02,    7.93it/s]
 79%|#######9  | CSD epoch blocks : 57/72 [00:07<00:01,    7.95it/s]
 81%|########  | CSD epoch blocks : 58/72 [00:07<00:01,    7.95it/s]
 82%|########1 | CSD epoch blocks : 59/72 [00:07<00:01,    7.91it/s]
 83%|########3 | CSD epoch blocks : 60/72 [00:07<00:01,    7.89it/s]
 85%|########4 | CSD epoch blocks : 61/72 [00:07<00:01,    7.90it/s]
 86%|########6 | CSD epoch blocks : 62/72 [00:07<00:01,    7.91it/s]
 88%|########7 | CSD epoch blocks : 63/72 [00:07<00:01,    7.93it/s]
 89%|########8 | CSD epoch blocks : 64/72 [00:08<00:01,    7.85it/s]
 90%|######### | CSD epoch blocks : 65/72 [00:08<00:00,    7.87it/s]
 92%|#########1| CSD epoch blocks : 66/72 [00:08<00:00,    7.89it/s]
 93%|#########3| CSD epoch blocks : 67/72 [00:08<00:00,    7.91it/s]
 94%|#########4| CSD epoch blocks : 68/72 [00:08<00:00,    7.93it/s]
 96%|#########5| CSD epoch blocks : 69/72 [00:08<00:00,    7.95it/s]
 97%|#########7| CSD epoch blocks : 70/72 [00:08<00:00,    7.97it/s]
 99%|#########8| CSD epoch blocks : 71/72 [00:08<00:00,    7.99it/s]
100%|##########| CSD epoch blocks : 72/72 [00:09<00:00,    8.01it/s]
100%|##########| CSD epoch blocks : 72/72 [00:09<00:00,    7.92it/s]
[done]

When computing the CSD with Morlet wavelets, you specify the exact frequencies at which to compute it. For each frequency, a corresponding wavelet will be constructed and convolved with the signal, resulting in a time-frequency decomposition.

The CSD is constructed by computing the correlation between the time-frequency representations between all sensor-to-sensor pairs. The time-frequency decomposition originally has the same sampling rate as the signal, in our case ~600Hz. This means the decomposition is over-specified in time and we may not need to use all samples during our CSD computation, just enough to get a reliable correlation statistic. By specifying decim=10, we use every 10th sample, which will greatly speed up the computation and will have a minimal effect on the CSD.

frequencies = [16, 17, 18, 19, 20]
csd_wav = csd_morlet(epochs, frequencies, decim=10, n_jobs=n_jobs)

Out:

Removing projector <Projection | PCA-v1, active : True, n_channels : 102>
Removing projector <Projection | PCA-v2, active : True, n_channels : 102>
Removing projector <Projection | PCA-v3, active : True, n_channels : 102>
Computing cross-spectral density from epochs...

  0%|          | CSD epoch blocks : 0/72 [00:00<?,       ?it/s]
  1%|1         | CSD epoch blocks : 1/72 [00:00<00:05,   13.04it/s]
  3%|2         | CSD epoch blocks : 2/72 [00:00<00:04,   14.09it/s]
  4%|4         | CSD epoch blocks : 3/72 [00:00<00:04,   14.58it/s]
  6%|5         | CSD epoch blocks : 4/72 [00:00<00:04,   14.84it/s]
  7%|6         | CSD epoch blocks : 5/72 [00:00<00:04,   14.94it/s]
  8%|8         | CSD epoch blocks : 6/72 [00:00<00:04,   15.09it/s]
 10%|9         | CSD epoch blocks : 7/72 [00:00<00:04,   15.14it/s]
 11%|#1        | CSD epoch blocks : 8/72 [00:00<00:04,   15.18it/s]
 12%|#2        | CSD epoch blocks : 9/72 [00:00<00:04,   15.23it/s]
 14%|#3        | CSD epoch blocks : 10/72 [00:00<00:04,   15.23it/s]
 15%|#5        | CSD epoch blocks : 11/72 [00:00<00:04,   15.16it/s]
 17%|#6        | CSD epoch blocks : 12/72 [00:00<00:03,   15.20it/s]
 18%|#8        | CSD epoch blocks : 13/72 [00:00<00:03,   15.20it/s]
 19%|#9        | CSD epoch blocks : 14/72 [00:00<00:03,   15.22it/s]
 21%|##        | CSD epoch blocks : 15/72 [00:00<00:03,   15.26it/s]
 22%|##2       | CSD epoch blocks : 16/72 [00:01<00:03,   15.26it/s]
 24%|##3       | CSD epoch blocks : 17/72 [00:01<00:03,   15.27it/s]
 25%|##5       | CSD epoch blocks : 18/72 [00:01<00:03,   15.30it/s]
 26%|##6       | CSD epoch blocks : 19/72 [00:01<00:03,   15.22it/s]
 28%|##7       | CSD epoch blocks : 20/72 [00:01<00:03,   15.25it/s]
 29%|##9       | CSD epoch blocks : 21/72 [00:01<00:03,   15.27it/s]
 31%|###       | CSD epoch blocks : 22/72 [00:01<00:03,   15.27it/s]
 32%|###1      | CSD epoch blocks : 23/72 [00:01<00:03,   15.30it/s]
 33%|###3      | CSD epoch blocks : 24/72 [00:01<00:03,   15.32it/s]
 35%|###4      | CSD epoch blocks : 25/72 [00:01<00:03,   15.30it/s]
 36%|###6      | CSD epoch blocks : 26/72 [00:01<00:03,   15.31it/s]
 38%|###7      | CSD epoch blocks : 27/72 [00:01<00:02,   15.31it/s]
 39%|###8      | CSD epoch blocks : 28/72 [00:01<00:02,   15.31it/s]
 40%|####      | CSD epoch blocks : 29/72 [00:01<00:02,   15.31it/s]
 42%|####1     | CSD epoch blocks : 30/72 [00:01<00:02,   15.29it/s]
 43%|####3     | CSD epoch blocks : 31/72 [00:02<00:02,   15.29it/s]
 44%|####4     | CSD epoch blocks : 32/72 [00:02<00:02,   15.30it/s]
 46%|####5     | CSD epoch blocks : 33/72 [00:02<00:02,   15.32it/s]
 47%|####7     | CSD epoch blocks : 34/72 [00:02<00:02,   15.33it/s]
 49%|####8     | CSD epoch blocks : 35/72 [00:02<00:02,   15.36it/s]
 50%|#####     | CSD epoch blocks : 36/72 [00:02<00:02,   15.36it/s]
 51%|#####1    | CSD epoch blocks : 37/72 [00:02<00:02,   15.18it/s]
 53%|#####2    | CSD epoch blocks : 38/72 [00:02<00:02,   15.21it/s]
 54%|#####4    | CSD epoch blocks : 39/72 [00:02<00:02,   15.20it/s]
 56%|#####5    | CSD epoch blocks : 40/72 [00:02<00:02,   15.17it/s]
 57%|#####6    | CSD epoch blocks : 41/72 [00:02<00:02,   15.00it/s]
 58%|#####8    | CSD epoch blocks : 42/72 [00:02<00:02,   14.97it/s]
 60%|#####9    | CSD epoch blocks : 43/72 [00:02<00:01,   14.94it/s]
 61%|######1   | CSD epoch blocks : 44/72 [00:02<00:01,   14.97it/s]
 62%|######2   | CSD epoch blocks : 45/72 [00:02<00:01,   15.01it/s]
 64%|######3   | CSD epoch blocks : 46/72 [00:03<00:01,   15.03it/s]
 65%|######5   | CSD epoch blocks : 47/72 [00:03<00:01,   15.05it/s]
 67%|######6   | CSD epoch blocks : 48/72 [00:03<00:01,   15.07it/s]
 68%|######8   | CSD epoch blocks : 49/72 [00:03<00:01,   15.09it/s]
 69%|######9   | CSD epoch blocks : 50/72 [00:03<00:01,   15.12it/s]
 71%|#######   | CSD epoch blocks : 51/72 [00:03<00:01,   15.14it/s]
 72%|#######2  | CSD epoch blocks : 52/72 [00:03<00:01,   15.14it/s]
 74%|#######3  | CSD epoch blocks : 53/72 [00:03<00:01,   15.16it/s]
 75%|#######5  | CSD epoch blocks : 54/72 [00:03<00:01,   15.16it/s]
 76%|#######6  | CSD epoch blocks : 55/72 [00:03<00:01,   15.16it/s]
 78%|#######7  | CSD epoch blocks : 56/72 [00:03<00:01,   15.18it/s]
 79%|#######9  | CSD epoch blocks : 57/72 [00:03<00:00,   15.16it/s]
 81%|########  | CSD epoch blocks : 58/72 [00:03<00:00,   15.18it/s]
 82%|########1 | CSD epoch blocks : 59/72 [00:03<00:00,   15.21it/s]
 83%|########3 | CSD epoch blocks : 60/72 [00:03<00:00,   15.23it/s]
 85%|########4 | CSD epoch blocks : 61/72 [00:04<00:00,   15.24it/s]
 86%|########6 | CSD epoch blocks : 62/72 [00:04<00:00,   15.24it/s]
 88%|########7 | CSD epoch blocks : 63/72 [00:04<00:00,   15.26it/s]
 89%|########8 | CSD epoch blocks : 64/72 [00:04<00:00,   15.29it/s]
 90%|######### | CSD epoch blocks : 65/72 [00:04<00:00,   15.32it/s]
 92%|#########1| CSD epoch blocks : 66/72 [00:04<00:00,   15.30it/s]
 93%|#########3| CSD epoch blocks : 67/72 [00:04<00:00,   15.33it/s]
 94%|#########4| CSD epoch blocks : 68/72 [00:04<00:00,   15.35it/s]
 96%|#########5| CSD epoch blocks : 69/72 [00:04<00:00,   15.37it/s]
 97%|#########7| CSD epoch blocks : 70/72 [00:04<00:00,   15.40it/s]
 99%|#########8| CSD epoch blocks : 71/72 [00:04<00:00,   15.41it/s]
100%|##########| CSD epoch blocks : 72/72 [00:04<00:00,   15.42it/s]
100%|##########| CSD epoch blocks : 72/72 [00:04<00:00,   15.26it/s]
[done]

The resulting mne.time_frequency.CrossSpectralDensity objects have a plotting function we can use to compare the results of the different methods. We’re plotting the mean CSD across frequencies.

csd_fft.mean().plot()
plt.suptitle('short-term Fourier transform')

csd_mt.mean().plot()
plt.suptitle('adaptive multitapers')

csd_wav.mean().plot()
plt.suptitle('Morlet wavelet transform')
  • short-term Fourier transform, 15.8-20.0 Hz.
  • adaptive multitapers, 15.8-20.0 Hz.
  • Morlet wavelet transform, 16.0-20.0 Hz.

Total running time of the script: ( 0 minutes 21.377 seconds)

Estimated memory usage: 118 MB

Gallery generated by Sphinx-Gallery