stage 1

Author: bruAristimunha

docs/source/conf.py

@@ -293,6 +293,14 @@ def linkcode_resolve(domain, info):
 registered dynamically from mongo database. The table below summarises
 the distribution by experimental type as tracked in the summary file.
 
+Base Dataset API
+----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   eegdash.dataset.EEGChallengeDataset
+
 .. list-table:: Dataset counts by experimental type
    :widths: 60 20
    :header-rows: 1

examples/core/tutorial_eoec.py

@@ -5,9 +5,9 @@
 
 EEGDash example for eyes open vs. closed classification.
 
-The code below provides an example of using the *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.
+This 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.
 
-1. **Data Retrieval Using EEGDash**: An instance of *EEGDashDataset* is created to search and retrieve an EEG dataset. At this step, only the metadata is transferred.
+1. **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.
 
 2. **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.
 
@@ -22,6 +22,9 @@
 # Data Retrieval Using EEGDash
 # ----------------------------
 #
+# This section instantiates :class:`eegdash.api.EEGDashDataset` to fetch
+# the metadata for the experiment before requesting any recordings.
+#
 # First we find one resting state dataset. This dataset contains both eyes open
 # and eyes closed data.
 from pathlib import Path
@@ -39,7 +42,7 @@
 # Data Preprocessing Using Braindecode
 # ------------------------------------
 #
-# [BrainDecode](https://braindecode.org/stable/install/install.html) is a
+# `braindecode <https://braindecode.org/stable/install/install.html>`__ is a
 # specialized library for preprocessing EEG and MEG data. In this dataset, there
 # are two key events in the continuous data: **instructed_toCloseEyes**, marking
 # the start of a 40-second eyes-closed period, and **instructed_toOpenEyes**,
@@ -49,10 +52,10 @@
 # after the event onset. Similarly, for the eyes-open event, we extract data
 # from 5 to 19 seconds after the event onset. This ensures an equal amount of
 # data for both conditions. The event extraction is handled by the custom
-# function **hbn_ec_ec_reannotation**.
+# function :func:`eegdash.hbn.preprocessing.hbn_ec_ec_reannotation`.
 #
 # Next, we apply four preprocessing steps in Braindecode:
-# 1. **Reannotation** of event markers using `hbn_ec_ec_reannotation()`.
+# 1. **Reannotation** of event markers using :func:`eegdash.hbn.preprocessing.hbn_ec_ec_reannotation`.
 # 2. **Selection** of 24 specific EEG channels from the original 128.
 # 3. **Resampling** the EEG data to a frequency of 128 Hz.
 # 4. **Filtering** the EEG signals to retain frequencies between 1 Hz and 55 Hz.

examples/core/tutorial_feature_extractor_open_close_eye.py

@@ -5,9 +5,9 @@
 
 EEGDash example for eyes open vs. closed classification.
 
-The code below provides an example of using the *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.
+This 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.
 
-1. **Data Retrieval Using EEGDash**: An instance of *EEGDashDataset* is created to search and retrieve an EEG dataset. At this step, only the metadata is transferred.
+1. **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.
 
 2. **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.
 
@@ -23,6 +23,9 @@
 # Data Retrieval Using EEGDash
 # ----------------------------
 #
+# We instantiate :class:`eegdash.api.EEGDashDataset` to pull the experiment
+# metadata and build the dataset definition.
+#
 # First we find one resting state dataset. This dataset contains both eyes open
 # and eyes closed data.
 
@@ -55,10 +58,10 @@
 # after the event onset. Similarly, for the eyes-open event, we extract data
 # from 5 to 19 seconds after the event onset. This ensures an equal amount of
 # data for both conditions. The event extraction is handled by the custom
-# function **hbn_ec_ec_reannotation**.
+# function :func:`eegdash.hbn.preprocessing.hbn_ec_ec_reannotation`.
 #
 # Next, we apply four preprocessing steps in Braindecode:
-# 1. **Reannotation** of event markers using `hbn_ec_ec_reannotation()`.
+# 1. **Reannotation** of event markers using :func:`eegdash.hbn.preprocessing.hbn_ec_ec_reannotation`.
 # 2. **Selection** of 24 specific EEG channels from the original 128.
 # 3. **Resampling** the EEG data to a frequency of 128 Hz.
 # 4. **Filtering** the EEG signals to retain frequencies between 1 Hz and 55 Hz.

