Improve config tutorial (mne-tools#14010)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: cbrnr

doc/changes/dev/14010.other.rst

@@ -0,0 +1 @@
+Add table with all available config options to :ref:`tut-configure-mne`, by `Clemens Brunner`_.

mne/utils/config.py

@@ -98,67 +98,62 @@ def set_memmap_min_size(memmap_min_size):
         "tuple, width and height of the raw browser window (in inches)"
     ),
     "MNE_BROWSER_BACKEND": (
-        "str, the backend to use for the MNE Browse Raw window (qt or matplotlib)"
+        'str, the backend to use for the raw browser ("qt" or "matplotlib")'
     ),
     "MNE_BROWSER_OVERVIEW_MODE": (
-        "str, the overview mode to use in the MNE Browse Raw window )"
-        "(see mne.viz.plot_raw for valid options)"
+        "str, the overview mode to use in the raw browser (see mne.viz.plot_raw() for "
+        "valid options)"
     ),
     "MNE_BROWSER_PRECOMPUTE": (
-        "bool, whether to precompute raw data in the MNE Browse Raw window"
+        "bool, whether to precompute raw data in the raw browser"
+    ),
+    "MNE_BROWSER_THEME": (
+        "str, the color theme (light or dark) to use for the raw browser"
     ),
-    "MNE_BROWSER_THEME": "str, the color theme (light or dark) to use for the browser",
     "MNE_BROWSER_USE_OPENGL": (
-        "bool, whether to use OpenGL for rendering in the MNE Browse Raw window"
+        "bool, whether to use OpenGL for rendering in the raw browser"
     ),
     "MNE_CACHE_DIR": "str, path to the cache directory for parallel execution",
     "MNE_COREG_ADVANCED_RENDERING": (
-        "bool, whether to use advanced OpenGL rendering in mne coreg"
+        "bool, whether to use advanced OpenGL rendering in coreg"
     ),
     "MNE_COREG_COPY_ANNOT": (
         "bool, whether to copy the annotation files during warping"
     ),
-    "MNE_COREG_FULLSCREEN": "bool, whether to use full-screen mode in mne coreg",
-    "MNE_COREG_GUESS_MRI_SUBJECT": (
-        "bool, whether to guess the MRI subject in mne coreg"
-    ),
-    "MNE_COREG_HEAD_HIGH_RES": (
-        "bool, whether to use high-res head surface in mne coreg"
-    ),
-    "MNE_COREG_HEAD_OPACITY": ("bool, the head surface opacity to use in mne coreg"),
+    "MNE_COREG_FULLSCREEN": "bool, whether to use full-screen mode in coreg",
+    "MNE_COREG_GUESS_MRI_SUBJECT": "bool, whether to guess the MRI subject in coreg",
+    "MNE_COREG_HEAD_HIGH_RES": "bool, whether to use high-res head surface in coreg",
+    "MNE_COREG_HEAD_OPACITY": "bool, the head surface opacity to use in coreg",
     "MNE_COREG_HEAD_INSIDE": (
-        "bool, whether to add an opaque inner scalp head surface to help "
-        "occlude points behind the head in mne coreg"
-    ),
-    "MNE_COREG_INTERACTION": (
-        "str, interaction style in mne coreg (trackball or terrain)"
+        "bool, whether to add an opaque inner scalp head surface to help occlude points"
+        " behind the head in coreg"
     ),
+    "MNE_COREG_INTERACTION": ("str, interaction style in coreg (trackball or terrain)"),
     "MNE_COREG_MARK_INSIDE": (
-        "bool, whether to mark points inside the head surface in mne coreg"
+        "bool, whether to mark points inside the head surface in coreg"
     ),
     "MNE_COREG_PREPARE_BEM": (
-        "bool, whether to prepare the BEM solution after warping in mne coreg"
+        "bool, whether to prepare the BEM solution after warping in coreg"
     ),
     "MNE_COREG_ORIENT_TO_SURFACE": (
-        "bool, whether to orient the digitization markers to the head surface "
-        "in mne coreg"
+        "bool, whether to orient the digitization markers to the head surface in coreg"
     ),
     "MNE_COREG_SCALE_LABELS": (
-        "bool, whether to scale the MRI labels during warping in mne coreg"
+        "bool, whether to scale the MRI labels during warping in coreg"
     ),
     "MNE_COREG_SCALE_BY_DISTANCE": (
-        "bool, whether to scale the digitization markers by their distance from "
-        "the scalp in mne coreg"
+        "bool, whether to scale the digitization markers by their distance from the "
+        "scalp in coreg"
     ),
     "MNE_COREG_SCENE_SCALE": (
-        "float, the scale factor of the 3D scene in mne coreg (default 0.16)"
+        "float, the scale factor of the 3D scene in coreg (default 0.16)"
     ),
