braindecode 1.4.0.dev981__tar.gz → 1.5.0__tar.gz

braindecode-1.5.0/.circleci/artifact_path

@@ -0,0 +1 @@
+0/docs/_build/html/index.html

braindecode-1.5.0/.circleci/config.yml

@@ -0,0 +1,56 @@
+# Tagging a commit with [circle front] will build the front page and perform test-doc.
+# Tagging a commit with [circle full] will build everything.
+version: 2.1
+parameters:
+  github-artifact-url:
+    type: string
+    default: "none"
+jobs:
+    fetch_docs_from_github:
+      docker:
+        - image: circleci/python:3.9
+      environment:
+        GITHUB_ARTIFACT_URL: << pipeline.parameters.github-artifact-url >>
+      steps:
+        - run:
+            name: Download some docs
+            command: |
+              echo "Show Github artifact url"
+              echo $GITHUB_ARTIFACT_URL
+              wget -O HTML-docs.zip $GITHUB_ARTIFACT_URL
+              ls -ahl .
+              unzip HTML-docs.zip -d downloaded_docs
+              ls -ahl .
+        # Save the outputs
+        - store_artifacts:
+           path: downloaded_docs/html/
+           destination: dev
+        - persist_to_workspace:
+           root: downloaded_docs
+           paths:
+             - html
+    dummy_job:
+      docker:
+       - image: circleci/python:3.9
+      steps:
+        - run:
+           name: Dummy echo
+           command: |
+             echo "Do nothing..."
+
+
+workflows:
+  version: 2.1
+
+  default:
+    when:
+      not:
+        equal: [ "none", << pipeline.parameters.github-artifact-url >> ]
+    jobs:
+      - fetch_docs_from_github
+
+  dummy_workflow:
+    when:
+      equal: [ "none", << pipeline.parameters.github-artifact-url >> ]
+    jobs:
+      - dummy_job

braindecode-1.5.0/.codacy.yaml

