{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# Using contralateral referencing for EEG\n\nInstead of using a single reference electrode for all channels, some\nresearchers reference the EEG electrodes in each hemisphere to an electrode in\nthe contralateral hemisphere (often an electrode over the mastoid bone; this is\ncommon in sleep research for example). Here we demonstrate how to set a\ncontralateral EEG reference.\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.\n\nimport mne\n\nssvep_folder = mne.datasets.ssvep.data_path()\nssvep_data_raw_path = (\n    ssvep_folder / \"sub-02\" / \"ses-01\" / \"eeg\" / \"sub-02_ses-01_task-ssvep_eeg.vhdr\"\n)\nraw = mne.io.read_raw(ssvep_data_raw_path, preload=True)\n_ = raw.set_montage(\"easycap-M1\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The electrodes TP9 and TP10 are near the mastoids so we'll use them as our\ncontralateral reference channels. Then we'll create our hemisphere groups.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "raw.rename_channels({\"TP9\": \"M1\", \"TP10\": \"M2\"})\n\n# this splits electrodes into 3 groups; left, midline, and right\nch_names = mne.channels.make_1020_channel_selections(raw.info, return_ch_names=True)\n\n# remove the ref channels from the lists of to-be-rereferenced channels\nch_names[\"Left\"].remove(\"M1\")\nch_names[\"Right\"].remove(\"M2\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Finally we do the referencing. For the midline channels we'll reference them\nto the mean of the two mastoid channels; the left and right hemispheres we'll\nreference to the single contralateral mastoid channel.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# midline referencing to mean of mastoids:\nmastoids = [\"M1\", \"M2\"]\nrereferenced_midline_chs = (\n    raw.copy()\n    .pick(mastoids + ch_names[\"Midline\"])\n    .set_eeg_reference(mastoids)\n    .drop_channels(mastoids)\n)\n\n# contralateral referencing (alters channels in `raw` in-place):\nfor ref, hemi in dict(M2=ch_names[\"Left\"], M1=ch_names[\"Right\"]).items():\n    mne.set_bipolar_reference(raw, anode=hemi, cathode=[ref] * len(hemi), copy=False)\n# strip off '-M1' and '-M2' suffixes added to each bipolar-referenced channel\nraw.rename_channels(lambda ch_name: ch_name.split(\"-\")[0])\n\n# replace unreferenced midline with rereferenced midline\n_ = raw.drop_channels(ch_names[\"Midline\"]).add_channels([rereferenced_midline_chs])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Make sure the channel locations still look right:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig = raw.plot_sensors(show_names=True, sphere=\"eeglab\")"
      ]
    }
  ],
  "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
}