Merge branch 'main' into enh-13863-soft-import-missing-version

drammock · web-flow · commit f51995ed0034 · 2026-05-01T10:01:30.000-05:00
diff --git a/.github/workflows/autofix.yml b/.github/workflows/autofix.yml
@@ -21,4 +21,4 @@ jobs:
       - run: pip install --upgrade towncrier pygithub gitpython numpy
       - run: python ./.github/actions/rename_towncrier/rename_towncrier.py
       - run: python ./tools/dev/ensure_headers.py
-      - uses: autofix-ci/action@7a166d7532b277f34e16238930461bf77f9d7ed8
+      - uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
@@ -44,7 +44,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v4.35.1
+      uses: github/codeql-action/init@v4.35.2
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -58,7 +58,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v4.35.1
+      uses: github/codeql-action/autobuild@v4.35.2
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -71,4 +71,4 @@ jobs:
     #   ./location_of_script_within_repo/buildscript.sh
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v4.35.1
+      uses: github/codeql-action/analyze@v4.35.2
diff --git a/.github/workflows/spec_zero.yml b/.github/workflows/spec_zero.yml
@@ -41,7 +41,7 @@ jobs:
         timeout-minutes: 10
         with:
           detached: true
-      - uses: astral-sh/setup-uv@v8.0.0
+      - uses: astral-sh/setup-uv@v8.1.0
         with:
           version: ">=0.9"
           activate-environment: true
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -154,7 +154,7 @@ jobs:
         if: matrix.kind == 'conda' || matrix.kind == 'mamba'
         timeout-minutes: 20
       # Python (if old)
-      - uses: astral-sh/setup-uv@v8.0.0
+      - uses: astral-sh/setup-uv@v8.1.0
         with:
           version: ">=0.9"
           activate-environment: true
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,7 +1,7 @@
 repos:
   # Ruff mne
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.11
+    rev: v0.15.12
     hooks:
       - id: ruff-check
         name: ruff lint mne
diff --git a/azure-pipelines.yml b/azure-pipelines.yml
@@ -133,7 +133,7 @@ stages:
               key: $(testing_version)
               path: /home/vsts/mne_data
             displayName: 'Cache testing data'
-          - script: python -c "import mne; mne.datasets.testing.data_path(verbose=True)"
+          - bash: ./tools/github_actions_download.sh
             displayName: 'Get test data'
           - script: pytest -m "ultraslowtest or pgtest" --tb=short --cov=mne --cov-report=xml -vv mne
             displayName: 'slow and mne-qt-browser tests'
@@ -188,7 +188,7 @@ stages:
               key: $(testing_version)
               path: /home/vsts/mne_data
             displayName: 'Cache testing data'
-          - script: python -c "import mne; mne.datasets.testing.data_path(verbose=True)"
+          - bash: ./tools/github_actions_download.sh
             displayName: 'Get test data'
           - bash: |
               set -eo pipefail
@@ -285,7 +285,7 @@ stages:
               key: $(testing_version)
               path: C:\Users\VssAdministrator\mne_data
             displayName: 'Cache testing data'
-          - script: python -c "import mne; mne.datasets.testing.data_path(verbose=True)"
+          - bash: ./tools/github_actions_download.sh
             displayName: 'Get test data'
           - script: pytest -m "not (slowtest or pgtest)" --tb=short --cov=mne --cov-report=xml -vv mne
             displayName: 'Run tests'
diff --git a/doc/changes/dev/13858.bugfix.rst b/doc/changes/dev/13858.bugfix.rst
@@ -0,0 +1 @@
+Add a ``memmap`` keyword argument to :meth:`mne.io.BaseRaw.load_data`, allowing loading deferred raw data into a memory-mapped file after object creation, by `Aniket Singh Yadav`_.
diff --git a/doc/changes/dev/13874.bugfix.rst b/doc/changes/dev/13874.bugfix.rst
@@ -0,0 +1 @@
+Improved error message when FreeSurfer executable is not found, by :newcontrib:`Ayushi Satodiya`.
diff --git a/doc/changes/names.inc b/doc/changes/names.inc
@@ -35,6 +35,7 @@
 .. _Ashley Drew: https://github.com/ashdrew
 .. _Asish Panda: https://github.com/kaichogami
 .. _Austin Hurst: https://github.com/a-hurst
+.. _Ayushi Satodiya: https://github.com/ayuclan
 .. _Baris Talar: https://github.com/baris-talar
 .. _Beige Jin: https://github.com/BeiGeJin
 .. _Ben Beasley: https://github.com/musicinmybrain
diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst
@@ -661,17 +661,49 @@ change, and append additional PR numbers in parentheticals with the ``:gh:`` rol
 
     Short description of the changes, by `Firstname Lastname`_. (:gh:`12346`)
 