examples/eeg2025/tutorial_challenge_2.py

@@ -51,14 +51,13 @@
 # Contents of this start kit
 # --------------------------
 # .. note:: If you need additional explanations on the
-#    `EEGChallengeDataset <https://eeglab.org/EEGDash/api/eegdash.html#eegdash.EEGChallengeDataset>`__
-#    class, dataloading, `braindecode <https://braindecode.org/stable/models/models_table.html>`__'s
+#    :class:`eegdash.dataset.EEGChallengeDataset` class, dataloading,
+#    `braindecode <https://braindecode.org/stable/models/models_table.html>`__'s
 #    deep learning models, or brain decoding in general, please refer to the
 #    start-kit of challenge 1 which delves deeper into these topics.
 #
 # More contents will be released during the competition inside the
-# `eegdash <https://eeglab.org/EEGDash/overview.html>`__
-# `examples webpage <https://eeglab.org/EEGDash/generated/auto_examples/index.html>`__.
+# :mod:`eegdash` `examples webpage <https://eeglab.org/EEGDash/generated/auto_examples/index.html>`__.
 #
 # .. admonition:: Prerequisites
 #    :class: important
@@ -142,7 +141,8 @@
 ######################################################################
 # Define local path and (down)load the data
 # -----------------------------------------
-# In this challenge 2 example, we load the EEG 2025 release using EEG Dash.
+# In this challenge 2 example, we load the EEG 2025 release using
+# :class:`eegdash.dataset.EEGChallengeDataset`.
 # **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.
 
 ######################################################################

examples/eeg2025/tutorial_eegdash_offline.py

@@ -4,8 +4,9 @@
 
 Many HPC clusters restrict or block network access. It's common to have
 dedicated queues for internet-enabled jobs that differ from GPU queues.
-This tutorial shows how to use EEGDash offline once a dataset is present
-on disk.
+This tutorial shows how to use :doc:`EEGChallengeDataset
+<api/dataset/eegdash.dataset.EEGChallengeDataset>` offline once a dataset is
+present on disk.
 """
 
 from pathlib import Path
@@ -15,8 +16,9 @@
 from eegdash.dataset.dataset import EEGChallengeDataset
 
 
-# We'll use Release R2 as an example (HBN subset). EEGChallengeDataset uses a
-# suffixed cache folder for the competition data (e.g., "-bdf-mini").
+# We'll use Release R2 as an example (HBN subset).
+# :class:`eegdash.dataset.EEGChallengeDataset` uses a suffixed cache folder for
+# the competition data (e.g., "-bdf-mini").
 release = "R2"
 dataset_id = RELEASE_TO_OPENNEURO_DATASET_MAP[release]
 task = "RestingState"
@@ -52,8 +54,9 @@
 # ---------------------------
 # Once the data is cached locally, you can interact with it without needing an
 # internet connection. The key is to instantiate your dataset object with the
-# ``download=False`` flag. This tells EEGDash to look for data in the
-# ``cache_dir`` instead of trying to connect to the database or S3.
+# ``download=False`` flag. This tells :class:`eegdash.dataset.EEGChallengeDataset`
+# to look for data in the ``cache_dir`` instead of trying to connect to the
+# database or S3.
 
 
 # Here we check that the local cache folder exists
@@ -76,9 +79,10 @@
 # Step 3: Filtering Entities Offline
 # ----------------------------------
 # Even without a database connection, you can still filter your dataset by
-# BIDS entities like subject, session, or task. When ``download=False``, EEGDash
-# uses the BIDS directory structure and filenames to apply these filters. This
-# example shows how to load data for a specific subject from the local cache.
+# BIDS entities like subject, session, or task. When ``download=False``,
+# :class:`eegdash.dataset.EEGChallengeDataset` uses the BIDS directory structure
+# and filenames to apply these filters. This example shows how to load data for
+# a specific subject from the local cache.
 
 ds_offline_sub = EEGChallengeDataset(
     cache_dir=cache_dir,