updating the version

Author: bruAristimunha

stable/.buildinfo

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

stable/_downloads/07fcc19ba03226cd3d83d4e40ec44385/auto_examples_python.zip

@@ -283,7 +283,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.12.11"
+      "version": "3.12.12"
     }
   },
   "nbformat": 4,

stable/_downloads/090305d06248840b75133975e5121f41/plot_sleep_staging_chambon2018.ipynb

@@ -148,7 +148,18 @@
 
 
 ######################################################################
-# Now we create the deep learning model! Braindecode comes with some
+# Now we create the deep learning model!
+# First thing we need to do is know the properties of our signals.
+# For this, we use the :func:`braindecode.datautil.infer_signal_properties` function:
+#
+from braindecode.datautil import infer_signal_properties
+
+sig_props = infer_signal_properties(train_set, mode="classification")
+print(sig_props)
+
+
+######################################################################
+# Braindecode comes with some
 # predefined convolutional neural network architectures for raw
 # time-domain EEG. Here, we use the :class:`ShallowFBCSPNet
 # <braindecode.models.ShallowFBCSPNet>` model from [3]_. These models are
@@ -175,16 +186,10 @@
 seed = 20200220
 set_random_seeds(seed=seed, cuda=cuda)
 
-n_classes = 4
-classes = list(range(n_classes))
-# Extract number of chans and time steps from dataset
-n_chans = train_set[0][0].shape[0]
-n_times = train_set[0][0].shape[1]
-
 model = ShallowFBCSPNet(
-    n_chans,
-    n_classes,
-    n_times=n_times,
+    n_chans=sig_props["n_chans"],
+    n_outputs=sig_props["n_outputs"],
+    n_times=sig_props["n_times"],
     final_conv_length="auto",
 )
 
@@ -234,6 +239,7 @@
 
 batch_size = 64
 n_epochs = 4
