1 - mne_data.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "80a188ea-1c3d-410e-8e62-69164f019ac1",
   "metadata": {},
   "source": [
    "# Exploring MNE's data structure\n",
    "---\n",
    "\n",
    "## Learning Objectives\n",
    "- Import raw EEG data using MNE\n",
    "- Examine the structure of an MNE `Raw` object\n",
    "- Access and view different attributes of a `Raw` data object\n",
    "- Visualize the positions of EEG electrodes \n",
    "\n",
    "\n",
    "---\n",
    "## Introduction\n",
    "\n",
    "In this lesson, we will load a raw EEG data file using MNE and gain an understanding of how MNE stores data. This is an important first step to working with data in MNE.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f49c294-5e2c-4678-ba98-3601061b1170",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Load pacakges"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91f054ba",
   "metadata": {},
   "source": [
    "~~~python\n",
    "import mne\n",
    "mne.set_log_level('error')\n",
    "\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import glob\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "6a2ddc56-2655-4f02-8b13-96a47db5da5d",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "181aebf8-1b36-4d1a-8fb6-3d1ffdebd19b",
   "metadata": {},
   "source": [
    "## Import raw data\n",
    "\n",
    "For EEG, raw data is typically stored in a single file containing continuous EEG data. There are many different file formats for EEG data; most of these are developed by the manufacturer of a particular EEG system. Fortunately, MNE provides functions to import data from most common EEG systems. \n",
    "\n",
    "In the present case, we are working with data from a system sold by Brain Products, whose software is called *Brain Vision*. So we will use MNE's `read_raw_brainvision()` function. The Brain Vision format actually specifies *three files* for any given data set, as we can see if we look for all the file names in the `data` subfolder that start with the subject ID code for our data set, `P4`:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89249974",
   "metadata": {},
   "source": [
    "~~~python\n",
    "glob.glob('data/N400_dataset_04*')\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "89e41c07-8dcb-4d0f-bcde-99024e4b57c6",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "2a25b8c5-eda6-41dc-8142-80600799778c",
   "metadata": {},
   "source": [
    "The three files are all created at the time that the EEG data is acquired, and it's important to ensure that all three are copied when moving them around. The files are as follows:\n",
    "- `*.eeg` is the actual EEG data (electrical potential measurements for all electrodes, at all time points). This is stored in a compressed (binary) format\n",
    "- `*.vmrk` is a text file containing all of the markers (*trigger codes*) that were sent to the EEG system during data collection, by the stimulus computer. These typically encode the onset of various stimuli, and times of any responses by the participant, as well as what each stimulus/response was. \n",
    "- `*.vhdr` is a text file with header information, or **metadata** about the data set, including technical details such as the sampling rate, and the settings of the EEG amplifier during the recording. The `.vhdr` file is particularly important because it specifies the file names of the `.eeg` and `.trg` files (although they should always be named consistently with the header file). \n",
    "\n",
    "When we run `read_raw_brainvision()` the file we will actually pass as an argument is the `.vhdr` file. Since it specifies the names of the associated `.eeg` and `.trg` files, from this file MNE can find the data and markers.\n",
    "\n",
    "As described previously, many of MNE's functions are nested inside subfolders (modules); for example, all of the file input-output (I/O) routines are in the module `mne.io`. So when we call the `read_raw_brainvision()` function, we have to do so as `mne.io.read_raw_brainvision()`. The one required argument for this function is the file name, and that's all we need for now: "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2f1fd77",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw = mne.io.read_raw_brainvision('data/N400_dataset_04.vhdr')\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "58516da4-96c2-4552-93dd-99df86731bb2",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "4e0930a7-3e8b-4bca-9767-6244110a0ea6",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "At the start of the lesson, we ran a command after importing mne, `mne.set_log_level('error')`. If you don't run this when using MNE, you will find that MNE provides a lot output, often including some concerning-looking Python warning messages. Most of these warnings are safely ignored. I generally find this output more confusing than helpful, and turn it off routinely. For our lessons we will keep the output off because it just creates confusion.\n",
    "    </div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40f30d27-7ccf-427a-82e8-4bd3d31a6293",
   "metadata": {},
   "source": [
    "### View raw data attributes\n",
    "\n",
    "We now have our raw EEG data represented in Python as an MNE `Raw` object. We can view it's basic information by asking for the `.info` property:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "51df7e07",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.info\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fd09952e-1a6a-4485-85e2-e3f349ade412",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "f6a269c9-f80e-4e8d-9b11-4e3335613f3f",
   "metadata": {},
   "source": [
    "Although some of the information is not available, this shows us a few important things about our data set, including that there are 16 EEG channels (each channel contains the data from one EEG electrode), that the sampling rate is 500 Hz (i.e., EEG data were sampled 500 times per second, so we have a data point every 2 ms), and that the data were filtered during data collection between 0.01–80 Hz (more on filtering below).\n",
    "\n",
    "The information provided above is actually a subset of the information stored in the `Raw` object's `info`. We can use the `.keys()` method to see all of the fields available in `info`:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2b23598",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.info.keys()\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "51533952-d21c-4570-a350-ba151f707b2a",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "05628b30-1567-4ce9-a7aa-6a4893e1b6c4",
   "metadata": {},
   "source": [
    "We can access the values stored with any of these info attributes by putting it in square brackets, like this command to access the names of all of the channels (electrodes) in the data set:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d928aa37",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.info['ch_names']\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0c718ce2-8d39-48b0-a988-058fbc0f5638",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "54b95a16-31c7-412c-b120-784eba6f7043",
   "metadata": {},
   "source": [
    "The `info` is a snapshot of a few pieces of information that researchers may want to know about a data file, but it's far less than all the information stored in the MNE `Raw` object. To see the entire contents of the object, we can ask for it's `__dict__` (note that there are two underscores below `dict` and two after). Recall that `Raw` is a Python class, and any instance of the `Raw` class (such as our `raw` data here) is a Python object. Any Python object has an atrribute `__dict__`, and this attribute contains a dictionary of all of the object's attributes, with keys being the attribute names, and values being the information stored for that attribute."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb7a1dc0",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.__dict__\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2a3e2259-7f81-453d-a048-e4c4e0af73f8",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "254f8f0b-bb4a-4887-babe-e23e25182e7a",
   "metadata": {},
   "source": [
    "## Where's the data?\n",
    "\n",
    "For all the information that is in the output above, one thing you may have noticed is that there doesn't seem to be any actual EEG data! This is because, by default, MNE's routines to read raw data read the data file's *header* into memory, but not the data itself. The reason for this is that data files are often quite large, and so reading them in sometimes takes a noticeable amount of time, and consume significant memory. The header of a raw EEG data file contains its metadata (information about the file), as you saw above in printing out the `__dict__` this is often enough for MNE to perform some operations on the data. At some point, if you want to perform operations on the EEG data, then MNE will automatically load in the data to work on it. \n",
    "\n",
    "We can force MNE to load in the data when we read the file, with the `preload` kwarg. We'll do this now so that we can look at the data:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee44fd05",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw = mne.io.read_raw_brainvision('data/N400_dataset_04.vhdr', \n",
    "                                    preload=True)\n",
    "raw.__dict__\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "64f34e47-24fe-4630-817a-e6a38af306d4",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "9c9c3da5-fb95-4ed6-bfa0-17859f969516",
   "metadata": {},
   "source": [
    "Now we can see that there is a `_data` attribute, containing a NumPy array. We can access the data like so:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3457ee2f",
   "metadata": {},
   "source": [
    "~~~python\n",
    "print(type(raw._data))\n",
    "print(raw._data.shape)\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5cc989e5-1fcc-4cb7-a1f5-b558ffc5faab",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "de6ee19b-bb1d-4cd0-96ca-2ad1b9626244",
   "metadata": {},
   "source": [
    "MNE represents the data as a 2D array with a row for each channel, and columns for time points. We can derive the length of the EEG recording, in seconds, by dividing the number of time points by the sampling rate:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99b04382",
   "metadata": {},
   "source": [
    "~~~python\n",
    "scan_durn = raw._data.shape[1] / raw.info['sfreq']\n",
    "print('Duration of EEG recording = ', scan_durn, 's, or', scan_durn / 60, 'min.')\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "42e1cfd2-c6a2-46e0-9a7c-daf5dcac10bc",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "ef76c073-230b-4f9a-90b2-d9ad68a87ed6",
   "metadata": {},
   "source": [
    "## Accessing subsets of data\n",
    "\n",
    "Since the data is stored as a NumPy array, we can access specific data points using standard indexing. For example, if we wanted to select all of the data from only channel 15, we would use:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "25876033",
   "metadata": {},
   "source": [
    "~~~python\n",
    "print(raw._data[15, :])\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "df57a294-98ff-4365-9bac-70439a4530de",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "a9854907-e71b-4028-83ff-2cf07c5c016f",
   "metadata": {},
   "source": [
    "Likewise, if we wanted to access only the first 10 time points of channel 8, we would use:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7d6c50fc",
   "metadata": {},
   "source": [
    "~~~python\n",
    "print(raw._data[8, :11])\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8c3ef8ea-3b22-43cc-9ea5-f967b2fc456b",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "f2d2df57-9392-47d3-bdb9-a935733c39c3",
   "metadata": {},
   "source": [
    "One challenge in working with the raw data directly in this way, is that we normally think of, and work with, EEG data in terms of units of time, such as seconds or milliseconds. However, EEG data is not always (or even usually) sampled at 1000 Hz, so each time point doesn't correspond to 1 ms. For example, in our current data set, the sampling rate was 500 Hz, so each time point reflects a period of 2 ms. This makes accessing specific time points or time ranges in the data tricky, because if you want, say, the data from 1500-1800 ms in the `raw` data, you would need to first convert those times to seconds (since `sfreq` is in samples per second), convert the result to `int` (since division is likely to yield a `float` result), then multiply each of those times by the sampling rate to get the correct indices. While this is not necessarily difficult, it's a bit tricky and prone to error, as well as creating complex code:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16f656bc",
   "metadata": {},
   "source": [
    "~~~python\n",
    "chan = 8 # set channel we want\n",
    "start_time = int((1500 / 1000) * raw.info['sfreq'])\n",
    "end_time   = int((1800 / 1000) * raw.info['sfreq'])\n",
    "raw._data[chan, start_time:end_time]\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "05ad474b-b6a2-4644-8291-b26132590d9d",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "3aa64451-714f-48fa-a2c4-62e97b05b5e7",
   "metadata": {},
   "source": [
    "## Accessing data using MNE tools\n",
    "\n",
    "Fortunately, since MNE is made to work with EEG data, it has lots of functions and methods that make it easy to do common tasks. Besides convenience, it's generally a good idea to use these because in general they provide an API that is more intuitive to use, and also create less risk that you will corrupt the data (since if you're using `._data`, it would be easy to accidentally assign new values to the array, or otherwise modify it, and Python would not warn you that you were doing something bad).\n",
    "\n",
    "We can access the data in an MNE object with the `.get_data()` method. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "358d36f7",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw_data = raw.get_data()\n",
    "print(raw_data.shape)\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4b8ec3c4-2e82-46bb-a5df-7f42fc99674f",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "effb6c47-19a5-40f2-b872-64b5b1116778",
   "metadata": {},
   "source": [
    "Moreover, `.get_data()` provides kwargs that allow us to select channels and time ranges, using more intuitive units like channel labels, and times, rather than NumPy array indices. `picks` is used to select the channel (or channels if you pass a list), and `tmin` and `tmax` specify the range of time that you want:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc741181",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.get_data(picks=['Fz', 'Cz'], tmin=1.5, tmax=1.8)\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "416f75d4-6bdd-47d2-84c3-d4d2b76a21f2",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "092c291a-767c-4870-b0e5-7ae48cc6ac51",
   "metadata": {},
   "source": [
    "If you look carefully at the output above, you'll note that it's a 2D NumPy array, with the data from each electrode enclosed in a separate set of square brackets."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "823b9bdd-0f93-4967-9c40-a6db58532e9d",
   "metadata": {},
   "source": [
    "## Visualizing raw EEG data\n",
    "\n",
    "### Plot EEG data with Matplotlib\n",
    "\n",
    "Since we understand how to select a particular segment of data and return it as a NumPy array, it's easy to pass the result of doing this to Matplotlib, and visualize the electrical potential of a specific electrode over a segment of time: "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d90c92e7",
   "metadata": {},
   "source": [
    "~~~python\n",
    "fig, ax = plt.subplots(figsize=[15, 5])\n",
    "start_time = 15\n",
    "end_time = 16\n",
    "\n",
    "ax.plot(raw.get_data(picks='Oz', tmin=start_time, tmax=end_time).T)\n",
    "plt.show()\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a5d67803-ef9d-4c13-8292-8d851d497b39",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "9b98f2f4-89d6-4590-8894-98555edc50e3",
   "metadata": {},
   "source": [
    "### Plot EEG data with MNE\n",
    "\n",
    "We could add more code to the above cell to do things like label the axes, add a title to indicate what electrode the data came from, make the *x* axis actually represent units of time, etc.. However, the great value of using MNE is that the developers have created customized functions for doing most everything you could ever want with EEG, with a lot less typing than if you were working with raw NumPy arrays and Matplotlib. \n",
    "\n",
    "For example, MNE data classes like `Raw` have a `.plot` method that allows you to generate a nice-looking plot that automatically does all the hard work of formatting it appropriately:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5afbcf2",
   "metadata": {},
   "source": [
    "~~~python\n",
    "# Be sure to include the semicolon at the end of the line. We'll learn why later.\n",
    "raw.plot(start=15, duration=1);  \n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7eb739ba-f6ad-41e6-92cb-e2a6de14a66e",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "afeee57c-31e1-4d63-9b60-f2a5d28d326d",
   "metadata": {},
   "source": [
    "Note carefully that there are two *x* axes in the plot. The top one (closer to the plot itself) are the time units of the data (in seconds). The bottom axis shows the timeline of the entire raw EEG recording, with a dark vertical bar near the start indicating the position in the file that is currently plotted. Although it doesn't work in web-based Jupyter environments like CoCalc, if you install Python on your own computer and run MNE you will get an interactive plot, that allows you to scroll through the data over time."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e559ead-723f-40cf-841a-d8337e534086",
   "metadata": {},
   "source": [
    "## Set electrode positions\n",
    "\n",
    "One thing that can be useful at this stage is visualizing the electrode positions on the head. Typically, EEG studies try to position electrodes in a fairly evenly-spaced way over the top of the head. However, the locations can depend on what ERP [components](./components) are predicted for the study, and how many electrodes are available. \n",
    "\n",
    "MNE provides a `.plot_sensors()` method for visualizing sensor locations. However, by default although our raw data contains the *names* of each channel, it does not contain information regarding where each channel was located. Fortunately, in this and most EEG studies, the electrode positions were based on the International 10-20 system. This was first introduced as a way of standardizing EEG electrode placement in clinical neurology, and is so-named because electrode positions are determined by first measuring the anterior-posterior and left-right dimensions of the participant's head, and then placing electrodes at positions determined by 10 and 20% increments of those measurements (E.g., electrode Cz is placed 50% of the anterior-posterior and left-right measurements). More recently, [Oostenveld and Praamstra (2001)](https://doi.org/10.1016/S1388-2457(00)00527-7) published an extension of this called the 10-5 system, that allows for a larger number of electrodes based on 5% increments. You can read more about this system and its variants on [Oostenveld's blog](https://robertoostenveld.nl/electrode/#oostenveld2001). \n",
    "\n",
    "Long story short, we have to first run an MNE method to look up the locations of each electrode based on its 10-20 system name, and set the positions in the raw file. We do this with `.set_montage()`, and as an argument use MNE's built-in list of 10-5 system electrode names and locations.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    \n",
    "**Note:** *Montage* is a common word used to describe the arrangement of EEG electrodes on a head, or in an EEG cap. In more general usage, *montage* means \"a collection of elements\".</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f3096823",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.set_montage('standard_1005')\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bebfec28-458f-47d8-b668-9edeb717eac0",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "01fbb447-7311-4880-9ff5-5359043c705c",
   "metadata": {},
   "source": [
    "MNE prints out the `info` for the `Raw` object again, and if you compare this output to that from earlier, you'll see that the *Digitized points* field has changed from \"Not available\" to \"19 points\". This terminology is a bit strange - \"digitized points\" seems more general and nonspecific than \"electrode locations\", for example. The reason for this is that in some cases, researchers will actually use a device to digitize the locations of electrodes when they are on a person's head, rather than relying on standard positions. Anyway, this information is stored under the `dig` attribute, which we can view with:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5ea71cd6",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.info['dig']\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "44b6ea02-ee05-4148-bdfe-e30d773db376",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "68ef9f29-51c7-4d86-a3ab-2391669b10f5",
   "metadata": {},
   "source": [
    "Each electrode location is stored as a set of (*x*, *y*, *z*) Cartesian coordinates, i.e., positions in a 3D grid, where *x* is the left-right dimension, *y* is posterior-anterior, and *z* is inferior-posterior. The (0, 0, 0) location is inside the head, located in a plane defined by the bridge of the nose (called the **nasion**) and the left and right ear canals. As shown in the figure below, *x* goes from left (negative) to right (positive), *y* goes from posterior to anterior, and *z* goes from inferior to superior. In general, you won't need to work with this coordinate system directly, but it's useful to know how the data are represented.\n",
    "\n",
    "![cartesian coordinate system for electrode positions](images/MRI_ax_sag_cor.jpg)\n",
    "\n",
    "Note above as well that the list of sensor locations does not contain the names of each sensor — the channel names we saw above. In general MNE's data structure is designed to assume that channels are listed in the same order in all attributes of the data structure. So, the list of channel names from"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2f4e92f4",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.info['ch_names']\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "322574cd-280b-4cd8-877c-9d72a46dde8e",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "fd5d899f-de54-4af7-9ab8-37b4df4ceac3",
   "metadata": {},
   "source": [
    "can be used to label the `EEG` channels in `raw.info['dig']`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e76de5e9-2788-4888-8f85-04c13f10ae62",
   "metadata": {},
   "source": [
    "### View electrode positions\n",
    "\n",
    "MNE provides tools for viewing channel locations in both 2D and 3D:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9828bb4",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.plot_sensors()\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1a258637-37f1-4ff8-b2cd-66ea92da54a6",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "8236895e-c413-4397-96c2-e825e163e903",
   "metadata": {},
   "source": [
    "## MNE plots in Jupyter notebooks\n",
    "\n",
    "You'll notice above that MNE actually drew two copies of the figure. This is a default behaviour of MNE for many plots, and it's annoying if you don't know how to deal with it. There are two ways to ensure MNE produces only a single copy of a figure:\n",
    "\n",
    "### End the plot command with a semicolon\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "690b6b0c",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.plot_sensors();\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0ba4fbb-854d-412c-807b-71158f1b8316",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "1a651deb-491c-47e8-b987-9e25b9ec2474",
   "metadata": {},
   "source": [
    "### Use `plt.show()` \n",
    "\n",
    "...at the bottom of the cell (or at least after all plotting commands in the cell)  "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eaa29abd",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.plot_sensors()\n",
    "plt.show()\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8bce7e6c-2e71-4c73-83f7-3890839a7017",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "cecc2724-9ff5-4ea3-bd57-d915aa8e09fc",
   "metadata": {},
   "source": [
    "### Show sensor names\n",
    "We can also add a kwarg to show the names of each sensor:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6fd00486",
   "metadata": {},
   "source": [
    "~~~python\n",
    "raw.plot_sensors(show_names=True)\n",
    "plt.show()\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1a418a35",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "38d61c03-4fe3-4305-beb0-9c3369b93dcb",
   "metadata": {},
   "source": [
    "## Event codes (markers/triggers)\n",
    "\n",
    "Yes, there are (at least) three names for the codes that mark events in EEG data! *Markers* makes intuitive sense because they mark the time of events of interest in the EEG data. *Triggers* is a somewhat old-fashioned term; its origin is obscure but perhaps reflects the idea that stimuli \"trigger\" brain responses that we can measure with EEG. *Event codes* makes sense since they are codes that indicate not only that an event occurred, but it's identity. We'll use *event codes* from this point forward.\n",
    "\n",
    "As noted earlier, the event codes are stored in the `.trg` file in Brain Vision format. When we import the raw data into MNE, these are stored in an attribute called `._annotations`. Although we can access that directly (e.g., `raw._annotations`), again MNE provides tools that makes this easier and generate more interpretable output: the `events_from_annotations()` function:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b63e3ffa",
   "metadata": {},
   "source": [
    "~~~python\n",
    "mne.events_from_annotations(raw)\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "092ad901-988d-4e7f-b206-a7ec96c8c2be",
   "metadata": {
    "scrolled": true,
    "tags": []
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "7a6730a2-148b-4807-a280-3a45bfe1cbba",
   "metadata": {},
   "source": [
    "The result includes two outputs, The first is a NumPy array that has three columns, with one row for each event code in the data. The first column indicates the time of the event (in milliseconds, relative to the start of the recording), and the last column stores the code associated with that event. These event codes are always represented as integers (since it is a NumPy array of integers). \n",
    "\n",
    "The second output is a dictionary mapping labels for each event code, to the numerical codes themselves. Usually these are not very informative in the raw data. In the next lesson, we will learn how to map the numerical codes to meaningful labels based on the experimental design. For now, it's simply important to understand how the event codes are stored in the `Raw` data object."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}