From c6d58aaab7a5c125323652231856b58c665a4d3d Mon Sep 17 00:00:00 2001 From: Mathieu Scheltienne Date: Wed, 3 Jan 2024 14:11:32 +0100 Subject: [PATCH] order docdict alphabetically (#142) --- pycrostates/utils/_docs.py | 155 ++++++++++++++++----------- pycrostates/utils/tests/test_docs.py | 21 +++- 2 files changed, 115 insertions(+), 61 deletions(-) diff --git a/pycrostates/utils/_docs.py b/pycrostates/utils/_docs.py index 3aa9432a..5a5c138d 100644 --- a/pycrostates/utils/_docs.py +++ b/pycrostates/utils/_docs.py @@ -9,11 +9,11 @@ from mne.utils.docs import docdict as docdict_mne -# ------------------------- Documentation dictionary ------------------------- +# -- Documentation dictionary ---------------------------------------------------------- docdict: dict[str, str] = {} -# ---- Documentation to inc. from MNE ---- -keys: tuple[str, ...] = ( +# -- Documentation to inc. from MNE ---------------------------------------------------- +_KEYS_MNE: tuple[str, ...] = ( "n_jobs", "picks_all", "random_state", @@ -22,7 +22,7 @@ "reject_by_annotation_raw", ) -for key in keys: +for key in _KEYS_MNE: entry: str = docdict_mne[key] if ".. versionchanged::" in entry: entry = entry.replace(".. versionchanged::", ".. versionchanged:: MNE ") @@ -31,105 +31,140 @@ docdict[key] = entry del key -docdict["verbose"] = """ -verbose : int | str | bool | None - Sets the verbosity level. The verbosity increases gradually between ``"CRITICAL"``, - ``"ERROR"``, ``"WARNING"``, ``"INFO"`` and ``"DEBUG"``. If None is provided, the - verbosity is set to ``"WARNING"``. If a bool is provided, the verbosity is set to - ``"WARNING"`` for False and to ``"INFO"`` for True.""" +# -- A --------------------------------------------------------------------------------- +docdict["axes_cbar"] = """ +cbar_axes : Axes | None + Axes on which to draw the colorbar, otherwise the colormap takes space from the main + axes.""" -# ---- Clusters ---- -docdict["n_clusters"] = """ -n_clusters : int - The number of clusters, i.e. the number of microstates. +docdict["axes_seg"] = """ +axes : Axes | None + Either ``None`` to create a new figure or axes on which the segmentation is + plotted.""" + +docdict["axes_topo"] = """ +axes : Axes | None + Either ``None`` to create a new figure or axes (or an array of axes) on which the + topographic map should be plotted. If the number of microstates maps to plot is + ``≥ 1``, an array of axes of size ``n_clusters`` should be provided.""" + +# -- B --------------------------------------------------------------------------------- +docdict["block"] = """ +block : bool + Whether to halt program execution until the figure is closed.""" + +# -- C --------------------------------------------------------------------------------- +docdict["cluster"] = """ +cluster : :ref:`cluster` + Fitted clustering algorithm from which to compute score. For more details about + current clustering implementations, check the :ref:`Clustering` section of the + documentation. """ + docdict["cluster_centers"] = """ cluster_centers : array (n_clusters, n_channels) Fitted clusters, i.e. the microstates maps.""" + +docdict["cluster_centers_seg"] = """ +cluster_centers : array (n_clusters, n_channels) + Clusters, i.e. the microstates maps used to compute the segmentation.""" + docdict["cluster_names"] = """ cluster_names : list | None Name of the clusters.""" -# ---- Metrics ----- -docdict["cluster"] = """ -cluster : :ref:`cluster` - Fitted clustering algorithm from which to compute score. For more details about - current clustering implementations, check the :ref:`Clustering` section of the - documentation. -""" +docdict["cmap"] = """ +cmap : str | colormap | None + The colormap to use. If None, ``viridis`` is used.""" -# ------ I/O ------- +# -- D --------------------------------------------------------------------------------- +# -- E --------------------------------------------------------------------------------- +# -- F --------------------------------------------------------------------------------- docdict["fname_fiff"] = """ fname : str | Path Path to the ``.fif`` file where the clustering solution is saved.""" -# -- Segmentation -- -docdict["cluster_centers_seg"] = """ -cluster_centers : array (n_clusters, n_channels) - Clusters, i.e. the microstates maps used to compute the segmentation.""" -docdict["labels_raw"] = """ -labels : array of shape ``(n_samples,)`` - Microstates labels attributed to each sample, i.e. the segmentation.""" +# -- G --------------------------------------------------------------------------------- +# -- H --------------------------------------------------------------------------------- +# -- I --------------------------------------------------------------------------------- +docdict["ignore_repetitions"] = """ +ignore_repetitions : bool + If ``True``, ignores state repetitions. + For example, the input sequence ``AAABBCCD`` + will be transformed into ``ABCD`` before any calculation. + This is equivalent to setting the duration of all states to 1 sample.""" + +# -- J --------------------------------------------------------------------------------- +# -- K --------------------------------------------------------------------------------- +# -- L --------------------------------------------------------------------------------- docdict["labels_epo"] = """ labels : array of shape ``(n_epochs, n_samples)`` Microstates labels attributed to each sample, i.e. the segmentation.""" + +docdict["labels_raw"] = """ +labels : array of shape ``(n_samples,)`` + Microstates labels attributed to each sample, i.e. the segmentation.""" + docdict["labels_transition"] = """ labels : array of shape ``(n_samples,)`` or ``(n_epochs, n_samples)`` Microstates labels attributed to each sample, i.e. the segmentation.""" -# TODO: predict_parameters docstring is missing. + +# -- M --------------------------------------------------------------------------------- +# -- N --------------------------------------------------------------------------------- +docdict["n_clusters"] = """ +n_clusters : int + The number of clusters, i.e. the number of microstates. +""" + +# -- O --------------------------------------------------------------------------------- +# -- P --------------------------------------------------------------------------------- docdict["predict_parameters"] = """ predict_parameters : dict | None The prediction parameters.""" -docdict["stat_transition"] = """ + +# -- Q --------------------------------------------------------------------------------- +# -- R --------------------------------------------------------------------------------- +# -- S --------------------------------------------------------------------------------- +docdict["stat_expected_transitions"] = """ stat : str Aggregate statistic to compute transitions. Can be: - * ``count``: show the number of observations of each transition. * ``probability`` or ``proportion``: normalize count such as the probabilities along the first axis is always equal to ``1``. * ``percent``: normalize count such as the probabilities along the first axis is always equal to ``100``.""" -docdict["stat_expected_transitions"] = """ + +docdict["stat_transition"] = """ stat : str Aggregate statistic to compute transitions. Can be: + * ``count``: show the number of observations of each transition. * ``probability`` or ``proportion``: normalize count such as the probabilities along the first axis is always equal to ``1``. * ``percent``: normalize count such as the probabilities along the first axis is always equal to ``100``.""" -docdict["ignore_repetitions"] = """ -ignore_repetitions : bool - If ``True``, ignores state repetitions. - For example, the input sequence ``AAABBCCD`` - will be transformed into ``ABCD`` before any calculation. - This is equivalent to setting the duration of all states to 1 sample.""" + +# -- T --------------------------------------------------------------------------------- docdict["transition_matrix"] = """ T : array of shape ``(n_cluster, n_cluster)`` Array of transition probability values from one label to another. First axis indicates state ``"from"``. Second axis indicates state ``"to"``.""" -# ------ Viz ------- -docdict["cmap"] = """ -cmap : str | colormap | None - The colormap to use. If None, ``viridis`` is used.""" -docdict["block"] = """ -block : bool - Whether to halt program execution until the figure is closed.""" -docdict["axes_topo"] = """ -axes : Axes | None - Either ``None`` to create a new figure or axes (or an array of axes) on which the - topographic map should be plotted. If the number of microstates maps to plot is - ``≥ 1``, an array of axes of size ``n_clusters`` should be provided.""" -docdict["axes_seg"] = """ -axes : Axes | None - Either ``None`` to create a new figure or axes on which the segmentation is - plotted.""" -docdict["axes_cbar"] = """ -cbar_axes : Axes | None - Axes on which to draw the colorbar, otherwise the colormap takes space from the main - axes.""" +# -- U --------------------------------------------------------------------------------- +# -- V --------------------------------------------------------------------------------- +docdict["verbose"] = """ +verbose : int | str | bool | None + Sets the verbosity level. The verbosity increases gradually between ``"CRITICAL"``, + ``"ERROR"``, ``"WARNING"``, ``"INFO"`` and ``"DEBUG"``. If None is provided, the + verbosity is set to ``"WARNING"``. If a bool is provided, the verbosity is set to + ``"WARNING"`` for False and to ``"INFO"`` for True.""" + +# -- W --------------------------------------------------------------------------------- +# -- X --------------------------------------------------------------------------------- +# -- Y --------------------------------------------------------------------------------- +# -- Z --------------------------------------------------------------------------------- -# ------------------------- Documentation functions -------------------------- +# -- Documentation functions ----------------------------------------------------------- docdict_indented: dict[int, dict[str, str]] = {} diff --git a/pycrostates/utils/tests/test_docs.py b/pycrostates/utils/tests/test_docs.py index cdcadaf4..a41d9ccb 100644 --- a/pycrostates/utils/tests/test_docs.py +++ b/pycrostates/utils/tests/test_docs.py @@ -1,8 +1,11 @@ """Test _docs.py""" +import re +from pathlib import Path + import pytest -from pycrostates.utils._docs import copy_doc, fill_doc +from pycrostates.utils._docs import _KEYS_MNE, copy_doc, docdict, fill_doc from pycrostates.utils._logs import verbose @@ -207,3 +210,19 @@ def method4(verbose=None): assert foo.method1.__doc__ == foo2.method2.__doc__ assert foo.method1.__doc__ == foo2.method3.__doc__ assert foo.method1.__doc__ == foo2.method4.__doc__ + + +def test_docdict_order(): + """Test that docdict is alphabetical.""" + # read the file as text, and get entries via regex + docdict_ = docdict.copy() + for key in _KEYS_MNE: + del docdict_[key] + docs_path = Path(__file__).parents[1] / "_docs.py" + assert docs_path.is_file() + with open(docs_path, "r", encoding="UTF-8") as fid: + docs = fid.read() + entries = re.findall(r'docdict\[(?:\n )?["\'](.+)["\']\n?\] = ', docs) + # test length, uniqueness and order + assert len(docdict_) == len(entries) + assert sorted(entries) == entries