-    "MNE_COREG_WINDOW_HEIGHT": "int, window height for mne coreg",
-    "MNE_COREG_WINDOW_WIDTH": "int, window width for mne coreg",
-    "MNE_COREG_SUBJECTS_DIR": "str, path to the subjects directory for mne coreg",
+    "MNE_COREG_WINDOW_HEIGHT": "int, window height for coreg",
+    "MNE_COREG_WINDOW_WIDTH": "int, window width for coreg",
+    "MNE_COREG_SUBJECTS_DIR": "str, path to the subjects directory for coreg",
     "MNE_CUDA_DEVICE": "int, CUDA device to use for GPU processing",
     "MNE_DATA": "str, default data directory",
-    "MNE_DATASETS_BRAINSTORM_PATH": "str, path for brainstorm data",
+    "MNE_DATASETS_BRAINSTORM_PATH": "str, path for Brainstorm data",
     "MNE_DATASETS_EEGBCI_PATH": "str, path for EEGBCI data",
     "MNE_DATASETS_EPILEPSY_ECOG_PATH": "str, path for epilepsy_ecog data",
     "MNE_DATASETS_HF_SEF_PATH": "str, path for HF_SEF data",
@@ -185,29 +180,28 @@ def set_memmap_min_size(memmap_min_size):
     "MNE_DATASETS_ERP_CORE_PATH": "str, path for erp_core data",
     "MNE_FORCE_SERIAL": "bool, force serial rather than parallel execution",
     "MNE_LOGGING_LEVEL": (
-        "str or int, controls the level of verbosity of any function "
-        "decorated with @verbose. See "
-        "https://mne.tools/stable/auto_tutorials/intro/50_configure_mne.html#logging"
+        "str or int, controls the level of verbosity of any function decorated with "
+        "@verbose"
     ),
     "MNE_MEMMAP_MIN_SIZE": (
         "str, threshold on the minimum size of arrays passed to the workers that "
         "triggers automated memory mapping, e.g., 1M or 0.5G"
     ),
     "MNE_REPR_HTML": (
-        "bool, represent some of our objects with rich HTML in a notebook environment"
+        "bool, represent some objects with rich HTML in a notebook environment"
     ),
     "MNE_SKIP_NETWORK_TESTS": (
-        "bool, used in a test decorator (@requires_good_network) to skip "
-        "tests that include large downloads"
+        "bool, used in a test decorator (@requires_good_network) to skip  tests that "
+        "include large downloads"
     ),
     "MNE_SKIP_TESTING_DATASET_TESTS": (
-        "bool, used in test decorators (@requires_spm_data, "
-        "@requires_bstraw_data) to skip tests that require specific datasets"
+        "bool, used in test decorators (@requires_spm_data, @requires_bstraw_data) to "
+        "skip tests that require specific datasets"
     ),
