Merge branch 'main' into exclude_bads_consistent_handling

Author: larsoner

.circleci/config.yml

@@ -100,6 +100,14 @@ jobs:
           name: Set BASH_ENV
           command: ./tools/circleci_bash_env.sh
 
+      # Writes testing_version.txt and misc_version.txt, used in the cache keys of
+      # the two datasets whose versions actually change on a regular basis. Caches
+      # are immutable on CircleCI, so a dataset with a fixed key would be pinned to
+      # whatever was first cached and re-downloaded in full on every later run.
+      - run:
+          name: Get dataset versions
+          command: ./tools/get_testing_version.sh
+
       - run:
           name: Install fonts needed for diagrams
           command: |
@@ -110,13 +118,15 @@ jobs:
             curl https://codeload.github.com/adobe-fonts/source-sans/tar.gz/3.028R | tar xz -C $HOME/.fonts
             fc-cache -f
 
-      # Load uv cache
-      - restore_cache:
-          keys:
-            - uv-cache-0
+      # Load uv cache. Caches are immutable on CircleCI, so a fixed key would freeze
+      # the cache at whatever the dependencies looked like the first time it was
+      # written; keying on pyproject.toml refreshes it when the dependencies change,
+      # and the prefix-only fallback still gets a warm (if slightly stale) cache in
+      # between.
       - restore_cache:
           keys:
-            - user-install-bin-cache-311
+            - uv-cache-1-{{ checksum "pyproject.toml" }}
+            - uv-cache-1-
 
       # Hack in uninstalls of libraries as necessary if pip doesn't do the right thing in upgrading for us...
       - run:
@@ -125,14 +135,9 @@ jobs:
             ./tools/circleci_dependencies.sh
 
       - save_cache:
-          key: uv-cache-0
+          key: uv-cache-1-{{ checksum "pyproject.toml" }}
           paths:
             - ~/.cache/uv
-      - save_cache:
-          key: user-install-bin-cache-311
-          paths:
-            - ~/.local/lib/python3.11/site-packages
-            - ~/.local/bin
 
       - run:
           name: Check Qt
@@ -142,7 +147,7 @@ jobs:
       # Load tiny cache so that ~/.mne does not need to be created below
       - restore_cache:
           keys:
-            - data-cache-tiny-0
+            - data-cache-tiny-0-{{ checksum "misc_version.txt" }}
 
       # Look at what we have and fail early if there is some library conflict
       - run:
@@ -211,7 +216,7 @@ jobs:
             - data-cache-spm-face
       - restore_cache:
           keys:
-            - data-cache-testing
+            - data-cache-testing-{{ checksum "testing_version.txt" }}
       - restore_cache:
           keys:
             - data-cache-visual-1
@@ -239,87 +244,12 @@ jobs:
             echo "BUILD=$(cat build.txt)"
             ls -al ~/mne_data;
 
