eegdash 0.4.0.dev173498563__tar.gz → 0.4.1__tar.gz

{eegdash-0.4.0.dev173498563/eegdash.egg-info → eegdash-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.4.0.dev173498563
+Version: 0.4.1
 Summary: EEG data for machine learning
 Author-email: Young Truong <dt.young112@gmail.com>, Arnaud Delorme <adelorme@gmail.com>, Aviv Dotan <avivd220@gmail.com>, Oren Shriki <oren70@gmail.com>, Bruno Aristimunha <b.aristimunha@gmail.com>
 License-Expression: GPL-3.0-only
@@ -27,23 +27,17 @@ License-File: LICENSE
 Requires-Dist: braindecode>=1.0
 Requires-Dist: mne_bids>=0.17.0
 Requires-Dist: numba
-Requires-Dist: numpy
-Requires-Dist: pandas
-Requires-Dist: pybids
 Requires-Dist: pymongo
-Requires-Dist: python-dotenv
 Requires-Dist: s3fs
-Requires-Dist: scipy
 Requires-Dist: tqdm
-Requires-Dist: h5io>=0.2.4
 Requires-Dist: pymatreader
 Requires-Dist: eeglabio
 Requires-Dist: tabulate
-Requires-Dist: docstring_inheritance
 Requires-Dist: rich
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: pytest-sugar; extra == "tests"
 Requires-Dist: codecov; extra == "tests"
 Requires-Dist: pytest_cases; extra == "tests"
 Requires-Dist: pytest-benchmark; extra == "tests"
@@ -66,10 +60,14 @@ Requires-Dist: lightgbm; extra == "docs"
 Requires-Dist: plotly; extra == "docs"
 Requires-Dist: nbformat; extra == "docs"
 Requires-Dist: graphviz; extra == "docs"
+Provides-Extra: digestion
+Requires-Dist: pybids; extra == "digestion"
+Requires-Dist: python-dotenv; extra == "digestion"
 Provides-Extra: all
 Requires-Dist: eegdash[docs]; extra == "all"
 Requires-Dist: eegdash[dev]; extra == "all"
 Requires-Dist: eegdash[tests]; extra == "all"
+Requires-Dist: eegdash[digestion]; extra == "all"
 Dynamic: license-file
 
 # EEG-Dash

eegdash-0.4.1/docs/build/html/_downloads/06c8d94b7e0b8be2de39fdc122dd12bb/tutorial_challenge_2.ipynb

@@ -0,0 +1,261 @@
+{
+  "cells": [
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# For tips on running notebooks in Google Colab:\n# `pip install eegdash`\n%matplotlib inline"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n.. meta::\n   :html_theme.sidebar_secondary.remove: true\n\n# Challenge 2: Predicting the p-factor from EEG\n   :depth: 2\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<img src=\"https://colab.research.google.com/assets/colab-badge.svg\" target=\"https://colab.research.google.com/github/eeg2025/startkit/blob/main/challenge_2.ipynb\" alt=\"Open In Colab\">\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Preliminary notes\nBefore we begin, I just want to make a deal with you, ok?\nThis is a community competition with a strong open-source foundation.\nWhen I say open-source, I mean volunteer work.\n\nSo, if you see something that does not work or could be improved, first, **please be kind**, and\nwe will fix it together on GitHub, okay?\n\nThe entire decoding community will only go further when we stop\nsolving the same problems over and over again, and it starts working together.\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Overview\nThe psychopathology factor (P-factor) is a widely recognized construct in mental health research, representing a common underlying dimension of psychopathology across various disorders.\nCurrently, the P-factor is often assessed using self-report questionnaires or clinician ratings, which can be subjective, prone to bias, and time-consuming.\n**The Challenge 2** consists of developing a model to predict the P-factor from EEG recordings.\n\nThe challenge encourages learning physiologically meaningful signal representations and discovery of reproducible biomarkers.\nModels of any size should emphasize robust, interpretable features that generalize across subjects,\nsessions, and acquisition sites.\n\nUnlike a standard in-distribution classification task, this regression problem stresses out-of-distribution robustness\nand extrapolation. The goal is not only to minimize error on seen subjects, but also to transfer effectively to unseen data.\nEnsure the dataset is available locally. If not, see the\n[dataset download guide](https://eeg2025.github.io/data/#downloading-the-data)_.\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Contents of this start kit\n<div class=\"alert alert-info\"><h4>Note</h4><p>If you need additional explanations on the\n   :doc:`EEGChallengeDataset\n   </api/dataset/eegdash.dataset.EEGChallengeDataset>` class, dataloading,\n   [braindecode](https://braindecode.org/stable/models/models_table.html)_'s\n   deep learning models, or brain decoding in general, please refer to the\n   start-kit of challenge 1 which delves deeper into these topics.</p></div>\n\nMore contents will be released during the competition inside the\n:mod:`eegdash` [examples webpage](https://eeglab.org/EEGDash/generated/auto_examples/index.html)_.\n\n.. admonition:: Prerequisites\n   :class: important\n\n   The tutorial assumes prior knowledge of:\n\n   - Standard neural network architectures (e.g., CNNs)\n   - Optimization by batch gradient descent and backpropagation\n   - Overfitting, early stopping, and regularization\n   - Some knowledge of PyTorch\n   - Basic familiarity with EEG and preprocessing\n   - An appreciation for open-source work :)\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Install dependencies on Colab\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>These installs are optional; skip on local environments\n   where you already have the dependencies installed.</p></div>\n\n```bash\npip install eegdash\n```\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Imports\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "from pathlib import Path\nimport math\nimport os\nimport random\nfrom joblib import Parallel, delayed\n\nimport torch\nfrom torch.utils.data import DataLoader\nfrom torch import optim\nfrom torch.nn.functional import l1_loss\nfrom braindecode.preprocessing import create_fixed_length_windows\nfrom braindecode.datasets.base import EEGWindowsDataset, BaseConcatDataset, BaseDataset\nfrom braindecode.models import EEGNeX\nfrom eegdash import EEGChallengeDataset"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<div class=\"alert alert-danger\"><h4>Warning</h4><p>In case of Colab, before starting, make sure you're on a GPU instance\n   for faster training! If running on Google Colab, please request a GPU runtime\n   by clicking `Runtime/Change runtime type` in the top bar menu, then selecting\n   'T4 GPU' under 'Hardware accelerator'.</p></div>\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Identify whether a CUDA-enabled GPU is available\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "device = \"cuda\" if torch.cuda.is_available() else \"cpu\"\nif device == \"cuda\":\n    msg = \"CUDA-enabled GPU found. Training should be faster.\"\nelse:\n    msg = (\n        \"No GPU found. Training will be carried out on CPU, which might be \"\n        \"slower.\\n\\nIf running on Google Colab, you can request a GPU runtime by\"\n        \" clicking\\n`Runtime/Change runtime type` in the top bar menu, then \"\n        \"selecting 'T4 GPU'\\nunder 'Hardware accelerator'.\"\n    )\nprint(msg)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Understanding the P-factor regression task.\n\nThe psychopathology factor (P-factor) is a widely recognized construct in mental health research, representing a common underlying dimension of psychopathology across various disorders.\nThe P-factor is thought to reflect the shared variance among different psychiatric conditions, suggesting that individuals with higher P-factor scores may be more vulnerable to a range of mental health issues.\nCurrently, the P-factor is often assessed using self-report questionnaires or clinician ratings, which can be subjective, prone to bias, and time-consuming.\nIn the dataset of this challenge, the P-factor was assessed using the Child\nBehavior Checklist (CBCL) [McElroy et al., (2017)](https://doi.org/10.1111/jcpp.12849)_.\n\nThe goal of Challenge 2 is to develop a model to predict the P-factor from EEG recordings.\n**The feasibility of using EEG data for this purpose is still an open question**.\nThe solution may involve finding meaningful representations of the EEG data that correlate with the P-factor scores.\nThe challenge encourages learning physiologically meaningful signal representations and discovery of reproducible biomarkers.\nIf contestants are successful in this task, it could pave the way for more objective and efficient assessments of the P-factor in clinical settings.\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Define local path and (down)load the data\nIn this challenge 2 example, we load the EEG 2025 release using\n:doc:`EEGChallengeDataset </api/dataset/eegdash.dataset.EEGChallengeDataset>`.\n**Note:** in this example notebook, we load the contrast change detection task from one mini release only as an example. Naturally, you are encouraged to train your models on all complete releases, using data from all the tasks you deem relevant.\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The first step is to define the cache folder!\nMatch tests' cache layout under ~/eegdash_cache/eeg_challenge_cache\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "DATA_DIR = (Path.home() / \"eegdash_cache\" / \"eeg_challenge_cache\").resolve()\n\n# Creating the path if it does not exist\nDATA_DIR.mkdir(parents=True, exist_ok=True)\n\n# We define the list of releases to load.\n# Here, only release 5 is loaded.\nrelease_list = [\"R5\"]\n\nall_datasets_list = [\n    EEGChallengeDataset(\n        release=release,\n        task=\"contrastChangeDetection\",\n        mini=True,\n        description_fields=[\n            \"subject\",\n            \"session\",\n            \"run\",\n            \"task\",\n            \"age\",\n            \"gender\",\n            \"sex\",\n            \"p_factor\",\n        ],\n        cache_dir=DATA_DIR,\n    )\n    for release in release_list\n]\nprint(\"Datasets loaded\")\nsub_rm = [\"NDARWV769JM7\"]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Combine the datasets into a single one\nHere, we combine the datasets from the different releases into a single\n``BaseConcatDataset`` object.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "all_datasets = BaseConcatDataset(all_datasets_list)\nprint(all_datasets.description)\n\nraws = Parallel(n_jobs=os.cpu_count())(\n    delayed(lambda d: d.raw)(d) for d in all_datasets.datasets\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Inspect your data\nWe can check what is inside the dataset consuming the\nMNE-object inside the Braindecode dataset.\n\nThe following snippet, if uncommented, will show the first 10 seconds of the raw EEG signal.\nWe can also inspect the data further by looking at the events and annotations.\nWe strongly recommend you to take a look into the details and check how the events are structured.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "raw = all_datasets.datasets[0].raw  # mne.io.Raw object\n\nprint(raw.info)\n\nraw.plot(duration=10, scalings=\"auto\", show=True)\n\nprint(raw.annotations)\n\nSFREQ = 100"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Wrap the data into a PyTorch-compatible dataset\nThe class below defines a dataset wrapper that will extract 2-second windows,\nuniformly sampled over the whole signal. In addition, it will add useful information\nabout the extracted windows, such as the p-factor, the subject or the task.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "class DatasetWrapper(BaseDataset):\n    def __init__(self, dataset: EEGWindowsDataset, crop_size_samples: int, seed=None):\n        self.dataset = dataset\n        self.crop_size_samples = crop_size_samples\n        self.rng = random.Random(seed)\n\n    def __len__(self):\n        return len(self.dataset)\n\n    def __getitem__(self, index):\n        X, _, crop_inds = self.dataset[index]\n\n        # P-factor label:\n        p_factor = self.dataset.description[\"p_factor\"]\n        p_factor = float(p_factor)\n\n        # Additional information:\n        infos = {\n            \"subject\": self.dataset.description[\"subject\"],\n            \"sex\": self.dataset.description[\"sex\"],\n            \"age\": float(self.dataset.description[\"age\"]),\n            \"task\": self.dataset.description[\"task\"],\n            \"session\": self.dataset.description.get(\"session\", None) or \"\",\n            \"run\": self.dataset.description.get(\"run\", None) or \"\",\n        }\n\n        # Randomly crop the signal to the desired length:\n        i_window_in_trial, i_start, i_stop = crop_inds\n        assert i_stop - i_start >= self.crop_size_samples, f\"{i_stop=} {i_start=}\"\n        start_offset = self.rng.randint(0, i_stop - i_start - self.crop_size_samples)\n        i_start = i_start + start_offset\n        i_stop = i_start + self.crop_size_samples\n        X = X[:, start_offset : start_offset + self.crop_size_samples]\n\n        return X, p_factor, (i_window_in_trial, i_start, i_stop), infos\n\n\n# We filter out certain recordings, create fixed length windows and finally make use of our `DatasetWrapper`."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Filter out recordings that are too short\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "all_datasets = BaseConcatDataset(\n    [\n        ds\n        for ds in all_datasets.datasets\n        if ds.description.subject not in sub_rm\n        and ds.raw.n_times >= 4 * SFREQ\n        and len(ds.raw.ch_names) == 129\n        and not math.isnan(ds.description[\"p_factor\"])\n    ]\n)\n\n# Create 4-seconds windows with 2-seconds stride\nwindows_ds = create_fixed_length_windows(\n    all_datasets,\n    window_size_samples=4 * SFREQ,\n    window_stride_samples=2 * SFREQ,\n    drop_last_window=True,\n)\n\n# Wrap each sub-dataset in the windows_ds\nwindows_ds = BaseConcatDataset(\n    [DatasetWrapper(ds, crop_size_samples=2 * SFREQ) for ds in windows_ds.datasets]\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Inspect the label distribution\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import numpy as np\nfrom skorch.helper import SliceDataset\n\ny_label = np.array(list(SliceDataset(windows_ds, 1)))\n\n# Plot histogram of the response times with matplotlib\nimport matplotlib.pyplot as plt\n\nfig, ax = plt.subplots(figsize=(10, 5))\nax.hist(y_label)\nax.set_title(\"Response Time Distribution\")\nax.set_xlabel(\"Response Time (s)\")\nax.set_ylabel(\"Count\")\nplt.tight_layout()\nplt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Define, train and save a model\n ---------------------------------\n Now we have our pytorch dataset necessary for the training!\n\n Below, we define a simple EEGNeX model from Braindecode.\n All the braindecode models expect the input to be of shape (batch_size, n_channels, n_times)\n and have a test coverage about the behavior of the model.\n However, you can use any pytorch model you want.\n\n#####################################################################\n Initialize model\n -----------------\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "model = EEGNeX(n_chans=129, n_outputs=1, n_times=2 * SFREQ).to(device)\n\n# Specify optimizer\noptimizer = optim.Adamax(params=model.parameters(), lr=0.002)\n\nprint(model)\n\n\n# Finally, we can train our model. Here we define a simple training loop using pure PyTorch.\n# In this example, we only train for a single epoch. Feel free to increase the number of epochs.\n# Create PyTorch Dataloader\n\nnum_workers = (\n    0  # Set num_workers to 0 to avoid multiprocessing issues in notebooks/tutorials.\n)\ndataloader = DataLoader(\n    windows_ds, batch_size=128, shuffle=True, num_workers=num_workers\n)\n\nn_epochs = 1\n\n# Train model for 1 epoch\nfor epoch in range(n_epochs):\n    for idx, batch in enumerate(dataloader):\n        # Reset gradients\n        optimizer.zero_grad()\n\n        # Unpack the batch\n        X, y, crop_inds, infos = batch\n        X = X.to(dtype=torch.float32, device=device)\n        y = y.to(dtype=torch.float32, device=device).unsqueeze(1)\n\n        # Forward pass\n        y_pred = model(X)\n\n        # Compute loss\n        loss = l1_loss(y_pred, y)\n        print(f\"Epoch {0} - step {idx}, loss: {loss.item()}\")\n\n        # Gradient backpropagation\n        loss.backward()\n        optimizer.step()\n\n# Finally, we can save the model for later use\ntorch.save(model.state_dict(), \"weights_challenge_2.pt\")\nprint(\"Model saved as 'weights_challenge_2.pt'\")"
+      ]
+    }
+  ],
+  "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.11"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