@@ -0,0 +1,26 @@
+---
+# Codacy project configuration.
+#
+# The defaults are sensible for most projects, but the docs landing page
+# (`docs/_static/landing.{css,js}`) is intentionally written with
+# compact single-line CSS rules (faster to read in a 1500-line file) and
+# uses function declarations after their reference site (legal in JS due
+# to hoisting). Both patterns get flagged by stylelint / ESLint default
+# configs that Codacy ships, so we narrow those rules below.
+engines:
+  stylelint:
+    enabled: true
+    rules:
+      # docs/_static/landing.css uses single-line rules for SVG keyframes
+      # and one-liner overrides where the visual pairing is the point.
+      declaration-block-single-line-max-declarations: false
+      # Blank-line-before-rule is a stylistic preference; the file
+      # already separates major sections with header comments.
+      rule-empty-line-before: false
+      # Allow lower-case shorthand hex; the file mixes 3- and 6-digit.
+      color-hex-length: false
+exclude_paths:
+  - docs/_build/**
+  - docs/auto_examples/**
+  - docs/sg_execution_times.rst
+  - examples/**

braindecode-1.5.0/.github/scripts/convert_to_notebook.py

@@ -0,0 +1,88 @@
+"""
+Convert Python example scripts to Jupyter notebooks for Colab integration.
+
+This script is adapted from deepinv's conversion script and simplified for braindecode's needs.
+It converts Sphinx-Gallery Python examples to Jupyter notebooks.
+"""
+
+import argparse
+import copy
+from pathlib import Path
+
+import nbformat
+from sphinx_gallery import gen_gallery
+from sphinx_gallery.notebook import jupyter_notebook, save_notebook
+from sphinx_gallery.py_source_parser import split_code_and_text_blocks
+
+
+def convert_script_to_notebook(src_file: Path, output_file: Path, gallery_conf):
+    """
+    Convert a single Python script to a Jupyter notebook.
+
+    Parameters
+    ----------
+    src_file : Path
+        Path to the source Python script
+    output_file : Path
+        Path where the notebook should be saved
+    gallery_conf : dict
+        Sphinx-Gallery configuration dictionary
+    """
+    # Parse the Python file
+    file_conf, blocks = split_code_and_text_blocks(str(src_file))
+
+    # Convert to notebook (returns a dict, not a notebook object)
+    example_nb_dict = jupyter_notebook(blocks, gallery_conf, str(src_file.parent))
+
+    # Convert dict to nbformat notebook object
+    example_nb = nbformat.from_dict(example_nb_dict)
+
+    # Prepend an installation cell for braindecode
+    # Check if first cell already has pip install
+    try:
+        first_source = example_nb.cells[0].source if example_nb.cells else ""
+    except (IndexError, AttributeError):
+        first_source = ""
+
+    install_cmd = "%pip install braindecode"
+    if "pip install" not in first_source or "braindecode" not in first_source:
+        install_cell = nbformat.v4.new_code_cell(source=install_cmd)
+        install_cell.metadata["language"] = "python"
+        example_nb.cells.insert(0, install_cell)
+
+    # Ensure the parent directory exists
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # Save notebook
+    save_notebook(example_nb, output_file)
+    print(f"Notebook saved to: {output_file}")
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Convert Python example scripts to Jupyter notebooks."
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        help="Path to the Python script to convert",
+    )
+    parser.add_argument(
+        "--output",
+        required=True,
+        help="Path to save the converted notebook",
+    )
+
+    args = parser.parse_args()
+
+    input_path = Path(args.input)
+    target_path = Path(args.output)
+
+    # Use default gallery configuration
+    gallery_conf = copy.deepcopy(gen_gallery.DEFAULT_GALLERY_CONF)
+
+    print(f"Processing: {input_path}")
+    try:
+        convert_script_to_notebook(input_path, target_path, gallery_conf)
+        print(f"Successfully converted {input_path} to {target_path}")
+    except Exception as e:
+        print(f"Error converting {input_path}: {e}")
+        raise

braindecode-1.5.0/.github/workflows/docs.yml

@@ -0,0 +1,99 @@
+name: docs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+on:
+  push:
+    branches:
+      - "master"
+  pull_request:
+    branches:
+      - '*' # all branches, including forks
+
+jobs:
+  build_docs:
+    runs-on: ubuntu-latest
+    env:
+      HF_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
+    steps:
+      ## Install Braindecode
+      - name: Checking Out Repository
+        uses: actions/checkout@v4
+      # Install python
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      # Cache MNE Data and HuggingFace Hub weights.
+      # Both caches are content-addressed (filenames + checksums for MNE,
+      # commit-pinned safetensors for HF), so they don't need to invalidate on
+      # pyproject.toml changes. Using github.run_id as the primary save key
+      # forces a fresh save each run; restore-keys lets every run start from
+      # the most recent cache instead of cold-downloading from physionet.org /
+      # huggingface.co.
+      - name: Create/Restore MNE Data Cache
+        id: cache-mne_data
+        uses: actions/cache@v4
+        with:
+          path: ~/mne_data
+          key: docs-mne-data-v1-${{ github.run_id }}
+          restore-keys: |
+            docs-mne-data-v1-
+            docs-mne-data-
+      - name: Create/Restore HuggingFace Cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface/hub
+          key: docs-hf-hub-v1-${{ github.run_id }}
+          restore-keys: |
+            docs-hf-hub-v1-
+            docs-hf-hub-
+      # Install uv
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+      # Install with all dependencies for doc build to go through
+      - name: Install with doc dependencies
+        run: uv pip install --system -e .[all]
+      # Show Braindecode Version
+      - run: python -c "import braindecode; print(braindecode.__version__)"
+      # Persist HF token to disk so sphinx-gallery examples can access gated repos
+      - name: Login to Hugging Face Hub
+        if: ${{ env.HF_TOKEN != '' }}
+        run: python -c "import os; from huggingface_hub import login; login(token=os.environ['HF_TOKEN'])"
+      - name: Create Docs
+        run: |
+          cd docs
+          make html
+
+      - name: Generate Notebooks from Examples
+        run: |
+          set -euo pipefail
+          echo "Converting Python examples to notebooks in docs/_build/html/auto_examples/_notebooks..."
+          mkdir -p docs/_build/html/auto_examples/_notebooks
+          find examples -type f -name '*.py' | while read -r f; do
+            rel="${f#examples/}"
+            out_dir="docs/_build/html/auto_examples/_notebooks/$(dirname "$rel")"
+            mkdir -p "$out_dir"
+            base="$(basename "$rel" .py)"
+            out_path="$out_dir/$base.ipynb"
+            python .github/scripts/convert_to_notebook.py --input "$f" --output "$out_path"
+          done
+
+      - name: Upload HTML Docs as Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: HTML-Docs
+          path: ./docs/_build/
+
+      - name: Deploy to Github Pages if on Master
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+          external_repository: braindecode/braindecode.github.io
+          destination_dir: dev
+          publish_branch: master
+          publish_dir: ./docs/_build/html
+          cname: braindecode.org

braindecode-1.5.0/.github/workflows/link-check.yml

@@ -0,0 +1,93 @@
+name: Link Check
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - "**.md"
+      - "docs/**"
+      - ".github/workflows/link-check.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "**.md"
+      - "docs/**"
+      - ".github/workflows/link-check.yml"
+  schedule:
+    - cron: "0 0 * * 1"
+  workflow_dispatch:
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check links in Markdown and RST files
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --verbose
+            --no-progress
+            --accept 200,204,206,301,302,303,307,308,429
+            --timeout 30
+            --max-retries 3
+            --exclude "^mailto:"
+            --exclude "^https://github\\.com/braindecode/braindecode/(issues|pulls|compare)"
+            --exclude "^https://github\\.com/.*/(fork|new)"
+            --exclude "localhost"
+            --exclude "127\\.0\\.0\\.1"
+            --exclude "example\\.com"
+            --exclude "^file://"
+            --exclude "^git\\+"
+            --exclude "arxiv\\.org"
+            --exclude "twitter\\.com"
+            --exclude "x\\.com"
+            --exclude "linkedin\\.com"
+            --exclude "app\\.gitter\\.im"
+            --exclude "gitter\\.im"
+            --exclude "gitlab\\.com"
+            --exclude "dx\\.doi\\.org"
+            --exclude "^https://doi\\.org/10\\.1002/hbm"
+            --exclude "^https://dl\\.acm\\.org/doi"
+            "./**/*.md"
+            "./**/*.rst"
+          fail: true
+          output: ./lychee-report.md
+
+      - name: Upload link check report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: link-check-report
+          path: ./lychee-report.md
+          retention-days: 30
+
+      - name: Create issue on link check failure
+        if: failure() && github.event_name == 'schedule'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            let report = '';
+            try {
+              report = fs.readFileSync('./lychee-report.md', 'utf8');
+            } catch (e) {
+              report = 'Could not read the link check report.';
+            }
+            const issues = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'broken-links'
+            });
+            if (issues.data.length === 0) {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title: 'Broken links detected in documentation',
+                body: `## Automated Link Check Report\n\nThe weekly link check has detected broken links.\n\n<details>\n<summary>Report</summary>\n\n${report}\n\n</details>`,
+                labels: ['broken-links', 'documentation']
+              });
+            }

