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:

Using short-term Fourier transform: mne.time_frequency.csd_fourier()
Using a multitaper approach: mne.time_frequency.csd_multitaper()
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()
meg_path = data_path / 'MEG' / 'sample'
fname_raw = meg_path / 'sample_audvis_raw.fif'
fname_event = meg_path / 'sample_audvis_raw-eve.fif'
raw = mne.io.read_raw_fif(fname_raw)
events = mne.read_events(fname_event)

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)

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)

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,   24.75it/s]
  3%|2         | CSD epoch blocks : 2/72 [00:00<00:01,   35.44it/s]
  4%|4         | CSD epoch blocks : 3/72 [00:00<00:01,   41.76it/s]
  7%|6         | CSD epoch blocks : 5/72 [00:00<00:01,   48.92it/s]
  8%|8         | CSD epoch blocks : 6/72 [00:00<00:01,   50.82it/s]
 11%|#1        | CSD epoch blocks : 8/72 [00:00<00:01,   53.83it/s]
 12%|#2        | CSD epoch blocks : 9/72 [00:00<00:01,   54.80it/s]
 15%|#5        | CSD epoch blocks : 11/72 [00:00<00:01,   56.47it/s]
 18%|#8        | CSD epoch blocks : 13/72 [00:00<00:01,   57.73it/s]
 21%|##        | CSD epoch blocks : 15/72 [00:00<00:00,   58.80it/s]
 24%|##3       | CSD epoch blocks : 17/72 [00:00<00:00,   59.45it/s]
 26%|##6       | CSD epoch blocks : 19/72 [00:00<00:00,   60.03it/s]
 29%|##9       | CSD epoch blocks : 21/72 [00:00<00:00,   60.51it/s]
 32%|###1      | CSD epoch blocks : 23/72 [00:00<00:00,   60.92it/s]
 35%|###4      | CSD epoch blocks : 25/72 [00:00<00:00,   61.21it/s]
 38%|###7      | CSD epoch blocks : 27/72 [00:00<00:00,   61.48it/s]
 40%|####      | CSD epoch blocks : 29/72 [00:00<00:00,   61.75it/s]
 43%|####3     | CSD epoch blocks : 31/72 [00:00<00:00,   61.92it/s]
 46%|####5     | CSD epoch blocks : 33/72 [00:00<00:00,   62.14it/s]
 49%|####8     | CSD epoch blocks : 35/72 [00:00<00:00,   62.36it/s]
 51%|#####1    | CSD epoch blocks : 37/72 [00:00<00:00,   62.62it/s]
 54%|#####4    | CSD epoch blocks : 39/72 [00:00<00:00,   62.88it/s]
 57%|#####6    | CSD epoch blocks : 41/72 [00:00<00:00,   63.12it/s]
 60%|#####9    | CSD epoch blocks : 43/72 [00:00<00:00,   63.25it/s]
 62%|######2   | CSD epoch blocks : 45/72 [00:00<00:00,   63.41it/s]
 65%|######5   | CSD epoch blocks : 47/72 [00:00<00:00,   63.63it/s]
 68%|######8   | CSD epoch blocks : 49/72 [00:00<00:00,   63.71it/s]
 71%|#######   | CSD epoch blocks : 51/72 [00:00<00:00,   63.67it/s]
 74%|#######3  | CSD epoch blocks : 53/72 [00:00<00:00,   63.77it/s]
 76%|#######6  | CSD epoch blocks : 55/72 [00:00<00:00,   63.11it/s]
 78%|#######7  | CSD epoch blocks : 56/72 [00:00<00:00,   62.33it/s]
 79%|#######9  | CSD epoch blocks : 57/72 [00:00<00:00,   62.31it/s]
 82%|########1 | CSD epoch blocks : 59/72 [00:00<00:00,   62.42it/s]
 85%|########4 | CSD epoch blocks : 61/72 [00:00<00:00,   62.58it/s]
 88%|########7 | CSD epoch blocks : 63/72 [00:01<00:00,   62.68it/s]
 90%|######### | CSD epoch blocks : 65/72 [00:01<00:00,   62.84it/s]
 93%|#########3| CSD epoch blocks : 67/72 [00:01<00:00,   62.92it/s]
 96%|#########5| CSD epoch blocks : 69/72 [00:01<00:00,   63.00it/s]
 99%|#########8| CSD epoch blocks : 71/72 [00:01<00:00,   63.15it/s]