-      # Run doctest (if it's full or front) before building the docs
-      - run:
-          name: make test-doc
-          command: |
-            if [[ $(cat gitlog.txt) == *"[circle front]"* ]] || [[ $(cat build.txt) == "html-memory" ]] ; then
-              make test-doc;
-              mkdir -p doc/_build/test-results/test-doc;
-              cp junit-results.xml doc/_build/test-results/test-doc/junit.xml;
-              cp coverage.xml doc/_build/test-results/test-doc/coverage.xml;
-            fi;
-      # Build docs
-      - run:
-          name: make html
-          command: |  # we have -o pipefail in #BASH_ENV so we should be okay
-            set -x
-            PATTERN=$(cat pattern.txt) make -C doc $(cat build.txt) 2>&1 | tee sphinx_log.txt
-      - run:
-          name: Check sphinx log for warnings (which are treated as errors)
-          when: always
-          command: |
-            ! grep "^.*\(WARNING\|ERROR\): " sphinx_log.txt
-      - run:
-          name: Show profiling output
-          when: always
-          command: |
-            if compgen -G "doc/*.dat" > /dev/null; then
-              mkdir -p doc/generated
-              mprof plot doc/*.dat --output doc/generated/memory.png
-            else
-              echo "No profile data found in doc/"
-            fi
-      - run:
-          name: Sanity check system state
-          command: |
-            python -c "import mne; level = mne.get_config('MNE_LOGGING_LEVEL'); assert level.lower() == 'info', repr(level)"
-
-      # Reduce upload time of artifacts we will (almost) never look at
-      - run:
-          name: Reduce artifact upload time
-          command: |
-            if grep -q html-pattern-memory build.txt; then
-              zip -rm doc/_build/html/_downloads.zip doc/_build/html/_downloads
-            fi
-            for NAME in generated auto_tutorials auto_examples; do
-              zip -rm doc/${NAME}.zip doc/${NAME}
-            done
-
-      # Save the JUnit file
-      - store_test_results:
-          path: doc/_build/test-results
-      - store_artifacts:
-          path: doc/_build/test-results
-          destination: test-results
-      # Upload test results to Codecov
-      - run:
-          name: Upload test results to Codecov
-          environment:
-            CODECOV_TOKEN: fb4c4a94-72d7-4743-bb08-af25b623a29a
-          command: |
-            if [[ -f doc/_build/test-results/test-doc/coverage.xml ]]; then
-              bash <(curl -s https://codecov.io/bash) -f doc/_build/test-results/test-doc/coverage.xml || true
-            fi
-      # Save the SG RST
-      - store_artifacts:
-          path: doc/auto_examples.zip
-      - store_artifacts:
-          path: doc/auto_tutorials.zip
-      - store_artifacts:
-          path: doc/generated.zip
-      # Save the HTML
-      - store_artifacts:
-          path: doc/_build/html/
-          destination: html
-      - persist_to_workspace:
-          root: doc/_build
-          paths:
-            - html
-
-      # Keep these separate, maybe better in terms of size limitations (?)
+      # Saved here rather than at the end of the job: everything above has
+      # finished downloading, and a failure in the (long, flaky) doc build below
+      # should not throw the downloads away. Kept as separate caches, maybe
+      # better in terms of size limitations (?)
       - save_cache:
-          key: data-cache-tiny-0  # < 100 M, might as well combine
+          key: data-cache-tiny-0-{{ checksum "misc_version.txt" }}  # < 100 M, might as well combine
           paths:
             - ~/.mne
             - ~/mne_data/MNE-kiloword-data  # (28 M)
@@ -394,7 +324,7 @@ jobs:
           paths:
             - ~/mne_data/MNE-spm-face  # (1.5 G)
       - save_cache:
-          key: data-cache-testing
+          key: data-cache-testing-{{ checksum "testing_version.txt" }}
           paths:
             - ~/mne_data/MNE-testing-data  # (2.5 G)
       - save_cache:
@@ -414,6 +344,84 @@ jobs:
           paths:
             - ~/mne_data/ds004388  # (1.8 G)
 
+      # Run doctest (if it's full or front) before building the docs
+      - run:
+          name: make test-doc
+          command: |
+            if [[ $(cat gitlog.txt) == *"[circle front]"* ]] || [[ $(cat build.txt) == "html-memory" ]] ; then
+              make test-doc;
+              mkdir -p doc/_build/test-results/test-doc;
+              cp junit-results.xml doc/_build/test-results/test-doc/junit.xml;
+              cp coverage.xml doc/_build/test-results/test-doc/coverage.xml;
+            fi;
+      # Build docs
+      - run:
+          name: make html
+          command: |  # we have -o pipefail in #BASH_ENV so we should be okay
+            set -x
+            PATTERN=$(cat pattern.txt) make -C doc $(cat build.txt) 2>&1 | tee sphinx_log.txt
+      - run:
+          name: Check sphinx log for warnings (which are treated as errors)
+          when: always
+          command: |
+            ! grep "^.*\(WARNING\|ERROR\): " sphinx_log.txt
+      - run:
+          name: Show profiling output
+          when: always
+          command: |
+            if compgen -G "doc/*.dat" > /dev/null; then
+              mkdir -p doc/generated
+              mprof plot doc/*.dat --output doc/generated/memory.png
+            else
+              echo "No profile data found in doc/"
+            fi
+      - run:
+          name: Sanity check system state
+          command: |
+            python -c "import mne; level = mne.get_config('MNE_LOGGING_LEVEL'); assert level.lower() == 'info', repr(level)"
+
+      # Reduce upload time of artifacts we will (almost) never look at
+      - run:
+          name: Reduce artifact upload time
+          command: |
+            if grep -q html-pattern-memory build.txt; then
+              zip -rm doc/_build/html/_downloads.zip doc/_build/html/_downloads
+            fi
+            for NAME in generated auto_tutorials auto_examples; do
+              zip -rm doc/${NAME}.zip doc/${NAME}
+            done
+
+      # Save the JUnit file
+      - store_test_results:
+          path: doc/_build/test-results
+      - store_artifacts:
+          path: doc/_build/test-results
+          destination: test-results
+      # Upload test results to Codecov
+      - run:
+          name: Upload test results to Codecov
+          environment:
+            CODECOV_TOKEN: fb4c4a94-72d7-4743-bb08-af25b623a29a
+          command: |
+            if [[ -f doc/_build/test-results/test-doc/coverage.xml ]]; then
+              bash <(curl -s https://codecov.io/bash) -f doc/_build/test-results/test-doc/coverage.xml || true
+            fi
+      # Save the SG RST
+      - store_artifacts:
+          path: doc/auto_examples.zip
+      - store_artifacts:
+          path: doc/auto_tutorials.zip
+      - store_artifacts:
+          path: doc/generated.zip
+      # Save the HTML
+      - store_artifacts:
+          path: doc/_build/html/
+          destination: html
+      - persist_to_workspace:
+          root: doc/_build
+          paths:
+            - html
+
 
   linkcheck:
     # there are a few files excluded from this for expediency, see Makefile
@@ -442,7 +450,8 @@ jobs:
           command: ./tools/circleci_bash_env.sh
       - restore_cache:
           keys:
-            - uv-cache-0
+            - uv-cache-1-{{ checksum "pyproject.toml" }}
+            - uv-cache-1-
       - run:
           name: Get Python running
           command: |

.github/workflows/tests.yml

@@ -136,14 +136,12 @@ jobs:
           project-root: ${{ github.workspace }}
           groups: lockfile_extras
         if: matrix.kind == 'old'
-      # Minimal commands on Linux (macOS stalls)
-      - uses: actions/cache@v6.1.0
-        with:
-          key: minimal-commands-1
-          path: ~/minimal_cmds
-        if: startswith(matrix.os, 'ubuntu') && matrix.kind != 'minimal' && matrix.kind != 'old' && matrix.kind != 'pip-ft'
-      - run: bash ./tools/get_minimal_commands.sh
-        if: startswith(matrix.os, 'ubuntu') && matrix.kind != 'minimal' && matrix.kind != 'old' && matrix.kind != 'pip-ft'
+      # MNE-C minimal commands. The action caches the download and no-ops on
+      # platforms that have no binaries (macOS arm64, Windows, Linux arm64), so it
+      # only needs to be gated on the kinds that deliberately do without them.
+      - name: Setup minimal commands
+        uses: mne-tools/mne-tools/actions/setup-minimal-commands@main
+        if: matrix.kind != 'minimal' && matrix.kind != 'old' && matrix.kind != 'pip-ft'
       - run: bash ./tools/github_actions_infos.sh
       - name: Check Qt import
         uses: mne-tools/mne-tools/actions/check-qt-import@main
@@ -156,7 +154,7 @@ jobs:
       - run: ./tools/get_testing_version.sh
       - uses: actions/cache@v6.1.0
         with:
-          key: ${{ env.TESTING_VERSION }}
+          key: mne_data-testing-${{ env.TESTING_VERSION }}-misc-${{ env.MISC_VERSION }}
           path: ~/mne_data
       - run: bash ./tools/github_actions_download.sh
       - run: bash ./tools/github_actions_test.sh  # for some reason on macOS we need to run "bash X" in order for a failed test run to show up

.gitignore

@@ -104,4 +104,13 @@ venv/
 .hypothesis/
 .ruff_cache/
 .ipynb_checkpoints/
-/.claude/
+/.claude/
+uv.lock
+
+# written into the repo root by the CI helper scripts in tools/
+/build.txt
+/gitlog.txt
+/merge.txt
+/misc_version.txt
+/pattern.txt
+/testing_version.txt

azure-pipelines.yml

@@ -59,7 +59,7 @@ stages:
               key: minimal-cmds-1
               path: /home/vsts/minimal_cmds
             displayName: Cache minimal commands
-          - bash: ./tools/get_minimal_commands.sh
+          - bash: $(MNE_TOOLS_DIR)/tools/get_minimal_commands.sh
             displayName: Get minimal commands
           - task: UsePythonVersion@0
             inputs:
@@ -82,7 +82,7 @@ stages:
             displayName: Get testing version
           - task: Cache@2
             inputs:
-              key: $(testing_version)
+              key: mne_data-testing-$(testing_version)-misc-$(misc_version)
               path: /home/vsts/mne_data
             displayName: Cache testing data
           - bash: ./tools/github_actions_download.sh
@@ -133,7 +133,7 @@ stages:
             displayName: Get testing version
           - task: Cache@2
             inputs:
-              key: $(testing_version)
+              key: mne_data-testing-$(testing_version)-misc-$(misc_version)
               path: /home/vsts/mne_data
             displayName: Cache testing data
           - bash: ./tools/github_actions_download.sh
@@ -211,7 +211,7 @@ stages:
             displayName: Get testing version
           - task: Cache@2
             inputs:
-              key: $(testing_version)
+              key: mne_data-testing-$(testing_version)-misc-$(misc_version)
               path: C:\Users\VssAdministrator\mne_data
             displayName: Cache testing data
           - bash: ./tools/github_actions_download.sh

doc/api/datasets.rst

@@ -48,5 +48,6 @@ Datasets
    refmeg_noise.data_path
    ssvep.data_path
    erp_core.data_path
+   erp_core.fetch_file
    epilepsy_ecog.data_path
    eyelink.data_path

doc/api/inverse.rst

@@ -85,6 +85,7 @@ Inverse Solutions
    Dipole
    DipoleFixed
    fit_dipole
+   gui.dipolefit
 
 :py:mod:`mne.dipole`:
 

doc/api/statistics.rst

@@ -68,10 +68,12 @@ Compute ``adjacency`` matrices for cluster-level statistics:
 
    channels.find_ch_adjacency
    channels.read_ch_adjacency
+   label_adjacency
    spatial_dist_adjacency
    spatial_src_adjacency
    spatial_tris_adjacency
    spatial_inter_hemi_adjacency
    spatio_temporal_src_adjacency
    spatio_temporal_tris_adjacency
    spatio_temporal_dist_adjacency
+   volume_label_adjacency

doc/changes/dev/13074.newfeature.rst

@@ -0,0 +1 @@
+Add a GUI for interactive guided dipole fitting (:func:`mne.gui.dipolefit`), by `Marijn van Vliet`_

doc/changes/dev/13795.other.rst

@@ -0,0 +1 @@
+Made :meth:`evoked.plot() <mne.Evoked.plot>` instantiate ``MNELineFigure`` when it creates its own figure, aligning this path with the ongoing 2D plotting figure-class refactor discussed in :gh:`7751`, by `Pragnya Khandelwal`_.

doc/changes/dev/14211.newfeature.rst

@@ -0,0 +1,3 @@
+Added :ref:`tut-gal-decoding`, a tutorial on Generalization Across Location
+(GAL) and Time-GAL decoding of EEG data, by `Bruno Aristimunha`_ and
+:newcontrib:`Alejandro Santos Mayo`.