-Test locally before opening pull requests (PRs)
------------------------------------------------
-
-MNE-Python uses `continuous integration`_ (CI) to ensure code quality and
-test across multiple installation targets. However, the CIs are often slower
-than testing locally, especially when other contributors also have open PRs
-(which is basically always the case). Therefore, do not rely on the CIs to
-catch bugs and style errors for you; :ref:`run the tests locally <run-tests>`
+Continuous integration (CI) and local testing before opening a PR
+-----------------------------------------------------------------
+
+Continuous integration (CI) uses automated systems to run tests and checks on your code
+whenever you open or update a pull request.
+MNE-Python uses `continuous integration`_ (CI) to ensure code quality,
+test across multiple platforms, and automatically validate pull requests.
+However, CI runs are slower than testing locally and some of them cost money to run.
+Therefore, *do not rely on the CIs to catch bugs and style errors for you*; 
+:ref:`run the tests locally <run-tests>`
 instead before opening a new PR and before each time you push additional
 changes to an already-open PR.
 
+MNE-Python uses the following CI services:
+
+- `GitHub Actions`_ and `Azure`_ for testing code across platforms
+- `CodeCov`_ checks how much of the code is tested
+- `CircleCI`_ for building the documentation
+
+If you are contributing for the first time, you may notice that `Github Actions`_
+jobs do not start automatically, or appear as "pending".
+This is expected behavior. Github Actions requires **manual approval from a
+maintainer** before running jobs submitted by new contributors. This is a
+security measure to prevent misuse of CI resources.
+
+As a result:
+
+- Github Actions jobs may remain in a *pending* or *not running* state
+- This does **not** indicate a problem with your code
+
+Once you have at least one PR merged into the MNE-Python repository, future
+contributions will not require manual approval.
+
+`CircleCI`_ will not build the documentation unless the GitHub account of the PR's most recent commit
+is associated with a CircleCI account. Creating one is easy and free, 
+choose "login with GitHub" on `CircleCI`_ to get started.
+If you do not do this, it will show up as a failing CI job.
+
+Before opening or updating a PR, check locally:
+
+- that all tests pass (see :ref:`run-tests`)
+- the documentation is built without errors if your changes affect it (see :ref:`build-docs`)
+- style checks pass (see :ref:`code-style`)
 
 Make tests fast and thorough
 ----------------------------
@@ -1108,11 +1140,12 @@ it can serve as a useful example of what to expect from the PR review process.
 
 .. _miniconda: https://conda.io/en/latest/miniconda.html
 .. _Spyder: https://www.spyder-ide.org/
-.. _continuous integration: https://en.wikipedia.org/wiki/Continuous_integration
+.. _continuous integration: https://about.gitlab.com/topics/ci-cd/
 .. _matplotlib: https://matplotlib.org/
 .. _github actions: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions
 .. _azure: https://dev.azure.com/mne-tools/mne-python/_build/latest?definitionId=1&branchName=main
 .. _CircleCI: https://circleci.com/gh/mne-tools/mne-python
+.. _CodeCov: https://about.codecov.io/
 
 .. optipng
 
diff --git a/doc/development/index.rst b/doc/development/index.rst
@@ -17,14 +17,17 @@ please consider posting your questions on our `MNE Forum`_.
 Users and contributors to MNE-Python are expected to follow our
 `code of conduct`_.
 
-The `contributing guide`_ has details on the preferred contribution workflow
+The :ref:`contributing` has details on the preferred contribution workflow
 and the recommended system configuration for a smooth contribution/development
 experience.
 
+.. note::
+    It's a good idea to always reference the version of the contributing guide `on the development version of our website`_, as this will be the most up-to-date.
+
 .. _`opening an issue`: https://github.com/mne-tools/mne-python/issues/new/choose
 .. _`MNE Forum`: https://mne.discourse.group
 .. _`code of conduct`: https://github.com/mne-tools/.github/blob/main/CODE_OF_CONDUCT.md
-.. _`contributing guide`: https://mne.tools/dev/development/contributing.html
+.. _`on the development version of our website`: https://mne.tools/dev/development/contributing.html
 
 .. toctree::
    :hidden:
diff --git a/mne/bem.py b/mne/bem.py
@@ -1313,7 +1313,19 @@ def make_watershed_bem(
         f"\nResults dir = {ws_dir}\nCommand = {' '.join(cmd)}\n"
     )
     os.makedirs(op.join(ws_dir))
-    run_subprocess_env(cmd)
+    try:
+        run_subprocess_env(cmd)
+    except FileNotFoundError as e:
+        raise RuntimeError(
+            "FreeSurfer executable 'mri_watershed' not found.\n\n"
+            "This usually means FreeSurfer is not properly configured.\n"
+            "Make sure:\n"
+            "- FREESURFER_HOME is set\n"
+            "- $FREESURFER_HOME/bin is in your PATH\n"
+            "- You started Python/Jupyter from a terminal where "
+            "SetupFreeSurfer.sh is sourced\n\n"
+            "See https://mne.tools/stable/install/index.html for details."
+        ) from e
     del tempdir  # clean up directory
     if op.isfile(T1_mgz):
         new_info = _extract_volume_info(T1_mgz)