100%|##########| CSD epoch blocks : 72/72 [00:01<00:00,   62.30it/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:16,    4.42it/s]
  3%|2         | CSD epoch blocks : 2/72 [00:00<00:12,    5.77it/s]
  4%|4         | CSD epoch blocks : 3/72 [00:00<00:10,    6.45it/s]
  6%|5         | CSD epoch blocks : 4/72 [00:00<00:09,    6.85it/s]
  7%|6         | CSD epoch blocks : 5/72 [00:00<00:09,    7.11it/s]
  8%|8         | CSD epoch blocks : 6/72 [00:00<00:09,    7.29it/s]
 10%|9         | CSD epoch blocks : 7/72 [00:00<00:08,    7.44it/s]
 11%|#1        | CSD epoch blocks : 8/72 [00:01<00:08,    7.55it/s]
 12%|#2        | CSD epoch blocks : 9/72 [00:01<00:08,    7.64it/s]
 14%|#3        | CSD epoch blocks : 10/72 [00:01<00:08,    7.69it/s]
 15%|#5        | CSD epoch blocks : 11/72 [00:01<00:07,    7.75it/s]
 17%|#6        | CSD epoch blocks : 12/72 [00:01<00:07,    7.80it/s]
 18%|#8        | CSD epoch blocks : 13/72 [00:01<00:07,    7.83it/s]
 19%|#9        | CSD epoch blocks : 14/72 [00:01<00:07,    7.87it/s]
 21%|##        | CSD epoch blocks : 15/72 [00:01<00:07,    7.90it/s]
 22%|##2       | CSD epoch blocks : 16/72 [00:02<00:07,    7.93it/s]
 24%|##3       | CSD epoch blocks : 17/72 [00:02<00:06,    7.95it/s]
 25%|##5       | CSD epoch blocks : 18/72 [00:02<00:06,    7.97it/s]
 26%|##6       | CSD epoch blocks : 19/72 [00:02<00:06,    7.98it/s]
 28%|##7       | CSD epoch blocks : 20/72 [00:02<00:06,    8.00it/s]
 29%|##9       | CSD epoch blocks : 21/72 [00:02<00:06,    8.01it/s]
 31%|###       | CSD epoch blocks : 22/72 [00:02<00:06,    8.02it/s]
 32%|###1      | CSD epoch blocks : 23/72 [00:02<00:06,    8.03it/s]
 33%|###3      | CSD epoch blocks : 24/72 [00:03<00:05,    8.05it/s]
 35%|###4      | CSD epoch blocks : 25/72 [00:03<00:05,    8.06it/s]
 36%|###6      | CSD epoch blocks : 26/72 [00:03<00:05,    8.06it/s]
 38%|###7      | CSD epoch blocks : 27/72 [00:03<00:05,    8.07it/s]
 39%|###8      | CSD epoch blocks : 28/72 [00:03<00:05,    8.07it/s]
 40%|####      | CSD epoch blocks : 29/72 [00:03<00:05,    8.08it/s]
 42%|####1     | CSD epoch blocks : 30/72 [00:03<00:05,    8.08it/s]
 43%|####3     | CSD epoch blocks : 31/72 [00:03<00:05,    8.09it/s]
 44%|####4     | CSD epoch blocks : 32/72 [00:04<00:04,    8.10it/s]
 46%|####5     | CSD epoch blocks : 33/72 [00:04<00:04,    8.10it/s]
 47%|####7     | CSD epoch blocks : 34/72 [00:04<00:04,    8.11it/s]
 49%|####8     | CSD epoch blocks : 35/72 [00:04<00:04,    8.12it/s]
 50%|#####     | CSD epoch blocks : 36/72 [00:04<00:04,    8.12it/s]
 51%|#####1    | CSD epoch blocks : 37/72 [00:04<00:04,    8.12it/s]
 53%|#####2    | CSD epoch blocks : 38/72 [00:04<00:04,    8.12it/s]
 54%|#####4    | CSD epoch blocks : 39/72 [00:04<00:04,    8.12it/s]
 56%|#####5    | CSD epoch blocks : 40/72 [00:04<00:03,    8.12it/s]
 57%|#####6    | CSD epoch blocks : 41/72 [00:05<00:03,    8.12it/s]
 58%|#####8    | CSD epoch blocks : 42/72 [00:05<00:03,    8.13it/s]
 60%|#####9    | CSD epoch blocks : 43/72 [00:05<00:03,    8.13it/s]
 61%|######1   | CSD epoch blocks : 44/72 [00:05<00:03,    8.14it/s]
 62%|######2   | CSD epoch blocks : 45/72 [00:05<00:03,    8.14it/s]
 64%|######3   | CSD epoch blocks : 46/72 [00:05<00:03,    8.15it/s]
 65%|######5   | CSD epoch blocks : 47/72 [00:05<00:03,    8.15it/s]
 67%|######6   | CSD epoch blocks : 48/72 [00:05<00:02,    8.15it/s]
 68%|######8   | CSD epoch blocks : 49/72 [00:06<00:02,    8.15it/s]
 69%|######9   | CSD epoch blocks : 50/72 [00:06<00:02,    8.15it/s]
 71%|#######   | CSD epoch blocks : 51/72 [00:06<00:02,    8.15it/s]
 72%|#######2  | CSD epoch blocks : 52/72 [00:06<00:02,    8.14it/s]
 74%|#######3  | CSD epoch blocks : 53/72 [00:06<00:02,    8.14it/s]
 75%|#######5  | CSD epoch blocks : 54/72 [00:06<00:02,    8.14it/s]
 76%|#######6  | CSD epoch blocks : 55/72 [00:06<00:02,    8.14it/s]
 78%|#######7  | CSD epoch blocks : 56/72 [00:06<00:01,    8.13it/s]
 79%|#######9  | CSD epoch blocks : 57/72 [00:07<00:01,    8.12it/s]
 81%|########  | CSD epoch blocks : 58/72 [00:07<00:01,    8.11it/s]
 82%|########1 | CSD epoch blocks : 59/72 [00:07<00:01,    8.10it/s]
 83%|########3 | CSD epoch blocks : 60/72 [00:07<00:01,    8.10it/s]
 85%|########4 | CSD epoch blocks : 61/72 [00:07<00:01,    8.09it/s]
 86%|########6 | CSD epoch blocks : 62/72 [00:07<00:01,    8.09it/s]
 88%|########7 | CSD epoch blocks : 63/72 [00:07<00:01,    8.09it/s]
 89%|########8 | CSD epoch blocks : 64/72 [00:07<00:00,    8.08it/s]
 90%|######### | CSD epoch blocks : 65/72 [00:08<00:00,    8.08it/s]
 92%|#########1| CSD epoch blocks : 66/72 [00:08<00:00,    8.08it/s]
 93%|#########3| CSD epoch blocks : 67/72 [00:08<00:00,    8.08it/s]
 94%|#########4| CSD epoch blocks : 68/72 [00:08<00:00,    8.07it/s]
 96%|#########5| CSD epoch blocks : 69/72 [00:08<00:00,    8.06it/s]
 97%|#########7| CSD epoch blocks : 70/72 [00:08<00:00,    8.02it/s]
 99%|#########8| CSD epoch blocks : 71/72 [00:08<00:00,    8.02it/s]
100%|##########| CSD epoch blocks : 72/72 [00:08<00:00,    8.02it/s]
100%|##########| CSD epoch blocks : 72/72 [00:08<00:00,    8.03it/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)

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:07,    9.86it/s]
  3%|2         | CSD epoch blocks : 2/72 [00:00<00:06,   11.62it/s]
  4%|4         | CSD epoch blocks : 3/72 [00:00<00:05,   12.35it/s]
  6%|5         | CSD epoch blocks : 4/72 [00:00<00:05,   12.92it/s]
  7%|6         | CSD epoch blocks : 5/72 [00:00<00:05,   13.20it/s]
  8%|8         | CSD epoch blocks : 6/72 [00:00<00:04,   13.36it/s]
 10%|9         | CSD epoch blocks : 7/72 [00:00<00:04,   13.49it/s]
 11%|#1        | CSD epoch blocks : 8/72 [00:00<00:04,   13.66it/s]
 12%|#2        | CSD epoch blocks : 9/72 [00:00<00:04,   13.65it/s]
 14%|#3        | CSD epoch blocks : 10/72 [00:00<00:04,   13.72it/s]
 15%|#5        | CSD epoch blocks : 11/72 [00:00<00:04,   13.74it/s]
 17%|#6        | CSD epoch blocks : 12/72 [00:00<00:04,   13.81it/s]
 18%|#8        | CSD epoch blocks : 13/72 [00:00<00:04,   13.73it/s]
 19%|#9        | CSD epoch blocks : 14/72 [00:01<00:04,   13.80it/s]
 21%|##        | CSD epoch blocks : 15/72 [00:01<00:04,   13.81it/s]
 22%|##2       | CSD epoch blocks : 16/72 [00:01<00:04,   13.76it/s]
 24%|##3       | CSD epoch blocks : 17/72 [00:01<00:03,   13.79it/s]
 25%|##5       | CSD epoch blocks : 18/72 [00:01<00:03,   13.88it/s]
 26%|##6       | CSD epoch blocks : 19/72 [00:01<00:03,   13.93it/s]
 28%|##7       | CSD epoch blocks : 20/72 [00:01<00:03,   13.97it/s]
 29%|##9       | CSD epoch blocks : 21/72 [00:01<00:03,   14.03it/s]
 31%|###       | CSD epoch blocks : 22/72 [00:01<00:03,   14.08it/s]
 32%|###1      | CSD epoch blocks : 23/72 [00:01<00:03,   14.12it/s]
 33%|###3      | CSD epoch blocks : 24/72 [00:01<00:03,   14.16it/s]
 35%|###4      | CSD epoch blocks : 25/72 [00:01<00:03,   14.20it/s]
 36%|###6      | CSD epoch blocks : 26/72 [00:01<00:03,   14.22it/s]
 38%|###7      | CSD epoch blocks : 27/72 [00:01<00:03,   14.21it/s]
 39%|###8      | CSD epoch blocks : 28/72 [00:01<00:03,   14.19it/s]
 40%|####      | CSD epoch blocks : 29/72 [00:02<00:03,   14.09it/s]
 42%|####1     | CSD epoch blocks : 30/72 [00:02<00:02,   14.05it/s]
 43%|####3     | CSD epoch blocks : 31/72 [00:02<00:02,   14.05it/s]
 44%|####4     | CSD epoch blocks : 32/72 [00:02<00:02,   14.08it/s]
 46%|####5     | CSD epoch blocks : 33/72 [00:02<00:02,   14.10it/s]
 47%|####7     | CSD epoch blocks : 34/72 [00:02<00:02,   14.11it/s]
 49%|####8     | CSD epoch blocks : 35/72 [00:02<00:02,   14.13it/s]
 50%|#####     | CSD epoch blocks : 36/72 [00:02<00:02,   14.13it/s]
 51%|#####1    | CSD epoch blocks : 37/72 [00:02<00:02,   14.12it/s]
 53%|#####2    | CSD epoch blocks : 38/72 [00:02<00:02,   14.07it/s]
 54%|#####4    | CSD epoch blocks : 39/72 [00:02<00:02,   14.02it/s]
 56%|#####5    | CSD epoch blocks : 40/72 [00:02<00:02,   13.96it/s]
 57%|#####6    | CSD epoch blocks : 41/72 [00:02<00:02,   13.96it/s]
 58%|#####8    | CSD epoch blocks : 42/72 [00:03<00:02,   13.89it/s]
 60%|#####9    | CSD epoch blocks : 43/72 [00:03<00:02,   13.88it/s]
 61%|######1   | CSD epoch blocks : 44/72 [00:03<00:02,   13.83it/s]
 62%|######2   | CSD epoch blocks : 45/72 [00:03<00:01,   13.73it/s]
 64%|######3   | CSD epoch blocks : 46/72 [00:03<00:01,   13.65it/s]
 65%|######5   | CSD epoch blocks : 47/72 [00:03<00:01,   13.61it/s]
 67%|######6   | CSD epoch blocks : 48/72 [00:03<00:01,   13.58it/s]
 68%|######8   | CSD epoch blocks : 49/72 [00:03<00:01,   13.52it/s]
 69%|######9   | CSD epoch blocks : 50/72 [00:03<00:01,   13.48it/s]
 71%|#######   | CSD epoch blocks : 51/72 [00:03<00:01,   13.52it/s]
 72%|#######2  | CSD epoch blocks : 52/72 [00:03<00:01,   13.51it/s]
 74%|#######3  | CSD epoch blocks : 53/72 [00:03<00:01,   13.48it/s]
 75%|#######5  | CSD epoch blocks : 54/72 [00:03<00:01,   13.45it/s]
 76%|#######6  | CSD epoch blocks : 55/72 [00:04<00:01,   13.13it/s]
 78%|#######7  | CSD epoch blocks : 56/72 [00:04<00:01,   12.87it/s]
 79%|#######9  | CSD epoch blocks : 57/72 [00:04<00:01,   12.85it/s]
 81%|########  | CSD epoch blocks : 58/72 [00:04<00:01,   12.84it/s]
 82%|########1 | CSD epoch blocks : 59/72 [00:04<00:01,   12.90it/s]
 83%|########3 | CSD epoch blocks : 60/72 [00:04<00:00,   12.89it/s]
 85%|########4 | CSD epoch blocks : 61/72 [00:04<00:00,   12.89it/s]
 86%|########6 | CSD epoch blocks : 62/72 [00:04<00:00,   12.93it/s]
 88%|########7 | CSD epoch blocks : 63/72 [00:04<00:00,   12.94it/s]
 89%|########8 | CSD epoch blocks : 64/72 [00:04<00:00,   12.93it/s]
 90%|######### | CSD epoch blocks : 65/72 [00:04<00:00,   12.93it/s]
 92%|#########1| CSD epoch blocks : 66/72 [00:04<00:00,   12.95it/s]
 93%|#########3| CSD epoch blocks : 67/72 [00:04<00:00,   13.02it/s]
 94%|#########4| CSD epoch blocks : 68/72 [00:05<00:00,   13.03it/s]
 96%|#########5| CSD epoch blocks : 69/72 [00:05<00:00,   13.02it/s]
 97%|#########7| CSD epoch blocks : 70/72 [00:05<00:00,   13.05it/s]
 99%|#########8| CSD epoch blocks : 71/72 [00:05<00:00,   13.11it/s]
100%|##########| CSD epoch blocks : 72/72 [00:05<00:00,   13.09it/s]
100%|##########| CSD epoch blocks : 72/72 [00:05<00:00,   13.42it/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')

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

Estimated memory usage: 226 MB

Gallery generated by Sphinx-Gallery