{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# Plotting whitened data\n\nThis tutorial demonstrates how to plot :term:`whitened <whitening>` evoked data.\n\nData are whitened for many processes, including dipole fitting, source\nlocalization and some decoding algorithms. Viewing whitened data thus gives\na different perspective on the data that these algorithms operate on.\n\nLet's start by loading some data and computing a signal (spatial) covariance\nthat we'll consider to be noise.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Authors: The MNE-Python contributors.\n# License: BSD-3-Clause\n# Copyright the MNE-Python contributors."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import mne\nfrom mne.datasets import sample"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Raw data with whitening\n<div class=\"alert alert-info\"><h4>Note</h4><p>In the :meth:`mne.io.Raw.plot` with ``noise_cov`` supplied,\n          you can press they \"w\" key to turn whitening on and off.</p></div>\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "data_path = sample.data_path()\nraw_fname = data_path / \"MEG\" / \"sample\" / \"sample_audvis_filt-0-40_raw.fif\"\nraw = mne.io.read_raw_fif(raw_fname, preload=True)\n\nevents = mne.find_events(raw, stim_channel=\"STI 014\")\nevent_id = {\n    \"auditory/left\": 1,\n    \"auditory/right\": 2,\n    \"visual/left\": 3,\n    \"visual/right\": 4,\n    \"smiley\": 5,\n    \"button\": 32,\n}\nreject = dict(grad=4000e-13, mag=4e-12, eog=150e-6)\nepochs = mne.Epochs(raw, events, event_id=event_id, reject=reject)\n\n# baseline noise cov, not a lot of samples\nnoise_cov = mne.compute_covariance(\n    epochs, tmax=0.0, method=\"shrunk\", rank=None, verbose=\"error\"\n)\n\n# butterfly mode shows the differences most clearly\nraw.plot(events=events, butterfly=True)\nraw.plot(noise_cov=noise_cov, events=events, butterfly=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Epochs with whitening\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "epochs.plot(events=True)\nepochs.plot(noise_cov=noise_cov, events=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Evoked data with whitening\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "evoked = epochs.average()\nevoked.plot(time_unit=\"s\")\nevoked.plot(noise_cov=noise_cov, time_unit=\"s\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Evoked data with scaled whitening\nThe :meth:`mne.Evoked.plot_white` function takes an additional step of\nscaling the whitened plots to show how well the assumption of Gaussian\nnoise is satisfied by the data:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "evoked.plot_white(noise_cov=noise_cov, time_unit=\"s\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Topographic plot with whitening\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "evoked.comment = \"All trials\"\nevoked.plot_topo(title=\"Evoked data\")\nevoked.plot_topo(noise_cov=noise_cov, title=\"Whitened evoked data\")"
      ]
    }
  ],
  "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
}