deploy: NeuroTechX/moabb@cf82872

Author: bruAristimunha

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: b3da49418314ae0f1d898c4e4e8b292d
+config: b5ea3e3ca47360e7923b9c986ea36f85
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_downloads/0408c1618e8b678e08951653e77bb2e1/plot_learning_curve_p300.zip

@@ -1,7 +1,7 @@
 """
-====================================
-Tutorial 5: Creating a dataset class
-====================================
+=============================================================
+Tutorial 5: Combining Multiple Datasets into a Single Dataset
+=============================================================
 """
 
 # Author: Gregoire Cattan

docs/_downloads/07fcc19ba03226cd3d83d4e40ec44385/auto_examples_python.zip

@@ -15,14 +15,14 @@
       },
       "outputs": [],
       "source": [
-        "# Authors: MOABB contributors\n#\n# License: BSD (3-clause)\n# sphinx_gallery_thumbnail_number = 1\n\nimport warnings\n\nimport matplotlib.pyplot as plt\nimport numpy as np\nfrom mne.decoding import SlidingEstimator, cross_val_multiscore\nfrom sklearn.linear_model import LogisticRegression\nfrom sklearn.pipeline import make_pipeline\nfrom sklearn.preprocessing import StandardScaler\n\nimport moabb\nfrom moabb.datasets import BNCI2014_001\nfrom moabb.paradigms import LeftRightImagery\n\n\nmoabb.set_log_level(\"info\")\nwarnings.filterwarnings(\"ignore\")"
+        "# Authors: MOABB contributors\n#\n# License: BSD (3-clause)\n# sphinx_gallery_thumbnail_number = 2\n\nimport warnings\n\nimport matplotlib.pyplot as plt\nimport numpy as np\nfrom mne.decoding import SlidingEstimator, cross_val_multiscore\nfrom scipy.stats import ttest_1samp\nfrom sklearn.linear_model import LogisticRegression\nfrom sklearn.pipeline import make_pipeline\nfrom sklearn.preprocessing import StandardScaler\n\nimport moabb\nfrom moabb.datasets import BNCI2014_001\nfrom moabb.paradigms import LeftRightImagery\n\n\nmoabb.set_log_level(\"info\")\nwarnings.filterwarnings(\"ignore\")"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Loading the Dataset\n\nWe instantiate the BNCI2014-001 dataset and restrict the analysis to the\nfirst 9 subjects to keep the example reasonably fast.\n\n"
+        "## Loading the Dataset\n\nWe instantiate the BNCI2014-001 dataset and use all 9 subjects.\n\n"
       ]
     },
     {
@@ -33,14 +33,14 @@
       },
       "outputs": [],
       "source": [
-        "dataset = BNCI2014_001()\ndataset.subject_list = dataset.subject_list[:9]"
+        "dataset = BNCI2014_001()"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Choosing a Paradigm\n\nThe :class:`~moabb.paradigms.LeftRightImagery` paradigm extracts\nleft-hand and right-hand motor-imagery epochs, applies a band-pass filter\n(8\u201332 Hz by default), and returns the data as a 3-D NumPy array of shape\n``(n_trials, n_channels, n_times)``.\n\n"
+        "## Choosing a Paradigm\n\nThe :class:`~moabb.paradigms.LeftRightImagery` paradigm extracts\nleft-hand and right-hand motor-imagery epochs, applies a band-pass filter\n(8--32 Hz by default), and returns the data as a 3-D NumPy array of shape\n``(n_trials, n_channels, n_times)``.\n\n"
       ]
     },
     {
@@ -76,7 +76,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Evaluating Each Subject\n\nFor each subject we:\n\n1. Retrieve the preprocessed epochs via the paradigm.\n2. Run stratified 5-fold cross-validation with\n   :func:`~mne.decoding.cross_val_multiscore`, which returns an array of\n   shape ``(n_folds, n_times)``.\n3. Average over folds to obtain a single time course per subject.\n\nAll per-subject time courses are collected for later aggregation.\n\n"
+        "## Evaluating Each Subject\n\nFor each subject we:\n\n1. Retrieve the preprocessed epochs via the paradigm using\n   ``return_epochs=True`` so we can extract the correct time vector and\n   sampling frequency from the :class:`mne.Epochs` metadata.\n2. Run stratified 5-fold cross-validation with\n   :func:`~mne.decoding.cross_val_multiscore`, which returns an array of\n   shape ``(n_folds, n_times)``.\n3. Average over folds to obtain a single time course per subject.\n\nAll per-subject time courses are collected for later aggregation.\n\n"
       ]
     },
     {
@@ -87,14 +87,14 @@
       },
       "outputs": [],
       "source": [
-        "all_scores = []\n\nfor subject in dataset.subject_list:\n    X, y, meta = paradigm.get_data(dataset=dataset, subjects=[subject])\n\n    # cross_val_multiscore returns (n_folds, n_times)\n    scores = cross_val_multiscore(sliding, X, y, cv=5, n_jobs=1)\n    all_scores.append(scores.mean(axis=0))  # average over folds\n\n# Stack into (n_subjects, n_times)\nall_scores = np.array(all_scores)"
+        "all_scores = []\n\nfor subject in dataset.subject_list:\n    epochs, y, meta = paradigm.get_data(\n        dataset=dataset, subjects=[subject], return_epochs=True\n    )\n    X = epochs.get_data()\n\n    # cross_val_multiscore returns (n_folds, n_times)\n    scores = cross_val_multiscore(sliding, X, y, cv=5, n_jobs=1)\n    all_scores.append(scores.mean(axis=0))  # average over folds\n\n# Stack into (n_subjects, n_times)\nall_scores = np.array(all_scores)"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Building the Time Vector\n\nThe time axis of the decoded epochs starts at ``tmin`` (0 s relative to the\nmotor-imagery cue) and ends at the trial duration defined by the dataset\n(4 s for BNCI2014-001 at 250 Hz).\n\n"
+        "## Extracting the Time Vector\n\nBecause we used ``return_epochs=True``, we can read the time axis and\nsampling frequency directly from the last Epochs object rather than\nhard-coding dataset-specific values.\n\n"
       ]
     },
     {
@@ -105,14 +105,14 @@
       },
       "outputs": [],
       "source": [
-        "sfreq = 250  # BNCI2014-001 sampling frequency\ntmin = paradigm.tmin  # 0.0 s\ntmax = dataset.interval[1] - dataset.interval[0]  # 4.0 s\ntimes = np.linspace(tmin, tmax, all_scores.shape[1])"
+        "times = epochs.times\nsfreq = epochs.info[\"sfreq\"]\nprint(f\"Sampling frequency: {sfreq} Hz, {len(times)} time points\")"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Plotting Time-Resolved Decoding Accuracy\n\nWe plot the group-average AUC score together with the standard error of the\nmean (SEM) across subjects.  A horizontal dashed line at 0.5 indicates\nchance level.\n\n"
+        "## Statistical Significance\n\nWe run a one-sample *t*-test against chance level (AUC = 0.5) at each time\npoint.  Time points with *p* < 0.05 (uncorrected) are flagged as\nsignificant.\n\n"
       ]
     },
     {
@@ -123,7 +123,43 @@
       },
       "outputs": [],
       "source": [
-        "mean_scores = all_scores.mean(axis=0)\nsem_scores = all_scores.std(axis=0) / np.sqrt(len(dataset.subject_list))\n\nfig, ax = plt.subplots(figsize=(8, 4))\nax.plot(times, mean_scores, label=\"Mean AUC across subjects\", color=\"steelblue\")\nax.fill_between(\n    times,\n    mean_scores - sem_scores,\n    mean_scores + sem_scores,\n    alpha=0.3,\n    color=\"steelblue\",\n    label=\"\u00b1SEM\",\n)\nax.axhline(0.5, linestyle=\"--\", color=\"k\", label=\"Chance level (AUC = 0.5)\")\nax.axvline(0, linestyle=\":\", color=\"gray\", label=\"Cue onset\")\nax.set_xlabel(\"Time (s)\")\nax.set_ylabel(\"AUC\")\nax.set_title(\"Time-Resolved Decoding \u2013 Left vs. Right Motor Imagery\\n(BNCI2014-001)\")\nax.legend(loc=\"upper left\")\nax.set_xlim(times[0], times[-1])\nax.set_ylim(0.4, 1.0)\nplt.tight_layout()\nplt.show()"
+        "_, p_values = ttest_1samp(all_scores, 0.5, axis=0)\nsig_mask = p_values < 0.05"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Plot 1 -- Mean AUC Time Course with Significance\n\nWe plot the group-average AUC score together with the standard error of the\nmean (SEM) across subjects.  A horizontal dashed line at 0.5 indicates\nchance level.  Time points that are significantly above chance are\nhighlighted with an orange bar along the *x*-axis.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "mean_scores = all_scores.mean(axis=0)\nsem_scores = all_scores.std(axis=0) / np.sqrt(len(dataset.subject_list))\n\nfig, ax = plt.subplots(figsize=(8, 4))\nax.plot(times, mean_scores, label=\"Mean AUC across subjects\", color=\"steelblue\")\nax.fill_between(\n    times,\n    mean_scores - sem_scores,\n    mean_scores + sem_scores,\n    alpha=0.3,\n    color=\"steelblue\",\n    label=\"\\u00b1SEM\",\n)\nax.axhline(0.5, linestyle=\"--\", color=\"k\", label=\"Chance level (AUC = 0.5)\")\nax.axvline(times[0], linestyle=\":\", color=\"gray\", label=\"MI onset\")\n\n# Mark significant time points with a bar at the bottom of the axes\nax.fill_between(\n    times,\n    0.0,\n    0.03,\n    where=sig_mask,\n    color=\"tab:orange\",\n    alpha=0.7,\n    label=\"p < 0.05 (uncorrected)\",\n    transform=ax.get_xaxis_transform(),\n)\n\nax.set_xlabel(\"Time (s)\")\nax.set_ylabel(\"AUC\")\nax.set_title(\"Time-Resolved Decoding \\u2013 Left vs. Right Motor Imagery\\n(BNCI2014-001)\")\nax.legend(loc=\"upper left\", fontsize=\"small\")\nax.set_xlim(times[0], times[-1])\nax.set_ylim(0.4, 1.0)\nplt.tight_layout()\nplt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Plot 2 -- Per-Subject Heatmap\n\nA heatmap of AUC scores (subjects x time) gives a richer picture than the\nmean curve alone, revealing inter-subject variability and the temporal\nstructure of discriminability for each participant.\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "fig, ax = plt.subplots(figsize=(8, 4))\nim = ax.imshow(\n    all_scores,\n    aspect=\"auto\",\n    origin=\"lower\",\n    extent=[times[0], times[-1], 0.5, len(dataset.subject_list) + 0.5],\n    cmap=\"RdBu_r\",\n    vmin=0.3,\n    vmax=0.7,\n)\nax.set_xlabel(\"Time (s)\")\nax.set_ylabel(\"Subject\")\nax.set_yticks(range(1, len(dataset.subject_list) + 1))\nax.set_title(\"Per-Subject Time-Resolved AUC\\n(BNCI2014-001)\")\nax.axvline(times[0], linestyle=\":\", color=\"k\", linewidth=0.8)\nax.set_xlim(times[0], times[-1])\nfig.colorbar(im, ax=ax, label=\"AUC\")\nplt.tight_layout()\nplt.show()"
       ]
     }
   ],

