Notebooks/Day 1/1 - Raw.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a7f32110-e046-4c35-94cd-dfc8aeda9c9d",
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "import os\n",
    "\n",
    "import mne\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Timeseries data in MNE - the `Raw` class\n",
    "\n",
    "The most basic form of electrophysiological data is timeseries data: a continuous set of voltage values recorded over time for each [channel](https://mne.tools/stable/documentation/glossary.html#term-channels).\n",
    "\n",
    "Timeseries data in MNE is stored in [`mne.io.Raw`](https://mne.tools/stable/generated/mne.io.Raw.html) and [`mne.io.RawArray`](https://mne.tools/stable/generated/mne.io.RawArray.html) objects.\n",
    "\n",
    "`Raw` objects can be created through loading data from the disk via one of the various [`mne.io.read_raw_xxx()`](https://mne.tools/stable/api/reading_raw_data.html) functions.\n",
    "\n",
    "`RawArray` objects can be created from data [arrays](https://numpy.org/doc/stable/reference/arrays.html) directly."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "08faf2c6",
   "metadata": {},
   "source": [
    "### Part 1 - Reading timeseries data from disk\n",
    "\n",
    "To familiarise ourselves with `Raw` objects, we will start by loading [MNE's sample dataset](https://mne.tools/stable/documentation/datasets.html#sample)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1be1ad46",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Filepath to MNE's sample dataset on disk\n",
    "sample_data_folder = mne.datasets.sample.data_path()\n",
    "\n",
    "# Load sample data from disk\n",
    "raw = mne.io.read_raw_fif(\n",
    "    os.path.join(sample_data_folder, \"MEG\", \"sample\", \"sample_audvis_raw.fif\")\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ff126be",
   "metadata": {},
   "source": [
    "`Raw` objects contain:\n",
    "- the timeseries data\n",
    "- the metadata, stored under the `info` attribute"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f453cf46",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Show information about the data object\n",
    "raw.info"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8586edd",
   "metadata": {},
   "source": [
    "For example, here you can see that the data we have loaded contains a mixture of MEG data (gradiometers and magnetometers) and EEG data sampled at 600 Hz, as well as the timings of stimulus presentation and subject behaviour during the recording ([stimulus channels](https://mne.tools/stable/documentation/glossary.html#term-stim-channel))."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bcb90bb1",
   "metadata": {},
   "source": [
    "The data itself can be accessed via the [`get_data()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.get_data) method, which returns an array of shape `(channels, times)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7968a4cf",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get data as an array\n",
    "data = raw.get_data()\n",
    "print(f\"Data has shape: {data.shape} (channels, times)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8bc07090",
   "metadata": {},
   "source": [
    "`Raw` objects have various methods for working with timeseries data, such as:\n",
    "- isolating specific channels - [`pick()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.pick), [`drop_channels()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.drop_channels)\n",
    "- isolating specific windows of time - [`crop()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.crop)\n",
    "- spectral filtering of the data - [`filter()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.filter), [`notch_filter()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.notch_filter)\n",
    "- plotting the data - [`plot()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.plot)\n",
    "- computing the power spectra of the data - [`compute_psd()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.compute_psd)\n",
    "\n",
    "We will explore some of these methods below, and others in later notebooks."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "050840af",
   "metadata": {},
   "source": [
    "**Exercises - Manipulating `Raw` objects**\n",
    "\n",
    "We will start by selecting only a subset of channels to store in our `Raw` object, using the [`pick()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.pick) method.\n",
    "\n",
    "`pick()` accepts channel names, channel types, or channel indices as input, and retains only those channels that match this criteria.\n",
    "\n",
    "Below, we select only the MEG channels.\n",
    "\n",
    "*Hint:* Generally in MNE, methods will modify the object in-place to save memory. Because we want to play around with the data without modifying the original object, we will first make a copy of the `Raw` object using the [`copy()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.copy) method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dc53d8f0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a copy of the data so that we can manipulate it\n",
    "raw_copy = raw.copy()\n",
    "\n",
    "# Select the MEG channels only\n",
    "raw_copy.pick(\"meg\")\n",
    "\n",
    "# Verify that we have only MEG channels\n",
    "print(raw_copy.get_data().shape)\n",
    "raw_copy.info"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "763f5cb0",
   "metadata": {},
   "source": [
    "As you can see, the new `Raw` object now has only 306 channels, corresponding to the 203 Gradiometers and 102 Magnetometers (as well as 1 'bad' channel where the data was not properly recorded)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7b513315",
   "metadata": {},
   "source": [
    "**Exercise:** Select only the EEG channels from the original `Raw` object, and verify that only these channels remain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ba1a38be",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Remember to copy the original data!\n",
    "raw_copy = raw.copy()\n",
    "\n",
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ffc94b9",
   "metadata": {},
   "source": [
    "**Exercise:** Now select the EEG and MEG channels simultaneously, and verify that only these channels remain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2b7c6b0e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Remember to copy the original data\n",
    "raw_copy = raw.copy()\n",
    "\n",
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84739775",
   "metadata": {},
   "source": [
    "\n",
    "**Exercise:** Select the EEG and stimulus channels simultaneously, and verify that only these channels remain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59e0cc90",
   "metadata": {},
   "outputs": [],
   "source": [
    "raw_copy = raw.copy()\n",
    "\n",
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57ff82a2",
   "metadata": {},
   "source": [
    "**Exercise:** Select three channels of your choice by specifying their names, and verify that only these channels remain.\n",
    "\n",
    "*Hint:* channel names are stored in the `ch_names` attribute of the `Raw` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2fc3b959",
   "metadata": {},
   "outputs": [],
   "source": [
    "raw_copy = raw.copy()\n",
    "\n",
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4519d91e",
   "metadata": {},
   "source": [
    "To proceed, we will select only the EEG data from the original `Raw` object.\n",
    "\n",
    "Having isolated the EEG data, we can visualise it using the [`plot()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.plot) method.\n",
    "\n",
    "Navigate through the different channels using the up and down arrow keys, and navigate through the timepoints using the left and right arrow keys.\n",
    "\n",
    "The home key reduces the time window displayed, and the end key increases the time window displayed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e2b1a4fa",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Select EEG data\n",
    "raw_eeg = raw.copy().pick(\"eeg\")\n",
    "\n",
    "# Plot EEG data\n",
    "raw_eeg.plot(scalings=\"auto\");"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2f29a9af",
   "metadata": {},
   "source": [
    "We can also plot the locations of the EEG sensors using the [`plot_sensors()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.plot_sensors) method.\n",
    "\n",
    "Why is one of the channels red?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e36e7d3",
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "# Plot EEG sensors\n",
    "raw_eeg.plot_sensors(show_names=True);\n",
    "\n",
    "%matplotlib widget"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fbe0e7f4",
   "metadata": {},
   "source": [
    "If you go to the end of the recording, you will see that is has a duration of ~280 seconds.\n",
    "\n",
    "You can find the exact end time using the `times` attribute of the `Raw` object, which contains the times of each sample in the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2904d6e2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Show how many timepoints are in the data\n",
    "print(f\"{raw_eeg.times.shape[0]} timepoints in the data\")\n",
    "\n",
    "# Take the last timepoint to show the duration of the data\n",
    "print(f\"{raw_eeg.times[-1] :.0f} seconds of data\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c049907a",
   "metadata": {},
   "source": [
    "Just like we were able to select only a specific set of channels, we can also select only a specific window of time using the [`crop()`](https://mne.tools/stable/generated/mne.io.Raw.html#mne.io.Raw.crop) method.\n",
    "\n",
    "Below, we omit the first 10 seconds of the recording (as for `pick()`, this modifies the object in-place)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a1ad3dd0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Units of time should be in seconds\n",
    "raw_eeg.crop(tmin=10, tmax=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2ded8c3",
   "metadata": {},
   "source": [
    "**Exercise:** Verify that the duration of the recording has been reduced by 10 seconds by plotting the data or using the number of timepoints."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f6618fed",
   "metadata": {},
   "outputs": [],
   "source": [
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6ffd302",
   "metadata": {},
   "source": [
    "**Exercise:** Omit the last 10 seconds of the same object, and verify that the duration of the recording has been reduced by a further 10 seconds."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "84772f27",
   "metadata": {},
   "outputs": [],
   "source": [
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d565cad",
   "metadata": {},
   "source": [
    "**Exercise:** Select only the time between 30 and 60 seconds, and verify that the duration of the recording is now 30 seconds."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e496b76c",
   "metadata": {},
   "outputs": [],
   "source": [
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d66e14b8",
   "metadata": {},
   "source": [
    "With this brief overview of `Raw` objects, we have seen how timeseries data can loaded and manipulated in MNE.\n",
    "\n",
    "Generally, timeseries data is loaded from disk using one of the many `mne.read_raw_xxx()` functions tailored to specific data formats, like we have done above.\n",
    "\n",
    "See also the [MNE-BIDS](https://mne.tools/mne-bids/stable/index.html) package for loading data in the BIDS format.\n",
    "\n",
    "However, it is sometimes also useful to create `Raw` objects from arrays directly, which we will explore below."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6db6258f",
   "metadata": {},
   "source": [
    "### Part 2 - Creating `RawArray` objects from data arrays\n",
    "\n",
    "Rather than using `Raw` objects to store data from arrays, we must instead use the [`RawArray`](https://mne.tools/stable/generated/mne.io.RawArray.html) class.\n",
    "\n",
    "But first, this requires having some data to store!\n",
    "\n",
    "Below we randomly generate some data consisting of 3 channels and 1,000 timepoints. Remember, MNE expects timeseries data to have shape `(channels, times)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0ba02d9e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define parameters for generating data\n",
    "n_channels = 3\n",
    "n_times = 1000  # samples\n",
    "np.random.seed(44)  # set seed for consistency\n",
    "\n",
    "# Generate the data\n",
    "data = np.random.randn(n_channels, n_times)\n",
    "print(f\"Data has shape: {data.shape} (channels, times)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cddeb137",
   "metadata": {},
   "source": [
    "If we want to store this data in a `RawArray` object, we need to also specify the metadata, so that MNE can keep track of what the data represents.\n",
    "\n",
    "This information is stored as an [`mne.Info`](https://mne.tools/stable/generated/mne.Info.html) object, which we create using the [`mne.create_info()`](https://mne.tools/stable/generated/mne.create_info.html) function.\n",
    "\n",
    "For this, we need to specify:\n",
    "- the names of the channels - `ch_names` parameter\n",
    "- the types of the channels - `ch_types` parameter\n",
    "- the sampling frequency - `sfreq` parameter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b2faff92",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the data information\n",
    "info = mne.create_info(ch_names=[\"CH_1\", \"CH_2\", \"CH_3\"], ch_types=\"eeg\", sfreq=100)\n",
    "\n",
    "# Show what is stored in the information object\n",
    "print(f\"Channel names: {info['ch_names']}\")\n",
    "info"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2129fa5e",
   "metadata": {},
   "source": [
    "As you can see, we have created an `Info` object for 3 EEG channels. We arbitrarily set the sampling frequency to 100 Hz (with 1,000 samples, this corresponds to 10 seconds of data)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6a92807",
   "metadata": {},
   "source": [
    "**Exercises - Creating `RawArray` objects from arrays**\n",
    "\n",
    "We can also specify the types of each channel separately using the `ch_types` argument.\n",
    "\n",
    "**Exercise:** Create an `Info` object for 3 EEG channels, specifying the type of each channel separately."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "44e87423",
   "metadata": {},
   "outputs": [],
   "source": [
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a0cf65af",
   "metadata": {},
   "source": [
    "**Exercise:** Create an `Info` object for 3 channels, where the first is EEG, the second a gradiometer, and the third a magnetometer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7a91f535",
   "metadata": {},
   "outputs": [],
   "source": [
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee132d5e",
   "metadata": {},
   "source": [
    "As you may have noticed, specific bits of information can be accessed from the `Info` object in the same way you would access information from a [dictionary](https://docs.python.org/3/tutorial/datastructures.html#dictionaries).\n",
    "\n",
    "**Exercise:** Get the sampling frequency from the `Info` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "360aa365",
   "metadata": {},
   "outputs": [],
   "source": [
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e3880447",
   "metadata": {},
   "source": [
    "**Exercise:** Get the channel names from the `Info` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ea627cb5",
   "metadata": {},
   "outputs": [],
   "source": [
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba1f1300",
   "metadata": {},
   "source": [
    "Using an `Info` object where all 3 channels are EEG, we can now create a `RawArray` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "81e53afb",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create data information\n",
    "info = mne.create_info(ch_names=[\"CH_1\", \"CH_2\", \"CH_3\"], ch_types=\"eeg\", sfreq=100)\n",
    "\n",
    "# Store the data and information in a RawArray object\n",
    "raw = mne.io.RawArray(data=data, info=info)\n",
    "\n",
    "# Show what is stored in the RawArray object\n",
    "raw.info"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "34f7bdc6",
   "metadata": {},
   "source": [
    "Although the `RawArray` object is of a different class to the `Raw` object we were working with before, is still supports the same methods, e.g. [`pick()`](https://mne.tools/stable/generated/mne.io.RawArray.html#mne.io.RawArray.pick), [`crop()`](https://mne.tools/stable/generated/mne.io.RawArray.html#mne.io.RawArray.crop), [`plot()`](https://mne.tools/stable/generated/mne.io.RawArray.html#mne.io.RawArray.plot), etc...\n",
    "\n",
    "Here we again use [`plot()`](https://mne.tools/stable/generated/mne.io.RawArray.html#mne.io.RawArray.plot) to visualise the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7c390f91",
   "metadata": {},
   "outputs": [],
   "source": [
    "raw.plot(scalings=\"auto\");"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc7a7a28",
   "metadata": {},
   "source": [
    "The `Info` object we created is now stored under the `info` attribute of the `RawArray` object.\n",
    "\n",
    "**Exercise:** Get the sampling frequency from the `info` attribute of the `RawArray` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "57261fa1",
   "metadata": {},
   "outputs": [],
   "source": [
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48ba0a80",
   "metadata": {},
   "source": [
    "**Exercise:** Get the channel names from the `info` attribute of the `RawArray` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c1aaeaad",
   "metadata": {},
   "outputs": [],
   "source": [
    "## CODE GOES HERE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e7bba4e",
   "metadata": {},
   "source": [
    "## Conclusion\n",
    "\n",
    "`Raw` class objects are one of the most heavily used items in the MNE package, being the way in which timeseries data is stored.\n",
    "\n",
    "They can be created easily from data stored on the disk (`mne.read_raw_xxx()` -> `Raw`), or from arrays (`array` -> `RawArray`).\n",
    "\n",
    "Here we have covered the very basic aspects of handling timeseries data in MNE. In later notebooks, we will explore the more advanced features of `Raw` objects, including filtering activity in particular frequency ranges, and computing the power spectral densities of data."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de913f10",
   "metadata": {},
   "source": [
    "## Additional resources\n",
    "\n",
    "MNE tutorial on `Raw` objects: https://mne.tools/stable/auto_tutorials/raw/10_raw_overview.html"
   ]
  }
 ],
 "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.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}