From 13ec4fa9557fa521eb1545eefaf14637ee4da082 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Richard=20H=C3=B6chenberger?= Date: Sat, 30 Mar 2024 12:20:13 +0100 Subject: [PATCH] Restructure documentation sections I replaced the `Execution` section with the folliwing new sections - Caching - Parallelization - Logging - Error handling --- docs/source/settings/gen_settings.py | 13 ++++- docs/source/v1.9.md.inc | 10 ++-- mne_bids_pipeline/_config.py | 81 +++++++++++++++++----------- 3 files changed, 67 insertions(+), 37 deletions(-) diff --git a/docs/source/settings/gen_settings.py b/docs/source/settings/gen_settings.py index 8300245fe..9f1929b81 100755 --- a/docs/source/settings/gen_settings.py +++ b/docs/source/settings/gen_settings.py @@ -46,7 +46,13 @@ "reports": "reports", "report generation": "report_generation", # root file - "execution": "execution", + "caching": "caching", + # root file + "parallelization": "parallelization", + # root file + "logging": "logging", + # root file + "error handling": "error_handling", } # TODO: Make sure these are consistent, autogenerate some based on section names, # and/or autogenerate based on inputs/outputs of actual functions. @@ -76,7 +82,10 @@ "inverse solution": ("inverse-solution",), "reports": (), "report generation": ("report",), - "execution": (), + "caching": ("cache",), + "parallelization": ("paralleliation", "dask", "out-of-core"), + "logging": ("logging", "error-handling"), + "error_handling": ("error-handling"), } extra_headers = { diff --git a/docs/source/v1.9.md.inc b/docs/source/v1.9.md.inc index c429abbcc..ead7758fa 100644 --- a/docs/source/v1.9.md.inc +++ b/docs/source/v1.9.md.inc @@ -6,18 +6,22 @@ - The type annotations in the default configuration file are now easier to read: We replaced `Union[X, Y]` with `X | Y` and `Optional[X]` with `X | None`. (#908, #911 by @hoechenberger) -[//]: # (- Whatever (#000 by @whoever)) - [//]: # (### :warning: Behavior changes) [//]: # (- Whatever (#000 by @whoever)) ### :package: Requirements -- We dropped support for Python 3.9. You now need Python 3.10 or newer. +- 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) + ### :bug: Bug fixes - When running the pipeline with [`find_bad_channels_meg`][mne_bids_pipeline._config. find_bad_channels_meg] enabled, diff --git a/mne_bids_pipeline/_config.py b/mne_bids_pipeline/_config.py index 175b96cd2..c4d382a3f 100644 --- a/mne_bids_pipeline/_config.py +++ b/mne_bids_pipeline/_config.py @@ -2172,10 +2172,44 @@ def noise_cov(bids_path): """ # %% -# # Execution +# # Caching # -# These options control how the pipeline is executed but should not affect -# what outputs get produced. +# These settings control if and how pipeline output is being cached to avoid unnecessary +# computations on a re-run. + +memory_location: PathLike | bool | None = True +""" +If not None (or False), caching will be enabled and the cache files will be +stored in the given directory. The default (True) will use a +`"_cache"` subdirectory (name configurable via the +[`memory_subdir`][mne_bids_pipeline._config.memory_subdir] +variable) in the BIDS derivative root of the dataset. +""" + +memory_subdir: str = "_cache" +""" +The caching directory name to use if `memory_location` is `True`. +""" + +memory_file_method: Literal["mtime", "hash"] = "mtime" +""" +The method to use for cache invalidation (i.e., detecting changes). Using the +"modified time" reported by the filesystem (`'mtime'`, default) is very fast +but requires that the filesystem supports proper mtime reporting. Using file +hashes (`'hash'`) is slower and requires reading all input files but should +work on any filesystem. +""" + +memory_verbose: int = 0 +""" +The verbosity to use when using memory. The default (0) does not print, while +1 will print the function calls that will be cached. See the documentation for +the joblib.Memory class for more information.""" + +# %% +# # Parallelization +# +# These options control parallel processing (e.g., multiple subjects at once), n_jobs: int = 1 """ @@ -2215,6 +2249,11 @@ def noise_cov(bids_path): The maximum amount of RAM per Dask worker. """ +# %% +# # Logging +# +# These options control how much logging output is produced. + log_level: Literal["info", "error"] = "info" """ Set the pipeline logging verbosity. @@ -2225,6 +2264,13 @@ def noise_cov(bids_path): Set the MNE-Python logging verbosity. """ + +# %% +# # Error handling +# +# These options control how errors while processing the data or the configuration file +# are handled. + on_error: Literal["continue", "abort", "debug"] = "abort" """ Whether to abort processing as soon as an error occurs, continue with all other @@ -2235,35 +2281,6 @@ def noise_cov(bids_path): Enabling debug mode deactivates parallel processing. """ -memory_location: PathLike | bool | None = True -""" -If not None (or False), caching will be enabled and the cache files will be -stored in the given directory. The default (True) will use a -`"_cache"` subdirectory (name configurable via the -[`memory_subdir`][mne_bids_pipeline._config.memory_subdir] -variable) in the BIDS derivative root of the dataset. -""" - -memory_subdir: str = "_cache" -""" -The caching directory name to use if `memory_location` is `True`. -""" - -memory_file_method: Literal["mtime", "hash"] = "mtime" -""" -The method to use for cache invalidation (i.e., detecting changes). Using the -"modified time" reported by the filesystem (`'mtime'`, default) is very fast -but requires that the filesystem supports proper mtime reporting. Using file -hashes (`'hash'`) is slower and requires reading all input files but should -work on any filesystem. -""" - -memory_verbose: int = 0 -""" -The verbosity to use when using memory. The default (0) does not print, while -1 will print the function calls that will be cached. See the documentation for -the joblib.Memory class for more information.""" - config_validation: Literal["raise", "warn", "ignore"] = "raise" """ How strictly to validate the configuration. Errors are always raised for