DOC: Morlet wavelet length in tfr_morlet (mne-tools#12073)

Co-authored-by: Daniel McCloy <dan@mccloy.info>
Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

Author: 3 people

doc/conf.py

@@ -201,7 +201,7 @@
     "path-like": ":term:`path-like`",
     "array-like": ":term:`array_like <numpy:array_like>`",
     "Path": ":class:`python:pathlib.Path`",
-    "bool": ":ref:`python:typebool`",
+    "bool": ":ref:`bool <python:typebool>`",
     # Matplotlib
     "colormap": ":ref:`colormap <matplotlib:colormaps>`",
     "color": ":doc:`color <matplotlib:api/colors_api>`",

mne/time_frequency/multitaper.py

@@ -534,7 +534,8 @@ def tfr_array_multitaper(
 
     Notes
     -----
-    %(temporal-window_tfr_notes)s
+    %(temporal_window_tfr_intro)s
+    %(temporal_window_tfr_multitaper_notes)s
     %(time_bandwidth_tfr_notes)s
 
     .. versionadded:: 0.14.0

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,9 +948,9 @@ def tfr_morlet(
 
     Notes
     -----
-    %(morlet_notes)s
-    %(temporal-window_tfr_notes)s
-    %(fwhm_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
     Morlet wavelet.
@@ -997,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.
@@ -1039,8 +1039,9 @@ def tfr_array_morlet(
 
     Notes
     -----
-    %(morlet_notes)s
-    %(temporal-window_tfr_notes)s
+    %(morlet_reference)s
+    %(temporal_window_tfr_intro)s
+    %(temporal_window_tfr_morlet_notes)s
 
     .. versionadded:: 0.14.0
 
@@ -1121,7 +1122,8 @@ def tfr_multitaper(
 
     Notes
     -----
-    %(temporal-window_tfr_notes)s
+    %(temporal_window_tfr_intro)s
+    %(temporal_window_tfr_multitaper_notes)s
     %(time_bandwidth_tfr_notes)s
 
     .. versionadded:: 0.9.0

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
@@ -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"
@@ -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[
@@ -4178,7 +4177,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"
@@ -4438,8 +4437,8 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
 """
 
 docdict[
-    "temporal-window_tfr_notes"
-] = r"""
+    "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"
@@ -4457,18 +4456,43 @@ 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 <https://www.fieldtriptoolbox.org/tutorial/timefrequencyanalysis>`_.
+"""  # noqa: E501
+
+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
+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{\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.
+
+For more information on the Morlet wavelet, see :func:`mne.time_frequency.morlet`.
+"""
 
-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"
+] = 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
+``n_cycles=freqs / 2`` yields ``T=array([0.5, 0.5, 0.5])``.
+"""
 
 _theme = """\
 theme : str | path-like