Merge branch 'main' into info_for_inverse

docs/source/v1.9.md.inc

@@ -10,20 +10,18 @@
 - Changed default for `source_info_path_update` to `None`.  In `_04_make_forward.py` 
   and `_05_make_inverse.py`, we retrieve the info from the file from which 
   the `noise_cov` is computed (#919 by @SophieHerbst)
-
-[//]: # (- Whatever (#000 by @whoever))
+- The [`depth`][mne_bids_pipeline._config.depth] parameter doesn't accept `None`
+  anymore. Please use `0` instead. (#915 by @hoechenberger)
 
 ### :package: Requirements
 
 - We dropped support for Python 3.9. You now need Python 3.10 or newer. (#908 by @hoechenberger)
 
-[//]: # (- Whatever (#000 by @whoever))
-
 ### :book: Documentation
 
 - We removed the `Execution` section from configuration options documentation and
   replaced it with new, more explicit sections (namely, Caching, Parallelization,
-  Logging, and Error handling). (#914 by @hoechenberger)
+  Logging, and Error handling), and enhanced documentation. (#914 by @hoechenberger, #916 by @SophieHerbst)
 
 ### :bug: Bug fixes
 

mne_bids_pipeline/_config.py

@@ -1979,24 +1979,33 @@ def mri_landmarks_kind(bids_path):
 
 # ## Inverse solution
 
-loose: float | Literal["auto"] = 0.2
+loose: Annotated[float, Interval(ge=0, le=1)] | Literal["auto"] = 0.2
 """
-Value that weights the source variances of the dipole components
-that are parallel (tangential) to the cortical surface. If `0`, then the
-inverse solution is computed with **fixed orientation.**
-If `1`, it corresponds to **free orientation.**
-The default value, `'auto'`, is set to `0.2` for surface-oriented source
-spaces, and to `1.0` for volumetric, discrete, or mixed source spaces,
-unless `fixed is True` in which case the value 0. is used.
+A value between 0 and 1 that weights the source variances of the dipole components
+that are parallel (tangential) to the cortical surface.
+
+If `0`, then the inverse solution is computed with **fixed orientation**, i.e.,
+only dipole components perpendicular to the cortical surface are considered.
+
+If `1`, it corresponds to **free orientation**, i.e., dipole components with any
+orientation are considered.
+
+The default value, `0.2`, is suitable for surface-oriented source spaces.
+
+For volume or mixed source spaces, choose `1.0`.
+
+!!! info
+    Support for modeling volume and mixed source spaces will be added in a future
+    version of MNE-BIDS-Pipeline.
 """
 
-depth: float | dict | None = 0.8
+depth: Annotated[float, Interval(ge=0, le=1)] | dict = 0.8
 """
-If float (default 0.8), it acts as the depth weighting exponent (`exp`)
-to use (must be between 0 and 1). None is equivalent to 0, meaning no
-depth weighting is performed. Can also be a `dict` containing additional
-keyword arguments to pass to :func:`mne.forward.compute_depth_prior`
-(see docstring for details and defaults).
+If a number, it acts as the depth weighting exponent to use
+(must be between `0` and`1`), with`0` meaning no depth weighting is performed.
+
+Can also be a dictionary containing additional keyword arguments to pass to
+`mne.forward.compute_depth_prior` (see docstring for details and defaults).
 """
 
 inverse_method: Literal["MNE", "dSPM", "sLORETA", "eLORETA"] = "dSPM"
@@ -2187,8 +2196,12 @@ def noise_cov(bids_path):
 # %%
 # # Caching
 #
-# These settings control if and how pipeline output is being cached to avoid unnecessary
-# computations on a re-run.
+# Per default, the pipeline output is cached (temporarily stored),
+# to avoid unnecessary reruns of previously computed steps.
+# Yet, for consistency, changes in configuration parameters trigger
+# automatic reruns of previous steps.
+# !!! info
+#     To force rerunning a given step, run the pipeline with the option: `--no-cache`.
 
 memory_location: PathLike | bool | None = True
 """