+classes = list(range(sig_props["n_outputs"]))
 
 clf = EEGClassifier(
     model,
@@ -364,6 +370,6 @@
 # .. [3] Schirrmeister, R.T., Springenberg, J.T., Fiederer, L.D.J., Glasstetter, M.,
 #        Eggensperger, K., Tangermann, M., Hutter, F., Burgard, W. and Ball, T. (2017),
 #        Deep learning with convolutional neural networks for EEG decoding and visualization.
-#        Hum. Brain Mapping, 38: 5391-5420. https://doi.org/10.1002/hbm.23730.
+#        Hum. Brain Mapping, 38: 5391-5420. https://onlinelibrary.wiley.com/doi/10.1002/hbm.23730.
 #
 # .. include:: /links.inc

stable/_downloads/0a8b8bc2f1b933515b7b4101626dd179/plot_bcic_iv_2a_moabb_trial.py

@@ -0,0 +1,237 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# Fine-tuning a Foundation Model (Signal-JEPA)\n\nFoundation models are large-scale pre-trained models that serve as a starting point\nfor a wide range of downstream tasks, leveraging their generalization capabilities.\nFine-tuning these models is necessary to adapt them to specific tasks or datasets,\nensuring optimal performance in specialized applications.\n\nIn this tutorial, we demonstrate how to load a pre-trained foundation model\nand fine-tune it for a specific task. We use the Signal-JEPA model [1]_\nand a MOABB motor-imagery dataset for this tutorial.\n   :depth: 2\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# Authors: Pierre Guetschel <pierre.guetschel@gmail.com>\n#\n# License: BSD (3-clause)\n#\nimport mne\nimport numpy as np\nimport torch\n\nfrom braindecode import EEGClassifier\nfrom braindecode.datasets import MOABBDataset\nfrom braindecode.models import SignalJEPA_PreLocal\nfrom braindecode.preprocessing import create_windows_from_events\n\ntorch.use_deterministic_algorithms(True)\ntorch.manual_seed(12)\nnp.random.seed(12)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Loading and preparing the data\n\n### Loading a dataset\n\nWe start by loading a MOABB dataset, a single subject only for speed.\nThe dataset contains motor imagery EEG recordings, which we will preprocess and use for fine-tuning.\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "subject_id = 3  # Just one subject for speed\ndataset = MOABBDataset(dataset_name=\"BNCI2014_001\", subject_ids=[subject_id])\n\n# Set the standard 10-20 montage for EEG channel locations\nmontage = mne.channels.make_standard_montage(\"standard_1020\")\nfor ds in dataset.datasets:\n    ds.raw.set_montage(montage)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Define Dataset parameters\n\nWe extract the sampling frequency and ensure that it is consistent across\nall recordings. We also extract the window size from the annotations and\ninformation about the EEG channels (names, positions, etc.).\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# Extract sampling frequency\nsfreq = dataset.datasets[0].raw.info[\"sfreq\"]\nassert all([ds.raw.info[\"sfreq\"] == sfreq for ds in dataset.datasets])\n\n# Extract and validate window size from annotations\nwindow_size_seconds = dataset.datasets[0].raw.annotations.duration[0]\nassert all(\n    d == window_size_seconds\n    for ds in dataset.datasets\n    for d in ds.raw.annotations.duration\n)\n\n# Extract channel information\nchs_info = dataset.datasets[0].raw.info[\"chs\"]  # Channel information\n\nprint(f\"{sfreq=}, {window_size_seconds=}, {len(chs_info)=}\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Create Windows from Events\n\nWe use the `create_windows_from_events` function from Braindecode to segment\nthe dataset into windows based on events.\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "classes = [\"feet\", \"left_hand\", \"right_hand\"]\nclasses_mapping = {c: i for i, c in enumerate(classes)}\n\nwindows_dataset = create_windows_from_events(\n    dataset,\n    preload=True,  # Preload the data into memory for faster processing\n    mapping=classes_mapping,\n)\nmetadata = windows_dataset.get_metadata()\nprint(metadata.head(10))"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Loading a pre-trained foundation model\n\n### Download and Load Pre-trained Weights\n\nWe download the pre-trained weights for the SignalJEPA model from the Hugging Face Hub.\nThese weights will serve as the starting point for finetuning.\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "model_state_dict = torch.hub.load_state_dict_from_url(\n    url=\"https://huggingface.co/braindecode/SignalJEPA/resolve/main/signal-jepa_16s-60_adeuwv4s.pth\"\n)\n# print(model_state_dict.keys())"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Instantiate the Foundation Model\n\nWe create an instance of the SignalJEPA model using the pre-local downstream\narchitecture. The model is initialized with the dataset's sampling frequency,\nwindow size, and channel information.\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "model = SignalJEPA_PreLocal(\n    sfreq=sfreq,\n    input_window_seconds=window_size_seconds,\n    chs_info=chs_info,\n    n_outputs=len(classes),\n)\nprint(model)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Load the Pre-trained Weights into the Model\n\nWe load the pre-trained weights into the model. The transformer layers are excluded\nas this module is not used in the pre-local downstream architecture (see [1]_).\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "# Define layers to exclude from the pre-trained weights\nnew_layers = {\n    \"spatial_conv.1.weight\",\n    \"spatial_conv.1.bias\",\n    \"final_layer.1.weight\",\n    \"final_layer.1.bias\",\n}\n\n# Filter out transformer weights and load the state dictionary\nmodel_state_dict = {\n    k: v for k, v in model_state_dict.items() if not k.startswith(\"transformer.\")\n}\nmissing_keys, unexpected_keys = model.load_state_dict(model_state_dict, strict=False)\n\n# Ensure no unexpected keys and validate missing keys\nassert unexpected_keys == [], f\"{unexpected_keys=}\"\nassert set(missing_keys) == new_layers, f\"{missing_keys=}\""
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Fine-tuning the Model\n\nSignal-JEPA is a model trained in a self-supervised manner on a masked\nprediction task. In this task, the model is configured in a many-to-many\nfashion, which is not suited for a classification task. Therefore, we need to\nadjust the model architecture for finetuning. This is what is done by the\n:class:`SignalJEPA_PreLocal`, :class:`SignalJEPA_Contextual`, and\n:class:`SignalJEPA_PostLocal` classes. In these classes, new layers are added\nspecifically for classification, as described in the article [1]_ and in the following figure:\n\n<img src=\"file://_static/model/sjepa_pre-local.jpg\" alt=\"Signal-JEPA Pre-Local Downstream Architecture\" align=\"center\">\n\nWith this downstream architecture, two options are possible for fine-tuning:\n\n1) Fine-tune only the newly added layers\n2) Fine-tune the entire model\n\n### Freezing Pre-trained Layers\n\nAs the second option is rather straightforward to implement,\nwe will focus on the first option here.\nWe will freeze all layers except the newly added ones.\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "for name, param in model.named_parameters():\n    if name not in new_layers:\n        param.requires_grad = False\n\nprint(\"Trainable parameters:\")\nother_modules = set()\nfor name, param in model.named_parameters():\n    if param.requires_grad:\n        print(name)\n    else:\n        other_modules.add(name.split(\".\")[0])\n\nprint(\"\\nOther modules:\")\nprint(other_modules)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Fine-tuning Procedure\n\nFinally, we set up the fine-tuning procedure using Braindecode's\n:class:`EEGClassifier`. We define the loss function, optimizer, and training\nparameters. We then fit the model to the windows dataset.\n\nWe only train for a few epochs for demonstration purposes.\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "clf = EEGClassifier(\n    model,\n    criterion=torch.nn.CrossEntropyLoss,\n    optimizer=torch.optim.AdamW,\n    optimizer__lr=0.005,\n    batch_size=16,\n    callbacks=[\"accuracy\"],\n    classes=range(3),\n)\n_ = clf.fit(windows_dataset, y=metadata[\"target\"], epochs=10)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### All-in-one Implementation\n\nIn the implementation above, we manually loaded the weights and froze the layers.\nThis forces us to pass an initialized model to :class:`EEGClassifier`, which may\ncreate issues if we use it in a cross-validation setting.\n\nInstead, we can implement the same procedure in a more compact and reproducible way,\nby using skorch's callback system.\n\nHere, we import a callback to freeze layers and define a custom\ncallback to load the pre-trained weights at the beginning of training:\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "from skorch.callbacks import Callback, Freezer\n\n\nclass WeightsLoader(Callback):\n    def __init__(self, url, strict=False):\n        self.url = url\n        self.strict = strict\n\n    def on_train_begin(self, net, X=None, y=None, **kwargs):\n        state_dict = torch.hub.load_state_dict_from_url(url=self.url)\n        net.module_.load_state_dict(state_dict, strict=self.strict)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can now define a classifier with those callbacks, without having\nto pass an initialized model, and fit it as before:\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "clf = EEGClassifier(\n    \"SignalJEPA_PreLocal\",\n    criterion=torch.nn.CrossEntropyLoss,\n    optimizer=torch.optim.AdamW,\n    optimizer__lr=0.005,\n    batch_size=16,\n    callbacks=[\n        \"accuracy\",\n        WeightsLoader(\n            url=\"https://huggingface.co/braindecode/SignalJEPA/resolve/main/signal-jepa_16s-60_adeuwv4s.pth\"\n        ),\n        Freezer(patterns=\"feature_encoder.*\"),\n    ],\n    classes=range(3),\n)\n_ = clf.fit(windows_dataset, y=metadata[\"target\"], epochs=10)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Conclusion and Next Steps\n\nIn this tutorial, we demonstrated how to fine-tune a pre-trained foundation\nmodel, Signal-JEPA, for a motor imagery classification task. We now have a basic\nimplementation that can automatically load pre-trained weights and freeze specific layers.\n\nThis setup can easily be extended to explore different fine-tuning techniques,\nbase foundation models, and downstream tasks.\n\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## References\n\n.. [1] Guetschel, P., Moreau, T., and Tangermann, M. (2024)\n       \u201cS-JEPA: towards seamless cross-dataset transfer\n       through dynamic spatial attention\u201d.  https://arxiv.org/abs/2403.11772\n\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.12"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

stable/_downloads/0ada35f18bb95235ba2842270483081f/plot_finetune_foundation_model.ipynb

@@ -175,7 +175,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.12.11"
+      "version": "3.12.12"
     }
   },
   "nbformat": 4,

stable/_downloads/0e7901d0b4f66d64949baca45cedfd0e/plot_hub_integration.zip

@@ -53,7 +53,7 @@
 from braindecode.datasets import MOABBDataset
 
 subject_id = 3
-dataset = MOABBDataset(dataset_name="BNCI2014001", subject_ids=[subject_id])
+dataset = MOABBDataset(dataset_name="BNCI2014_001", subject_ids=[subject_id])
 
 ######################################################################
 # Preprocessing