diff --git a/mne/commands/tests/test_commands.py b/mne/commands/tests/test_commands.py
@@ -49,6 +49,7 @@
 from mne.io import read_info, read_raw_fif, show_fiff
 from mne.utils import (
     ArgvSetter,
+    _chmod_rw_R,
     _record_warnings,
     _stamp_to_dt,
     requires_freesurfer,
@@ -207,6 +208,7 @@ def test_make_scalp_surfaces(tmp_path, monkeypatch):
     shutil.copy(t1_path, t1_path_new)
     shutil.copy(headseg_path, headseg_path_new)
     shutil.copy(surf_path, surf_path_new)
+    _chmod_rw_R(tmp_path)
 
     cmd = (
         "-s",
diff --git a/mne/conftest.py b/mne/conftest.py
@@ -39,6 +39,7 @@
     Bunch,
     _assert_no_instances,
     _check_qt_version,
+    _chmod_rw_R,
     _pl,
     _record_warnings,
     _TempDir,
@@ -771,6 +772,7 @@ def subjects_dir_tmp(tmp_path):
     """Copy MNE-testing-data subjects_dir to a temp dir for manipulation."""
     for key in ("sample", "fsaverage"):
         shutil.copytree(op.join(subjects_dir, key), str(tmp_path / key))
+    _chmod_rw_R(tmp_path)
     return str(tmp_path)
 
 
@@ -788,6 +790,7 @@ def subjects_dir_tmp_few(tmp_path):
         shutil.copytree(
             test_path / "subjects" / "sample" / dirname, sample_path / dirname
         )
+    _chmod_rw_R(subjects_path)
     return subjects_path
 
 
diff --git a/mne/io/base.py b/mne/io/base.py
@@ -566,11 +566,16 @@ def _check_bad_segment(
         return self._getitem((picks, slice(start, stop)), return_times=False)
 
     @verbose
-    def load_data(self, verbose=None):
+    def load_data(self, *, memmap=None, verbose=None):
         """Load raw data.
 
         Parameters
         ----------
+        memmap : path-like | None
+            If not ``None``, preload data into a memory-mapped file at this
+            path. If ``None`` (default), preload data into RAM.
+
+            .. versionadded:: 1.13
         %(verbose)s
 
         Returns
@@ -586,7 +591,9 @@ def load_data(self, verbose=None):
         .. versionadded:: 0.10.0
         """
         if not self.preload:
-            self._preload_data(True)
+            if memmap is not None:
+                _validate_type(memmap, "path-like", "memmap")
+            self._preload_data(memmap if memmap is not None else True)
         return self
 
     def _preload_data(self, preload):
diff --git a/mne/io/ctf/tests/test_ctf.py b/mne/io/ctf/tests/test_ctf.py
@@ -32,7 +32,13 @@
 from mne.io.tests.test_raw import _test_raw_reader
 from mne.tests.test_annotations import _assert_annotations_equal
 from mne.transforms import apply_trans
-from mne.utils import _clean_names, _record_warnings, _stamp_to_dt, catch_logging
+from mne.utils import (
+    _clean_names,
+    _record_warnings,
+    _stamp_to_dt,
+    catch_logging,
+    copytree_rw,
+)
 
 ctf_dir = testing.data_path(download=False) / "CTF"
 ctf_fname_continuous = "testdata_ctf.ds"
@@ -75,7 +81,7 @@ def test_read_ctf(tmp_path):
     # Create a dummy .eeg file so we can test our reading/application of it
     os.mkdir(op.join(temp_dir, "randpos"))
     ctf_eeg_fname = op.join(temp_dir, "randpos", ctf_fname_catch)
-    shutil.copytree(op.join(ctf_dir, ctf_fname_catch), ctf_eeg_fname)
+    copytree_rw(op.join(ctf_dir, ctf_fname_catch), ctf_eeg_fname)
     with pytest.warns(RuntimeWarning, match="RMSP .* changed to a MISC ch"):
         raw = _test_raw_reader(read_raw_ctf, directory=ctf_eeg_fname)
     picks = pick_types(raw.info, meg=False, eeg=True)
@@ -689,7 +695,7 @@ def _bad_res4_grad_comp(dsdir):
 def test_missing_res4(tmp_path):
     """Test that res4 missing is handled gracefully."""
     use_ds = tmp_path / ctf_fname_continuous
-    shutil.copytree(ctf_dir / ctf_fname_continuous, tmp_path / ctf_fname_continuous)
+    copytree_rw(ctf_dir / ctf_fname_continuous, tmp_path / ctf_fname_continuous)
     read_raw_ctf(use_ds)
     os.remove(use_ds / (ctf_fname_continuous[:-2] + "meg4"))
     with pytest.raises(OSError, match="could not find the following"):
diff --git a/mne/io/egi/tests/test_egi.py b/mne/io/egi/tests/test_egi.py
@@ -4,7 +4,6 @@
 
 
 import os
-import shutil
 from copy import deepcopy
 from datetime import datetime, timezone
 from pathlib import Path
@@ -20,7 +19,7 @@
 from mne.io import read_evokeds_mff, read_raw_egi, read_raw_fif
 from mne.io.egi.egi import _combine_triggers
 from mne.io.tests.test_raw import _test_raw_reader
-from mne.utils import object_diff
+from mne.utils import copytree_rw, object_diff
 
 base_dir = Path(__file__).parent / "data"
 egi_fname = base_dir / "test_egi.raw"
@@ -337,7 +336,7 @@ def test_io_egi_pns_mff(tmp_path):
 
     # EEG missing
     new_mff = tmp_path / "temp.mff"
-    shutil.copytree(egi_mff_pns_fname, new_mff)
+    copytree_rw(egi_mff_pns_fname, new_mff)
     read_raw_egi(new_mff, verbose="error")
     os.remove(new_mff / "info1.xml")
     os.remove(new_mff / "signal1.bin")
@@ -593,7 +592,7 @@ def test_set_standard_montage_mff(fname, standard_montage):
 def test_egi_mff_bad_xml(tmp_path):
     """Test that corrupt XML files are gracefully handled."""
     pytest.importorskip("defusedxml")
-    mff_fname = shutil.copytree(egi_mff_fname, tmp_path / "test_egi_bad_xml.mff")
+    mff_fname = copytree_rw(egi_mff_fname, tmp_path / "test_egi_bad_xml.mff")
     bad_xml = mff_fname / "bad.xml"
     bad_xml.write_text("<foo>", encoding="utf-8")
     # Missing coordinate file
diff --git a/mne/io/fil/tests/test_fil.py b/mne/io/fil/tests/test_fil.py
@@ -2,7 +2,6 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
-import shutil
 from os import remove
 
 import pytest
@@ -14,6 +13,7 @@
 from mne.datasets import testing
 from mne.io import read_raw_fil
 from mne.io.fil.sensors import _get_pos_units
+from mne.utils import copytree_rw
 
 fil_path = testing.data_path(download=False) / "FIL"
 
@@ -161,7 +161,7 @@ def test_fil_complete():
 def test_fil_no_positions(tmp_path):
     """Test FIL reader in cases where a position file is missing."""
     test_path = tmp_path / "FIL"
-    shutil.copytree(fil_path, test_path)
+    copytree_rw(fil_path, test_path)
 
     posname = test_path / "sub-noise_ses-001_task-noise220622_run-001_positions.tsv"
     binname = test_path / "sub-noise_ses-001_task-noise220622_run-001_meg.bin"
@@ -179,7 +179,7 @@ def test_fil_no_positions(tmp_path):
 def test_fil_bad_channel_spec(tmp_path):
     """Test FIL reader when a bad channel is specified in channels.tsv."""
     test_path = tmp_path / "FIL"
-    shutil.copytree(fil_path, test_path)
+    copytree_rw(fil_path, test_path)
 
     channame = test_path / "sub-noise_ses-001_task-noise220622_run-001_channels.tsv"
     binname = test_path / "sub-noise_ses-001_task-noise220622_run-001_meg.bin"
diff --git a/mne/io/nirx/tests/test_nirx.py b/mne/io/nirx/tests/test_nirx.py
diff --git a/mne/io/persyst/tests/test_persyst.py b/mne/io/persyst/tests/test_persyst.py
diff --git a/mne/io/snirf/tests/test_snirf.py b/mne/io/snirf/tests/test_snirf.py
diff --git a/mne/io/tests/test_raw.py b/mne/io/tests/test_raw.py
diff --git a/mne/source_space/tests/test_source_space.py b/mne/source_space/tests/test_source_space.py
diff --git a/mne/tests/test_bem.py b/mne/tests/test_bem.py
diff --git a/mne/utils/__init__.pyi b/mne/utils/__init__.pyi
diff --git a/mne/utils/_testing.py b/mne/utils/_testing.py
diff --git a/tools/github_actions_download.sh b/tools/github_actions_download.sh

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Add a ``memmap`` keyword argument to :meth:`mne.io.BaseRaw.load_data`, allowing loading deferred raw data into a memory-mapped file after object creation, by `Aniket Singh Yadav`_.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Improved error message when FreeSurfer executable is not found, by :newcontrib:`Ayushi Satodiya`.