…b84/tutorial_5_build_a_custom_dataset.py …43b4efe/tutorial_5_combining_datasets.pydocs/_downloads/d04c0dc7171471ea51f4d366ca95bb84/tutorial_5_build_a_custom_dataset.py renamed to docs/_downloads/0b1ec83b0a2aca7fc81aefb4043b4efe/tutorial_5_combining_datasets.py docs/_downloads/d04c0dc7171471ea51f4d366ca95bb84/tutorial_5_build_a_custom_dataset.py renamed to docs/_downloads/0b1ec83b0a2aca7fc81aefb4043b4efe/tutorial_5_combining_datasets.py

@@ -4,7 +4,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# Tutorial 5: Creating a dataset class\n"
+        "\n# Tutorial 5: Combining Multiple Datasets into a Single Dataset\n"
       ]
     },
     {

docs/_downloads/13d975862a3185d53f9ceeeff453cdaa/plot_hinss2021_classification.zip

@@ -1,7 +1,23 @@
 """
 ====================================
-Tutorial 4: Creating a dataset class
+Tutorial 4: Creating custom datasets
 ====================================
+
+MOABB provides several ways to integrate a custom dataset, depending on the
+format of your data:
+
+1. :class:`~moabb.datasets.base.BaseDataset` — for datasets with arbitrary
+   file formats. Requires implementing data downloading and file reading.
+2. :class:`~moabb.datasets.base.BaseBIDSDataset` /
+   :class:`~moabb.datasets.base.LocalBIDSDataset` — for datasets already
+   provided in `BIDS format <https://bids.neuroimaging.io/>`_.
+   ``BaseBIDSDataset`` is used for online datasets (only the download step
+   needs to be implemented); ``LocalBIDSDataset`` is used for local or private
+   datasets with no subclassing required at all.
+
+**BIDS is the preferred format for new datasets in MOABB.**
+
+This tutorial illustrates both approaches.
 """
 
 # Authors: Pedro L. C. Rodrigues, Sylvain Chevallier
@@ -16,12 +32,15 @@
 from sklearn.pipeline import make_pipeline
 
 from moabb.datasets import download as dl
-from moabb.datasets.base import BaseDataset
+from moabb.datasets.base import BaseBIDSDataset, BaseDataset
 from moabb.evaluations import WithinSessionEvaluation
 from moabb.paradigms import LeftRightImagery
 
 
 ##############################################################################
+# 1. Creating a dataset class from scratch (BaseDataset)
+# ======================================================
+#
 # Creating some Data
 # ------------------
 #
@@ -30,7 +49,7 @@
 # 8 channels lasting for 150 seconds (sampling frequency 256 Hz). We have
 # included the script that creates this dataset and have uploaded it online.
 # The fake dataset is available on the
-# `Zenodo website <https://sandbox.zenodo.org/record/369543>`_
+# `Zenodo website <https://zenodo.org/records/14973598>`_
 
 
 def create_example_dataset():
@@ -172,3 +191,76 @@ def data_path(
 # your data on public server (like Zenodo or Figshare) and signal that you
 # want to add your dataset to MOABB in the  `dedicated issue <https://github.com/NeuroTechX/moabb/issues/1>`_.  # noqa: E501
 # You could then follow the instructions on `how to contribute <https://github.com/NeuroTechX/moabb/blob/master/CONTRIBUTING.md>`_  # noqa: E501
+
+##############################################################################
+# 2. Creating a BIDS dataset class (BaseBIDSDataset)
+# ==================================================
+#
+# If your dataset is already provided in the
+# `BIDS format <https://bids.neuroimaging.io/>`_, you can subclass
+# :class:`~moabb.datasets.base.BaseBIDSDataset` instead of
+# :class:`~moabb.datasets.base.BaseDataset`.
+# The ``BaseBIDSDataset`` base class handles reading the BIDS files
+# automatically via ``mne-bids``; you only need to implement the
+# ``_download_subject`` method that downloads the data for a single subject
+# and returns the local path to the **root** of the BIDS dataset.
+#
+# Several MOABB datasets already use this approach — for example
+# :class:`moabb.datasets.Zhou2016`.
+#
+# The skeleton below shows the minimal implementation required.
+# **Note:** ``ExampleBIDSDataset`` is intentionally non-functional — its
+# ``_download_subject`` raises ``NotImplementedError``. Replace it with your
+# own download logic before instantiating the class.
+
+
+class ExampleBIDSDataset(BaseBIDSDataset):
+    """Skeleton showing how to wrap an online BIDS dataset.
+
+    Replace ``_download_subject`` with the actual download logic for your
+    dataset (e.g. fetching a zip archive from Zenodo and extracting it).
+    """
+
+    def __init__(self):
+        super().__init__(
+            subjects=[1, 2, 3],
+            sessions_per_subject=1,
+            events={"left_hand": 1, "right_hand": 2},
+            code="ExampleBIDSDataset",
+            interval=[0, 0.75],
+            paradigm="imagery",
+            doi="",
+        )
+
+    def _download_subject(self, subject, path, force_update, update_path, verbose):
+        """Download the BIDS dataset for *subject* and return the BIDS root."""
+        # Example (not executed here — replace with your actual download URL):
+        #
+        #   url = f"https://zenodo.org/records/XXXXX/files/bids_dataset.zip"
+        #   bids_root = dl.data_dl(url, "ExampleBIDSDataset")
+        #   return bids_root
+        raise NotImplementedError("Replace this with your actual download logic.")
+
+
+##############################################################################
+# Using LocalBIDSDataset for local/private BIDS datasets
+# -------------------------------------------------------
+#
+# If you already have a BIDS dataset on your local machine and you do **not**
+# want to write a dedicated class, you can use
+# :class:`~moabb.datasets.base.LocalBIDSDataset` directly.
+# It auto-discovers subjects and sessions from the BIDS directory structure:
+#
+# .. code-block:: python
+#
+#    from moabb.datasets.base import LocalBIDSDataset
+#
+#    dataset = LocalBIDSDataset(
+#        bids_root="/path/to/bids/dataset",
+#        events={"left_hand": 1, "right_hand": 2},
+#        interval=[0, 0.75],
+#        paradigm="imagery",
+#    )
+#
+#    paradigm = LeftRightImagery()
+#    X, labels, meta = paradigm.get_data(dataset=dataset, subjects=[1])