{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# The role of dipole orientations in distributed source localization\n\nWhen performing source localization in a distributed manner\n(i.e., using MNE/dSPM/sLORETA/eLORETA),\nthe source space is defined as a grid of dipoles that spans a large portion of\nthe cortex. These dipoles have both a position and an orientation. In this\ntutorial, we will look at the various options available to restrict the\norientation of the dipoles and the impact on the resulting source estimate.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>A common \"gotcha!\" is that by default, dipole orientation information is discarded\n   in the source estimate. Only the magnitude of the activity is retained. This means\n   that by default, the source-level values are always positive. This has some\n   implications that may not be immediately obvious:\n\n   * Averaging across source estimated epochs does not produce a source estimated\n     evoked response. Since values are always positive, noise does not \"cancel out\".\n     This means the default settings are probably not suitable for things like\n     performing linear regression or computing correlations across epochs in source\n     space.\n\n   * Oscillatory signals are distorted, as for example a sine wave will become a series\n     of bumps. Hence, frequency analysis in source space is not meaningful when using\n     the default settings.</p></div>\n\n\nSee `inverse_orientation_constraints` for related information.\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": "markdown",
      "metadata": {},
      "source": [
        "## Load data\nLoad everything we need to perform source localization on the sample dataset.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import numpy as np\n\nimport mne\nfrom mne.datasets import sample\nfrom mne.minimum_norm import apply_inverse, make_inverse_operator\n\ndata_path = sample.data_path()\nmeg_path = data_path / \"MEG\" / \"sample\"\nevokeds = mne.read_evokeds(meg_path / \"sample_audvis-ave.fif\")\nleft_auditory = evokeds[0].apply_baseline()\nfwd = mne.read_forward_solution(meg_path / \"sample_audvis-meg-eeg-oct-6-fwd.fif\")\nmne.convert_forward_solution(fwd, surf_ori=True, copy=False)\nnoise_cov = mne.read_cov(meg_path / \"sample_audvis-cov.fif\")\nsubject = \"sample\"\nsubjects_dir = data_path / \"subjects\"\ntrans_fname = meg_path / \"sample_audvis_raw-trans.fif\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## The source space\nLet's start by examining the source space as constructed by the\n:func:`mne.setup_source_space` function. Dipoles are placed along fixed\nintervals on the cortex, determined by the ``spacing`` parameter. The source\nspace does not define the orientation for these dipoles.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "lh = fwd[\"src\"][0]  # Visualize the left hemisphere\nverts = lh[\"rr\"]  # The vertices of the source space\ntris = lh[\"tris\"]  # Groups of three vertices that form triangles\ndip_pos = lh[\"rr\"][lh[\"vertno\"]]  # The position of the dipoles\ndip_ori = lh[\"nn\"][lh[\"vertno\"]]\ndip_len = len(dip_pos)\ndip_times = [0]\nwhite = (1.0, 1.0, 1.0)  # RGB values for a white color\n\nactual_amp = np.ones(dip_len)  # fake amp, needed to create Dipole instance\nactual_gof = np.ones(dip_len)  # fake GOF, needed to create Dipole instance\ndipoles = mne.Dipole(dip_times, dip_pos, actual_amp, dip_ori, actual_gof)\ntrans = mne.read_trans(trans_fname)\n\nfig = mne.viz.create_3d_figure(size=(600, 400), bgcolor=white)\ncoord_frame = \"mri\"\n\n# Plot the cortex\nmne.viz.plot_alignment(\n    subject=subject,\n    subjects_dir=subjects_dir,\n    trans=trans,\n    surfaces=\"white\",\n    coord_frame=coord_frame,\n    fig=fig,\n)\n\n# Mark the position of the dipoles with small red dots\nmne.viz.plot_dipole_locations(\n    dipoles=dipoles,\n    trans=trans,\n    mode=\"sphere\",\n    subject=subject,\n    subjects_dir=subjects_dir,\n    coord_frame=coord_frame,\n    scale=7e-4,\n    fig=fig,\n)\n\nmne.viz.set_3d_view(figure=fig, azimuth=180, distance=0.1, focalpoint=\"auto\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n## Fixed dipole orientations\nWhile the source space defines the position of the dipoles, the inverse\noperator defines the possible orientations of them. One of the options is to\nassign a fixed orientation. Since the neural currents from which MEG and EEG\nsignals originate flows mostly perpendicular to the cortex\n:footcite:`HamalainenEtAl1993`, restricting the orientation of the dipoles\naccordingly places a useful restriction on the source estimate.\n\nBy specifying ``fixed=True`` when calling\n:func:`mne.minimum_norm.make_inverse_operator`, the dipole orientations are\nfixed to be orthogonal to the surface of the cortex, pointing outwards. Let's\nvisualize this:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig = mne.viz.create_3d_figure(size=(600, 400))\n\n# Plot the cortex\nmne.viz.plot_alignment(\n    subject=subject,\n    subjects_dir=subjects_dir,\n    trans=trans,\n    surfaces=\"white\",\n    coord_frame=\"head\",\n    fig=fig,\n)\n\n# Show the dipoles as arrows pointing along the surface normal\nmne.viz.plot_dipole_locations(\n    dipoles=dipoles,\n    trans=trans,\n    mode=\"arrow\",\n    subject=subject,\n    subjects_dir=subjects_dir,\n    coord_frame=\"head\",\n    scale=7e-4,\n    fig=fig,\n)\n\nmne.viz.set_3d_view(figure=fig, azimuth=180, distance=0.1, focalpoint=\"auto\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Restricting the dipole orientations in this manner leads to the following\nsource estimate for the sample data:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Compute the source estimate for the left auditory condition in the sample\n# dataset.\ninv = make_inverse_operator(left_auditory.info, fwd, noise_cov, fixed=True)\nstc = apply_inverse(left_auditory, inv, pick_ori=None)\n\n# Visualize it at the moment of peak activity.\n_, time_max = stc.get_peak(hemi=\"lh\")\nbrain_fixed = stc.plot(\n    surface=\"white\",\n    subjects_dir=subjects_dir,\n    initial_time=time_max,\n    time_unit=\"s\",\n    size=(600, 400),\n)\nmne.viz.set_3d_view(figure=brain_fixed, focalpoint=(0.0, 0.0, 50))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The direction of the estimated current is now restricted to two directions:\ninward and outward. In the plot, blue areas indicate current flowing inwards\nand red areas indicate current flowing outwards. Given the curvature of the\ncortex, groups of dipoles tend to point in the same direction: the direction\nof the electromagnetic field picked up by the sensors.\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n## Loose dipole orientations\nForcing the source dipoles to be strictly orthogonal to the cortex makes the\nsource estimate sensitive to the spacing of the dipoles along the cortex,\nsince the curvature of the cortex changes within each ~10 square mm patch.\nFurthermore, misalignment of the MEG/EEG and MRI coordinate frames is more\ncritical when the source dipole orientations are strictly constrained\n:footcite:`LinEtAl2006`. To lift the restriction on the orientation of the\ndipoles, the inverse operator has the ability to place not one, but three\ndipoles at each location defined by the source space. These three dipoles are\nplaced orthogonally to form a Cartesian coordinate system. Let's visualize\nthis:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig = mne.viz.create_3d_figure(size=(600, 400))\n\n# Plot the cortex\nmne.viz.plot_alignment(\n    subject=subject,\n    subjects_dir=subjects_dir,\n    trans=trans,\n    surfaces=\"white\",\n    coord_frame=\"head\",\n    fig=fig,\n)\n\n# Show the three dipoles defined at each location in the source space\nmne.viz.plot_alignment(\n    subject=subject,\n    subjects_dir=subjects_dir,\n    trans=trans,\n    fwd=fwd,\n    surfaces=\"white\",\n    coord_frame=\"head\",\n    fig=fig,\n)\n\nmne.viz.set_3d_view(figure=fig, azimuth=180, distance=0.1, focalpoint=\"auto\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "When computing the source estimate, the activity at each of the three dipoles\nis collapsed into the XYZ components of a single vector, which leads to the\nfollowing source estimate for the sample data:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Make an inverse operator with loose dipole orientations\ninv = make_inverse_operator(left_auditory.info, fwd, noise_cov, fixed=False, loose=1.0)\n\n# Compute the source estimate, indicate that we want a vector solution\nstc = apply_inverse(left_auditory, inv, pick_ori=\"vector\")\n\n# Visualize it at the moment of peak activity.\n_, time_max = stc.magnitude().get_peak(hemi=\"lh\")\nbrain_mag = stc.plot(\n    subjects_dir=subjects_dir,\n    initial_time=time_max,\n    time_unit=\"s\",\n    size=(600, 400),\n    overlay_alpha=0,\n)\nmne.viz.set_3d_view(figure=brain_mag, focalpoint=(0.0, 0.0, 50))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n## Limiting orientations, but not fixing them\nOften, the best results will be obtained by allowing the dipoles to have\nsomewhat free orientation, but not stray too far from a orientation that is\nperpendicular to the cortex. The ``loose`` parameter of the\n:func:`mne.minimum_norm.make_inverse_operator` allows you to specify a value\nbetween 0 (fixed) and 1 (unrestricted or \"free\") to indicate the amount the\norientation is allowed to deviate from the surface normal.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Set loose to 0.2, the default value\ninv = make_inverse_operator(left_auditory.info, fwd, noise_cov, fixed=False, loose=0.2)\nstc = apply_inverse(left_auditory, inv, pick_ori=\"vector\")\n\n# Visualize it at the moment of peak activity.\n_, time_max = stc.magnitude().get_peak(hemi=\"lh\")\nbrain_loose = stc.plot(\n    subjects_dir=subjects_dir,\n    initial_time=time_max,\n    time_unit=\"s\",\n    size=(600, 400),\n    overlay_alpha=0,\n)\nmne.viz.set_3d_view(figure=brain_loose, focalpoint=(0.0, 0.0, 50))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Discarding dipole orientation information\nOften, further analysis of the data does not need information about the\norientation of the dipoles, but rather their magnitudes. The ``pick_ori``\nparameter of the :func:`mne.minimum_norm.apply_inverse` function allows you\nto specify whether to return the full vector solution (``'vector'``) or\nrather the magnitude of the vectors (``None``, the default) or only the\nactivity in the direction perpendicular to the cortex (``'normal'``).\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Only retain vector magnitudes\nstc = apply_inverse(left_auditory, inv, pick_ori=None)\n\n# Visualize it at the moment of peak activity\n_, time_max = stc.get_peak(hemi=\"lh\")\nbrain = stc.plot(\n    surface=\"white\",\n    subjects_dir=subjects_dir,\n    initial_time=time_max,\n    time_unit=\"s\",\n    size=(600, 400),\n)\nmne.viz.set_3d_view(figure=brain, focalpoint=(0.0, 0.0, 50))"
      ]
    },
    {
      "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
}