eegdash-0.4.1/docs/build/html/_downloads/2c592649a2079630923cb072bc1beaf3/tutorial_eoec.ipynb

@@ -0,0 +1,187 @@
+{
+  "cells": [
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# For tips on running notebooks in Google Colab:\n# `pip install eegdash`\n%matplotlib inline"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# Eyes Open vs. Closed Classification\n\nEEGDash example for eyes open vs. closed classification.\n\nThis example uses the :mod:`eegdash` library in combination with PyTorch to develop a deep learning model for analyzing EEG data, specifically for eyes open vs. closed classification in a single subject.\n\n1. **Data Retrieval Using EEGDash**: An instance of :class:`eegdash.api.EEGDashDataset` is created to search and retrieve an EEG dataset. At this step, only the metadata is transferred.\n\n2. **Data Preprocessing Using BrainDecode**: This process preprocesses EEG data using Braindecode by reannotating events, selecting specific channels, resampling, filtering, and extracting 2-second epochs, ensuring balanced eyes-open and eyes-closed data for analysis.\n\n3. **Creating train and testing sets**: The dataset is split into training (80%) and testing (20%) sets with balanced labels, converted into PyTorch tensors, and wrapped in DataLoader objects for efficient mini-batch training.\n\n4. **Model Definition**: The model is a shallow convolutional neural network (ShallowFBCSPNet) with 24 input channels (EEG channels), 2 output classes (eyes-open and eyes-closed).\n\n5. **Model Training and Evaluation Process**: This section trains the neural network, normalizes input data, computes cross-entropy loss, updates model parameters, and evaluates classification accuracy over six epochs.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Data Retrieval Using EEGDash\n\nThis section instantiates :class:`eegdash.api.EEGDashDataset` to fetch\nthe metadata for the experiment before requesting any recordings.\n\nFirst we find one resting state dataset. This dataset contains both eyes open\nand eyes closed data.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "from pathlib import Path\n\ncache_folder = Path.home() / \"eegdash\""
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "from eegdash import EEGDashDataset\n\nds_eoec = EEGDashDataset(\n    query={\"dataset\": \"ds005514\", \"task\": \"RestingState\", \"subject\": \"NDARDB033FW5\"},\n    cache_dir=cache_folder,\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Data Preprocessing Using Braindecode\n\n[braindecode](https://braindecode.org/stable/install/install.html)_ is a\nspecialized library for preprocessing EEG and MEG data. In this dataset, there\nare two key events in the continuous data: **instructed_toCloseEyes**, marking\nthe start of a 40-second eyes-closed period, and **instructed_toOpenEyes**,\nindicating the start of a 20-second eyes-open period.\n\nFor the eyes-closed event, we extract 14 seconds of data from 15 to 29 seconds\nafter the event onset. Similarly, for the eyes-open event, we extract data\nfrom 5 to 19 seconds after the event onset. This ensures an equal amount of\ndata for both conditions. The event extraction is handled by the custom\nfunction :func:`eegdash.hbn.preprocessing.hbn_ec_ec_reannotation`.\n\nNext, we apply four preprocessing steps in Braindecode:\n1. **Reannotation** of event markers using :func:`eegdash.hbn.preprocessing.hbn_ec_ec_reannotation`.\n2. **Selection** of 24 specific EEG channels from the original 128.\n3. **Resampling** the EEG data to a frequency of 128 Hz.\n4. **Filtering** the EEG signals to retain frequencies between 1 Hz and 55 Hz.\n\nWhen calling the `preprocess` function, the data is retrieved from the remote\nrepository.\n\nFinally, we use `create_windows_from_events` to extract 2-second epochs from\nthe data. These epochs serve as the dataset samples. At this stage, each\nsample is automatically labeled with the corresponding event type (eyes-open\nor eyes-closed). `windows_ds` is a PyTorch dataset, and when queried, it\nreturns labels for eyes-open and eyes-closed (assigned as labels 0 and 1,\ncorresponding to their respective event markers).\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "from braindecode.preprocessing import (\n    preprocess,\n    Preprocessor,\n    create_windows_from_events,\n)\nimport numpy as np\nfrom eegdash.hbn.preprocessing import hbn_ec_ec_reannotation\nimport warnings\n\nwarnings.simplefilter(\"ignore\", category=RuntimeWarning)\n\n\n# BrainDecode preprocessors\npreprocessors = [\n    hbn_ec_ec_reannotation(),\n    Preprocessor(\n        \"pick_channels\",\n        ch_names=[\n            \"E22\",\n            \"E9\",\n            \"E33\",\n            \"E24\",\n            \"E11\",\n            \"E124\",\n            \"E122\",\n            \"E29\",\n            \"E6\",\n            \"E111\",\n            \"E45\",\n            \"E36\",\n            \"E104\",\n            \"E108\",\n            \"E42\",\n            \"E55\",\n            \"E93\",\n            \"E58\",\n            \"E52\",\n            \"E62\",\n            \"E92\",\n            \"E96\",\n            \"E70\",\n            \"Cz\",\n        ],\n    ),\n    Preprocessor(\"resample\", sfreq=128),\n    Preprocessor(\"filter\", l_freq=1, h_freq=55),\n]\npreprocess(ds_eoec, preprocessors)\n\n# Extract 2-second segments\nwindows_ds = create_windows_from_events(\n    ds_eoec,\n    trial_start_offset_samples=0,\n    trial_stop_offset_samples=256,\n    preload=True,\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Plotting a Single Channel for One Sample\n\nIt\u2019s always a good practice to verify that the data has been properly loaded\nand processed. Here, we plot a single channel from one sample to ensure the\nsignal is present and looks as expected.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import matplotlib.pyplot as plt\n\nplt.figure()\nplt.plot(windows_ds[2][0][0, :].transpose())  # first channel of first epoch\nplt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Creating training and test sets\n\nThe code below creates a training and test set. We first split the data into\ntraining and test sets using the **train_test_split** function from the\n**sklearn** library. We then create a **TensorDataset** for the training and\ntest sets.\n\n1. **Set Random Seed** \u2013 The random seed is fixed using\n   `torch.manual_seed(random_state)` to ensure reproducibility in dataset\n   splitting and model training.\n2. **Extract Labels from the Dataset** \u2013 Labels (eye-open or eye-closed\n   events) are extracted from `windows_ds`, stored as a NumPy array, and\n   printed for verification.\n3. **Split Dataset into Train and Test Sets** \u2013 The dataset is split into\n   training (80%) and testing (20%) subsets using `train_test_split()`,\n   ensuring balanced stratification based on the extracted labels.\n4. **Convert Data to PyTorch Tensors** \u2013 The selected training and testing\n   samples are converted into `FloatTensor` for input features and\n   `LongTensor` for labels, making them compatible with PyTorch models.\n5. **Create DataLoaders** \u2013 The datasets are wrapped in PyTorch DataLoader\n   objects with a batch size of 10, enabling efficient mini-batch training and\n   shuffling.\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import torch\nfrom sklearn.model_selection import train_test_split\nfrom torch.utils.data import DataLoader\nfrom torch.utils.data import TensorDataset\n\n# Set random seed for reproducibility\nrandom_state = 42\ntorch.manual_seed(random_state)\nnp.random.seed(random_state)\n\n# Extract labels from the dataset\neo_ec = np.array([ds[1] for ds in windows_ds]).transpose()  # check labels\nprint(\"labels: \", eo_ec)\n\n# Get balanced indices for male and female subjects\ntrain_indices, test_indices = train_test_split(\n    range(len(windows_ds)), test_size=0.2, stratify=eo_ec, random_state=random_state\n)\n\n# Convert the data to tensors\nX_train = torch.FloatTensor(\n    np.array([windows_ds[i][0] for i in train_indices])\n)  # Convert list of arrays to single tensor\nX_test = torch.FloatTensor(\n    np.array([windows_ds[i][0] for i in test_indices])\n)  # Convert list of arrays to single tensor\ny_train = torch.LongTensor(eo_ec[train_indices])  # Convert targets to tensor\ny_test = torch.LongTensor(eo_ec[test_indices])  # Convert targets to tensor\ndataset_train = TensorDataset(X_train, y_train)\ndataset_test = TensorDataset(X_test, y_test)\n\n# Create data loaders for training and testing (batch size 10)\ntrain_loader = DataLoader(dataset_train, batch_size=10, shuffle=True)\ntest_loader = DataLoader(dataset_test, batch_size=10, shuffle=True)\n\n# Print shapes and sizes to verify split\nprint(\n    f\"Shape of data {X_train.shape} number of samples - Train: {len(train_loader)}, Test: {len(test_loader)}\"\n)\nprint(\n    f\"Eyes-Open/Eyes-Closed balance, train: {np.mean(eo_ec[train_indices]):.2f}, test: {np.mean(eo_ec[test_indices]):.2f}\"\n)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Check labels\n\nIt is good practice to verify the labels and ensure the random seed is\nfunctioning correctly. If all labels are 0s (eyes closed) or 1s (eyes open),\nit could indicate an issue with data loading or stratification, requiring\nfurther investigation.\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Visualize a batch of target labels\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "dataiter = iter(train_loader)\nfirst_item, label = dataiter.__next__()\nlabel"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Create model\n\nThe model is a shallow convolutional neural network (ShallowFBCSPNet) with 24\ninput channels (EEG channels), 2 output classes (eyes-open and eyes-closed),\nand an input window size of 256 samples (2 seconds of EEG data).\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import torch\nimport numpy as np\nfrom torch.nn import functional as F\nfrom braindecode.models import ShallowFBCSPNet\nfrom torchinfo import summary\n\ntorch.manual_seed(random_state)\nmodel = ShallowFBCSPNet(24, 2, n_times=256, final_conv_length=\"auto\")\nsummary(model, input_size=(1, 24, 256))"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Model Training and Evaluation Process\n\nThis section trains the neural network using the Adamax optimizer, normalizes\ninput data, computes cross-entropy loss, updates model parameters, and tracks\naccuracy across six epochs.\n\n1. **Set Up Optimizer and Learning Rate Scheduler** \u2013 The `Adamax` optimizer\n   initializes with a learning rate of 0.002 and weight decay of 0.001 for\n   regularization. An `ExponentialLR` scheduler with a decay factor of 1 keeps\n   the learning rate constant.\n2. **Allocate Model to Device** \u2013 The model moves to the specified device\n   (CPU, GPU, or MPS for Mac silicon) to optimize computation efficiency.\n3. **Normalize Input Data** \u2013 The `normalize_data` function standardizes input\n   data by subtracting the mean and dividing by the standard deviation along\n   the time dimension before transferring it to the appropriate device.\n4. **Evaluates Classification Accuracy Over Six Epochs** \u2013 The training loop\n   iterates through data batches with the model in training mode. It\n   normalizes inputs, computes predictions, calculates cross-entropy loss,\n   performs backpropagation, updates model parameters, and steps the learning\n   rate scheduler. It tracks correct predictions to compute accuracy.\n5. **Evaluate on Test Data** \u2013 After each epoch, the model runs in evaluation\n   mode on the test set. It computes predictions on normalized data and\n   calculates test accuracy by comparing outputs with actual labels.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "optimizer = torch.optim.Adamax(model.parameters(), lr=0.002, weight_decay=0.001)\nscheduler = torch.optim.lr_scheduler.ExponentialLR(optimizer, gamma=1)\n\ndevice = torch.device(\n    \"cuda\"\n    if torch.cuda.is_available()\n    else \"mps\"\n    if torch.backends.mps.is_available()\n    else \"cpu\"\n)\nmodel = model.to(device=device)  # move the model parameters to CPU/GPU\nepochs = 6\n\n\ndef normalize_data(x):\n    mean = x.mean(dim=2, keepdim=True)\n    std = x.std(dim=2, keepdim=True) + 1e-7  # add small epsilon for numerical stability\n    x = (x - mean) / std\n    x = x.to(device=device, dtype=torch.float32)  # move to device, e.g. GPU\n    return x\n\n\nfor e in range(epochs):\n    # training\n    correct_train = 0\n    for t, (x, y) in enumerate(train_loader):\n        model.train()  # put model to training mode\n        scores = model(normalize_data(x))\n        y = y.to(device=device, dtype=torch.long)\n        _, preds = scores.max(1)\n        correct_train += (preds == y).sum() / len(dataset_train)\n\n        loss = F.cross_entropy(scores, y)\n        optimizer.zero_grad()\n        loss.backward()\n        optimizer.step()\n        scheduler.step()\n\n    # Validation\n    correct_test = 0\n    for t, (x, y) in enumerate(test_loader):\n        model.eval()  # put model to testing mode\n        scores = model(normalize_data(x))\n        y = y.to(device=device, dtype=torch.long)\n        _, preds = scores.max(1)\n        correct_test += (preds == y).sum() / len(dataset_test)\n\n    # Reporting\n    print(\n        f\"Epoch {e}, Train accuracy: {correct_train:.2f}, Test accuracy: {correct_test:.2f}\"\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.11"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}