-    "MNE_STIM_CHANNEL": "string, the default channel name for mne.find_events",
+    "MNE_STIM_CHANNEL": "str, the default channel name for mne.find_events()",
     "MNE_TQDM": (
-        'str, either "tqdm", "tqdm.auto", or "off". Controls presence/absence '
-        "of progress bars"
+        'str, either "tqdm", "tqdm.auto", or "off". Controls presence/absence of '
+        "progress bars"
     ),
     "MNE_USE_CUDA": "bool, use GPU for filtering/resampling",
     "MNE_USE_NUMBA": (

tutorials/intro/50_configure_mne.py

@@ -19,6 +19,8 @@
 
 import os
 
+import pandas as pd
+
 import mne
 
 # %%
@@ -34,12 +36,15 @@
 # if you want):
 
 print(mne.get_config("MNE_USE_CUDA"))
-print(type(mne.get_config("MNE_USE_CUDA")))
 
 # %%
-# Note that the string values read from the JSON file are not parsed in any
-# way, so :func:`~mne.get_config` returns a string even for true/false config
-# values, rather than a Python :ref:`boolean <python:typebool>`.
+# ``None`` is returned above if the requested key hasn't been set on your
+# system. In fact, :func:`~mne.get_config` never invents a default value for a
+# recognized key, it only reports what's actually stored in the JSON file or
+# the environment. Also note that the string values that are read from the
+# JSON file are not parsed in any way, so :func:`~mne.get_config` returns a
+# string even for true/false config values, rather than a Python
+# :ref:`boolean <python:typebool>`.
 # Similarly, :func:`~mne.set_config` will only set string values (or ``None``
 # values, to unset a variable):
 
@@ -64,12 +69,36 @@
 print(mne.get_config())  # same as mne.get_config(key=None)
 
 # %%
-# The second convenience mode will return a :class:`tuple` of all the keys that
-# MNE-Python recognizes and uses, regardless of whether they've been set on
-# your system. This is done by passing an empty string ``''`` as the ``key``:
+# The second convenience mode will return a :class:`dict` containing all the
+# keys that MNE-Python recognizes and uses, mapped to a short description of
+# each one, regardless of whether they've been set on your system. This is
+# done by passing an empty string as the ``key``:
 
 print(mne.get_config(key=""))
 
+# %%
+# Overview of all configuration keys
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#
+# Since the dictionary above can be hard to read, here it is again, sorted
+# alphabetically and displayed as a table (using a :class:`pandas.DataFrame`)
+# so you can get an overview of all the configuration keys MNE-Python
+# recognizes and what they're used for:
+
+pd.set_option("display.max_rows", None)
+pd.set_option("display.max_colwidth", None)
+(
+    pd.DataFrame(sorted(mne.get_config(key="").items()), columns=["Key", "Description"])
+    .style.hide(axis="index")
+    .set_table_attributes('class="dataframe" style="width: 100%;"')
+)
+
+# %%
+# Restore the pandas defaults we changed above:
+
+pd.reset_option("display.max_rows")
+pd.reset_option("display.max_colwidth")
+
 # %%
 # It is possible to add config variables that are not part of the recognized
 # list, by passing any arbitrary key to :func:`~mne.set_config`. This will
@@ -99,7 +128,7 @@
 print(mne.get_config_path())
 
 # %%
-# However it is not a good idea to directly edit files in the :file:`.mne`
+# However, it is not a good idea to directly edit files in the :file:`.mne`
 # directory; use the getting and setting functions described in :ref:`the
 # previous section <config-get-set>`.
 #
@@ -130,7 +159,7 @@
 # %%
 # Also by default, :func:`~mne.set_config` will set values in both the JSON
 # file and in :data:`os.environ`; to set a config variable *only* in the JSON
-# file use ``set_env=False``. Here we'll use :func:`print` statement to confirm
+# file use ``set_env=False``. Here we'll use a :func:`print` statement to confirm
 # that an environment variable is being created and deleted (we could have used
 # the Python :ref:`assert statement <assert>` instead, but it doesn't print any
 # output when it succeeds so it's a little less obvious):
@@ -150,13 +179,11 @@
 #
 # One important configuration variable is ``MNE_LOGGING_LEVEL``. Throughout the
 # module, messages are generated describing the actions MNE-Python is taking
-# behind-the-scenes. How you set ``MNE_LOGGING_LEVEL`` determines how many of
+# behind the scenes. How you set ``MNE_LOGGING_LEVEL`` determines how many of
 # those messages you see. The default logging level on a fresh install of
-# MNE-Python is ``info``:
-
-print(mne.get_config("MNE_LOGGING_LEVEL"))
-
-# %%
+# MNE-Python is ``info``.
+#
+#
 # The logging levels that can be set as config variables are ``debug``,
 # ``info``, ``warning``, ``error``, and ``critical``. Around 90% of the log
 # messages in MNE-Python are ``info`` messages, so for most users the choice is
@@ -169,7 +196,7 @@
 # :func:`mne.set_config` is used to change the logging level for the current
 # Python session and all future sessions. To change the logging level only for
 # the current Python session, you can use :func:`mne.set_log_level` instead.
-# The :func:`~mne.set_log_level` function takes the same five string options
+# This function takes the same five string options
 # that are used for the ``MNE_LOGGING_LEVEL`` config variable; additionally, it
 # can accept :class:`int` or :class:`bool` values that are equivalent to those
 # strings. The equivalencies are given in this table:
@@ -191,7 +218,7 @@
 # +----------+---------+---------+
 #
 # With many MNE-Python functions it is possible to change the logging level
-# temporarily for just that function call, by using the ``verbose`` parameter.
+# temporarily for just that function call by using the ``verbose`` parameter.
 # To illustrate this, we'll load some sample data with different logging levels
 # set. First, with log level ``warning``: