From ddb7f3d49a0d11611303e82b73be4d588a860a25 Mon Sep 17 00:00:00 2001 From: Santeri Ruuskanen Date: Wed, 4 Oct 2023 23:52:41 +0300 Subject: [PATCH 01/11] Add note on Morlet wavelet length This change improves the docstring of mne.time_frequency.tfr_morlet and mne.time_frequency.tfr_array_morlet. An explanation on the length of the Morlet wavelet for time-frequency representation is added. Closes #11645 . --- mne/time_frequency/multitaper.py | 2 +- mne/time_frequency/tfr.py | 7 +++--- mne/utils/docs.py | 37 ++++++++++++++++++++++++++------ 3 files changed, 34 insertions(+), 12 deletions(-) diff --git a/mne/time_frequency/multitaper.py b/mne/time_frequency/multitaper.py index a3ccad28080..96d6b92a911 100644 --- a/mne/time_frequency/multitaper.py +++ b/mne/time_frequency/multitaper.py @@ -534,7 +534,7 @@ def tfr_array_multitaper( Notes ----- - %(temporal-window_tfr_notes)s + %(temporal-window_tfr_multitaper_notes)s %(time_bandwidth_tfr_notes)s .. versionadded:: 0.14.0 diff --git a/mne/time_frequency/tfr.py b/mne/time_frequency/tfr.py index 8a687515dda..a53706bbc3e 100644 --- a/mne/time_frequency/tfr.py +++ b/mne/time_frequency/tfr.py @@ -949,8 +949,7 @@ def tfr_morlet( Notes ----- %(morlet_notes)s - %(temporal-window_tfr_notes)s - %(fwhm_morlet_notes)s + %(temporal-window_tfr_morlet_notes)s See :func:`mne.time_frequency.morlet` for more information about the Morlet wavelet. @@ -1040,7 +1039,7 @@ def tfr_array_morlet( Notes ----- %(morlet_notes)s - %(temporal-window_tfr_notes)s + %(temporal-window_tfr_morlet_notes)s .. versionadded:: 0.14.0 @@ -1121,7 +1120,7 @@ def tfr_multitaper( Notes ----- - %(temporal-window_tfr_notes)s + %(temporal-window_tfr_multitaper_notes)s %(time_bandwidth_tfr_notes)s .. versionadded:: 0.9.0 diff --git a/mne/utils/docs.py b/mne/utils/docs.py index d32e1923aa4..3024c5d41de 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4408,9 +4408,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): the distribution. """ -docdict[ - "temporal-window_tfr_notes" -] = r""" +_temporal_window_tfr_base = """ In spectrotemporal analysis (as with traditional fourier methods), the temporal and spectral resolution are interrelated: longer temporal windows allow more precise frequency estimates; shorter temporal windows "smear" @@ -4428,10 +4426,14 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): smoothing increases with frequency.* Source: `FieldTrip tutorial: Time-frequency analysis using Hanning window, multitapers and wavelets `_. +""" -In MNE-Python, the temporal window length is defined by the arguments ``freqs`` -and ``n_cycles``, respectively defining the frequencies of interest and the -number of cycles: :math:`T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}` +docdict["temporal-window_tfr_multitaper_notes"] = ( + _temporal_window_tfr_base + + r""" +In MNE-Python, the multitaper temporal window length is defined by the arguments +``freqs`` and ``n_cycles``, respectively defining the frequencies of interest +and the number of cycles: :math:`T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}` A fixed number of cycles for all frequencies will yield a temporal window which decreases with frequency. For example, ``freqs=np.arange(1, 6, 2)`` and @@ -4439,7 +4441,28 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): To use a temporal window with fixed length, the number of cycles has to be defined based on the frequency. For example, ``freqs=np.arange(1, 6, 2)`` and -``n_cycles=freqs / 2`` yields ``T=array([0.5, 0.5, 0.5])``.""" # noqa: E501 +``n_cycles=freqs / 2`` yields ``T=array([0.5, 0.5, 0.5])``.""" +) # noqa: E501 + +docdict["temporal-window_tfr_morlet_notes"] = ( + _temporal_window_tfr_base + + r""" +In MNE-Python, the length of the Morlet wavelet is affected by the arguments +``freqs`` and ``n_cycles``, which define the frequencies of interest +and the number of cycles, respectively. For the time-frequency representation, +the length of the wavelet is defined such that both tails of +the wavelet extend five standard deviations from the midpoint of its Gaussian +envelope and that there is a sample at time zero. + +The length of the wavelet is thus :math:`10\times\mathtt{sfreq}\cdot\sigma-1`, +which is equal to :math:`\frac{5}{\pi} \cdot \frac{\mathtt{n\_cycles} \cdot +\mathtt{sfreq}}{\mathtt{freqs}} - 1`, where +:math:`\sigma = \frac{\texttt{n\_cycles}}{2\pi f}` corresponds to the standard +deviation of the wavelet's Gaussian envelope. Note that the length of the +wavelet must not exceed the length of your signal. + +For more information on the Morlet wavelet, see `mne.time_frequency.morlet`.""" +) _theme = """\ theme : str | path-like From 98d0bab066da5af905faf9065d585d798a431099 Mon Sep 17 00:00:00 2001 From: Santeri Ruuskanen Date: Thu, 5 Oct 2023 10:14:59 +0300 Subject: [PATCH 02/11] Fix docdict order --- mne/utils/docs.py | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 3024c5d41de..06797180fe9 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4428,22 +4428,6 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): multitapers and wavelets `_. """ -docdict["temporal-window_tfr_multitaper_notes"] = ( - _temporal_window_tfr_base - + r""" -In MNE-Python, the multitaper temporal window length is defined by the arguments -``freqs`` and ``n_cycles``, respectively defining the frequencies of interest -and the number of cycles: :math:`T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}` - -A fixed number of cycles for all frequencies will yield a temporal window which -decreases with frequency. For example, ``freqs=np.arange(1, 6, 2)`` and -``n_cycles=2`` yields ``T=array([2., 0.7, 0.4])``. - -To use a temporal window with fixed length, the number of cycles has to be -defined based on the frequency. For example, ``freqs=np.arange(1, 6, 2)`` and -``n_cycles=freqs / 2`` yields ``T=array([0.5, 0.5, 0.5])``.""" -) # noqa: E501 - docdict["temporal-window_tfr_morlet_notes"] = ( _temporal_window_tfr_base + r""" @@ -4464,6 +4448,22 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): For more information on the Morlet wavelet, see `mne.time_frequency.morlet`.""" ) +docdict["temporal-window_tfr_multitaper_notes"] = ( + _temporal_window_tfr_base + + r""" +In MNE-Python, the multitaper temporal window length is defined by the arguments +``freqs`` and ``n_cycles``, respectively defining the frequencies of interest +and the number of cycles: :math:`T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}` + +A fixed number of cycles for all frequencies will yield a temporal window which +decreases with frequency. For example, ``freqs=np.arange(1, 6, 2)`` and +``n_cycles=2`` yields ``T=array([2., 0.7, 0.4])``. + +To use a temporal window with fixed length, the number of cycles has to be +defined based on the frequency. For example, ``freqs=np.arange(1, 6, 2)`` and +``n_cycles=freqs / 2`` yields ``T=array([0.5, 0.5, 0.5])``.""" +) # noqa: E501 + _theme = """\ theme : str | path-like Can be "auto", "light", or "dark" or a path-like to a From 3b5d47d27eb5e08671c608d5a4c36f427f08c99e Mon Sep 17 00:00:00 2001 From: Santeri Ruuskanen <66060772+ruuskas@users.noreply.github.com> Date: Thu, 5 Oct 2023 16:20:23 +0300 Subject: [PATCH 03/11] Fix cross-reference Co-authored-by: Daniel McCloy --- mne/utils/docs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index f72e825d49a..7c6a3fd8c75 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4448,7 +4448,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): deviation of the wavelet's Gaussian envelope. Note that the length of the wavelet must not exceed the length of your signal. -For more information on the Morlet wavelet, see `mne.time_frequency.morlet`.""" +For more information on the Morlet wavelet, see :func:`mne.time_frequency.morlet`.""" ) docdict["temporal-window_tfr_multitaper_notes"] = ( From e170e579308db9ccdc841020e6bfc56516aa509a Mon Sep 17 00:00:00 2001 From: Santeri Ruuskanen <66060772+ruuskas@users.noreply.github.com> Date: Thu, 5 Oct 2023 16:20:50 +0300 Subject: [PATCH 04/11] Add whitespace Co-authored-by: Daniel McCloy --- mne/time_frequency/tfr.py | 1 + 1 file changed, 1 insertion(+) diff --git a/mne/time_frequency/tfr.py b/mne/time_frequency/tfr.py index a53706bbc3e..3af4af96f5c 100644 --- a/mne/time_frequency/tfr.py +++ b/mne/time_frequency/tfr.py @@ -1039,6 +1039,7 @@ def tfr_array_morlet( Notes ----- %(morlet_notes)s + %(temporal-window_tfr_morlet_notes)s .. versionadded:: 0.14.0 From 42bea329e13be452613bfd77eb60014c2e067ee0 Mon Sep 17 00:00:00 2001 From: Santeri Ruuskanen <66060772+ruuskas@users.noreply.github.com> Date: Thu, 5 Oct 2023 16:21:29 +0300 Subject: [PATCH 05/11] Fix LaTeX Co-authored-by: Daniel McCloy --- mne/utils/docs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 7c6a3fd8c75..48556e69830 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4444,7 +4444,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): The length of the wavelet is thus :math:`10\times\mathtt{sfreq}\cdot\sigma-1`, which is equal to :math:`\frac{5}{\pi} \cdot \frac{\mathtt{n\_cycles} \cdot \mathtt{sfreq}}{\mathtt{freqs}} - 1`, where -:math:`\sigma = \frac{\texttt{n\_cycles}}{2\pi f}` corresponds to the standard +:math:`\sigma = \frac{\mathtt{n\_cycles}}{2\pi f}` corresponds to the standard deviation of the wavelet's Gaussian envelope. Note that the length of the wavelet must not exceed the length of your signal. From e0a0c0077b09306ef01d488f8ca679f0b62cca44 Mon Sep 17 00:00:00 2001 From: Santeri Ruuskanen <66060772+ruuskas@users.noreply.github.com> Date: Thu, 5 Oct 2023 16:21:56 +0300 Subject: [PATCH 06/11] More whitespace Co-authored-by: Daniel McCloy --- mne/time_frequency/tfr.py | 1 + 1 file changed, 1 insertion(+) diff --git a/mne/time_frequency/tfr.py b/mne/time_frequency/tfr.py index 3af4af96f5c..c02da881bcc 100644 --- a/mne/time_frequency/tfr.py +++ b/mne/time_frequency/tfr.py @@ -1122,6 +1122,7 @@ def tfr_multitaper( Notes ----- %(temporal-window_tfr_multitaper_notes)s + %(time_bandwidth_tfr_notes)s .. versionadded:: 0.9.0 From 65ef52d42655a690bf4cdb0600bcc704f5b6e08a Mon Sep 17 00:00:00 2001 From: Santeri Ruuskanen <66060772+ruuskas@users.noreply.github.com> Date: Thu, 5 Oct 2023 16:22:25 +0300 Subject: [PATCH 07/11] Update mne/time_frequency/multitaper.py Co-authored-by: Daniel McCloy --- mne/time_frequency/multitaper.py | 1 + 1 file changed, 1 insertion(+) diff --git a/mne/time_frequency/multitaper.py b/mne/time_frequency/multitaper.py index e4f404afe5d..ae70a26cf59 100644 --- a/mne/time_frequency/multitaper.py +++ b/mne/time_frequency/multitaper.py @@ -535,6 +535,7 @@ def tfr_array_multitaper( Notes ----- %(temporal-window_tfr_multitaper_notes)s + %(time_bandwidth_tfr_notes)s .. versionadded:: 0.14.0 From dce4db33035958f6cf18f657f4d2dc1fc263166a Mon Sep 17 00:00:00 2001 From: Santeri Ruuskanen <66060772+ruuskas@users.noreply.github.com> Date: Thu, 5 Oct 2023 16:22:50 +0300 Subject: [PATCH 08/11] More whitespace Co-authored-by: Daniel McCloy --- mne/utils/docs.py | 1 + 1 file changed, 1 insertion(+) diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 48556e69830..7080ab26e73 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -4429,6 +4429,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): smoothing increases with frequency.* Source: `FieldTrip tutorial: Time-frequency analysis using Hanning window, multitapers and wavelets `_. + """ docdict["temporal-window_tfr_morlet_notes"] = ( From c93165fdf393eb9fca752355034b072968ec421c Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Thu, 5 Oct 2023 18:02:26 +0300 Subject: [PATCH 09/11] whitespace --- mne/time_frequency/multitaper.py | 4 +++- mne/time_frequency/tfr.py | 11 ++++++++--- mne/utils/docs.py | 34 ++++++++++++-------------------- 3 files changed, 24 insertions(+), 25 deletions(-) diff --git a/mne/time_frequency/multitaper.py b/mne/time_frequency/multitaper.py index ae70a26cf59..49975e23e35 100644 --- a/mne/time_frequency/multitaper.py +++ b/mne/time_frequency/multitaper.py @@ -534,7 +534,9 @@ def tfr_array_multitaper( Notes ----- - %(temporal-window_tfr_multitaper_notes)s + %(temporal_window_tfr_intro)s + + %(temporal_window_tfr_multitaper_notes)s %(time_bandwidth_tfr_notes)s diff --git a/mne/time_frequency/tfr.py b/mne/time_frequency/tfr.py index c02da881bcc..78041760b51 100644 --- a/mne/time_frequency/tfr.py +++ b/mne/time_frequency/tfr.py @@ -949,7 +949,8 @@ def tfr_morlet( Notes ----- %(morlet_notes)s - %(temporal-window_tfr_morlet_notes)s + + %(temporal_window_tfr_morlet_notes)s See :func:`mne.time_frequency.morlet` for more information about the Morlet wavelet. @@ -1040,7 +1041,9 @@ def tfr_array_morlet( ----- %(morlet_notes)s - %(temporal-window_tfr_morlet_notes)s + %(temporal_window_tfr_intro)s + + %(temporal_window_tfr_morlet_notes)s .. versionadded:: 0.14.0 @@ -1121,7 +1124,9 @@ def tfr_multitaper( Notes ----- - %(temporal-window_tfr_multitaper_notes)s + %(temporal_window_tfr_intro)s + + %(temporal_window_tfr_multitaper_notes)s %(time_bandwidth_tfr_notes)s diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 7080ab26e73..2111c9a89f5 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -2669,10 +2669,8 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): docdict[ "morlet_notes" -] = """ -The Morlet wavelets follow the formulation in -:footcite:`Tallon-BaudryEtAl1997`. -""" +] = """The Morlet wavelets follow the formulation in +:footcite:`Tallon-BaudryEtAl1997`.""" docdict[ "moving" @@ -4411,8 +4409,9 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): the distribution. """ -_temporal_window_tfr_base = """ -In spectrotemporal analysis (as with traditional fourier methods), +docdict[ + "temporal_window_tfr_intro" +] = """In spectrotemporal analysis (as with traditional fourier methods), the temporal and spectral resolution are interrelated: longer temporal windows allow more precise frequency estimates; shorter temporal windows "smear" frequency estimates while providing more precise timing information. @@ -4428,14 +4427,11 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): decrease with frequency, the temporal smoothing decreases and the frequency smoothing increases with frequency.* Source: `FieldTrip tutorial: Time-frequency analysis using Hanning window, -multitapers and wavelets `_. - -""" +multitapers and wavelets `_.""" -docdict["temporal-window_tfr_morlet_notes"] = ( - _temporal_window_tfr_base - + r""" -In MNE-Python, the length of the Morlet wavelet is affected by the arguments +docdict[ + "temporal_window_tfr_morlet_notes" +] = r"""In MNE-Python, the length of the Morlet wavelet is affected by the arguments ``freqs`` and ``n_cycles``, which define the frequencies of interest and the number of cycles, respectively. For the time-frequency representation, the length of the wavelet is defined such that both tails of @@ -4450,12 +4446,10 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): wavelet must not exceed the length of your signal. For more information on the Morlet wavelet, see :func:`mne.time_frequency.morlet`.""" -) -docdict["temporal-window_tfr_multitaper_notes"] = ( - _temporal_window_tfr_base - + r""" -In MNE-Python, the multitaper temporal window length is defined by the arguments +docdict[ + "temporal_window_tfr_multitaper_notes" +] = r"""In MNE-Python, the multitaper temporal window length is defined by the arguments ``freqs`` and ``n_cycles``, respectively defining the frequencies of interest and the number of cycles: :math:`T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}` @@ -4466,7 +4460,6 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): To use a temporal window with fixed length, the number of cycles has to be defined based on the frequency. For example, ``freqs=np.arange(1, 6, 2)`` and ``n_cycles=freqs / 2`` yields ``T=array([0.5, 0.5, 0.5])``.""" -) # noqa: E501 _theme = """\ theme : str | path-like @@ -4563,8 +4556,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): docdict[ "time_bandwidth_tfr_notes" -] = r""" -In MNE-Python's multitaper functions, the frequency bandwidth is +] = r"""In MNE-Python's multitaper functions, the frequency bandwidth is additionally affected by the parameter ``time_bandwidth``. The ``n_cycles`` parameter determines the temporal window length based on the frequencies of interest: :math:`T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}`. From 5ebd9a19d96fa5c06e0a2366881f175ed59d500d Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 6 Oct 2023 11:36:01 +0300 Subject: [PATCH 10/11] FIX: Notes --- mne/time_frequency/multitaper.py | 2 -- mne/time_frequency/tfr.py | 5 ----- mne/utils/docs.py | 33 ++++++++++++++++++++------------ 3 files changed, 21 insertions(+), 19 deletions(-) diff --git a/mne/time_frequency/multitaper.py b/mne/time_frequency/multitaper.py index 49975e23e35..8810926f817 100644 --- a/mne/time_frequency/multitaper.py +++ b/mne/time_frequency/multitaper.py @@ -535,9 +535,7 @@ def tfr_array_multitaper( Notes ----- %(temporal_window_tfr_intro)s - %(temporal_window_tfr_multitaper_notes)s - %(time_bandwidth_tfr_notes)s .. versionadded:: 0.14.0 diff --git a/mne/time_frequency/tfr.py b/mne/time_frequency/tfr.py index 78041760b51..91ca5e586be 100644 --- a/mne/time_frequency/tfr.py +++ b/mne/time_frequency/tfr.py @@ -949,7 +949,6 @@ def tfr_morlet( Notes ----- %(morlet_notes)s - %(temporal_window_tfr_morlet_notes)s See :func:`mne.time_frequency.morlet` for more information about the @@ -1040,9 +1039,7 @@ def tfr_array_morlet( Notes ----- %(morlet_notes)s - %(temporal_window_tfr_intro)s - %(temporal_window_tfr_morlet_notes)s .. versionadded:: 0.14.0 @@ -1125,9 +1122,7 @@ def tfr_multitaper( Notes ----- %(temporal_window_tfr_intro)s - %(temporal_window_tfr_multitaper_notes)s - %(time_bandwidth_tfr_notes)s .. versionadded:: 0.9.0 diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 2111c9a89f5..3b6bc613452 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -1852,7 +1852,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): frequency in ``freqs``. If you want different FWHM values at each frequency, do the same computation with ``desired_fwhm`` as an array of the same shape as ``freqs``. -""" # noqa E501 +""" # %% # G @@ -2344,7 +2344,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): ] = """ label_tc : array | list (or generator) of array, shape (n_labels[, n_orient], n_times) Extracted time course for each label and source estimate. -""" # noqa: E501 +""" docdict[ "labels_eltc" @@ -2669,8 +2669,10 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): docdict[ "morlet_notes" -] = """The Morlet wavelets follow the formulation in -:footcite:`Tallon-BaudryEtAl1997`.""" +] = """ +The Morlet wavelets follow the formulation in +:footcite:`Tallon-BaudryEtAl1997`. +""" docdict[ "moving" @@ -4150,7 +4152,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): .. versionadded:: 0.20 .. versionchanged:: 1.1 Added ``'eeglab'`` option. -""" # noqa E501 +""" docdict[ "split_naming" @@ -4411,7 +4413,8 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): docdict[ "temporal_window_tfr_intro" -] = """In spectrotemporal analysis (as with traditional fourier methods), +] = """ +In spectrotemporal analysis (as with traditional fourier methods), the temporal and spectral resolution are interrelated: longer temporal windows allow more precise frequency estimates; shorter temporal windows "smear" frequency estimates while providing more precise timing information. @@ -4427,11 +4430,13 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): decrease with frequency, the temporal smoothing decreases and the frequency smoothing increases with frequency.* Source: `FieldTrip tutorial: Time-frequency analysis using Hanning window, -multitapers and wavelets `_.""" +multitapers and wavelets `_. +""" # noqa: E501 docdict[ "temporal_window_tfr_morlet_notes" -] = r"""In MNE-Python, the length of the Morlet wavelet is affected by the arguments +] = r""" +In MNE-Python, the length of the Morlet wavelet is affected by the arguments ``freqs`` and ``n_cycles``, which define the frequencies of interest and the number of cycles, respectively. For the time-frequency representation, the length of the wavelet is defined such that both tails of @@ -4445,11 +4450,13 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): deviation of the wavelet's Gaussian envelope. Note that the length of the wavelet must not exceed the length of your signal. -For more information on the Morlet wavelet, see :func:`mne.time_frequency.morlet`.""" +For more information on the Morlet wavelet, see :func:`mne.time_frequency.morlet`. +""" docdict[ "temporal_window_tfr_multitaper_notes" -] = r"""In MNE-Python, the multitaper temporal window length is defined by the arguments +] = r""" +In MNE-Python, the multitaper temporal window length is defined by the arguments ``freqs`` and ``n_cycles``, respectively defining the frequencies of interest and the number of cycles: :math:`T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}` @@ -4459,7 +4466,8 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): To use a temporal window with fixed length, the number of cycles has to be defined based on the frequency. For example, ``freqs=np.arange(1, 6, 2)`` and -``n_cycles=freqs / 2`` yields ``T=array([0.5, 0.5, 0.5])``.""" +``n_cycles=freqs / 2`` yields ``T=array([0.5, 0.5, 0.5])``. +""" _theme = """\ theme : str | path-like @@ -4556,7 +4564,8 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): docdict[ "time_bandwidth_tfr_notes" -] = r"""In MNE-Python's multitaper functions, the frequency bandwidth is +] = r""" +In MNE-Python's multitaper functions, the frequency bandwidth is additionally affected by the parameter ``time_bandwidth``. The ``n_cycles`` parameter determines the temporal window length based on the frequencies of interest: :math:`T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}`. From 40386819721ceb0b669b2527940c092492707844 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Fri, 6 Oct 2023 13:18:23 +0300 Subject: [PATCH 11/11] fix missing section; little tweaks --- doc/conf.py | 2 +- mne/time_frequency/tfr.py | 9 +++++---- mne/utils/docs.py | 7 +++---- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 68e63396bd4..ccfe4c0b08f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -200,7 +200,7 @@ "path-like": ":term:`path-like`", "array-like": ":term:`array_like `", "Path": ":class:`python:pathlib.Path`", - "bool": ":class:`python:bool`", + "bool": ":class:`bool `", # Matplotlib "colormap": ":ref:`colormap `", "color": ":doc:`color `", diff --git a/mne/time_frequency/tfr.py b/mne/time_frequency/tfr.py index 91ca5e586be..1a061b8b173 100644 --- a/mne/time_frequency/tfr.py +++ b/mne/time_frequency/tfr.py @@ -114,7 +114,7 @@ def morlet(sfreq, freqs, n_cycles=7.0, sigma=None, zero_mean=False): Notes ----- - %(morlet_notes)s + %(morlet_reference)s %(fwhm_morlet_notes)s References @@ -948,7 +948,8 @@ def tfr_morlet( Notes ----- - %(morlet_notes)s + %(morlet_reference)s + %(temporal_window_tfr_intro)s %(temporal_window_tfr_morlet_notes)s See :func:`mne.time_frequency.morlet` for more information about the @@ -996,7 +997,7 @@ def tfr_array_morlet( Sampling frequency of the data. %(freqs_tfr)s %(n_cycles_tfr)s - zero_mean : bool | False + zero_mean : bool If True, make sure the wavelets have a mean of zero. default False. use_fft : bool Use the FFT for convolutions or not. default True. @@ -1038,7 +1039,7 @@ def tfr_array_morlet( Notes ----- - %(morlet_notes)s + %(morlet_reference)s %(temporal_window_tfr_intro)s %(temporal_window_tfr_morlet_notes)s diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 3b6bc613452..2eeb739937a 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -1829,7 +1829,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): of the wavelet is determined by the ``sigma`` parameter, which gives the standard deviation of the wavelet's Gaussian envelope (our wavelets extend to ±5 standard deviations to ensure values very close to zero at the endpoints). -Some authors (e.g., :footcite:`Cohen2019`) recommend specifying and reporting +Some authors (e.g., :footcite:t:`Cohen2019`) recommend specifying and reporting wavelet duration in terms of the full-width half-maximum (FWHM) of the wavelet's Gaussian envelope. The FWHM is related to ``sigma`` by the following identity: :math:`\mathrm{FWHM} = \sigma \times 2 \sqrt{2 \ln{2}}` (or the @@ -2668,10 +2668,9 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): """ docdict[ - "morlet_notes" + "morlet_reference" ] = """ -The Morlet wavelets follow the formulation in -:footcite:`Tallon-BaudryEtAl1997`. +The Morlet wavelets follow the formulation in :footcite:t:`Tallon-BaudryEtAl1997`. """ docdict[