{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# Compute source power using DICS beamformer\n\nCompute a Dynamic Imaging of Coherent Sources (DICS) :footcite:`GrossEtAl2001`\nfilter from single-trial activity to estimate source power across a frequency\nband. This example demonstrates how to source localize the event-related\nsynchronization (ERS) of beta band activity in the\n`somato dataset <somato-dataset>`.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Author: Marijn van Vliet <w.m.vanvliet@gmail.com>\n#         Roman Goj <roman.goj@gmail.com>\n#         Denis Engemann <denis.engemann@gmail.com>\n#         Stefan Appelhoff <stefan.appelhoff@mailbox.org>\n#\n# License: BSD-3-Clause\n# Copyright the MNE-Python contributors."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import numpy as np\n\nimport mne\nfrom mne.beamformer import apply_dics_csd, make_dics\nfrom mne.datasets import somato\nfrom mne.time_frequency import csd_morlet\n\nprint(__doc__)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Reading the raw data and creating epochs:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "data_path = somato.data_path()\nsubject = \"01\"\ntask = \"somato\"\nraw_fname = data_path / f\"sub-{subject}\" / \"meg\" / f\"sub-{subject}_task-{task}_meg.fif\"\n\n# Use a shorter segment of raw just for speed here\nraw = mne.io.read_raw_fif(raw_fname)\nraw.crop(0, 120)  # one minute for speed (looks similar to using all ~800 s)\n\n# Read epochs\nevents = mne.find_events(raw)\n\nepochs = mne.Epochs(raw, events, event_id=1, tmin=-1.5, tmax=2, preload=True)\ndel raw\n\n# Paths to forward operator and FreeSurfer subject directory\nfname_fwd = (\n    data_path / \"derivatives\" / f\"sub-{subject}\" / f\"sub-{subject}_task-{task}-fwd.fif\"\n)\n\nsubjects_dir = data_path / \"derivatives\" / \"freesurfer\" / \"subjects\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We are interested in the beta band. Define a range of frequencies, using a\nlog scale, from 12 to 30 Hz.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "freqs = np.logspace(np.log10(12), np.log10(30), 9)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Computing the cross-spectral density matrix for the beta frequency band, for\ndifferent time intervals. We use a decim value of 20 to speed up the\ncomputation in this example at the loss of accuracy.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "csd = csd_morlet(epochs, freqs, tmin=-1, tmax=1.5, decim=20)\ncsd_baseline = csd_morlet(epochs, freqs, tmin=-1, tmax=0, decim=20)\n# ERS activity starts at 0.5 seconds after stimulus onset\ncsd_ers = csd_morlet(epochs, freqs, tmin=0.5, tmax=1.5, decim=20)\ninfo = epochs.info\ndel epochs"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "To compute the source power for a frequency band, rather than each frequency\nseparately, we average the CSD objects across frequencies.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "csd = csd.mean()\ncsd_baseline = csd_baseline.mean()\ncsd_ers = csd_ers.mean()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Computing DICS spatial filters using the CSD that was computed on the entire\ntimecourse.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fwd = mne.read_forward_solution(fname_fwd)\nfilters = make_dics(\n    info,\n    fwd,\n    csd,\n    noise_csd=csd_baseline,\n    pick_ori=\"max-power\",\n    reduce_rank=True,\n    real_filter=True,\n)\ndel fwd"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Applying DICS spatial filters separately to the CSD computed using the\nbaseline and the CSD computed during the ERS activity.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "baseline_source_power, freqs = apply_dics_csd(csd_baseline, filters)\nbeta_source_power, freqs = apply_dics_csd(csd_ers, filters)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Visualizing source power during ERS activity relative to the baseline power.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "stc = beta_source_power / baseline_source_power\nmessage = \"DICS source power in the 12-30 Hz frequency band\"\nbrain = stc.plot(\n    hemi=\"both\",\n    views=\"axial\",\n    subjects_dir=subjects_dir,\n    subject=subject,\n    time_label=message,\n)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## References\n.. footbibliography::\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.12.2"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}