braindecode-1.5.0/.github/workflows/link-to-doc.yaml

@@ -0,0 +1,14 @@
+on: [status]
+jobs:
+  circleci_artifacts_redirector:
+    runs-on: ubuntu-latest
+    name: Run CircleCI artifacts redirector
+    steps:
+      - name: GitHub Action step
+        uses: larsoner/circleci-artifacts-redirector-action@master
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          api-token: ${{ secrets.CIRCLECI_TOKEN }}
+          artifact-path: 0/dev/index.html
+          circleci-jobs: fetch_docs_from_github
+          job-title: Check rendered doc here!

braindecode-1.5.0/.github/workflows/pre-commit.yaml

@@ -0,0 +1,14 @@
+name: pre-commit-codestyle
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+
+on: [pull_request]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+    - uses: pre-commit/action@v3.0.1

braindecode-1.5.0/.github/workflows/push-artifact-to-circleci.yml

@@ -0,0 +1,52 @@
+name: push-artifact-to-circle-ci
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+# will be changed to on workflow_run
+on:
+  workflow_run:
+    workflows: ["docs"]
+    branches-ignore: ["master"]
+    types:
+      - completed
+
+jobs:
+  Push-Artifact-to-CircleCI:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+    - name: Trigger CircleCI download and publication of HTML Doc Artifact
+      env:
+        EVENT_OBJ:  ${{ toJson(github.event) }}
+        COMMIT_SHA:  ${{ github.event.workflow_run.head_sha }}
+        REPO_NAME:  ${{ github.event.workflow_run.head_repository.full_name }}
+        CIRCLECI_TOKEN: ${{ secrets.CIRCLECI_TOKEN }}
+        RUN_ID: ${{github.event.workflow_run.id}}
+      run: |
+        echo "github.event.workflow_run.head_sha"
+        echo ${{ github.event.workflow_run.head_sha }}
+        echo "github.event.workflow_run.head_repository.html_url"
+        echo ${{ github.event.workflow_run.head_repository.html_url }}
+        echo "RUN_ID"
+        echo $RUN_ID
+        # Acquire the Pull Request Number from Github API
+        echo "automated curl"
+        PR_NUMBER=$(curl -H "Accept: application/vnd.github.groot-preview+json"   https://api.github.com/repos/$REPO_NAME/commits/$COMMIT_SHA/pulls 2>/dev/null | jq '.[0].number')
+        echo "PR_NUMBER"
+        echo $PR_NUMBER
+
+        # Use Pull Request Number to trigger pipeline on CircleCI which will just download artifact,
+        # unzip it and make it available for browsing
+        curl --request POST \
+          --url https://circleci.com/api/v2/project/gh/braindecode/braindecode/pipeline \
+          --header "Circle-Token: $CIRCLECI_TOKEN" \
+          --header 'content-type: application/json' \
+          --header 'x-attribution-actor-id: github_actions' \
+          --header 'x-attribution-login: github_actions' \
+          --data \{\"branch\":\"pull/$PR_NUMBER/head\",\"parameters\":\{\"github-artifact-url\":\"https://nightly.link/braindecode/braindecode/actions/runs/$RUN_ID/HTML-Docs.zip\"\}\}
+        # Just for debugging
+        echo "EVENT_OBJ"
+        echo $EVENT_OBJ

braindecode-1.5.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Publish to PyPI on main updates
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pypi-publish
+      cancel-in-progress: false
+    permissions:
+      contents: read
+    env:
+      PYPI_USERNAME: __token__
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install build packaging
+
+      # Figure out if this push is a merged PR or a direct push
+      - name: Derive version suffix (PR number if merged, else short SHA)
+        id: ver
+        shell: bash
+        run: |
+          set -euo pipefail
+          COMMIT_MSG="$(git log -1 --pretty=%B)"
+          if [[ "$COMMIT_MSG" =~ Merge\ pull\ request\ \#([0-9]+) ]]; then
+            echo "suffix=pr${BASH_REMATCH[1]}" >> "$GITHUB_OUTPUT"
+            echo "pr_number=${BASH_REMATCH[1]}" >> "$GITHUB_OUTPUT"
+            echo "Detected merged PR #${BASH_REMATCH[1]}"
+          else
+            SHORT_SHA="$(git rev-parse --short HEAD)"
+            echo "suffix=sha${SHORT_SHA}" >> "$GITHUB_OUTPUT"
+            echo "Detected direct push (no PR); using ${SHORT_SHA}"
+          fi
+
+      # Use your script, passing PR number when present, otherwise a SHA-based suffix
+      - name: Bump version
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ -n "${{ steps.ver.outputs.pr_number || '' }}" ]]; then
+            python scripts/release_script.py \
+              --init-file braindecode/version.py \
+              --pr "${{ steps.ver.outputs.pr_number }}"
+          else
+            # Fallback path must be supported by your script; if not, change the script
+            # to accept --pr and append a compliant .devN/.postN label.
+            python scripts/release_script.py \
+              --init-file braindecode/version.py \
+              --suffix "${{ steps.ver.outputs.suffix }}"
+          fi
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

braindecode-1.5.0/.github/workflows/tests.yml

@@ -0,0 +1,66 @@
+name: tests
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+on:
+  push:
+    branches:
+      - "master"
+  pull_request:
+    branches:
+      - '*' # all branches, including forks
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ "ubuntu-latest", "macos-latest", "windows-latest" ]
+        python-version: [ "3.12", "3.13" ] # , "3.11", "3.14"]
+    steps:
+    ## Install Braindecode
+    - name: Checking Out Repository
+      uses: actions/checkout@v4
+    # Cache MNE Data
+    # The cache key includes the OS and a hash of pyproject.toml to invalidate
+    # when dependencies change. This ensures that test data is fresh when
+    # the test configuration changes.
+    - name: Create/Restore MNE Data Cache
+      id: cache-mne_data
+      uses: actions/cache@v3
+      with:
+        path: ~/mne_data
+        key: test-2-${{ runner.os }}-${{ matrix.python-version }}
+        restore-keys: |
+          test-2-${{ runner.os }}-${{ matrix.python-version }}-
+          test-2-${{ runner.os }}-
+    - uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+        cache-dependency-glob: "**/pyproject.toml"
+
+    - name: Show Python Version
+      run: python --version
+    - name: Install Braindecode from Current Checkout
+      run: uv pip install --system -e .[all]
+    # Show Braindecode Version
+    - run: python -c "import braindecode; print(braindecode.__version__)"
+
+    ## Run Tests
+    - name: Run Tests # See https://stackoverflow.com/a/59959080/1469195 for the cov-report logic
+      env:
+        HF_TOKEN_REVE: ${{ secrets.HF_TOKEN_REVE }}
+      run: pytest --cov=braindecode test/ --cov-report term --cov-report xml:coverage.xml
+    - name: Upload Coverage to Codecov
+      uses: codecov/codecov-action@v4
+      if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'}}
+      with:
+        fail_ci_if_error: true
+        file: ./coverage.xml
+        env_vars: OS,PYTHON
+        token: ${{ secrets.CODECOV_TOKEN }}

braindecode-1.5.0/.github/workflows/whats-new.yml

@@ -0,0 +1,16 @@
+name: Check Whats News Changes
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+on:
+  pull_request:
+    types: [ assigned, opened, synchronize, reopened, labeled, unlabeled ]
+    branches:
+      - '*'
+jobs:
+  check-whats-news:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: tarides/changelog-check-action@v3
+        with:
+          changelog: docs/whats_new.rst

braindecode-1.5.0/.gitignore

@@ -0,0 +1,74 @@
+junit-results.xml
+*.pyc
+*.pyo
+*.sh
+*.so
+*.tar.gz
+*.log
+*~
+.#*
+*.swp
+*.lprof
+*.npy
+*.zip
+*.tar.*
+*.egg*
+*.tmproj
+*.png
+!docs/_static/*.png
+!docs/_static/**/*.png
+*.dat
+.DS_Store
+auto_examples
+build
+coverage
+.cache/
+.pytest_cache/
+__pycache__/
+prof/
+.ipynb_checkpoints
+*.pt
+
+dist/
+docs/_build/
+docs/generated/
+docs/auto_examples/
+docs/auto_tutorials/
+docs/modules/generated/
+docs/sphinxext/cachedir
+docs/source
+pip-log.txt
+.coverage*
+tags
+doc/coverages
+doc/samples
+cover
+*.html
+!docs/_templates/*.html
+!docs/_templates/**/*.html
+
+*.orig
+
+# PyCharm
+.idea/**
+
+# sublime
+*-e
+
+# Visual Studio Code
+.vscode
+*.code-workspace
+
+# Emacs
+*.py#
+*.rst#
+
+.venv/
+venv/
+*.json
+examples/model_building/lightning_logs/*
+
+thesis/
+
+# zoo-data.js is auto-generated into the build outdir by docs/sphinxext/zoo_data_gen.py
+docs/_static/zoo-data.js