File: docs.py

package info (click to toggle)
python-mne 1.3.0%2Bdfsg-1
links: PTS, VCS
area: main
in suites: bookworm
size: 100,172 kB
sloc: python: 166,349; pascal: 3,602; javascript: 1,472; sh: 334; makefile: 236
file content (4556 lines) | stat: -rw-r--r-- 167,460 bytes
# -*- coding: utf-8 -*-
"""The documentation functions."""
# Authors: Eric Larson <larson.eric.d@gmail.com>
#
# License: BSD-3-Clause

import inspect
import os
import os.path as op
import re
import sys
import webbrowser
from copy import deepcopy

from decorator import FunctionMaker

from ..defaults import HEAD_SIZE_DEFAULT
from ._bunch import BunchConst


def _reflow_param_docstring(docstring, has_first_line=True, width=75):
    """Reflow text to a nice width for terminals.

    WARNING: does not handle gracefully things like .. versionadded::
    """
    maxsplit = docstring.count('\n') - 1 if has_first_line else -1
    merged = ' '.join(line.strip() for line in
                      docstring.rsplit('\n', maxsplit=maxsplit))
    reflowed = '\n    '.join(re.findall(fr'.{{1,{width}}}(?:\s+|$)', merged))
    if has_first_line:
        reflowed = reflowed.replace('\n    \n', '\n', 1)
    return reflowed


##############################################################################
# Define our standard documentation entries
#
# To reduce redundancy across functions, please standardize the format to
# ``argument_optional_keywords``. For example ``tmin_raw`` for an entry that
# is specific to ``raw`` and since ``tmin`` is used other places, needs to
# be disambiguated. This way the entries will be easy to find since they
# are alphabetized (you can look up by the name of the argument). This way
# the same ``docdict`` entries are easier to reuse.

docdict = BunchConst()

# %%
# A

docdict['accept'] = """
accept : bool
    If True (default False), accept the license terms of this dataset.
"""

docdict['add_ch_type_export_params'] = """
add_ch_type : bool
    Whether to incorporate the channel type into the signal label (e.g. whether
    to store channel "Fz" as "EEG Fz"). Only used for EDF format. Default is
    ``False``.
"""

docdict['add_data_kwargs'] = """
add_data_kwargs : dict | None
    Additional arguments to brain.add_data (e.g.,
    ``dict(time_label_size=10)``).
"""

docdict['add_frames'] = """
add_frames : int | None
    If int, enable (>=1) or disable (0) the printing of stack frame
    information using formatting. Default (None) does not change the
    formatting. This can add overhead so is meant only for debugging.
"""

docdict['adjacency_clust'] = """
adjacency : scipy.sparse.spmatrix | None | False
    Defines adjacency between locations in the data, where "locations" can be
    spatial vertices, frequency bins, time points, etc. For spatial vertices,
    see: :func:`mne.channels.find_ch_adjacency`. If ``False``, assumes
    no adjacency (each location is treated as independent and unconnected).
    If ``None``, a regular lattice adjacency is assumed, connecting
    each {sp} location to its neighbor(s) along the last dimension
    of {{eachgrp}} ``{{x}}``{lastdim}.
    If ``adjacency`` is a matrix, it is assumed to be symmetric (only the
    upper triangular half is used) and must be square with dimension equal to
    ``{{x}}.shape[-1]`` {parone} or ``{{x}}.shape[-1] * {{x}}.shape[-2]``
    {partwo} or (optionally)
    ``{{x}}.shape[-1] * {{x}}.shape[-2] * {{x}}.shape[-3]``
    {parthree}.{memory}
"""

mem = (' If spatial adjacency is uniform in time, it is recommended to use '
       'a square matrix with dimension ``{x}.shape[-1]`` (n_vertices) to save '
       'memory and computation, and to use ``max_step`` to define the extent '
       'of temporal adjacency to consider when clustering.')
comb = ' The function `mne.stats.combine_adjacency` may be useful for 4D data.'
st = dict(sp='spatial', lastdim='', parone='(n_vertices)',
          partwo='(n_times * n_vertices)',
          parthree='(n_times * n_freqs * n_vertices)', memory=mem)
tf = dict(sp='', lastdim=' (or the last two dimensions if ``{x}`` is 2D)',
          parone='(for 2D data)', partwo='(for 3D data)',
          parthree='(for 4D data)', memory=comb)
nogroups = dict(eachgrp='', x='X')
groups = dict(eachgrp='each group ', x='X[k]')
docdict['adjacency_clust_1'] = \
    docdict['adjacency_clust'].format(**tf).format(**nogroups)
docdict['adjacency_clust_n'] = \
    docdict['adjacency_clust'].format(**tf).format(**groups)
docdict['adjacency_clust_st1'] = \
    docdict['adjacency_clust'].format(**st).format(**nogroups)
docdict['adjacency_clust_stn'] = \
    docdict['adjacency_clust'].format(**st).format(**groups)

docdict['adjust_dig_chpi'] = """
adjust_dig : bool
    If True, adjust the digitization locations used for fitting based on
    the positions localized at the start of the file.
"""

docdict['agg_fun_psd_topo'] = """
agg_fun : callable
    The function used to aggregate over frequencies. Defaults to
    :func:`numpy.sum` if ``normalize=True``, else :func:`numpy.mean`.
"""

docdict['align_view'] = """
align : bool
    If True, consider view arguments relative to canonical MRI
    directions (closest to MNI for the subject) rather than native MRI
    space. This helps when MRIs are not in standard orientation (e.g.,
    have large rotations).
"""

docdict['allow_empty_eltc'] = """
allow_empty : bool | str
    ``False`` (default) will emit an error if there are labels that have no
    vertices in the source estimate. ``True`` and ``'ignore'`` will return
    all-zero time courses for labels that do not have any vertices in the
    source estimate, and True will emit a warning while and "ignore" will
    just log a message.

    .. versionchanged:: 0.21.0
       Support for "ignore".
"""

docdict['alpha'] = """
alpha : float in [0, 1]
    Alpha level to control opacity.
"""

docdict['anonymize_info_notes'] = """
Removes potentially identifying information if it exists in ``info``.
Specifically for each of the following we use:

- meas_date, file_id, meas_id
        A default value, or as specified by ``daysback``.
- subject_info
        Default values, except for 'birthday' which is adjusted
        to maintain the subject age.
- experimenter, proj_name, description
        Default strings.
- utc_offset
        ``None``.
- proj_id
        Zeros.
- proc_history
        Dates use the ``meas_date`` logic, and experimenter a default string.
- helium_info, device_info
        Dates use the ``meas_date`` logic, meta info uses defaults.

If ``info['meas_date']`` is ``None``, it will remain ``None`` during processing
the above fields.

Operates in place.
"""

# raw/epochs/evoked apply_function method
# apply_function method summary
applyfun_summary = """\
The function ``fun`` is applied to the channels defined in ``picks``.
The {} object's data is modified in-place. If the function returns a different
data type (e.g. :py:obj:`numpy.complex128`) it must be specified
using the ``dtype`` parameter, which causes the data type of **all** the data
to change (even if the function is only applied to channels in ``picks``).{}

.. note:: If ``n_jobs`` > 1, more memory is required as
          ``len(picks) * n_times`` additional time points need to
          be temporarily stored in memory.
.. note:: If the data type changes (``dtype != None``), more memory is
          required since the original and the converted data needs
          to be stored in memory.
"""
applyfun_preload = (' The object has to have the data loaded e.g. with '
                    '``preload=True`` or ``self.load_data()``.')
docdict['applyfun_summary_epochs'] = \
    applyfun_summary.format('epochs', applyfun_preload)
docdict['applyfun_summary_evoked'] = \
    applyfun_summary.format('evoked', '')
docdict['applyfun_summary_raw'] = \
    applyfun_summary.format('raw', applyfun_preload)

docdict['area_alpha_plot_psd'] = """\
area_alpha : float
    Alpha for the area.
"""

docdict['area_mode_plot_psd'] = """\
area_mode : str | None
    Mode for plotting area. If 'std', the mean +/- 1 STD (across channels)
    will be plotted. If 'range', the min and max (across channels) will be
    plotted. Bad channels will be excluded from these calculations.
    If None, no area will be plotted. If average=False, no area is plotted.
"""

docdict['aseg'] = """
aseg : str
    The anatomical segmentation file. Default ``aparc+aseg``. This may
    be any anatomical segmentation file in the mri subdirectory of the
    Freesurfer subject directory.
"""

docdict['average_plot_evoked_topomap'] = """
average : float | array-like of float, shape (n_times,) | None
    The time window (in seconds) around a given time point to be used for
    averaging. For example, 0.2 would translate into a time window that
    starts 0.1 s before and ends 0.1 s after the given time point. If the
    time window exceeds the duration of the data, it will be clipped.
    Different time windows (one per time point) can be provided by
    passing an ``array-like`` object (e.g., ``[0.1, 0.2, 0.3]``). If
    ``None`` (default), no averaging will take place.

    .. versionchanged:: 1.1
       Support for ``array-like`` input.
"""

docdict['average_plot_psd'] = """\
average : bool
    If False, the PSDs of all channels is displayed. No averaging
    is done and parameters area_mode and area_alpha are ignored. When
    False, it is possible to paint an area (hold left mouse button and
    drag) to plot a topomap.
"""

docdict['average_psd'] = """\
average : str | None
    How to average the segments. If ``mean`` (default), calculate the
    arithmetic mean. If ``median``, calculate the median, corrected for
    its bias relative to the mean. If ``None``, returns the unaggregated
    segments.
"""

docdict['average_tfr'] = """
average : bool, default True
    If ``False`` return an `EpochsTFR` containing separate TFRs for each
    epoch. If ``True`` return an `AverageTFR` containing the average of all
    TFRs across epochs.

    .. note::
        Using ``average=True`` is functionally equivalent to using
        ``average=False`` followed by ``EpochsTFR.average()``, but is
        more memory efficient.

    .. versionadded:: 0.13.0
"""

_axes_base = """\
{} : instance of Axes | {}None
    The axes to plot to. If ``None``, a new :class:`~matplotlib.figure.Figure`
    will be created{}. {}Default is ``None``.
"""
_axes_num = ('If :class:`~matplotlib.axes.Axes` are provided (either as a '
             'single instance or a :class:`list` of axes), the number of axes '
             'provided must {}.')
_axes_list = _axes_base.format(
    '{}', 'list of Axes | ', ' with the correct number of axes', _axes_num)
_ch_types_present = ('match the number of channel types present in the {}'
                     'object.')
docdict['ax_plot_psd'] = _axes_list.format('ax', _ch_types_present.format(''))
docdict['axes_cov_plot_topomap'] = _axes_list.format('axes', 'be length 1')
docdict['axes_evoked_plot_topomap'] = _axes_list.format(
    'axes',
    'match the number of ``times`` provided (unless ``times`` is ``None``)')
docdict['axes_plot_projs_topomap'] = _axes_list.format(
    'axes', 'match the number of projectors')
docdict['axes_plot_topomap'] = _axes_base.format('axes', '', '', '')
docdict['axes_spectrum_plot'] = _axes_list.format(
    'axes', _ch_types_present.format(':class:`~mne.time_frequency.Spectrum`'))
docdict['axes_spectrum_plot_topo'] = _axes_list.format(
    'axes',
    'be length 1 (for efficiency, subplots for each channel are simulated '
    'within a single :class:`~matplotlib.axes.Axes` object)')
docdict['axes_spectrum_plot_topomap'] = _axes_list.format(
    'axes', 'match the length of ``bands``')

docdict['axis_facecolor'] = """\
axis_facecolor : str | tuple
    A matplotlib-compatible color to use for the axis background.
    Defaults to black.
"""

docdict['azimuth'] = """
azimuth : float
    The azimuthal angle of the camera rendering the view in degrees.
"""

# %%
# B

docdict['bad_condition_maxwell_cond'] = """
bad_condition : str
    How to deal with ill-conditioned SSS matrices. Can be "error"
    (default), "warning", "info", or "ignore".
"""

docdict['bands_psd_topo'] = """
bands : None | dict | list of tuple
    The frequencies or frequency ranges to plot. If a :class:`dict`, keys will
    be used as subplot titles and values should be either a single frequency
    (e.g., ``{'presentation rate': 6.5}``) or a length-two sequence of lower
    and upper frequency band edges (e.g., ``{'theta': (4, 8)}``). If a single
    frequency is provided, the plot will show the frequency bin that is closest
    to the requested value. If ``None`` (the default), expands to::

        bands = {'Delta (0-4 Hz)': (0, 4), 'Theta (4-8 Hz)': (4, 8),
                 'Alpha (8-12 Hz)': (8, 12), 'Beta (12-30 Hz)': (12, 30),
                 'Gamma (30-45 Hz)': (30, 45)}

    .. note::
       For backwards compatibility, :class:`tuples<tuple>` of length 2 or 3 are
       also accepted, where the last element of the tuple is the subplot title
       and the other entries are frequency values (a single value or band
       edges). New code should use :class:`dict` or ``None``.

    .. versionchanged:: 1.2
       Allow passing a dict and discourage passing tuples.
"""

docdict['base_estimator'] = """
base_estimator : object
    The base estimator to iteratively fit on a subset of the dataset.
"""

_baseline_rescale_base = """
baseline : None | tuple of length 2
    The time interval to consider as "baseline" when applying baseline
    correction. If ``None``, do not apply baseline correction.
    If a tuple ``(a, b)``, the interval is between ``a`` and ``b``
    (in seconds), including the endpoints.
    If ``a`` is ``None``, the **beginning** of the data is used; and if ``b``
    is ``None``, it is set to the **end** of the interval.
    If ``(None, None)``, the entire time interval is used.

    .. note:: The baseline ``(a, b)`` includes both endpoints, i.e. all
                timepoints ``t`` such that ``a <= t <= b``.
"""

docdict['baseline_epochs'] = f"""{_baseline_rescale_base}
    Correction is applied **to each epoch and channel individually** in the
    following way:

    1. Calculate the mean signal of the baseline period.
    2. Subtract this mean from the **entire** epoch.

"""

docdict['baseline_evoked'] = f"""{_baseline_rescale_base}
    Correction is applied **to each channel individually** in the following
    way:

    1. Calculate the mean signal of the baseline period.
    2. Subtract this mean from the **entire** ``Evoked``.

"""

docdict['baseline_report'] = f"""{_baseline_rescale_base}
    Correction is applied in the following way **to each channel:**

    1. Calculate the mean signal of the baseline period.
    2. Subtract this mean from the **entire** time period.

    For `~mne.Epochs`, this algorithm is run **on each epoch individually.**
"""

docdict['baseline_rescale'] = _baseline_rescale_base

docdict['baseline_stc'] = f"""{_baseline_rescale_base}
    Correction is applied **to each source individually** in the following
    way:

    1. Calculate the mean signal of the baseline period.
    2. Subtract this mean from the **entire** source estimate data.

    .. note:: Baseline correction is appropriate when signal and noise are
              approximately additive, and the noise level can be estimated from
              the baseline interval. This can be the case for non-normalized
              source activities (e.g. signed and unsigned MNE), but it is not
              the case for normalized estimates (e.g. signal-to-noise ratios,
              dSPM, sLORETA).

"""

docdict['block'] = """\
block : bool
    Whether to halt program execution until the figure is closed.
    May not work on all systems / platforms. Defaults to ``False``.
"""

docdict['border_topomap'] = """
border : float | 'mean'
    Value to extrapolate to on the topomap borders. If ``'mean'`` (default),
    then each extrapolated point has the average value of its neighbours.

    .. versionadded:: 0.20
"""

docdict['brain_kwargs'] = """
brain_kwargs : dict | None
    Additional arguments to the :class:`mne.viz.Brain` constructor (e.g.,
    ``dict(silhouette=True)``).
"""

docdict['browser'] = """
fig : matplotlib.figure.Figure | mne_qt_browser.figure.MNEQtBrowser
    Browser instance.
"""

docdict['buffer_size_clust'] = """
buffer_size : int | None
    Block size to use when computing test statistics. This can significantly
    reduce memory usage when ``n_jobs > 1`` and memory sharing between
    processes is enabled (see :func:`mne.set_cache_dir`), because ``X`` will be
    shared between processes and each process only needs to allocate space for
    a small block of locations at a time.
"""

docdict['by_event_type'] = """
by_event_type : bool
    When ``False`` (the default) all epochs are processed together and a single
    :class:`~mne.Evoked` object is returned. When ``True``, epochs are first
    grouped by event type (as specified using the ``event_id`` parameter) and a
    list is returned containing a separate :class:`~mne.Evoked` object for each
    event type. The ``.comment`` attribute is set to the label of the event
    type.

    .. versionadded:: 0.24.0
"""

# %%
# C

docdict['calibration_maxwell_cal'] = """
calibration : str | None
    Path to the ``'.dat'`` file with fine calibration coefficients.
    File can have 1D or 3D gradiometer imbalance correction.
    This file is machine/site-specific.
"""

docdict['cbar_fmt_topomap'] = """\
cbar_fmt : str
    Formatting string for colorbar tick labels. See :ref:`formatspec` for
    details.
"""
docdict['cbar_fmt_topomap_psd'] = docdict['cbar_fmt_topomap'] + """\
    If ``'auto'``, is equivalent to '%0.3f' if ``dB=False`` and '%0.1f' if
    ``dB=True``. Defaults to ``'auto'``.
"""

docdict['center'] = """
center : float or None
    If not None, center of a divergent colormap, changes the meaning of
    fmin, fmax and fmid.
"""

docdict['ch_name_ecg'] = """
ch_name : None | str
    The name of the channel to use for ECG peak detection.
    If ``None`` (default), ECG channel is used if present. If ``None`` and
    **no** ECG channel is present, a synthetic ECG channel is created from
    the cross-channel average. This synthetic channel can only be created from
    MEG channels.
"""

docdict['ch_name_eog'] = """
ch_name : str | list of str | None
    The name of the channel(s) to use for EOG peak detection. If a string,
    can be an arbitrary channel. This doesn't have to be a channel of
    ``eog`` type; it could, for example, also be an ordinary EEG channel
    that was placed close to the eyes, like ``Fp1`` or ``Fp2``.

    Multiple channel names can be passed as a list of strings.

    If ``None`` (default), use the channel(s) in ``raw`` with type ``eog``.
"""

docdict['ch_names_annot'] = """
ch_names : list | None
    List of lists of channel names associated with the annotations.
    Empty entries are assumed to be associated with no specific channel,
    i.e., with all channels or with the time slice itself. None (default) is
    the same as passing all empty lists. For example, this creates three
    annotations, associating the first with the time interval itself, the
    second with two channels, and the third with a single channel::

        Annotations(onset=[0, 3, 10], duration=[1, 0.25, 0.5],
                    description=['Start', 'BAD_flux', 'BAD_noise'],
                    ch_names=[[], ['MEG0111', 'MEG2563'], ['MEG1443']])
"""

docdict['ch_type_set_eeg_reference'] = """
ch_type : list of str | str
    The name of the channel type to apply the reference to.
    Valid channel types are ``'auto'``, ``'eeg'``, ``'ecog'``, ``'seeg'``,
    ``'dbs'``. If ``'auto'``, the first channel type of eeg, ecog, seeg or dbs
    that is found (in that order) will be selected.

    .. versionadded:: 0.19
    .. versionchanged:: 1.2
       ``list-of-str`` is now supported with ``projection=True``.
"""

_ch_type_topomap_base = """\
ch_type : 'mag' | 'grad' | 'planar1' | 'planar2' | 'eeg' | None{}
    The channel type to plot. For ``'grad'``, the gradiometers are
    collected in pairs and the {} for each pair is plotted. If
    ``None`` {}. {}Defaults to ``None``.
"""
_ch_type_topomap = _ch_type_topomap_base.format(
    '{}', '{}',
    'the first available channel type from order shown above is used', '{}')
docdict['ch_type_topomap'] = _ch_type_topomap.format('', 'RMS', '')
docdict['ch_type_topomap_proj'] = _ch_type_topomap_base.format(
    ' | list',
    'RMS',
    'it will return all channel types present.',
    'If a list of ch_types is provided, it will return multiple figures. ')
docdict['ch_type_topomap_psd'] = _ch_type_topomap.format('', 'mean', '')

chwise = """
channel_wise : bool
    Whether to apply the function to each channel {}individually. If ``False``,
    the function will be applied to all {}channels at once. Default ``True``.
"""
docdict['channel_wise_applyfun'] = chwise.format('', '')
docdict['channel_wise_applyfun_epo'] = chwise.format(
    'in each epoch ', 'epochs and ')


docdict['check_disjoint_clust'] = """
check_disjoint : bool
    Whether to check if the connectivity matrix can be separated into disjoint
    sets before clustering. This may lead to faster clustering, especially if
    the second dimension of ``X`` (usually the "time" dimension) is large.
"""

docdict['chpi_amplitudes'] = """
chpi_amplitudes : dict
    The time-varying cHPI coil amplitudes, with entries
    "times", "proj", and "slopes".
"""

docdict['chpi_locs'] = """
chpi_locs : dict
    The time-varying cHPI coils locations, with entries
    "times", "rrs", "moments", and "gofs".
"""

docdict['clim'] = """
clim : str | dict
    Colorbar properties specification. If 'auto', set clim automatically
    based on data percentiles. If dict, should contain:

        ``kind`` : 'value' | 'percent'
            Flag to specify type of limits.
        ``lims`` : list | np.ndarray | tuple of float, 3 elements
            Lower, middle, and upper bounds for colormap.
        ``pos_lims`` : list | np.ndarray | tuple of float, 3 elements
            Lower, middle, and upper bound for colormap. Positive values
            will be mirrored directly across zero during colormap
            construction to obtain negative control points.

    .. note:: Only one of ``lims`` or ``pos_lims`` should be provided.
              Only sequential colormaps should be used with ``lims``, and
              only divergent colormaps should be used with ``pos_lims``.
"""

docdict['clim_onesided'] = """
clim : str | dict
    Colorbar properties specification. If 'auto', set clim automatically
    based on data percentiles. If dict, should contain:

        ``kind`` : 'value' | 'percent'
            Flag to specify type of limits.
        ``lims`` : list | np.ndarray | tuple of float, 3 elements
            Lower, middle, and upper bound for colormap.

    Unlike :meth:`stc.plot <mne.SourceEstimate.plot>`, it cannot use
    ``pos_lims``, as the surface plot must show the magnitude.
"""

docdict['cmap_topomap'] = """
cmap : matplotlib colormap | (colormap, bool) | 'interactive' | None
    Colormap to use. If :class:`tuple`, the first value indicates the colormap
    to use and the second value is a boolean defining interactivity. In
    interactive mode the colors are adjustable by clicking and dragging the
    colorbar with left and right mouse button. Left mouse button moves the
    scale up and down and right mouse button adjusts the range. Hitting
    space bar resets the range. Up and down arrows can be used to change
    the colormap. If ``None``, ``'Reds'`` is used for data that is either
    all-positive or all-negative, and ``'RdBu_r'`` is used otherwise.
    ``'interactive'`` is equivalent to ``(None, True)``. Defaults to ``None``.

    .. warning::  Interactive mode works smoothly only for a small amount
        of topomaps. Interactive mode is disabled by default for more than
        2 topomaps.
"""

docdict['cmap_topomap_simple'] = """
cmap : matplotlib colormap | None
    Colormap to use. If None, 'Reds' is used for all positive data,
    otherwise defaults to 'RdBu_r'.
"""

docdict['cnorm'] = """
cnorm : matplotlib.colors.Normalize | None
    How to normalize the colormap. If ``None``, standard linear normalization
    is performed. If not ``None``, ``vmin`` and ``vmax`` will be ignored.
    See :doc:`Matplotlib docs <matplotlib:tutorials/colors/colormapnorms>`
    for more details on colormap normalization, and
    :ref:`the ERDs example<cnorm-example>` for an example of its use.
"""

docdict['color_matplotlib'] = """
color : color
    A list of anything matplotlib accepts: string, RGB, hex, etc.
"""

docdict['color_plot_psd'] = """\
color : str | tuple
    A matplotlib-compatible color to use. Has no effect when
    spatial_colors=True.
"""

docdict['color_spectrum_plot_topo'] = """\
color : str | tuple
    A matplotlib-compatible color to use for the curves. Defaults to
    white.
"""

docdict['colorbar_topomap'] = """
colorbar : bool
    Plot a colorbar in the rightmost column of the figure.
"""

docdict['colormap'] = """
colormap : str | np.ndarray of float, shape(n_colors, 3 | 4)
    Name of colormap to use or a custom look up table. If array, must
    be (n x 3) or (n x 4) array for with RGB or RGBA values between
    0 and 255.
"""

docdict['combine'] = """
combine : None | str | callable
    How to combine information across channels. If a :class:`str`, must be
    one of 'mean', 'median', 'std' (standard deviation) or 'gfp' (global
    field power).
"""

docdict['compute_proj_ecg'] = """This function will:

#. Filter the ECG data channel.

#. Find ECG R wave peaks using :func:`mne.preprocessing.find_ecg_events`.

#. Filter the raw data.

#. Create `~mne.Epochs` around the R wave peaks, capturing the heartbeats.

#. Optionally average the `~mne.Epochs` to produce an `~mne.Evoked` if
   ``average=True`` was passed (default).

#. Calculate SSP projection vectors on that data to capture the artifacts."""

docdict['compute_proj_eog'] = """This function will:

#. Filter the EOG data channel.

#. Find the peaks of eyeblinks in the EOG data using
   :func:`mne.preprocessing.find_eog_events`.

#. Filter the raw data.

#. Create `~mne.Epochs` around the eyeblinks.

#. Optionally average the `~mne.Epochs` to produce an `~mne.Evoked` if
   ``average=True`` was passed (default).

#. Calculate SSP projection vectors on that data to capture the artifacts."""

docdict['compute_ssp'] = """This function aims to find those SSP vectors that
will project out the ``n`` most prominent signals from the data for each
specified sensor type. Consequently, if the provided input data contains high
levels of noise, the produced SSP vectors can then be used to eliminate that
noise from the data.
"""

docdict['contours_topomap'] = """
contours : int | array-like
    The number of contour lines to draw. If ``0``, no contours will be drawn.
    If a positive integer, that number of contour levels are chosen using the
    matplotlib tick locator (may sometimes be inaccurate, use array for
    accuracy). If array-like, the array values are used as the contour levels.
    The values should be in µV for EEG, fT for magnetometers and fT/m for
    gradiometers. If ``colorbar=True``, the colorbar will have ticks
    corresponding to the contour levels. Default is ``6``.
"""

docdict['coord_frame_maxwell'] = """
coord_frame : str
    The coordinate frame that the ``origin`` is specified in, either
    ``'meg'`` or ``'head'``. For empty-room recordings that do not have
    a head<->meg transform ``info['dev_head_t']``, the MEG coordinate
    frame should be used.
"""

docdict['copy_df'] = """
copy : bool
    If ``True``, data will be copied. Otherwise data may be modified in place.
    Defaults to ``True``.
"""

docdict['create_ecg_epochs'] = """This function will:

#. Filter the ECG data channel.

#. Find ECG R wave peaks using :func:`mne.preprocessing.find_ecg_events`.

#. Create `~mne.Epochs` around the R wave peaks, capturing the heartbeats.
"""

docdict['create_eog_epochs'] = """This function will:

#. Filter the EOG data channel.

#. Find the peaks of eyeblinks in the EOG data using
   :func:`mne.preprocessing.find_eog_events`.

#. Create `~mne.Epochs` around the eyeblinks.
"""

docdict['cross_talk_maxwell'] = """
cross_talk : str | None
    Path to the FIF file with cross-talk correction information.
"""

# %%
# D

_dB = """\
dB : bool
    Whether to plot on a decibel-like scale. If ``True``, plots
    10 × log₁₀(spectral power){}.{}
"""

docdict['dB_plot_psd'] = """\
dB : bool
    Plot Power Spectral Density (PSD), in units (amplitude**2/Hz (dB)) if
    ``dB=True``, and ``estimate='power'`` or ``estimate='auto'``. Plot PSD
    in units (amplitude**2/Hz) if ``dB=False`` and,
    ``estimate='power'``. Plot Amplitude Spectral Density (ASD), in units
    (amplitude/sqrt(Hz)), if ``dB=False`` and ``estimate='amplitude'`` or
    ``estimate='auto'``. Plot ASD, in units (amplitude/sqrt(Hz) (dB)), if
    ``dB=True`` and ``estimate='amplitude'``.
"""
docdict['dB_plot_topomap'] = _dB.format(
    ' following the application of ``agg_fun``',
    ' Ignored if ``normalize=True``.')
docdict['dB_spectrum_plot'] = _dB.format('', '')
docdict['dB_spectrum_plot_topo'] = _dB.format(
    '', ' Ignored if ``normalize=True``.')

docdict['daysback_anonymize_info'] = """
daysback : int | None
    Number of days to subtract from all dates.
    If ``None`` (default), the acquisition date, ``info['meas_date']``,
    will be set to ``January 1ˢᵗ, 2000``. This parameter is ignored if
    ``info['meas_date']`` is ``None`` (i.e., no acquisition date has been set).
"""

docdict['dbs'] = """
dbs : bool
    If True (default), show DBS (deep brain stimulation) electrodes.
"""
docdict['decim'] = """
decim : int
    Factor by which to subsample the data.

    .. warning:: Low-pass filtering is not performed, this simply selects
                 every Nth sample (where N is the value passed to
                 ``decim``), i.e., it compresses the signal (see Notes).
                 If the data are not properly filtered, aliasing artifacts
                 may occur.
"""

docdict['decim_notes'] = """
For historical reasons, ``decim`` / "decimation" refers to simply subselecting
samples from a given signal. This contrasts with the broader signal processing
literature, where decimation is defined as (quoting
:footcite:`OppenheimEtAl1999`, p. 172; which cites
:footcite:`CrochiereRabiner1983`):

    "... a general system for downsampling by a factor of M is the one shown
    in Figure 4.23. Such a system is called a decimator, and downsampling
    by lowpass filtering followed by compression [i.e, subselecting samples]
    has been termed decimation (Crochiere and Rabiner, 1983)."

Hence "decimation" in MNE is what is considered "compression" in the signal
processing community.

Decimation can be done multiple times. For example,
``inst.decimate(2).decimate(2)`` will be the same as
``inst.decimate(4)``.
"""

docdict['decim_tfr'] = """
decim : int | slice, default 1
    To reduce memory usage, decimation factor after time-frequency
    decomposition.

    - if `int`, returns ``tfr[..., ::decim]``.
    - if `slice`, returns ``tfr[..., decim]``.

    .. note::
        Decimation is done after convolutions and may create aliasing
        artifacts.
"""

docdict['depth'] = """
depth : None | float | dict
    How to weight (or normalize) the forward using a depth prior.
    If float (default 0.8), it acts as the depth weighting exponent (``exp``)
    to use None is equivalent to 0, meaning no depth weighting is performed.
    It can also be a :class:`dict` containing keyword arguments to pass to
    :func:`mne.forward.compute_depth_prior` (see docstring for details and
    defaults). This is effectively ignored when ``method='eLORETA'``.

    .. versionchanged:: 0.20
       Depth bias ignored for ``method='eLORETA'``.
"""

docdict['destination_maxwell_dest'] = """
destination : str | array-like, shape (3,) | None
    The destination location for the head. Can be ``None``, which
    will not change the head position, or a string path to a FIF file
    containing a MEG device<->head transformation, or a 3-element array
    giving the coordinates to translate to (with no rotations).
    For example, ``destination=(0, 0, 0.04)`` would translate the bases
    as ``--trans default`` would in MaxFilter™ (i.e., to the default
    head location).
"""

docdict['detrend_epochs'] = """
detrend : int | None
    If 0 or 1, the data channels (MEG and EEG) will be detrended when
    loaded. 0 is a constant (DC) detrend, 1 is a linear detrend. None
    is no detrending. Note that detrending is performed before baseline
    correction. If no DC offset is preferred (zeroth order detrending),
    either turn off baseline correction, as this may introduce a DC
    shift, or set baseline correction to use the entire time interval
    (will yield equivalent results but be slower).
"""

docdict['df_return'] = """
df : instance of pandas.DataFrame
    A dataframe suitable for usage with other statistical/plotting/analysis
    packages.
"""

docdict['dig_kinds'] = """
dig_kinds : list of str | str
    Kind of digitization points to use in the fitting. These can be any
    combination of ('cardinal', 'hpi', 'eeg', 'extra'). Can also
    be 'auto' (default), which will use only the 'extra' points if
    enough (more than 4) are available, and if not, uses 'extra' and
    'eeg' points.
"""

docdict['dipole'] = """
dipole : instance of Dipole | list of Dipole
    Dipole object containing position, orientation and amplitude of
    one or more dipoles. Multiple simultaneous dipoles may be defined by
    assigning them identical times. Alternatively, multiple simultaneous
    dipoles may also be specified as a list of Dipole objects.

    .. versionchanged:: 1.1
        Added support for a list of :class:`mne.Dipole` instances.
"""

docdict['distance'] = """
distance : float | None
    The distance from the camera rendering the view to the focalpoint
    in plot units (either m or mm).
"""

docdict['drop_log'] = """
drop_log : tuple | None
    Tuple of tuple of strings indicating which epochs have been marked to
    be ignored.
"""

docdict['dtype_applyfun'] = """
dtype : numpy.dtype
    Data type to use after applying the function. If None
    (default) the data type is not modified.
"""

# %%
# E

docdict['ecog'] = """
ecog : bool
    If True (default), show ECoG sensors.
"""

docdict['eeg'] = """
eeg : bool | str | list
    String options are:

    - "original" (default; equivalent to ``True``)
        Shows EEG sensors using their digitized locations (after
        transformation to the chosen ``coord_frame``)
    - "projected"
        The EEG locations projected onto the scalp, as is done in
        forward modeling

    Can also be a list of these options, or an empty list (``[]``,
    equivalent of ``False``).
"""

docdict['elevation'] = """
elevation : float
    The The zenith angle of the camera rendering the view in degrees.
"""

docdict['eltc_mode_notes'] = """
Valid values for ``mode`` are:

- ``'max'``
    Maximum value across vertices at each time point within each label.
- ``'mean'``
    Average across vertices at each time point within each label. Ignores
    orientation of sources for standard source estimates, which varies
    across the cortical surface, which can lead to cancellation.
    Vector source estimates are always in XYZ / RAS orientation, and are thus
    already geometrically aligned.
- ``'mean_flip'``
    Finds the dominant direction of source space normal vector orientations
    within each label, applies a sign-flip to time series at vertices whose
    orientation is more than 180° different from the dominant direction, and
    then averages across vertices at each time point within each label.
- ``'pca_flip'``
    Applies singular value decomposition to the time courses within each label,
    and uses the first right-singular vector as the representative label time
    course. This signal is scaled so that its power matches the average
    (per-vertex) power within the label, and sign-flipped by multiplying by
    ``np.sign(u @ flip)``, where ``u`` is the first left-singular vector and
    ``flip`` is the same sign-flip vector used when ``mode='mean_flip'``. This
    sign-flip ensures that extracting time courses from the same label in
    similar STCs does not result in 180° direction/phase changes.
- ``'auto'`` (default)
    Uses ``'mean_flip'`` when a standard source estimate is applied, and
    ``'mean'`` when a vector source estimate is supplied.

    .. versionadded:: 0.21
       Support for ``'auto'``, vector, and volume source estimates.

The only modes that work for vector and volume source estimates are ``'mean'``,
``'max'``, and ``'auto'``.
"""

docdict['emit_warning'] = """
emit_warning : bool
    Whether to emit warnings when cropping or omitting annotations.
"""

docdict['encoding_edf'] = """
encoding : str
    Encoding of annotations channel(s). Default is "utf8" (the only correct
    encoding according to the EDF+ standard).
"""

docdict['epochs_preload'] = """
    Load all epochs from disk when creating the object
    or wait before accessing each epoch (more memory
    efficient but can be slower).
"""

docdict['epochs_reject_tmin_tmax'] = """
reject_tmin, reject_tmax : float | None
    Start and end of the time window used to reject epochs based on
    peak-to-peak (PTP) amplitudes as specified via ``reject`` and ``flat``.
    The default ``None`` corresponds to the first and last time points of the
    epochs, respectively.

    .. note:: This parameter controls the time period used in conjunction with
              both, ``reject`` and ``flat``.
"""

docdict['epochs_tmin_tmax'] = """
tmin, tmax : float
    Start and end time of the epochs in seconds, relative to the time-locked
    event. The closest or matching samples corresponding to the start and end
    time are included. Defaults to ``-0.2`` and ``0.5``, respectively.
"""

docdict['estimate_plot_psd'] = """\
estimate : str, {'auto', 'power', 'amplitude'}
    Can be "power" for power spectral density (PSD), "amplitude" for
    amplitude spectrum density (ASD), or "auto" (default), which uses
    "power" when dB is True and "amplitude" otherwise.
"""

docdict['event_color'] = """
event_color : color object | dict | None
    Color(s) to use for :term:`events`. To show all :term:`events` in the same
    color, pass any matplotlib-compatible color. To color events differently,
    pass a `dict` that maps event names or integer event numbers to colors
    (must include entries for *all* events, or include a "fallback" entry with
    key ``-1``). If ``None``, colors are chosen from the current Matplotlib
    color cycle.
"""

docdict['event_id'] = """
event_id : int | list of int | dict | None
    The id of the :term:`events` to consider. If dict, the keys can later be
    used to access associated :term:`events`. Example:
    dict(auditory=1, visual=3). If int, a dict will be created with the id as
    string. If a list, all :term:`events` with the IDs specified in the list
    are used. If None, all :term:`events` will be used and a dict is created
    with string integer names corresponding to the event id integers."""

docdict['event_id_ecg'] = """
event_id : int
    The index to assign to found ECG events.
"""

docdict['event_repeated_epochs'] = """
event_repeated : str
    How to handle duplicates in ``events[:, 0]``. Can be ``'error'``
    (default), to raise an error, 'drop' to only retain the row occurring
    first in the :term:`events`, or ``'merge'`` to combine the coinciding
    events (=duplicates) into a new event (see Notes for details).

    .. versionadded:: 0.19
"""

docdict['events'] = """
events : array of int, shape (n_events, 3)
    The array of :term:`events`. The first column contains the event time in
    samples, with :term:`first_samp` included. The third column contains the
    event id."""

docdict['events_epochs'] = """
events : array of int, shape (n_events, 3)
    The array of :term:`events`. The first column contains the event time in
    samples, with :term:`first_samp` included. The third column contains the
    event id.
    If some events don't match the events of interest as specified by event_id,
    they will be marked as ``IGNORED`` in the drop log."""

docdict['evoked_by_event_type_returns'] = """
evoked : instance of Evoked | list of Evoked
    The averaged epochs.
    When ``by_event_type=True`` was specified, a list is returned containing a
    separate :class:`~mne.Evoked` object for each event type. The list has the
    same order as the event types as specified in the ``event_id``
    dictionary.
"""

docdict['exclude_clust'] = """
exclude : bool array or None
    Mask to apply to the data to exclude certain points from clustering
    (e.g., medial wall vertices). Should be the same shape as ``X``.
    If ``None``, no points are excluded.
"""

docdict['exclude_frontal'] = """
exclude_frontal : bool
    If True, exclude points that have both negative Z values
    (below the nasion) and positive Y values (in front of the LPA/RPA).
"""

_exclude_spectrum = """\
exclude : list of str | 'bads'
    Channel names to exclude{}. If ``'bads'``, channels
    in ``spectrum.info['bads']`` are excluded; pass an empty list to
    plot all channels (including "bad" channels, if any).
"""

docdict['exclude_spectrum_get_data'] = _exclude_spectrum.format('')
docdict['exclude_spectrum_plot'] = _exclude_spectrum.format(
    ' from being drawn')

docdict['export_edf_note'] = """
For EDF exports, only channels measured in Volts are allowed; in MNE-Python
this means channel types 'eeg', 'ecog', 'seeg', 'emg', 'eog', 'ecg', 'dbs',
'bio', and 'misc'. 'stim' channels are dropped. Although this function
supports storing channel types in the signal label (e.g. ``EEG Fz`` or
``MISC E``), other software may not support this (optional) feature of
the EDF standard.

If ``add_ch_type`` is True, then channel types are written based on what
they are currently set in MNE-Python. One should double check that all
their channels are set correctly. You can call
:attr:`raw.set_channel_types <mne.io.Raw.set_channel_types>` to set
channel types.

In addition, EDF does not support storing a montage. You will need
to store the montage separately and call :attr:`raw.set_montage()
<mne.io.Raw.set_montage>`.
"""

docdict['export_eeglab_note'] = """
For EEGLAB exports, channel locations are expanded to full EEGLAB format.
For more details see :func:`eeglabio.utils.cart_to_eeglab`.
"""

_export_fmt_params_base = """\
Format of the export. Defaults to ``'auto'``, which will infer the format
    from the filename extension. See supported formats above for more
    information."""

docdict['export_fmt_params_epochs'] = """
fmt : 'auto' | 'eeglab'
    {}
""".format(_export_fmt_params_base)

docdict['export_fmt_params_evoked'] = """
fmt : 'auto' | 'mff'
    {}
""".format(_export_fmt_params_base)

docdict['export_fmt_params_raw'] = """
fmt : 'auto' | 'brainvision' | 'edf' | 'eeglab'
    {}
""".format(_export_fmt_params_base)

docdict['export_fmt_support_epochs'] = """\
Supported formats:
    - EEGLAB (``.set``, uses :mod:`eeglabio`)
"""

docdict['export_fmt_support_evoked'] = """\
Supported formats:
    - MFF (``.mff``, uses :func:`mne.export.export_evokeds_mff`)
"""

docdict['export_fmt_support_raw'] = """\
Supported formats:
    - BrainVision (``.vhdr``, ``.vmrk``, ``.eeg``, uses `pybv <https://github.com/bids-standard/pybv>`_)
    - EEGLAB (``.set``, uses :mod:`eeglabio`)
    - EDF (``.edf``, uses `EDFlib-Python <https://gitlab.com/Teuniz/EDFlib-Python>`_)
"""  # noqa: E501

docdict['export_warning'] = """\
.. warning::
    Since we are exporting to external formats, there's no guarantee that all
    the info will be preserved in the external format. See Notes for details.
"""

_export_warning_note_base = """\
Export to external format may not preserve all the information from the
instance. To save in native MNE format (``.fif``) without information loss,
use :meth:`mne.{0}.save` instead.
Export does not apply projector(s). Unapplied projector(s) will be lost.
Consider applying projector(s) before exporting with
:meth:`mne.{0}.apply_proj`."""

docdict['export_warning_note_epochs'] = \
    _export_warning_note_base.format('Epochs')

docdict['export_warning_note_evoked'] = \
    _export_warning_note_base.format('Evoked')

docdict['export_warning_note_raw'] = \
    _export_warning_note_base.format('io.Raw')

docdict['ext_order_chpi'] = """
ext_order : int
    The external order for SSS-like interfence suppression.
    The SSS bases are used as projection vectors during fitting.

    .. versionchanged:: 0.20
        Added ``ext_order=1`` by default, which should improve
        detection of true HPI signals.
"""

docdict['ext_order_maxwell'] = """
ext_order : int
    Order of external component of spherical expansion.
"""

docdict['extended_proj_maxwell'] = """
extended_proj : list
    The empty-room projection vectors used to extend the external
    SSS basis (i.e., use eSSS).

    .. versionadded:: 0.21
"""

docdict['extrapolate_topomap'] = """
extrapolate : str
    Options:

    - ``'box'``
        Extrapolate to four points placed to form a square encompassing all
        data points, where each side of the square is three times the range
        of the data in the respective dimension.
    - ``'local'`` (default for MEG sensors)
        Extrapolate only to nearby points (approximately to points closer than
        median inter-electrode distance). This will also set the
        mask to be polygonal based on the convex hull of the sensors.
    - ``'head'`` (default for non-MEG sensors)
        Extrapolate out to the edges of the clipping circle. This will be on
        the head circle when the sensors are contained within the head circle,
        but it can extend beyond the head when sensors are plotted outside
        the head circle.

    .. versionchanged:: 0.21

       - The default was changed to ``'local'`` for MEG sensors.
       - ``'local'`` was changed to use a convex hull mask
       - ``'head'`` was changed to extrapolate out to the clipping circle.
"""

# %%
# F

docdict['f_power_clust'] = """
t_power : float
    Power to raise the statistical values (usually F-values) by before
    summing (sign will be retained). Note that ``t_power=0`` will give a
    count of locations in each cluster, ``t_power=1`` will weight each location
    by its statistical score.
"""

docdict['fiducials'] = """
fiducials : list | dict | str
    The fiducials given in the MRI (surface RAS) coordinate
    system. If a dictionary is provided, it must contain the **keys**
    ``'lpa'``, ``'rpa'``, and ``'nasion'``, with **values** being the
    respective coordinates in meters.
    If a list, it must be a list of ``DigPoint`` instances as returned by the
    :func:`mne.io.read_fiducials` function.
    If ``'estimated'``, the fiducials are derived from the ``fsaverage``
    template. If ``'auto'`` (default), tries to find the fiducials
    in a file with the canonical name
    (``{subjects_dir}/{subject}/bem/{subject}-fiducials.fif``)
    and if absent, falls back to ``'estimated'``.
"""

docdict['fig_facecolor'] = """\
fig_facecolor : str | tuple
    A matplotlib-compatible color to use for the figure background.
    Defaults to black.
"""

docdict['filter_length'] = """
filter_length : str | int
    Length of the FIR filter to use (if applicable):

    * **'auto' (default)**: The filter length is chosen based
      on the size of the transition regions (6.6 times the reciprocal
      of the shortest transition band for fir_window='hamming'
      and fir_design="firwin2", and half that for "firwin").
    * **str**: A human-readable time in
      units of "s" or "ms" (e.g., "10s" or "5500ms") will be
      converted to that number of samples if ``phase="zero"``, or
      the shortest power-of-two length at least that duration for
      ``phase="zero-double"``.
    * **int**: Specified length in samples. For fir_design="firwin",
      this should not be used.
"""

docdict['filter_length_ecg'] = """
filter_length : str | int | None
    Number of taps to use for filtering.
"""

docdict['filter_length_notch'] = """
filter_length : str | int
    Length of the FIR filter to use (if applicable):

    * **'auto' (default)**: The filter length is chosen based
      on the size of the transition regions (6.6 times the reciprocal
      of the shortest transition band for fir_window='hamming'
      and fir_design="firwin2", and half that for "firwin").
    * **str**: A human-readable time in
      units of "s" or "ms" (e.g., "10s" or "5500ms") will be
      converted to that number of samples if ``phase="zero"``, or
      the shortest power-of-two length at least that duration for
      ``phase="zero-double"``.
    * **int**: Specified length in samples. For fir_design="firwin",
      this should not be used.

    When ``method=='spectrum_fit'``, this sets the effective window duration
    over which fits are computed. See :func:`mne.filter.create_filter`
    for options. Longer window lengths will give more stable frequency
    estimates, but require (potentially much) more processing and are not able
    to adapt as well to non-stationarities.

    The default in 0.21 is None, but this will change to ``'10s'`` in 0.22.
"""

docdict['fir_design'] = """
fir_design : str
    Can be "firwin" (default) to use :func:`scipy.signal.firwin`,
    or "firwin2" to use :func:`scipy.signal.firwin2`. "firwin" uses
    a time-domain design technique that generally gives improved
    attenuation using fewer samples than "firwin2".

    .. versionadded:: 0.15
"""

docdict['fir_window'] = """
fir_window : str
    The window to use in FIR design, can be "hamming" (default),
    "hann" (default in 0.13), or "blackman".

    .. versionadded:: 0.15
"""

_flat_common = """\
    Reject epochs based on **minimum** peak-to-peak signal amplitude (PTP).
    Valid **keys** can be any channel type present in the object. The
    **values** are floats that set the minimum acceptable PTP. If the PTP
    is smaller than this threshold, the epoch will be dropped. If ``None``
    then no rejection is performed based on flatness of the signal."""

docdict['flat'] = f"""
flat : dict | None
{_flat_common}

    .. note:: To constrain the time period used for estimation of signal
              quality, pass the ``reject_tmin`` and ``reject_tmax`` parameters.
"""

docdict['flat_drop_bad'] = f"""
flat : dict | str | None
{_flat_common}
    If ``'existing'``, then the flat parameters set during epoch creation are
    used.
"""

_fmin_fmax = """\
fmin, fmax : float
    The lower- and upper-bound on frequencies of interest. Default is {}"""

docdict['fmin_fmax_psd'] = _fmin_fmax.format(
    '``fmin=0, fmax=np.inf`` (spans all frequencies present in the data).')

docdict['fmin_fmax_psd_topo'] = _fmin_fmax.format('``fmin=0, fmax=100``.')

docdict['fmin_fmid_fmax'] = """
fmin : float
    Minimum value in colormap (uses real fmin if None).
fmid : float
    Intermediate value in colormap (fmid between fmin and
    fmax if None).
fmax : float
    Maximum value in colormap (uses real max if None).
"""

docdict['fname_epochs'] = """
fname : path-like | file-like
    The epochs to load. If a filename, should end with ``-epo.fif`` or
    ``-epo.fif.gz``. If a file-like object, preloading must be used.
"""

docdict['fname_export_params'] = """
fname : str
    Name of the output file.
"""

docdict['fnirs'] = """
fnirs : str | list | bool | None
    Can be "channels", "pairs", "detectors", and/or "sources" to show the
    fNIRS channel locations, optode locations, or line between
    source-detector pairs, or a combination like ``('pairs', 'channels')``.
    True translates to ``('pairs',)``.
"""

docdict['focalpoint'] = """
focalpoint : tuple, shape (3,) | None
    The focal point of the camera rendering the view: (x, y, z) in
    plot units (either m or mm).
"""

docdict['forward_set_eeg_reference'] = """
forward : instance of Forward | None
    Forward solution to use. Only used with ``ref_channels='REST'``.

    .. versionadded:: 0.21
"""

docdict['freqs_tfr'] = """
freqs : array of float, shape (n_freqs,)
    The frequencies of interest in Hz.
"""

docdict['fullscreen'] = """
fullscreen : bool
    Whether to start in fullscreen (``True``) or windowed mode
    (``False``).
"""

applyfun_fun_base = """
fun : callable
    A function to be applied to the channels. The first argument of
    fun has to be a timeseries (:class:`numpy.ndarray`). The function must
    operate on an array of shape ``(n_times,)`` {}.
    The function must return an :class:`~numpy.ndarray` shaped like its input.
"""
docdict['fun_applyfun'] = applyfun_fun_base .format(
    ' if ``channel_wise=True`` and ``(len(picks), n_times)`` otherwise')
docdict['fun_applyfun_evoked'] = applyfun_fun_base .format(
    ' because it will apply channel-wise')

docdict['fwd'] = """
fwd : instance of Forward
    The forward solution. If present, the orientations of the dipoles
    present in the forward solution are displayed.
"""

docdict['fwhm_morlet_notes'] = r"""
In wavelet analysis, the oscillation that is defined by ``n_cycles`` is tapered
by a Gaussian taper, i.e., the edges of the wavelet are dampened. This means
that reporting the number of cycles is not necessarily helpful for
understanding the amount of temporal smoothing that has been applied (see
:footcite:`Cohen2019`). Instead, the full width at half-maximum (FWHM) of the
wavelet can be reported.

The FWHM of the wavelet at a specific frequency is defined as:
:math:`\mathrm{FWHM} = \frac{\mathtt{n\_cycles} \times \sqrt{2 \ln{2}}}{\pi \times \mathtt{freq}}`
(cf. eq. 4 in :footcite:`Cohen2019`).
"""  # noqa E501

# %%
# G

docdict['get_peak_parameters'] = """
tmin : float | None
    The minimum point in time to be considered for peak getting.
tmax : float | None
    The maximum point in time to be considered for peak getting.
mode : {'pos', 'neg', 'abs'}
    How to deal with the sign of the data. If 'pos' only positive
    values will be considered. If 'neg' only negative values will
    be considered. If 'abs' absolute values will be considered.
    Defaults to 'abs'.
vert_as_index : bool
    Whether to return the vertex index (True) instead of of its ID
    (False, default).
time_as_index : bool
    Whether to return the time index (True) instead of the latency
    (False, default).
"""

_getitem_base = """\
data : ndarray
    The selected spectral data. Shape will be
    ``({}n_channels, n_freqs)`` for normal power spectra,
    ``({}n_channels, n_freqs, n_segments)`` for unaggregated
    Welch estimates, or ``({}n_channels, n_tapers, n_freqs)``
    for unaggregated multitaper estimates.
"""
_fill_epochs = ['n_epochs, '] * 3
docdict['getitem_epochspectrum_return'] = _getitem_base.format(*_fill_epochs)
docdict['getitem_spectrum_return'] = _getitem_base.format('', '', '')

docdict['group_by_browse'] = """
group_by : str
    How to group channels. ``'type'`` groups by channel type,
    ``'original'`` plots in the order of ch_names, ``'selection'`` uses
    Elekta's channel groupings (only works for Neuromag data),
    ``'position'`` groups the channels by the positions of the sensors.
    ``'selection'`` and ``'position'`` modes allow custom selections by
    using a lasso selector on the topomap. In butterfly mode, ``'type'``
    and ``'original'`` group the channels by type, whereas ``'selection'``
    and ``'position'`` use regional grouping. ``'type'`` and ``'original'``
    modes are ignored when ``order`` is not ``None``. Defaults to ``'type'``.
"""

# %%
# H

docdict['h_freq'] = """
h_freq : float | None
    For FIR filters, the upper pass-band edge; for IIR filters, the upper
    cutoff frequency. If None the data are only high-passed.
"""

docdict['h_trans_bandwidth'] = """
h_trans_bandwidth : float | str
    Width of the transition band at the high cut-off frequency in Hz
    (low pass or cutoff 2 in bandpass). Can be "auto"
    (default in 0.14) to use a multiple of ``h_freq``::

        min(max(h_freq * 0.25, 2.), info['sfreq'] / 2. - h_freq)

    Only used for ``method='fir'``.
"""

docdict['head_pos'] = """
head_pos : None | str | dict | tuple | array
    Name of the position estimates file. Should be in the format of
    the files produced by MaxFilter. If dict, keys should
    be the time points and entries should be 4x4 ``dev_head_t``
    matrices. If None, the original head position (from
    ``info['dev_head_t']``) will be used. If tuple, should have the
    same format as data returned by ``head_pos_to_trans_rot_t``.
    If array, should be of the form returned by
    :func:`mne.chpi.read_head_pos`.
"""

docdict['head_pos_maxwell'] = """
head_pos : array | None
    If array, movement compensation will be performed.
    The array should be of shape (N, 10), holding the position
    parameters as returned by e.g. ``read_head_pos``.
"""

docdict['head_source'] = """
head_source : str | list of str
    Head source(s) to use. See the ``source`` option of
    :func:`mne.get_head_surf` for more information.
"""

docdict['hitachi_fname'] = """
fname : list | str
    Path(s) to the Hitachi CSV file(s). This should only be a list for
    multiple probes that were acquired simultaneously.

    .. versionchanged:: 1.2
        Added support for list-of-str.
"""

docdict['hitachi_notes'] = """
Hitachi does not encode their channel positions, so you will need to
create a suitable mapping using :func:`mne.channels.make_standard_montage`
or :func:`mne.channels.make_dig_montage` like (for a 3x5/ETG-7000 example):

>>> mon = mne.channels.make_standard_montage('standard_1020')
>>> need = 'S1 D1 S2 D2 S3 D3 S4 D4 S5 D5 S6 D6 S7 D7 S8'.split()
>>> have = 'F3 FC3 C3 CP3 P3 F5 FC5 C5 CP5 P5 F7 FT7 T7 TP7 P7'.split()
>>> mon.rename_channels(dict(zip(have, need)))
>>> raw.set_montage(mon)  # doctest: +SKIP

The 3x3 (ETG-100) is laid out as two separate layouts::

    S1--D1--S2    S6--D6--S7
    |   |   |     |   |   |
    D2--S3--D3    D7--S8--D8
    |   |   |     |   |   |
    S4--D4--S5    S9--D9--S10

The 3x5 (ETG-7000) is laid out as::

    S1--D1--S2--D2--S3
    |   |   |   |   |
    D3--S4--D4--S5--D5
    |   |   |   |   |
    S6--D6--S7--D7--S8

The 4x4 (ETG-7000) is laid out as::

    S1--D1--S2--D2
    |   |   |   |
    D3--S3--D4--S4
    |   |   |   |
    S5--D5--S6--D6
    |   |   |   |
    D7--S7--D8--S8

The 3x11 (ETG-4000) is laid out as::

    S1--D1--S2--D2--S3--D3--S4--D4--S5--D5--S6
    |   |   |   |   |   |   |   |   |   |   |
    D6--S7--D7--S8--D8--S9--D9--S10-D10-S11-D11
    |   |   |   |   |   |   |   |   |   |   |
    S12-D12-S13-D13-S14-D14-S16-D16-S17-D17-S18

For each layout, the channels come from the (left-to-right) neighboring
source-detector pairs in the first row, then between the first and second row,
then the second row, etc.

.. versionadded:: 0.24
"""

# %%
# I

docdict['idx_pctf'] = """
idx : list of int | list of Label
    Source for indices for which to compute PSFs or CTFs. If mode is None,
    PSFs/CTFs will be returned for all indices. If mode is not None, the
    corresponding summary measure will be computed across all PSFs/CTFs
    available from idx.
    Can be:

    * list of integers : Compute PSFs/CTFs for all indices to source space
      vertices specified in idx.
    * list of Label : Compute PSFs/CTFs for source space vertices in
      specified labels.
"""

docdict['ignore_ref_maxwell'] = """
ignore_ref : bool
    If True, do not include reference channels in compensation. This
    option should be True for KIT files, since Maxwell filtering
    with reference channels is not currently supported.
"""

docdict['iir_params'] = """
iir_params : dict | None
    Dictionary of parameters to use for IIR filtering.
    If iir_params is None and method="iir", 4th order Butterworth will be used.
    For more information, see :func:`mne.filter.construct_iir_filter`.
"""

docdict['image_format_report'] = """
image_format : 'png' | 'svg' | 'gif' | None
    The image format to be used for the report, can be ``'png'``,
    ``'svg'``, or ``'gif'``.
    None (default) will use the default specified during `~mne.Report`
    instantiation.
"""

docdict['image_interp_topomap'] = """
image_interp : str
    The image interpolation to be used. Options are ``'cubic'`` (default)
    to use :class:`scipy.interpolate.CloughTocher2DInterpolator`,
    ``'nearest'`` to use :class:`scipy.spatial.Voronoi` or
    ``'linear'`` to use :class:`scipy.interpolate.LinearNDInterpolator`.
"""

docdict['include_tmax'] = """
include_tmax : bool
    If True (default), include tmax. If False, exclude tmax (similar to how
    Python indexing typically works).

    .. versionadded:: 0.19
"""

_index_df_base = """
index : {} | None
    Kind of index to use for the DataFrame. If ``None``, a sequential
    integer index (:class:`pandas.RangeIndex`) will be used. If ``'time'``, a
    :class:`pandas.Float64Index`, :class:`pandas.Int64Index`, {}or
    :class:`pandas.TimedeltaIndex` will be used
    (depending on the value of ``time_format``). {}
"""

datetime = ':class:`pandas.DatetimeIndex`, '
multiindex = ('If a list of two or more string values, a '
              ':class:`pandas.MultiIndex` will be created. ')
raw = ("'time'", datetime, '')
epo = ('str | list of str', '', multiindex)
evk = ("'time'", '', '')

docdict['index_df_epo'] = _index_df_base.format(*epo)
docdict['index_df_evk'] = _index_df_base.format(*evk)
docdict['index_df_raw'] = _index_df_base.format(*raw)

_info_base = ('The :class:`mne.Info` object with information about the '
              'sensors and methods of measurement.')

docdict['info'] = f"""
info : mne.Info | None
    {_info_base}
"""

docdict['info_not_none'] = f"""
info : mne.Info
    {_info_base}
"""

docdict['info_str'] = f"""
info : mne.Info | path-like
    {_info_base} If ``path-like``, it should be a :class:`str` or
    :class:`pathlib.Path` to a file with measurement information
    (e.g. :class:`mne.io.Raw`).
"""

docdict['int_order_maxwell'] = """
int_order : int
    Order of internal component of spherical expansion.
"""

docdict['interaction_scene'] = """
interaction : 'trackball' | 'terrain'
    How interactions with the scene via an input device (e.g., mouse or
    trackpad) modify the camera position. If ``'terrain'``, one axis is
    fixed, enabling "turntable-style" rotations. If ``'trackball'``,
    movement along all axes is possible, which provides more freedom of
    movement, but you may incidentally perform unintentional rotations along
    some axes.
"""

docdict['interaction_scene_none'] = """
interaction : 'trackball' | 'terrain' | None
    How interactions with the scene via an input device (e.g., mouse or
    trackpad) modify the camera position. If ``'terrain'``, one axis is
    fixed, enabling "turntable-style" rotations. If ``'trackball'``,
    movement along all axes is possible, which provides more freedom of
    movement, but you may incidentally perform unintentional rotations along
    some axes.
    If ``None``, the setting stored in the MNE-Python configuration file is
    used.
"""

docdict['interp'] = """
interp : str
    Either 'hann', 'cos2' (default), 'linear', or 'zero', the type of
    forward-solution interpolation to use between forward solutions
    at different head positions.
"""

docdict['interpolation_brain_time'] = """
interpolation : str | None
    Interpolation method (:class:`scipy.interpolate.interp1d` parameter).
    Must be one of 'linear', 'nearest', 'zero', 'slinear', 'quadratic',
    or 'cubic'.
"""

docdict['inversion_bf'] = """
inversion : 'single' | 'matrix'
    This determines how the beamformer deals with source spaces in "free"
    orientation. Such source spaces define three orthogonal dipoles at each
    source point. When ``inversion='single'``, each dipole is considered
    as an individual source and the corresponding spatial filter is
    computed for each dipole separately. When ``inversion='matrix'``, all
    three dipoles at a source vertex are considered as a group and the
    spatial filters are computed jointly using a matrix inversion. While
    ``inversion='single'`` is more stable, ``inversion='matrix'`` is more
    precise. See section 5 of :footcite:`vanVlietEtAl2018`.
    Defaults to ``'matrix'``.
"""

# %%
# J

docdict['joint_set_eeg_reference'] = """
joint : bool
    How to handle list-of-str ``ch_type``. If False (default), one projector
    is created per channel type. If True, one projector is created across
    all channel types. This is only used when ``projection=True``.

    .. versionadded:: 1.2
"""

# %%
# K

docdict['keep_his_anonymize_info'] = """
keep_his : bool
    If ``True``, ``his_id`` of ``subject_info`` will **not** be overwritten.
    Defaults to ``False``.

    .. warning:: This could mean that ``info`` is not fully
                 anonymized. Use with caution.
"""

docdict['kwargs_fun'] = """
**kwargs : dict
    Additional keyword arguments to pass to ``fun``.
"""

# %%
# L

docdict['l_freq'] = """
l_freq : float | None
    For FIR filters, the lower pass-band edge; for IIR filters, the lower
    cutoff frequency. If None the data are only low-passed.
"""

docdict['l_freq_ecg_filter'] = """
l_freq : float
    Low pass frequency to apply to the ECG channel while finding events.
h_freq : float
    High pass frequency to apply to the ECG channel while finding events.
"""

docdict['l_trans_bandwidth'] = """
l_trans_bandwidth : float | str
    Width of the transition band at the low cut-off frequency in Hz
    (high pass or cutoff 1 in bandpass). Can be "auto"
    (default) to use a multiple of ``l_freq``::

        min(max(l_freq * 0.25, 2), l_freq)

    Only used for ``method='fir'``.
"""

docdict['label_tc_el_returns'] = """
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'] = """
labels : Label | BiHemiLabel | list | tuple | str
    If using a surface or mixed source space, this should be the
    :class:`~mne.Label`'s for which to extract the time course.
    If working with whole-brain volume source estimates, this must be one of:

    - a string path to a FreeSurfer atlas for the subject (e.g., their
      'aparc.a2009s+aseg.mgz') to extract time courses for all volumes in the
      atlas
    - a two-element list or tuple, the first element being a path to an atlas,
      and the second being a list or dict of ``volume_labels`` to extract
      (see :func:`mne.setup_volume_source_space` for details).

    .. versionchanged:: 0.21.0
       Support for volume source estimates.
"""

docdict['layout_spectrum_plot_topo'] = """\
layout : instance of Layout | None
    Layout instance specifying sensor positions (does not need to be
    specified for Neuromag data). If ``None`` (default), the layout is
    inferred from the data.
"""

docdict['line_alpha_plot_psd'] = """\
line_alpha : float | None
    Alpha for the PSD line. Can be None (default) to use 1.0 when
    ``average=True`` and 0.1 when ``average=False``.
"""

_long_format_df_base = """
long_format : bool
    If True, the DataFrame is returned in long format where each row is one
    observation of the signal at a unique combination of {}.
    {}Defaults to ``False``.
"""

ch_type = ('For convenience, a ``ch_type`` column is added to facilitate '
           'subsetting the resulting DataFrame. ')
raw = ('time point and channel', ch_type)
epo = ('time point, channel, epoch number, and condition', ch_type)
stc = ('time point and vertex', '')
spe = ('frequency and channel', ch_type)

docdict['long_format_df_epo'] = _long_format_df_base.format(*epo)
docdict['long_format_df_raw'] = _long_format_df_base.format(*raw)
docdict['long_format_df_spe'] = _long_format_df_base.format(*spe)
docdict['long_format_df_stc'] = _long_format_df_base.format(*stc)

docdict['loose'] = """
loose : float | 'auto' | dict
    Value that weights the source variances of the dipole components
    that are parallel (tangential) to the cortical surface. Can be:

    - float between 0 and 1 (inclusive)
        If 0, then the solution is computed with fixed orientation.
        If 1, it corresponds to free orientations.
    - ``'auto'`` (default)
        Uses 0.2 for surface source spaces (unless ``fixed`` is True) and
        1.0 for other source spaces (volume or mixed).
    - dict
        Mapping from the key for a given source space type (surface, volume,
        discrete) to the loose value. Useful mostly for mixed source spaces.
"""

# %%
# M

docdict['mag_scale_maxwell'] = """
mag_scale : float | str
    The magenetometer scale-factor used to bring the magnetometers
    to approximately the same order of magnitude as the gradiometers
    (default 100.), as they have different units (T vs T/m).
    Can be ``'auto'`` to use the reciprocal of the physical distance
    between the gradiometer pickup loops (e.g., 0.0168 m yields
    59.5 for VectorView).
"""

docdict['mapping_rename_channels_duplicates'] = """
mapping : dict | callable
    A dictionary mapping the old channel to a new channel name
    e.g. {'EEG061' : 'EEG161'}. Can also be a callable function
    that takes and returns a string.

    .. versionchanged:: 0.10.0
       Support for a callable function.
allow_duplicates : bool
    If True (default False), allow duplicates, which will automatically
    be renamed with ``-N`` at the end.

    .. versionadded:: 0.22.0
"""

_mask_base = """
mask : ndarray of bool, shape {shape} | None
    Array indicating channel{shape_appendix} to highlight with a distinct
    plotting style{example}. Array elements set to ``True`` will be plotted
    with the parameters given in ``mask_params``. Defaults to ``None``,
    equivalent to an array of all ``False`` elements.
"""

docdict['mask_evoked_topomap'] = _mask_base.format(
    shape='(n_channels, n_times)', shape_appendix='-time combinations',
    example=' (useful for, e.g. marking which channels at which times a '
            'statistical test of the data reaches significance)')

docdict['mask_params_topomap'] = """
mask_params : dict | None
    Additional plotting parameters for plotting significant sensors.
    Default (None) equals::

        dict(marker='o', markerfacecolor='w', markeredgecolor='k',
                linewidth=0, markersize=4)
"""

docdict['mask_patterns_topomap'] = _mask_base.format(
    shape='(n_channels, n_patterns)', shape_appendix='-pattern combinations',
    example='')

docdict['mask_topomap'] = _mask_base.format(
    shape='(n_channels,)', shape_appendix='(s)', example='')

docdict['match_alias'] = """
match_alias : bool | dict
    Whether to use a lookup table to match unrecognized channel location names
    to their known aliases. If True, uses the mapping in
    ``mne.io.constants.CHANNEL_LOC_ALIASES``. If a :class:`dict` is passed, it
    will be used instead, and should map from non-standard channel names to
    names in the specified ``montage``. Default is ``False``.

    .. versionadded:: 0.23
"""

docdict['match_case'] = """
match_case : bool
    If True (default), channel name matching will be case sensitive.

    .. versionadded:: 0.20
"""

docdict['max_iter_multitaper'] = """
max_iter : int
    Maximum number of iterations to reach convergence when combining the
    tapered spectra with adaptive weights (see argument ``adaptive``). This
    argument has not effect if ``adaptive`` is set to ``False``."""

docdict['max_step_clust'] = """
max_step : int
    Maximum distance between samples along the second axis of ``X`` to be
    considered adjacent (typically the second axis is the "time" dimension).
    Only used when ``adjacency`` has shape (n_vertices, n_vertices), that is,
    when adjacency is only specified for sensors (e.g., via
    :func:`mne.channels.find_ch_adjacency`), and not via sensors **and**
    further dimensions such as time points (e.g., via an additional call of
    :func:`mne.stats.combine_adjacency`).
"""

docdict['measure'] = """
measure : 'zscore' | 'correlation'
    Which method to use for finding outliers among the components:

    - ``'zscore'`` (default) is the iterative z-scoring method. This method
      computes the z-score of the component's scores and masks the components
      with a z-score above threshold. This process is repeated until no
      supra-threshold component remains.
    - ``'correlation'`` is an absolute raw correlation threshold ranging from 0
      to 1.

    .. versionadded:: 0.21"""

docdict['meg'] = """
meg : str | list | bool | None
    Can be "helmet", "sensors" or "ref" to show the MEG helmet, sensors or
    reference sensors respectively, or a combination like
    ``('helmet', 'sensors')`` (same as None, default). True translates to
    ``('helmet', 'sensors', 'ref')``.
"""

docdict['metadata_epochs'] = """
metadata : instance of pandas.DataFrame | None
    A :class:`pandas.DataFrame` specifying metadata about each epoch.
    If given, ``len(metadata)`` must equal ``len(events)``. The DataFrame
    may only contain values of type (str | int | float | bool).
    If metadata is given, then pandas-style queries may be used to select
    subsets of data, see :meth:`mne.Epochs.__getitem__`.
    When a subset of the epochs is created in this (or any other
    supported) manner, the metadata object is subsetted accordingly, and
    the row indices will be modified to match ``epochs.selection``.

    .. versionadded:: 0.16
"""

docdict['method_fir'] = """
method : str
    'fir' will use overlap-add FIR filtering, 'iir' will use IIR
    forward-backward filtering (via filtfilt).
"""

docdict['method_kw_psd'] = """\
**method_kw
    Additional keyword arguments passed to the spectral estimation
    function (e.g., ``n_fft, n_overlap, n_per_seg, average, window``
    for Welch method, or
    ``bandwidth, adaptive, low_bias, normalization`` for multitaper
    method). See :func:`~mne.time_frequency.psd_array_welch` and
    :func:`~mne.time_frequency.psd_array_multitaper` for details.
"""

_method_psd = r"""
method : ``'welch'`` | ``'multitaper'``{}
    Spectral estimation method. ``'welch'`` uses Welch's
    method\ :footcite:p:`Welch1967`, ``'multitaper'`` uses DPSS
    tapers\ :footcite:p:`Slepian1978`.{}
"""
docdict['method_plot_psd_auto'] = _method_psd.format(
    " | ``'auto'``",
    (" ``'auto'`` (default) uses Welch's method for continuous data and "
     "multitaper for :class:`~mne.Epochs` or :class:`~mne.Evoked` data.")
)
docdict['method_psd'] = _method_psd.format('', '')
docdict['method_psd_auto'] = _method_psd.format(" | ``'auto'``", '')

docdict['mode_eltc'] = """
mode : str
    Extraction mode, see Notes.
"""

docdict['mode_pctf'] = """
mode : None | 'mean' | 'max' | 'svd'
    Compute summary of PSFs/CTFs across all indices specified in 'idx'.
    Can be:

    * None : Output individual PSFs/CTFs for each specific vertex
      (Default).
    * 'mean' : Mean of PSFs/CTFs across vertices.
    * 'max' : PSFs/CTFs with maximum norm across vertices. Returns the
      n_comp largest PSFs/CTFs.
    * 'svd' : SVD components across PSFs/CTFs across vertices. Returns the
      n_comp first SVD components.
"""

docdict['montage'] = """
montage : None | str | DigMontage
    A montage containing channel positions. If a string or
    :class:`~mne.channels.DigMontage` is
    specified, the existing channel information will be updated with the
    channel positions from the montage. Valid strings are the names of the
    built-in montages that ship with MNE-Python; you can list those via
    :func:`mne.channels.get_builtin_montages`.
    If ``None`` (default), the channel positions will be removed from the
    :class:`~mne.Info`.
"""

docdict['montage_types'] = """EEG/sEEG/ECoG/DBS/fNIRS"""

docdict['montage_units'] = """
montage_units : str
    Units that channel positions are represented in. Defaults to "mm"
    (millimeters), but can be any prefix + "m" combination (including just
    "m" for meters).

    .. versionadded:: 1.3
"""

docdict['morlet_notes'] = """
The Morlet wavelets follow the formulation in
:footcite:`Tallon-BaudryEtAl1997`.
"""

docdict['moving'] = """
moving : instance of SpatialImage
    The image to morph ("from" volume).
"""

docdict['mri_resolution_eltc'] = """
mri_resolution : bool
    If True (default), the volume source space will be upsampled to the
    original MRI resolution via trilinear interpolation before the atlas values
    are extracted. This ensnures that each atlas label will contain source
    activations. When False, only the original source space points are used,
    and some atlas labels thus may not contain any source space vertices.

    .. versionadded:: 0.21.0
"""

# %%
# N

docdict['n_comp_pctf_n'] = """
n_comp : int
    Number of PSF/CTF components to return for mode='max' or mode='svd'.
    Default n_comp=1.
"""

docdict['n_cycles_tfr'] = """
n_cycles : int | array of int, shape (n_freqs,)
    Number of cycles in the wavelet, either a fixed number or one per
    frequency. The number of cycles ``n_cycles`` and the frequencies of
    interest ``freqs`` define the temporal window length. See notes for
    additional information about the relationship between those arguments
    and about time and frequency smoothing.
"""

docdict['n_jobs'] = """\
n_jobs : int | None
    The number of jobs to run in parallel. If ``-1``, it is set
    to the number of CPU cores. Requires the :mod:`joblib` package.
    ``None`` (default) is a marker for 'unset' that will be interpreted
    as ``n_jobs=1`` (sequential execution) unless the call is performed under
    a :func:`joblib:joblib.parallel_backend` context manager that sets another
    value for ``n_jobs``.
"""

docdict['n_jobs_cuda'] = """
n_jobs : int | str
    Number of jobs to run in parallel. Can be 'cuda' if ``cupy``
    is installed properly.
"""

docdict['n_jobs_fir'] = """
n_jobs : int | str
    Number of jobs to run in parallel. Can be 'cuda' if ``cupy``
    is installed properly and method='fir'.
"""

docdict['n_pca_components_apply'] = """
n_pca_components : int | float | None
    The number of PCA components to be kept, either absolute (int)
    or fraction of the explained variance (float). If None (default),
    the ``ica.n_pca_components`` from initialization will be used in 0.22;
    in 0.23 all components will be used.
"""

docdict['n_permutations_clust_all'] = """
n_permutations : int | 'all'
    The number of permutations to compute. Can be 'all' to perform
    an exact test.
"""

docdict['n_permutations_clust_int'] = """
n_permutations : int
    The number of permutations to compute.
"""

docdict['names_topomap'] = """\
names : None | list
    Labels for the sensors. If a :class:`list`, labels should correspond
    to the order of channels in ``data``. If ``None`` (default), no channel
    names are plotted.
"""

docdict['nirx_notes'] = """
This function has only been tested with NIRScout and NIRSport devices,
and with the NIRStar software version 15 and above and Aurora software
2021 and above.

The NIRSport device can detect if the amplifier is saturated.
Starting from NIRStar 14.2, those saturated values are replaced by NaNs
in the standard .wlX files.
The raw unmodified measured values are stored in another file
called .nosatflags_wlX. As NaN values can cause unexpected behaviour with
mathematical functions the default behaviour is to return the
saturated data.
"""

docdict['niter'] = """
niter : dict | tuple | None
    For each phase of the volume registration, ``niter`` is the number of
    iterations per successive stage of optimization. If a tuple is
    provided, it will be used for all steps (except center of mass, which does
    not iterate). It should have length 3 to
    correspond to ``sigmas=[3.0, 1.0, 0.0]`` and ``factors=[4, 2, 1]`` in
    the pipeline (see :func:`dipy.align.affine_registration
    <dipy.align._public.affine_registration>` for details).
    If a dictionary is provided, number of iterations can be set for each
    step as a key. Steps not in the dictionary will use the default value.
    The default (None) is equivalent to:

        niter=dict(translation=(100, 100, 10),
                   rigid=(100, 100, 10),
                   affine=(100, 100, 10),
                   sdr=(5, 5, 3))
"""

docdict['norm_pctf'] = """
norm : None | 'max' | 'norm'
    Whether and how to normalise the PSFs and CTFs. This will be applied
    before computing summaries as specified in 'mode'.
    Can be:

    * None : Use un-normalized PSFs/CTFs (Default).
    * 'max' : Normalize to maximum absolute value across all PSFs/CTFs.
    * 'norm' : Normalize to maximum norm across all PSFs/CTFs.
"""

docdict['normalization'] = """normalization : 'full' | 'length'
    Normalization strategy. If "full", the PSD will be normalized by the
    sampling rate as well as the length of the signal (as in
    :ref:`Nitime <nitime:users-guide>`). Default is ``'length'``."""

docdict['normalize_psd_topo'] = """
normalize : bool
    If True, each band will be divided by the total power. Defaults to
    False.
"""

docdict['notes_2d_backend'] = """\
MNE-Python provides two different backends for browsing plots (i.e.,
:meth:`raw.plot()<mne.io.Raw.plot>`, :meth:`epochs.plot()<mne.Epochs.plot>`,
and :meth:`ica.plot_sources()<mne.preprocessing.ICA.plot_sources>`). One is
based on :mod:`matplotlib`, and the other is based on
:doc:`PyQtGraph<pyqtgraph:index>`. You can set the backend temporarily with the
context manager :func:`mne.viz.use_browser_backend`, you can set it for the
duration of a Python session using :func:`mne.viz.set_browser_backend`, and you
can set the default for your computer via
:func:`mne.set_config('MNE_BROWSER_BACKEND', 'matplotlib')<mne.set_config>`
(or ``'qt'``).

.. note:: For the PyQtGraph backend to run in IPython with ``block=False``
          you must run the magic command ``%gui qt5`` first.
.. note:: To report issues with the PyQtGraph backend, please use the
          `issues <https://github.com/mne-tools/mne-qt-browser/issues>`_
          of ``mne-qt-browser``.
"""

_notes_plot_psd = """\
This {} exists to support legacy code; for new code the preferred
idiom is ``inst.compute_psd().plot()`` (where ``inst`` is an instance
of :class:`~mne.io.Raw`, :class:`~mne.Epochs`, or :class:`~mne.Evoked`).
"""

docdict['notes_plot_*_psd_func'] = _notes_plot_psd.format('function')
docdict['notes_plot_psd_meth'] = _notes_plot_psd.format('method')

docdict['notes_tmax_included_by_default'] = """
Unlike Python slices, MNE time intervals by default include **both**
their end points; ``crop(tmin, tmax)`` returns the interval
``tmin <= t <= tmax``. Pass ``include_tmax=False`` to specify the half-open
interval ``tmin <= t < tmax`` instead.
"""

docdict['npad'] = """
npad : int | str
    Amount to pad the start and end of the data.
    Can also be "auto" to use a padding that will result in
    a power-of-two size (can be much faster).
"""

docdict['nrows_ncols_ica_components'] = """
nrows, ncols : int | 'auto'
    The number of rows and columns of topographies to plot. If both ``nrows``
    and ``ncols`` are ``'auto'``, will plot up to 20 components in a 5×4 grid,
    and return multiple figures if more than 20 components are requested.
    If one is ``'auto'`` and the other a scalar, a single figure is generated.
    If scalars are provided for both arguments, will plot up to ``nrows*ncols``
    components in a grid and return multiple figures as needed. Default is
    ``nrows='auto', ncols='auto'``.
"""

docdict['nrows_ncols_topomap'] = """
nrows, ncols : int | 'auto'
    The number of rows and columns of topographies to plot. If either ``nrows``
    or ``ncols`` is ``'auto'``, the necessary number will be inferred. Defaults
    to ``nrows=1, ncols='auto'``.
"""

# %%
# O

docdict['offset_decim'] = """
offset : int
    Apply an offset to where the decimation starts relative to the
    sample corresponding to t=0. The offset is in samples at the
    current sampling rate.

    .. versionadded:: 0.12
"""

docdict['on_baseline_ica'] = """
on_baseline : str
    How to handle baseline-corrected epochs or evoked data.
    Can be ``'raise'`` to raise an error, ``'warn'`` (default) to emit a
    warning, ``'ignore'`` to ignore, or "reapply" to reapply the baseline
    after applying ICA.

    .. versionadded:: 1.2
"""
docdict['on_defects'] = """
on_defects : 'raise' | 'warn' | 'ignore'
    What to do if the surface is found to have topological defects.
    Can be ``'raise'`` (default) to raise an error, ``'warn'`` to emit a
    warning, or ``'ignore'`` to ignore when one or more defects are found.
    Note that a lot of computations in MNE-Python assume the surfaces to be
    topologically correct, topological defects may still make other
    computations (e.g., `mne.make_bem_model` and `mne.make_bem_solution`)
    fail irrespective of this parameter.
"""

docdict['on_header_missing'] = """
on_header_missing : str
    Can be ``'raise'`` (default) to raise an error, ``'warn'`` to emit a
    warning, or ``'ignore'`` to ignore when the FastSCAN header is missing.

    .. versionadded:: 0.22
"""

_on_missing_base = """\
Can be ``'raise'`` (default) to raise an error, ``'warn'`` to emit a
    warning, or ``'ignore'`` to ignore when"""


docdict['on_mismatch_info'] = f"""
on_mismatch : 'raise' | 'warn' | 'ignore'
    {_on_missing_base} the device-to-head transformation differs between
    instances.

    .. versionadded:: 0.24
"""

docdict['on_missing_ch_names'] = f"""
on_missing : 'raise' | 'warn' | 'ignore'
    {_on_missing_base} entries in ch_names are not present in the raw instance.

    .. versionadded:: 0.23.0
"""

docdict['on_missing_chpi'] = f"""
on_missing : 'raise' | 'warn' | 'ignore'
    {_on_missing_base} no cHPI information can be found. If ``'ignore'`` or
    ``'warn'``, all return values will be empty arrays or ``None``. If
    ``'raise'``, an exception will be raised.
"""

docdict['on_missing_epochs'] = """
on_missing : 'raise' | 'warn' | 'ignore'
    What to do if one or several event ids are not found in the recording.
    Valid keys are 'raise' | 'warn' | 'ignore'
    Default is ``'raise'``. If ``'warn'``, it will proceed but
    warn; if ``'ignore'``, it will proceed silently.

    .. note::
       If none of the event ids are found in the data, an error will be
       automatically generated irrespective of this parameter.
"""

docdict['on_missing_events'] = f"""
on_missing : 'raise' | 'warn' | 'ignore'
    {_on_missing_base} event numbers from ``event_id`` are missing from
    :term:`events`. When numbers from :term:`events` are missing from
    ``event_id`` they will be ignored and a warning emitted; consider
    using ``verbose='error'`` in this case.

    .. versionadded:: 0.21
"""

docdict['on_missing_fiducials'] = f"""
on_missing : 'raise' | 'warn' | 'ignore'
    {_on_missing_base} some necessary fiducial points are missing.
"""

docdict['on_missing_fwd'] = f"""
on_missing : 'raise' | 'warn' | 'ignore'
    {_on_missing_base} ``stc`` has vertices that are not in ``fwd``.
"""

docdict['on_missing_montage'] = f"""
on_missing : 'raise' | 'warn' | 'ignore'
    {_on_missing_base} channels have missing coordinates.

    .. versionadded:: 0.20.1
"""

docdict['on_rank_mismatch'] = """
on_rank_mismatch : str
    If an explicit MEG value is passed, what to do when it does not match
    an empirically computed rank (only used for covariances).
    Can be 'raise' to raise an error, 'warn' (default) to emit a warning, or
    'ignore' to ignore.

    .. versionadded:: 0.23
"""

docdict['on_split_missing'] = f"""
on_split_missing : str
    {_on_missing_base} split file is missing.

    .. versionadded:: 0.22
"""

docdict['origin_maxwell'] = """
origin : array-like, shape (3,) | str
    Origin of internal and external multipolar moment space in meters.
    The default is ``'auto'``, which means ``(0., 0., 0.)`` when
    ``coord_frame='meg'``, and a head-digitization-based
    origin fit using :func:`~mne.bem.fit_sphere_to_headshape`
    when ``coord_frame='head'``. If automatic fitting fails (e.g., due
    to having too few digitization points),
    consider separately calling the fitting function with different
    options or specifying the origin manually.
"""

docdict['out_type_clust'] = """
out_type : 'mask' | 'indices'
    Output format of clusters within a list.
    If ``'mask'``, returns a list of boolean arrays,
    each with the same shape as the input data (or slices if the shape is 1D
    and adjacency is None), with ``True`` values indicating locations that are
    part of a cluster. If ``'indices'``, returns a list of tuple of ndarray,
    where each ndarray contains the indices of locations that together form the
    given cluster along the given dimension. Note that for large datasets,
    ``'indices'`` may use far less memory than ``'mask'``.
    Default is ``'indices'``.
"""

docdict['outlines_topomap'] = """
outlines : 'head' | dict | None
    The outlines to be drawn. If 'head', the default head scheme will be
    drawn. If dict, each key refers to a tuple of x and y positions, the values
    in 'mask_pos' will serve as image mask.
    Alternatively, a matplotlib patch object can be passed for advanced
    masking options, either directly or as a function that returns patches
    (required for multi-axis plots). If None, nothing will be drawn.
    Defaults to 'head'.
"""

docdict['overview_mode'] = """
overview_mode : str | None
    Can be "channels", "empty", or "hidden" to set the overview bar mode
    for the ``'qt'`` backend. If None (default), the config option
    ``MNE_BROWSER_OVERVIEW_MODE`` will be used, defaulting to "channels"
    if it's not found.
"""

docdict['overwrite'] = """
overwrite : bool
    If True (default False), overwrite the destination file if it
    exists.
"""

# %%
# P

_pad_base = """
pad : str
    The type of padding to use. Supports all :func:`numpy.pad` ``mode``
    options. Can also be ``"reflect_limited"``, which pads with a
    reflected version of each vector mirrored on the first and last values
    of the vector, followed by zeros.
"""

docdict['pad'] = _pad_base

docdict['pad_fir'] = _pad_base + """
    Only used for ``method='fir'``.
"""

docdict['pca_vars_pctf'] = """
pca_vars : array, shape (n_comp,) | list of array
    The explained variances of the first n_comp SVD components across the
    PSFs/CTFs for the specified vertices. Arrays for multiple labels are
    returned as list. Only returned if mode='svd' and return_pca_vars=True.
"""

docdict['per_sample_metric'] = """
per_sample : bool
    If True the metric is computed for each sample
    separately. If False, the metric is spatio-temporal.
"""

docdict['phase'] = """
phase : str
    Phase of the filter, only used if ``method='fir'``.
    Symmetric linear-phase FIR filters are constructed, and if ``phase='zero'``
    (default), the delay of this filter is compensated for, making it
    non-causal. If ``phase='zero-double'``,
    then this filter is applied twice, once forward, and once backward
    (also making it non-causal). If ``'minimum'``, then a minimum-phase filter
    will be constricted and applied, which is causal but has weaker stop-band
    suppression.

    .. versionadded:: 0.13
"""

docdict['physical_range_export_params'] = """
physical_range : str | tuple
    The physical range of the data. If 'auto' (default), then
    it will infer the physical min and max from the data itself,
    taking the minimum and maximum values per channel type.
    If it is a 2-tuple of minimum and maximum limit, then those
    physical ranges will be used. Only used for exporting EDF files.
"""

_pick_ori_novec = """
    Options:

    - ``None``
        Pooling is performed by taking the norm of loose/free
        orientations. In case of a fixed source space no norm is computed
        leading to signed source activity.
    - ``"normal"``
        Only the normal to the cortical surface is kept. This is only
        implemented when working with loose orientations.
"""

docdict['pick_ori'] = """
pick_ori : None | "normal" | "vector"
""" + _pick_ori_novec + """
    - ``"vector"``
        No pooling of the orientations is done, and the vector result
        will be returned in the form of a :class:`mne.VectorSourceEstimate`
        object.
"""

docdict['pick_ori_bf'] = """
pick_ori : None | str
    For forward solutions with fixed orientation, None (default) must be
    used and a scalar beamformer is computed. For free-orientation forward
    solutions, a vector beamformer is computed and:

    - ``None``
        Orientations are pooled after computing a vector beamformer (Default).
    - ``'normal'``
        Filters are computed for the orientation tangential to the
        cortical surface.
    - ``'max-power'``
        Filters are computed for the orientation that maximizes power.
"""

docdict['pick_ori_novec'] = """
pick_ori : None | "normal"
""" + _pick_ori_novec

docdict['pick_types_params'] = """
meg : bool | str
    If True include MEG channels. If string it can be 'mag', 'grad',
    'planar1' or 'planar2' to select only magnetometers, all
    gradiometers, or a specific type of gradiometer.
eeg : bool
    If True include EEG channels.
stim : bool
    If True include stimulus channels.
eog : bool
    If True include EOG channels.
ecg : bool
    If True include ECG channels.
emg : bool
    If True include EMG channels.
ref_meg : bool | str
    If True include CTF / 4D reference channels. If 'auto', reference
    channels are included if compensations are present and ``meg`` is
    not False. Can also be the string options for the ``meg``
    parameter.
misc : bool
    If True include miscellaneous analog channels.
resp : bool
    If ``True`` include respiratory channels.
chpi : bool
    If True include continuous HPI coil channels.
exci : bool
    Flux excitation channel used to be a stimulus channel.
ias : bool
    Internal Active Shielding data (maybe on Triux only).
syst : bool
    System status channel information (on Triux systems only).
seeg : bool
    Stereotactic EEG channels.
dipole : bool
    Dipole time course channels.
gof : bool
    Dipole goodness of fit channels.
bio : bool
    Bio channels.
ecog : bool
    Electrocorticography channels.
fnirs : bool | str
    Functional near-infrared spectroscopy channels. If True include all
    fNIRS channels. If False (default) include none. If string it can
    be 'hbo' (to include channels measuring oxyhemoglobin) or 'hbr' (to
    include channels measuring deoxyhemoglobin).
csd : bool
    EEG-CSD channels.
dbs : bool
    Deep brain stimulation channels.
temperature : bool
    Temperature channels.
gsr : bool
    Galvanic skin response channels.
include : list of str
    List of additional channels to include. If empty do not include
    any.
exclude : list of str | str
    List of channels to exclude. If 'bads' (default), exclude channels
    in ``info['bads']``.
selection : list of str
    Restrict sensor channels (MEG, EEG, etc.) to this list of channel names.
"""

_picks_types = 'str | array-like | slice | None'
_picks_header = f'picks : {_picks_types}'
_picks_desc = 'Channels to include.'
_picks_int = ('Slices and lists of integers will be interpreted as channel '
              'indices.')
_picks_str = """In lists, channel *type* strings
    (e.g., ``['meg', 'eeg']``) will pick channels of those
    types, channel *name* strings (e.g., ``['MEG0111', 'MEG2623']``
    will pick the given channels. Can also be the string values
    "all" to pick all channels, or "data" to pick :term:`data channels`.
    None (default) will pick"""
_reminder = ("Note that channels in ``info['bads']`` *will be included* if "
             "their {}indices are explicitly provided.")
reminder = _reminder.format('names or ')
reminder_nostr = _reminder.format('')
noref = f'(excluding reference MEG channels). {reminder}'
picks_base = f"""{_picks_header}
    {_picks_desc} {_picks_int} {_picks_str}"""
docdict['picks_all'] = _reflow_param_docstring(
    f'{picks_base} all channels. {reminder}')
docdict['picks_all_data'] = _reflow_param_docstring(
    f'{picks_base} all data channels. {reminder}')
docdict['picks_all_data_noref'] = _reflow_param_docstring(
    f'{picks_base} all data channels {noref}')
docdict['picks_base'] = _reflow_param_docstring(picks_base)
docdict['picks_good_data'] = _reflow_param_docstring(
    f'{picks_base} good data channels. {reminder}')
docdict['picks_good_data_noref'] = _reflow_param_docstring(
    f'{picks_base} good data channels {noref}')
docdict['picks_header'] = _picks_header
docdict['picks_ica'] = """
picks : int | list of int | slice | None
    Indices of the independent components (ICs) to visualize.
    If an integer, represents the index of the IC to pick.
    Multiple ICs can be selected using a list of int or a slice.
    The indices are 0-indexed, so ``picks=1`` will pick the second
    IC: ``ICA001``. ``None`` will pick all independent components in the order
    fitted.
"""
docdict['picks_nostr'] = f"""picks : list | slice | None
    {_picks_desc} {_picks_int}
    None (default) will pick all channels. {reminder_nostr}"""

docdict['picks_plot_projs_joint_trace'] = f"""\
picks_trace : {_picks_types}
    Channels to show alongside the projected time courses. Typically
    these are the ground-truth channels for an artifact (e.g., ``'eog'`` or
    ``'ecg'``). {_picks_int} {_picks_str} no channels.
"""

docdict['pipeline'] = """
pipeline : str | tuple
    The volume registration steps to perform (a ``str`` for a single step,
    or ``tuple`` for a set of sequential steps). The following steps can be
    performed, and do so by matching mutual information between the images
    (unless otherwise noted):

    ``'translation'``
        Translation.

    ``'rigid'``
        Rigid-body, i.e., rotation and translation.

    ``'affine'``
        A full affine transformation, which includes translation, rotation,
        scaling, and shear.

    ``'sdr'``
        Symmetric diffeomorphic registration :footcite:`AvantsEtAl2008`, a
        non-linear similarity-matching algorithm.

    The following string shortcuts can also be used:

    ``'all'`` (default)
        All steps will be performed above in the order above, i.e.,
        ``('translation', 'rigid', 'affine', 'sdr')``.

    ``'rigids'``
        The rigid steps (first two) will be performed, which registers
        the volume without distorting its underlying structure, i.e.,
        ``('translation', 'rigid')``. This is useful for
        example when registering images from the same subject, such as
        CT and MR images.

    ``'affines'``
        The affine steps (first three) will be performed, i.e., omitting
        the SDR step.
"""

docdict['plot_psd_doc'] = """\
Plot power or amplitude spectra.

Separate plots are drawn for each channel type. When the data have been
processed with a bandpass, lowpass or highpass filter, dashed lines (╎)
indicate the boundaries of the filter. The line noise frequency is also
indicated with a dashed line (⋮). If ``average=False``, the plot will
be interactive, and click-dragging on the spectrum will generate a
scalp topography plot for the chosen frequency range in a new figure
"""
# lack of trailing . is intentional; it must be in actual docstring ↑↑↑ (D400)

_pos_topomap = """\
pos : array, shape (n_channels, 2){}
    Location information for the channels. If an array, should provide the x
    and y coordinates for plotting the channels in 2D.
"""
docdict['pos_topomap'] = _pos_topomap.format(' | instance of Info')
docdict['pos_topomap_psd'] = _pos_topomap.format('')

docdict['position'] = """
position : int
    The position for the progress bar.
"""

docdict['precompute'] = """
precompute : bool | str
    Whether to load all data (not just the visible portion) into RAM and
    apply preprocessing (e.g., projectors) to the full data array in a separate
    processor thread, instead of window-by-window during scrolling. The default
    None uses the ``MNE_BROWSER_PRECOMPUTE`` variable, which defaults to
    ``'auto'``. ``'auto'`` compares available RAM space to the expected size of
    the precomputed data, and precomputes only if enough RAM is available.
    This is only used with the Qt backend.

    .. versionadded:: 0.24
    .. versionchanged:: 1.0
       Support for the MNE_BROWSER_PRECOMPUTE config variable.
"""

docdict['preload'] = """
preload : bool or str (default False)
    Preload data into memory for data manipulation and faster indexing.
    If True, the data will be preloaded into memory (fast, requires
    large amount of memory). If preload is a string, preload is the
    file name of a memory-mapped file which is used to store the data
    on the hard drive (slower, requires less memory)."""

docdict['preload_concatenate'] = """
preload : bool, str, or None (default None)
    Preload data into memory for data manipulation and faster indexing.
    If True, the data will be preloaded into memory (fast, requires
    large amount of memory). If preload is a string, preload is the
    file name of a memory-mapped file which is used to store the data
    on the hard drive (slower, requires less memory). If preload is
    None, preload=True or False is inferred using the preload status
    of the instances passed in.
"""

docdict['proj_epochs'] = """
proj : bool | 'delayed'
    Apply SSP projection vectors. If proj is 'delayed' and reject is not
    None the single epochs will be projected before the rejection
    decision, but used in unprojected state if they are kept.
    This way deciding which projection vectors are good can be postponed
    to the evoked stage without resulting in lower epoch counts and
    without producing results different from early SSP application
    given comparable parameters. Note that in this case baselining,
    detrending and temporal decimation will be postponed.
    If proj is False no projections will be applied which is the
    recommended value if SSPs are not used for cleaning the data.
"""

docdict['proj_plot'] = """
proj : bool | 'interactive' | 'reconstruct'
    If true SSP projections are applied before display. If 'interactive',
    a check box for reversible selection of SSP projection vectors will
    be shown. If 'reconstruct', projection vectors will be applied and then
    M/EEG data will be reconstructed via field mapping to reduce the signal
    bias caused by projection.

    .. versionchanged:: 0.21
       Support for 'reconstruct' was added.
"""

docdict['proj_psd'] = """\
proj : bool
    Whether to apply SSP projection vectors before spectral estimation.
    Default is ``False``.
"""

docdict['projection_set_eeg_reference'] = """
projection : bool
    If ``ref_channels='average'`` this argument specifies if the
    average reference should be computed as a projection (True) or not
    (False; default). If ``projection=True``, the average reference is
    added as a projection and is not applied to the data (it can be
    applied afterwards with the ``apply_proj`` method). If
    ``projection=False``, the average reference is directly applied to
    the data. If ``ref_channels`` is not ``'average'``, ``projection``
    must be set to ``False`` (the default in this case).
"""

docdict['projs_report'] = """
projs : bool | None
    Whether to add SSP projector plots if projectors are present in
    the data. If ``None``, use ``projs`` from `~mne.Report` creation.
"""

# %%
# R

docdict['random_state'] = """
random_state : None | int | instance of ~numpy.random.RandomState
    A seed for the NumPy random number generator (RNG). If ``None`` (default),
    the seed will be  obtained from the operating system
    (see  :class:`~numpy.random.RandomState` for details), meaning it will most
    likely produce different output every time this function or method is run.
    To achieve reproducible results, pass a value here to explicitly initialize
    the RNG with a defined state.
"""

_rank_base = """
rank : None | 'info' | 'full' | dict
    This controls the rank computation that can be read from the
    measurement info or estimated from the data. When a noise covariance
    is used for whitening, this should reflect the rank of that covariance,
    otherwise amplification of noise components can occur in whitening (e.g.,
    often during source localization).

    :data:`python:None`
        The rank will be estimated from the data after proper scaling of
        different channel types.
    ``'info'``
        The rank is inferred from ``info``. If data have been processed
        with Maxwell filtering, the Maxwell filtering header is used.
        Otherwise, the channel counts themselves are used.
        In both cases, the number of projectors is subtracted from
        the (effective) number of channels in the data.
        For example, if Maxwell filtering reduces the rank to 68, with
        two projectors the returned value will be 66.
    ``'full'``
        The rank is assumed to be full, i.e. equal to the
        number of good channels. If a `~mne.Covariance` is passed, this can
        make sense if it has been (possibly improperly) regularized without
        taking into account the true data rank.
    :class:`dict`
        Calculate the rank only for a subset of channel types, and explicitly
        specify the rank for the remaining channel types. This can be
        extremely useful if you already **know** the rank of (part of) your
        data, for instance in case you have calculated it earlier.

        This parameter must be a dictionary whose **keys** correspond to
        channel types in the data (e.g. ``'meg'``, ``'mag'``, ``'grad'``,
        ``'eeg'``), and whose **values** are integers representing the
        respective ranks. For example, ``{'mag': 90, 'eeg': 45}`` will assume
        a rank of ``90`` and ``45`` for magnetometer data and EEG data,
        respectively.

        The ranks for all channel types present in the data, but
        **not** specified in the dictionary will be estimated empirically.
        That is, if you passed a dataset containing magnetometer, gradiometer,
        and EEG data together with the dictionary from the previous example,
        only the gradiometer rank would be determined, while the specified
        magnetometer and EEG ranks would be taken for granted.
"""

docdict['rank'] = _rank_base
docdict['rank_info'] = _rank_base + "\n    The default is ``'info'``."
docdict['rank_none'] = _rank_base + "\n    The default is ``None``."

docdict['raw_epochs'] = """
raw : Raw object
    An instance of `~mne.io.Raw`.
"""

docdict['raw_sfreq'] = """
raw_sfreq : float
    The original Raw object sampling rate. If None, then it is set to
    ``info['sfreq']``.
"""

docdict['reduce_rank'] = """
reduce_rank : bool
    If True, the rank of the denominator of the beamformer formula (i.e.,
    during pseudo-inversion) will be reduced by one for each spatial location.
    Setting ``reduce_rank=True`` is typically necessary if you use a single
    sphere model with MEG data.

    .. versionchanged:: 0.20
        Support for reducing rank in all modes (previously only supported
        ``pick='max_power'`` with weight normalization).
"""

docdict['ref_channels'] = """
ref_channels : str | list of str
    Name of the electrode(s) which served as the reference in the
    recording. If a name is provided, a corresponding channel is added
    and its data is set to 0. This is useful for later re-referencing.
"""

docdict['ref_channels_set_eeg_reference'] = """
ref_channels : list of str | str
    Can be:

    - The name(s) of the channel(s) used to construct the reference.
    - ``'average'`` to apply an average reference (default)
    - ``'REST'`` to use the Reference Electrode Standardization Technique
      infinity reference :footcite:`Yao2001`.
    - An empty list, in which case MNE will not attempt any re-referencing of
      the data
"""

docdict['reg_affine'] = """
reg_affine : ndarray of float, shape (4, 4)
    The affine that registers one volume to another.
"""

docdict['regularize_maxwell_reg'] = """
regularize : str | None
    Basis regularization type, must be "in" or None.
    "in" is the same algorithm as the "-regularize in" option in
    MaxFilter™.
"""


_reject_by_annotation_base = """
reject_by_annotation : bool
    Whether to omit bad segments from the data before fitting. If ``True``
    (default), annotated segments whose description begins with ``'bad'`` are
    omitted. If ``False``, no rejection based on annotations is performed.
"""

docdict['reject_by_annotation_all'] = _reject_by_annotation_base

docdict['reject_by_annotation_epochs'] = """
reject_by_annotation : bool
    Whether to reject based on annotations. If ``True`` (default), epochs
    overlapping with segments whose description begins with ``'bad'`` are
    rejected. If ``False``, no rejection based on annotations is performed.
"""

docdict['reject_by_annotation_psd'] = """\
reject_by_annotation : bool
    Whether to omit bad spans of data before spectral estimation. If
    ``True``, spans with annotations whose description begins with
    ``bad`` will be omitted.
"""

docdict['reject_by_annotation_raw'] = _reject_by_annotation_base + """
    Has no effect if ``inst`` is not a :class:`mne.io.Raw` object.
"""

_reject_common = """\
    Reject epochs based on **maximum** peak-to-peak signal amplitude (PTP),
    i.e. the absolute difference between the lowest and the highest signal
    value. In each individual epoch, the PTP is calculated for every channel.
    If the PTP of any one channel exceeds the rejection threshold, the
    respective epoch will be dropped.

    The dictionary keys correspond to the different channel types; valid
    **keys** can be any channel type present in the object.

    Example::

        reject = dict(grad=4000e-13,  # unit: T / m (gradiometers)
                      mag=4e-12,      # unit: T (magnetometers)
                      eeg=40e-6,      # unit: V (EEG channels)
                      eog=250e-6      # unit: V (EOG channels)
                      )

    .. note:: Since rejection is based on a signal **difference**
              calculated for each channel separately, applying baseline
              correction does not affect the rejection procedure, as the
              difference will be preserved.
"""

docdict['reject_drop_bad'] = f"""
reject : dict | str | None
{_reject_common}
    If ``reject`` is ``None``, no rejection is performed. If ``'existing'``
    (default), then the rejection parameters set at instantiation are used.
"""

docdict['reject_epochs'] = f"""
reject : dict | None
{_reject_common}
    .. note:: To constrain the time period used for estimation of signal
              quality, pass the ``reject_tmin`` and ``reject_tmax`` parameters.

    If ``reject`` is ``None`` (default), no rejection is performed.
"""

docdict['replace_report'] = """
replace : bool
    If ``True``, content already present that has the same ``title`` and
    ``section`` will be replaced. Defaults to ``False``, which will cause
    duplicate entries in the table of contents if an entry for ``title``
    already exists.
"""

docdict['res_topomap'] = """
res : int
    The resolution of the topomap image (number of pixels along each side).
"""

docdict['return_pca_vars_pctf'] = """
return_pca_vars : bool
    Whether or not to return the explained variances across the specified
    vertices for individual SVD components. This is only valid if
    mode='svd'.
    Default return_pca_vars=False.
"""

docdict['roll'] = """
roll : float | None
    The roll of the camera rendering the view in degrees.
"""

# %%
# S

docdict['saturated'] = """saturated : str
    Replace saturated segments of data with NaNs, can be:

    ``"ignore"``
        The measured data is returned, even if it contains measurements
        while the amplifier was saturated.
    ``"nan"``
        The returned data will contain NaNs during time segments
        when the amplifier was saturated.
    ``"annotate"`` (default)
        The returned data will contain annotations specifying
        sections the saturate segments.

    This argument will only be used if there is no .nosatflags file
    (only if a NIRSport device is used and saturation occurred).

    .. versionadded:: 0.24
"""

docdict['scalings'] = """
scalings : 'auto' | dict | None
    Scaling factors for the traces. If a dictionary where any
    value is ``'auto'``, the scaling factor is set to match the 99.5th
    percentile of the respective data. If ``'auto'``, all scalings (for all
    channel types) are set to ``'auto'``. If any values are ``'auto'`` and the
    data is not preloaded, a subset up to 100 MB will be loaded. If ``None``,
    defaults to::

        dict(mag=1e-12, grad=4e-11, eeg=20e-6, eog=150e-6, ecg=5e-4,
             emg=1e-3, ref_meg=1e-12, misc=1e-3, stim=1,
             resp=1, chpi=1e-4, whitened=1e2)

    .. note::
        A particular scaling value ``s`` corresponds to half of the visualized
        signal range around zero (i.e. from ``0`` to ``+s`` or from ``0`` to
        ``-s``). For example, the default scaling of ``20e-6`` (20µV) for EEG
        signals means that the visualized range will be 40 µV (20 µV in the
        positive direction and 20 µV in the negative direction).
"""

docdict['scalings_df'] = """
scalings : dict | None
    Scaling factor applied to the channels picked. If ``None``, defaults to
    ``dict(eeg=1e6, mag=1e15, grad=1e13)`` — i.e., converts EEG to µV,
    magnetometers to fT, and gradiometers to fT/cm.
"""

docdict['scalings_topomap'] = """
scalings : dict | float | None
    The scalings of the channel types to be applied for plotting.
    If None, defaults to ``dict(eeg=1e6, grad=1e13, mag=1e15)``.
"""

docdict['scoring'] = """
scoring : callable | str | None
    Score function (or loss function) with signature
    ``score_func(y, y_pred, **kwargs)``.
    Note that the "predict" method is automatically identified if scoring is
    a string (e.g. ``scoring='roc_auc'`` calls ``predict_proba``), but is
    **not**  automatically set if ``scoring`` is a callable (e.g.
    ``scoring=sklearn.metrics.roc_auc_score``).
"""

docdict['sdr_morph'] = """
sdr_morph : instance of dipy.align.DiffeomorphicMap
    The class that applies the the symmetric diffeomorphic registration
    (SDR) morph.
"""

docdict['section_report'] = """
section : str | None
    The name of the section (or content block) to add the content to. This
    feature is useful for grouping multiple related content elements
    together under a single, collapsible section. Each content element will
    retain its own title and functionality, but not appear separately in the
    table of contents. Hence, using sections is a way to declutter the table
    of contents, and to easy navigation of the report.

    .. versionadded:: 1.1
"""

docdict['seed'] = """
seed : None | int | instance of ~numpy.random.RandomState
    A seed for the NumPy random number generator (RNG). If ``None`` (default),
    the seed will be  obtained from the operating system
    (see  :class:`~numpy.random.RandomState` for details), meaning it will most
    likely produce different output every time this function or method is run.
    To achieve reproducible results, pass a value here to explicitly initialize
    the RNG with a defined state.
"""

docdict['seeg'] = """
seeg : bool
    If True (default), show sEEG electrodes.
"""

docdict['selection'] = """
selection : iterable | None
    Iterable of indices of selected epochs. If ``None``, will be
    automatically generated, corresponding to all non-zero events.
"""

docdict['sensors_topomap'] = """
sensors : bool | str
    Whether to add markers for sensor locations. If :class:`str`, should be a
    valid matplotlib format string (e.g., ``'r+'`` for red plusses, see the
    Notes section of :meth:`~matplotlib.axes.Axes.plot`). If ``True`` (the
    default), black circles will be used.
"""

docdict['set_eeg_reference_see_also_notes'] = """
See Also
--------
mne.set_bipolar_reference : Convenience function for creating bipolar
                        references.

Notes
-----
Some common referencing schemes and the corresponding value for the
``ref_channels`` parameter:

- Average reference:
    A new virtual reference electrode is created by averaging the current
    EEG signal by setting ``ref_channels='average'``. Bad EEG channels are
    automatically excluded if they are properly set in ``info['bads']``.

- A single electrode:
    Set ``ref_channels`` to a list containing the name of the channel that
    will act as the new reference, for example ``ref_channels=['Cz']``.

- The mean of multiple electrodes:
    A new virtual reference electrode is created by computing the average
    of the current EEG signal recorded from two or more selected channels.
    Set ``ref_channels`` to a list of channel names, indicating which
    channels to use. For example, to apply an average mastoid reference,
    when using the 10-20 naming scheme, set ``ref_channels=['M1', 'M2']``.

- REST
    The given EEG electrodes are referenced to a point at infinity using the
    lead fields in ``forward``, which helps standardize the signals.

1. If a reference is requested that is not the average reference, this
   function removes any pre-existing average reference projections.

2. During source localization, the EEG signal should have an average
   reference.

3. In order to apply a reference, the data must be preloaded. This is not
   necessary if ``ref_channels='average'`` and ``projection=True``.

4. For an average or REST reference, bad EEG channels are automatically
   excluded if they are properly set in ``info['bads']``.

.. versionadded:: 0.9.0

References
----------
.. footbibliography::
"""

docdict['show'] = """\
show : bool
    Show the figure if ``True``.
"""

docdict['show_names_topomap'] = """
show_names : bool | callable
    If ``True``, show channel names next to each sensor marker. If callable,
    channel names will be formatted using the callable; e.g., to
    delete the prefix 'MEG ' from all channel names, pass the function
    ``lambda x: x.replace('MEG ', '')``. If ``mask`` is not ``None``, only
    non-masked sensor names will be shown.
"""

docdict['show_scalebars'] = """
show_scalebars : bool
    Whether to show scale bars when the plot is initialized. Can be toggled
    after initialization by pressing :kbd:`s` while the plot window is focused.
    Default is ``True``.
"""

docdict['show_scrollbars'] = """
show_scrollbars : bool
    Whether to show scrollbars when the plot is initialized. Can be toggled
    after initialization by pressing :kbd:`z` ("zen mode") while the plot
    window is focused. Default is ``True``.

    .. versionadded:: 0.19.0
"""

docdict['show_traces'] = """
show_traces : bool | str | float
    If True, enable interactive picking of a point on the surface of the
    brain and plot its time course.
    This feature is only available with the PyVista 3d backend, and requires
    ``time_viewer=True``. Defaults to 'auto', which will use True if and
    only if ``time_viewer=True``, the backend is PyVista, and there is more
    than one time point. If float (between zero and one), it specifies what
    proportion of the total window should be devoted to traces (True is
    equivalent to 0.25, i.e., it will occupy the bottom 1/4 of the figure).

    .. versionadded:: 0.20.0
"""

docdict['size_topomap'] = """
size : float
    Side length of each subplot in inches.
"""

docdict['skip_by_annotation_maxwell'] = """
skip_by_annotation : str | list of str
    If a string (or list of str), any annotation segment that begins
    with the given string will not be included in filtering, and
    segments on either side of the given excluded annotated segment
    will be filtered separately (i.e., as independent signals).
    The default ``('edge', 'bad_acq_skip')`` will separately filter
    any segments that were concatenated by :func:`mne.concatenate_raws`
    or :meth:`mne.io.Raw.append`, or separated during acquisition.
    To disable, provide an empty list.
"""

docdict['smooth'] = """
smooth : float in [0, 1)
    The smoothing factor to be applied. Default 0 is no smoothing.
"""

docdict['spatial_colors_psd'] = """\
spatial_colors : bool
    Whether to color spectrum lines by channel location. Ignored if
    ``average=True``.
"""

docdict['sphere_topomap_auto'] = f"""\
sphere : float | array-like | instance of ConductorModel | None  | 'auto' | 'eeglab'
    The sphere parameters to use for the head outline. Can be array-like of
    shape (4,) to give the X/Y/Z origin and radius in meters, or a single float
    to give just the radius (origin assumed 0, 0, 0). Can also be an instance
    of a spherical :class:`~mne.bem.ConductorModel` to use the origin and
    radius from that object. If ``'auto'`` the sphere is fit to digitization
    points. If ``'eeglab'`` the head circle is defined by EEG electrodes
    ``'Fpz'``, ``'Oz'``, ``'T7'``, and ``'T8'`` (if ``'Fpz'`` is not present,
    it will be approximated from the coordinates of ``'Oz'``). ``None`` (the
    default) is equivalent to ``'auto'`` when enough extra digitization points
    are available, and (0, 0, 0, {HEAD_SIZE_DEFAULT}) otherwise.

    .. versionadded:: 0.20
    .. versionchanged:: 1.1 Added ``'eeglab'`` option.
"""  # noqa E501

docdict['split_naming'] = """
split_naming : 'neuromag' | 'bids'
    When splitting files, append a filename partition with the appropriate
    naming schema: for ``'neuromag'``, a split file ``fname.fif`` will be named
    ``fname.fif``, ``fname-1.fif``, ``fname-2.fif`` etc.; while for ``'bids'``,
    it will be named ``fname_split-01.fif``, ``fname_split-02.fif``, etc.
"""

docdict['src_eltc'] = """
src : instance of SourceSpaces
    The source spaces for the source time courses.
"""

docdict['src_volume_options'] = """
src : instance of SourceSpaces | None
    The source space corresponding to the source estimate. Only necessary
    if the STC is a volume or mixed source estimate.
volume_options : float | dict | None
    Options for volumetric source estimate plotting, with key/value pairs:

    - ``'resolution'`` : float | None
        Resolution (in mm) of volume rendering. Smaller (e.g., 1.) looks
        better at the cost of speed. None (default) uses the volume source
        space resolution, which is often something like 7 or 5 mm,
        without resampling.
    - ``'blending'`` : str
        Can be "mip" (default) for :term:`maximum intensity projection` or
        "composite" for composite blending using alpha values.
    - ``'alpha'`` : float | None
        Alpha for the volumetric rendering. Defaults are 0.4 for vector source
        estimates and 1.0 for scalar source estimates.
    - ``'surface_alpha'`` : float | None
        Alpha for the surface enclosing the volume(s). None (default) will use
        half the volume alpha. Set to zero to avoid plotting the surface.
    - ``'silhouette_alpha'`` : float | None
        Alpha for a silhouette along the outside of the volume. None (default)
        will use ``0.25 * surface_alpha``.
    - ``'silhouette_linewidth'`` : float
        The line width to use for the silhouette. Default is 2.

    A float input (default 1.) or None will be used for the ``'resolution'``
    entry.
"""

docdict['st_fixed_maxwell_only'] = """
st_fixed : bool
    If True (default), do tSSS using the median head position during the
    ``st_duration`` window. This is the default behavior of MaxFilter
    and has been most extensively tested.

    .. versionadded:: 0.12
st_only : bool
    If True, only tSSS (temporal) projection of MEG data will be
    performed on the output data. The non-tSSS parameters (e.g.,
    ``int_order``, ``calibration``, ``head_pos``, etc.) will still be
    used to form the SSS bases used to calculate temporal projectors,
    but the output MEG data will *only* have temporal projections
    performed. Noise reduction from SSS basis multiplication,
    cross-talk cancellation, movement compensation, and so forth
    will not be applied to the data. This is useful, for example, when
    evoked movement compensation will be performed with
    :func:`~mne.epochs.average_movements`.

    .. versionadded:: 0.12
"""

docdict['standardize_names'] = """
standardize_names : bool
    If True, standardize MEG and EEG channel names to be
    ``"MEG ###"`` and ``"EEG ###"``. If False (default), native
    channel names in the file will be used when possible.
"""

_stat_fun_clust_base = """
stat_fun : callable | None
    Function called to calculate the test statistic. Must accept 1D-array as
    input and return a 1D array. If ``None`` (the default), uses
    `mne.stats.{}`.
"""

docdict['stat_fun_clust_f'] = _stat_fun_clust_base.format('f_oneway')

docdict['stat_fun_clust_t'] = _stat_fun_clust_base.format('ttest_1samp_no_p')

docdict['static'] = """
static : instance of SpatialImage
    The image to align with ("to" volume).
"""

docdict['stc_est_metric'] = """
stc_est : instance of (Vol|Mixed)SourceEstimate
    The source estimates containing estimated values
    e.g. obtained with a source imaging method.
"""

docdict['stc_metric'] = """
metric : float | array, shape (n_times,)
    The metric. float if per_sample is False, else
    array with the values computed for each time point.
"""

docdict['stc_plot_kwargs_report'] = """
stc_plot_kwargs : dict
    Dictionary of keyword arguments to pass to
    :class:`mne.SourceEstimate.plot`. Only used when plotting in 3D
    mode.
"""

docdict['stc_true_metric'] = """
stc_true : instance of (Vol|Mixed)SourceEstimate
    The source estimates containing correct values.
"""

docdict['stcs_pctf'] = """
stcs : instance of SourceEstimate | list of instances of SourceEstimate
    The PSFs or CTFs as STC objects. All PSFs/CTFs will be returned as
    successive samples in STC objects, in the order they are specified
    in idx. STCs for different labels willbe returned as a list.
    If resmat was computed with n_orient_inv==3 for CTFs or
    n_orient_fwd==3 for PSFs then 3 functions per vertex will be returned
    as successive samples (i.e. one function per orientation).
    If vector=False (default) and resmat was computed with
    n_orient_inv==3 for PSFs or n_orient_fwd==3 for CTFs, then the three
    values per vertex will be combined into one intensity value per
    vertex in a SourceEstimate object. If vector=True, PSFs or CTFs
    with 3 values per vertex (one per orientation) will be returned in
    a VectorSourceEstimate object.
"""

docdict['std_err_by_event_type_returns'] = """
std_err : instance of Evoked | list of Evoked
    The standard error over epochs.
    When ``by_event_type=True`` was specified, a list is returned containing a
    separate :class:`~mne.Evoked` object for each event type. The list has the
    same order as the event types as specified in the ``event_id``
    dictionary.
"""

docdict['step_down_p_clust'] = """
step_down_p : float
    To perform a step-down-in-jumps test, pass a p-value for clusters to
    exclude from each successive iteration. Default is zero, perform no
    step-down test (since no clusters will be smaller than this value).
    Setting this to a reasonable value, e.g. 0.05, can increase sensitivity
    but costs computation time.
"""

docdict['subject'] = """
subject : str
    The FreeSurfer subject name.
"""

docdict['subject_label'] = """
subject : str | None
    Subject which this label belongs to. Should only be specified if it is not
    specified in the label.
"""

docdict['subject_none'] = """
subject : str | None
    The FreeSurfer subject name.
"""

docdict['subject_optional'] = """
subject : str
    The FreeSurfer subject name. While not necessary, it is safer to set the
    subject parameter to avoid analysis errors.
"""

docdict['subjects_dir'] = """
subjects_dir : path-like | None
    The path to the directory containing the FreeSurfer subjects
    reconstructions. If ``None``, defaults to the ``SUBJECTS_DIR`` environment
    variable.
"""

docdict['surface'] = """surface : str
    The surface along which to do the computations, defaults to ``'white'``
    (the gray-white matter boundary).
"""

# %%
# T

docdict['t_power_clust'] = """
t_power : float
    Power to raise the statistical values (usually t-values) by before
    summing (sign will be retained). Note that ``t_power=0`` will give a
    count of locations in each cluster, ``t_power=1`` will weight each location
    by its statistical score.
"""

docdict['t_window_chpi_t'] = """
t_window : float
    Time window to use to estimate the amplitudes, default is
    0.2 (200 ms).
"""

docdict['tags_report'] = """
tags : array-like of str | str
    Tags to add for later interactive filtering. Must not contain spaces.
"""

docdict['tail_clust'] = """
tail : int
    If tail is 1, the statistic is thresholded above threshold.
    If tail is -1, the statistic is thresholded below threshold.
    If tail is 0, the statistic is thresholded on both sides of
    the distribution.
"""

docdict['temporal-window_tfr_notes'] = r"""
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.

Time-frequency representations are computed using a sliding temporal window.
Either the temporal window has a fixed length independent of frequency, or the
temporal window decreases in length with increased frequency.

.. image:: https://www.fieldtriptoolbox.org/assets/img/tutorial/timefrequencyanalysis/figure1.png

*Figure: Time and frequency smoothing. (a) For a fixed length temporal window
the time and frequency smoothing remains fixed. (b) For temporal windows that
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 <https://www.fieldtriptoolbox.org/tutorial/timefrequencyanalysis>`_.

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}}`

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
    custom stylesheet. For Dark-Mode and automatic Dark-Mode-Detection,
    :mod:`qdarkstyle` and
    `darkdetect <https://github.com/albertosottile/darkdetect>`__,
    respectively, are required.\
    If None (default), the config option {config_option} will be used,
    defaulting to "auto" if it's not found.\
"""

docdict['theme_3d'] = """
{theme}
""".format(theme=_theme.format(config_option='MNE_3D_OPTION_THEME'))

docdict['theme_pg'] = """
{theme}
    Only supported by the ``'qt'`` backend.
""".format(theme=_theme.format(config_option='MNE_BROWSER_THEME'))

docdict['thresh'] = """
thresh : None or float
    Not supported yet.
    If not None, values below thresh will not be visible.
"""

_threshold_clust_base = """
threshold : float | dict | None
    The so-called "cluster forming threshold" in the form of a test statistic
    (note: this is not an alpha level / "p-value").
    If numeric, vertices with data values more extreme than ``threshold`` will
    be used to form clusters. If ``None``, {} will be chosen
    automatically that corresponds to a p-value of 0.05 for the given number of
    observations (only valid when using {}). If ``threshold`` is a
    :class:`dict` (with keys ``'start'`` and ``'step'``) then threshold-free
    cluster enhancement (TFCE) will be used (see the
    :ref:`TFCE example <tfce_example>` and :footcite:`SmithNichols2009`).
    See Notes for an example on how to compute a threshold based on
    a particular p-value for one-tailed or two-tailed tests.
"""

f_test = ('an F-threshold', 'an F-statistic')
docdict['threshold_clust_f'] = _threshold_clust_base.format(*f_test)

docdict['threshold_clust_f_notes'] = """
For computing a ``threshold`` based on a p-value, use the conversion
from :meth:`scipy.stats.rv_continuous.ppf`::

    pval = 0.001  # arbitrary
    dfn = n_conditions - 1  # degrees of freedom numerator
    dfd = n_observations - n_conditions  # degrees of freedom denominator
    thresh = scipy.stats.f.ppf(1 - pval, dfn=dfn, dfd=dfd)  # F distribution
"""

t_test = ('a t-threshold', 'a t-statistic')
docdict['threshold_clust_t'] = _threshold_clust_base.format(*t_test)

docdict['threshold_clust_t_notes'] = """
For computing a ``threshold`` based on a p-value, use the conversion
from :meth:`scipy.stats.rv_continuous.ppf`::

    pval = 0.001  # arbitrary
    df = n_observations - 1  # degrees of freedom for the test
    thresh = scipy.stats.t.ppf(1 - pval / 2, df)  # two-tailed, t distribution

For a one-tailed test (``tail=1``), don't divide the p-value by 2.
For testing the lower tail (``tail=-1``), don't subtract ``pval`` from 1.
"""

docdict['time_bandwidth_tfr'] = """
time_bandwidth : float ``≥ 2.0``
    Product between the temporal window length (in seconds) and the *full*
    frequency bandwidth (in Hz). This product can be seen as the surface of the
    window on the time/frequency plane and controls the frequency bandwidth
    (thus the frequency resolution) and the number of good tapers. See notes
    for additional information."""

docdict['time_bandwidth_tfr_notes'] = 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}}`.
The ``time_bandwidth`` parameter defines the "time-bandwidth product", which is
the product of the temporal window length (in seconds) and the frequency
bandwidth (in Hz). Thus once ``n_cycles`` has been set, frequency bandwidth is
determined by :math:`\frac{\mathrm{time~bandwidth}}{\mathrm{time~window}}`, and
thus passing a larger ``time_bandwidth`` value will increase the frequency
bandwidth (thereby decreasing the frequency *resolution*).

The increased frequency bandwidth is reached by averaging spectral estimates
obtained from multiple tapers. Thus, ``time_bandwidth`` also determines the
number of tapers used. MNE-Python uses only "good" tapers (tapers with minimal
leakage from far-away frequencies); the number of good tapers is
``floor(time_bandwidth - 1)``. This means there is another trade-off at play,
between frequency resolution and the variance reduction that multitaper
analysis provides. Striving for finer frequency resolution (by setting
``time_bandwidth`` low) means fewer tapers will be used, which undermines what
is unique about multitaper methods — namely their ability to improve accuracy /
reduce noise in the power estimates by using several (orthogonal) tapers.

.. warning::

    In `~mne.time_frequency.tfr_array_multitaper` and
    `~mne.time_frequency.tfr_multitaper`, ``time_bandwidth`` defines the
    product of the temporal window length with the *full* frequency bandwidth
    For example, a full bandwidth of 4 Hz at a frequency of interest of 10 Hz
    will "smear" the frequency estimate between 8 Hz and 12 Hz.

    This is not the case for `~mne.time_frequency.psd_array_multitaper` where
    the argument ``bandwidth`` defines the *half* frequency bandwidth. In the
    example above, the half-frequency bandwidth is 2 Hz.
"""

docdict['time_format'] = """
time_format : 'float' | 'clock'
    Style of time labels on the horizontal axis. If ``'float'``, labels will be
    number of seconds from the start of the recording. If ``'clock'``,
    labels will show "clock time" (hours/minutes/seconds) inferred from
    ``raw.info['meas_date']``. Default is ``'float'``.

    .. versionadded:: 0.24
"""

_time_format_df_base = """
time_format : str | None
    Desired time format. If ``None``, no conversion is applied, and time values
    remain as float values in seconds. If ``'ms'``, time values will be rounded
    to the nearest millisecond and converted to integers. If ``'timedelta'``,
    time values will be converted to :class:`pandas.Timedelta` values. {}
    Default is ``None``.
"""

docdict['time_format_df'] = _time_format_df_base.format('')

_raw_tf = ("If ``'datetime'``, time values will be converted to "
           ":class:`pandas.Timestamp` values, relative to "
           "``raw.info['meas_date']`` and offset by ``raw.first_samp``. ")
docdict['time_format_df_raw'] = _time_format_df_base.format(_raw_tf)

docdict['time_label'] = """
time_label : str | callable | None
    Format of the time label (a format string, a function that maps
    floating point time values to strings, or None for no label). The
    default is ``'auto'``, which will use ``time=%0.2f ms`` if there
    is more than one time point.
"""

docdict['time_unit'] = """\
time_unit : str
    The units for the time axis, can be "s" (default) or "ms".
"""

docdict['time_viewer_brain_screenshot'] = """
time_viewer : bool
    If True, include time viewer traces. Only used if
    ``time_viewer=True`` and ``separate_canvas=False``.
"""

docdict['title_none'] = """
title : str | None
    The title of the generated figure. If ``None`` (default), no title is
    displayed.
"""

docdict['tmax_raw'] = """
tmax : float
    End time of the raw data to use in seconds (cannot exceed data duration).
"""

docdict['tmin'] = """
tmin : scalar
    Time point of the first sample in data.
"""

docdict['tmin_raw'] = """
tmin : float
    Start time of the raw data to use in seconds (must be >= 0).
"""

docdict['tmin_tmax_psd'] = """\
tmin, tmax : float | None
    First and last times to include, in seconds. ``None`` uses the first or
    last time present in the data. Default is ``tmin=None, tmax=None`` (all
    times).
"""

docdict['tol_kind_rank'] = """
tol_kind : str
    Can be: "absolute" (default) or "relative". Only used if ``tol`` is a
    float, because when ``tol`` is a string the mode is implicitly relative.
    After applying the chosen scale factors / normalization to the data,
    the singular values are computed, and the rank is then taken as:

    - ``'absolute'``
        The number of singular values ``s`` greater than ``tol``.
        This mode can fail if your data do not adhere to typical
        data scalings.
    - ``'relative'``
        The number of singular values ``s`` greater than ``tol * s.max()``.
        This mode can fail if you have one or more large components in the
        data (e.g., artifacts).

    .. versionadded:: 0.21.0
"""

docdict['tol_rank'] = """
tol : float | 'auto'
    Tolerance for singular values to consider non-zero in
    calculating the rank. The singular values are calculated
    in this method such that independent data are expected to
    have singular value around one. Can be 'auto' to use the
    same thresholding as :func:`scipy.linalg.orth`.
"""

docdict['topomap_kwargs'] = """
topomap_kwargs : dict | None
    Keyword arguments to pass to the topomap-generating functions.
"""

_trans_base = """\
If str, the path to the head<->MRI transform ``*-trans.fif`` file produced
    during coregistration. Can also be ``'fsaverage'`` to use the built-in
    fsaverage transformation."""

docdict['trans'] = f"""
trans : path-like | dict | instance of Transform | None
    {_trans_base}
    If trans is None, an identity matrix is assumed.
"""

docdict['trans_not_none'] = """
trans : str | dict | instance of Transform
    %s
""" % (_trans_base,)

docdict['transparent'] = """
transparent : bool | None
    If True: use a linear transparency between fmin and fmid
    and make values below fmin fully transparent (symmetrically for
    divergent colormaps). None will choose automatically based on colormap
    type.
"""

docdict['tstart_ecg'] = """
tstart : float
    Start ECG detection after ``tstart`` seconds. Useful when the beginning
    of the run is noisy.
"""

docdict['tstep'] = """
tstep : scalar
    Time step between successive samples in data.
"""

# %%
# U

docdict['uint16_codec'] = """
uint16_codec : str | None
    If your set file contains non-ascii characters, sometimes reading
    it may fail and give rise to error message stating that "buffer is
    too small". ``uint16_codec`` allows to specify what codec (for example:
    'latin1' or 'utf-8') should be used when reading character arrays and
    can therefore help you solve this problem.
"""

docdict['units'] = """
units : str | dict | None
    Specify the unit(s) that the data should be returned in. If
    ``None`` (default), the data is returned in the
    channel-type-specific default units, which are SI units (see
    :ref:`units` and :term:`data channels`). If a string, must be a
    sub-multiple of SI units that will be used to scale the data from
    all channels of the type associated with that unit. This only works
    if the data contains one channel type that has a unit (unitless
    channel types are left unchanged). For example if there are only
    EEG and STIM channels, ``units='uV'`` will scale EEG channels to
    micro-Volts while STIM channels will be unchanged. Finally, if a
    dictionary is provided, keys must be channel types, and values must
    be units to scale the data of that channel type to. For example
    ``dict(grad='fT/cm', mag='fT')`` will scale the corresponding types
    accordingly, but all other channel types will remain in their
    channel-type-specific default unit.
"""

docdict['units_edf_bdf_io'] = """
units : dict | str
    The units of the channels as stored in the file. This argument
    is useful only if the units are missing from the original file.
    If a dict, it must map a channel name to its unit, and if str
    it is assumed that all channels have the same units.
"""

_units = """
units : {}str | None
    The units to use for the colorbar label. Ignored if ``colorbar=False``.
    If ``None`` {}the label will be "AU" indicating arbitrary units.
    Default is ``None``.
"""
docdict['units_topomap'] = _units.format('', '')
docdict['units_topomap_evoked'] = _units.format(
    'dict | ',
    'and ``scalings=None`` the unit is automatically determined, otherwise ')

docdict['use_cps'] = """
use_cps : bool
    Whether to use cortical patch statistics to define normal orientations for
    surfaces (default True).
"""

docdict['use_cps_restricted'] = """
use_cps : bool
    Whether to use cortical patch statistics to define normal orientations for
    surfaces (default True).

    Only used when the inverse is free orientation (``loose=1.``),
    not in surface orientation, and ``pick_ori='normal'``.
"""

docdict['use_opengl'] = """
use_opengl : bool | None
    Whether to use OpenGL when rendering the plot (requires ``pyopengl``).
    May increase performance, but effect is dependent on system CPU and
    graphics hardware. Only works if using the Qt backend. Default is
    None, which will use False unless the user configuration variable
    ``MNE_BROWSER_USE_OPENGL`` is set to ``'true'``,
    see :func:`mne.set_config`.

    .. versionadded:: 0.24
"""

# %%
# V

docdict['vector_pctf'] = """
vector : bool
    Whether to return PSF/CTF as vector source estimate (3 values per
    location) or source estimate object (1 intensity value per location).
    Only allowed to be True if corresponding dimension of resolution matrix
    is 3 * n_dipoles. Defaults to False.

    .. versionadded:: 1.2
"""

docdict['verbose'] = """
verbose : bool | str | int | None
    Control verbosity of the logging output. If ``None``, use the default
    verbosity level. See the :ref:`logging documentation <tut-logging>` and
    :func:`mne.verbose` for details. Should only be passed as a keyword
    argument.
"""

docdict['vertices_volume'] = """
vertices : list of array of int
    The indices of the dipoles in the source space. Should be a single
    array of shape (n_dipoles,) unless there are subvolumes.
"""

docdict['view'] = """
view : str | None
    The name of the view to show (e.g. "lateral"). Other arguments
    take precedence and modify the camera starting from the ``view``.
    See :meth:`Brain.show_view <mne.viz.Brain.show_view>` for valid
    string shortcut options.
"""

docdict['view_layout'] = """
view_layout : str
    Can be "vertical" (default) or "horizontal". When using "horizontal" mode,
    the PyVista backend must be used and hemi cannot be "split".
"""

docdict['views'] = """
views : str | list
    View to use. Using multiple views (list) is not supported for mpl
    backend. See :meth:`Brain.show_view <mne.viz.Brain.show_view>` for
    valid string options.
"""

_vlim = """
vlim : tuple of length 2{}
    Colormap limits to use. If a :class:`tuple` of floats, specifies the
    lower and upper bounds of the colormap (in that order); providing
    ``None`` for either entry will set the corresponding boundary at the
    min/max of the data{}. {}{}{}Defaults to ``(None, None)``.
"""
_vlim_joint = _vlim.format(
    " | 'joint'",
    " (separately for each {0})",
    '{1}',
    "If ``vlim='joint'``, will compute the colormap limits jointly across "
    "all {0}s of the same channel type, using the min/max of the data for "
    "that channel type. ",
    '{2}'
)
_vlim_callable = (
    'Elements of the :class:`tuple` may also be callable functions which '
    'take in a :class:`NumPy array <numpy.ndarray>` and return a scalar. ')

docdict['vlim_plot_topomap'] = _vlim.format('', '', '', '', '')
docdict['vlim_plot_topomap_proj'] = _vlim_joint.format(
    'projector', _vlim_callable,
    "If vlim is ``'joint'``, ``info`` must not be ``None``. ")
docdict['vlim_plot_topomap_psd'] = _vlim_joint.format(
    'topomap', _vlim_callable, '')

docdict['vmin_vmax_topomap'] = """
vmin, vmax : float | callable | None
    Lower and upper bounds of the colormap, in the same units as the data.
    If ``vmin`` and ``vmax`` are both ``None``, they are set at ± the
    maximum absolute value of the data (yielding a colormap with midpoint
    at 0). If only one of ``vmin``, ``vmax`` is ``None``, will use
    ``min(data)`` or ``max(data)``, respectively. If callable, should
    accept a :class:`NumPy array <numpy.ndarray>` of data and return a
    float.
"""

# %%
# W

docdict['weight_norm'] = """
weight_norm : str | None
    Can be:

    - ``None``
        The unit-gain LCMV beamformer :footcite:`SekiharaNagarajan2008` will be
        computed.
    - ``'unit-noise-gain'``
        The unit-noise gain minimum variance beamformer will be computed
        (Borgiotti-Kaplan beamformer) :footcite:`SekiharaNagarajan2008`,
        which is not rotation invariant when ``pick_ori='vector'``.
        This should be combined with
        :meth:`stc.project('pca') <mne.VectorSourceEstimate.project>` to follow
        the definition in :footcite:`SekiharaNagarajan2008`.
    - ``'nai'``
        The Neural Activity Index :footcite:`VanVeenEtAl1997` will be computed,
        which simply scales all values from ``'unit-noise-gain'`` by a fixed
        value.
    - ``'unit-noise-gain-invariant'``
        Compute a rotation-invariant normalization using the matrix square
        root. This differs from ``'unit-noise-gain'`` only when
        ``pick_ori='vector'``, creating a solution that:

        1. Is rotation invariant (``'unit-noise-gain'`` is not);
        2. Satisfies the first requirement from
           :footcite:`SekiharaNagarajan2008` that ``w @ w.conj().T == I``,
           whereas ``'unit-noise-gain'`` has non-zero off-diagonals; but
        3. Does not satisfy the second requirement that ``w @ G.T = θI``,
           which arguably does not make sense for a rotation-invariant
           solution.
"""

docdict['window_psd'] = """\
window : str | float | tuple
    Windowing function to use. See :func:`scipy.signal.get_window`.
"""

docdict['window_resample'] = """
window : str | tuple
    Frequency-domain window to use in resampling.
    See :func:`scipy.signal.resample`.
"""

# %%
# X

docdict['xscale_plot_psd'] = """\
xscale : 'linear' | 'log'
    Scale of the frequency axis. Default is ``'linear'``.
"""

# %%
# Y

# %%
# Z

# this is needed in test_docstring_parameters, which reads the file as text
docdict['¿test—üñɪçøɖɘ_keys*'] = '¿test—üñɪçøɖɘ_values*'

docdict_indented = {}


def fill_doc(f):
    """Fill a docstring with docdict entries.

    Parameters
    ----------
    f : callable
        The function to fill the docstring of. Will be modified in place.

    Returns
    -------
    f : callable
        The function, potentially with an updated ``__doc__``.
    """
    docstring = f.__doc__
    if not docstring:
        return f
    lines = docstring.splitlines()
    # Find the minimum indent of the main docstring, after first line
    if len(lines) < 2:
        icount = 0
    else:
        icount = _indentcount_lines(lines[1:])
    # Insert this indent to dictionary docstrings
    try:
        indented = docdict_indented[icount]
    except KeyError:
        indent = ' ' * icount
        docdict_indented[icount] = indented = {}
        for name, dstr in docdict.items():
            lines = dstr.splitlines()
            try:
                newlines = [lines[0]]
                for line in lines[1:]:
                    newlines.append(indent + line)
                indented[name] = '\n'.join(newlines)
            except IndexError:
                indented[name] = dstr
    try:
        f.__doc__ = docstring % indented
    except (TypeError, ValueError, KeyError) as exp:
        funcname = f.__name__
        funcname = docstring.split('\n')[0] if funcname is None else funcname
        raise RuntimeError('Error documenting %s:\n%s'
                           % (funcname, str(exp)))
    return f


##############################################################################
# Utilities for docstring manipulation.

def copy_doc(source):
    """Copy the docstring from another function (decorator).

    The docstring of the source function is prepepended to the docstring of the
    function wrapped by this decorator.

    This is useful when inheriting from a class and overloading a method. This
    decorator can be used to copy the docstring of the original method.

    Parameters
    ----------
    source : function
        Function to copy the docstring from

    Returns
    -------
    wrapper : function
        The decorated function

    Examples
    --------
    >>> class A:
    ...     def m1():
    ...         '''Docstring for m1'''
    ...         pass
    >>> class B (A):
    ...     @copy_doc(A.m1)
    ...     def m1():
    ...         ''' this gets appended'''
    ...         pass
    >>> print(B.m1.__doc__)
    Docstring for m1 this gets appended
    """
    def wrapper(func):
        if source.__doc__ is None or len(source.__doc__) == 0:
            raise ValueError('Cannot copy docstring: docstring was empty.')
        doc = source.__doc__
        if func.__doc__ is not None:
            doc += func.__doc__
        func.__doc__ = doc
        return func
    return wrapper


def copy_function_doc_to_method_doc(source):
    """Use the docstring from a function as docstring for a method.

    The docstring of the source function is prepepended to the docstring of the
    function wrapped by this decorator. Additionally, the first parameter
    specified in the docstring of the source function is removed in the new
    docstring.

    This decorator is useful when implementing a method that just calls a
    function.  This pattern is prevalent in for example the plotting functions
    of MNE.

    Parameters
    ----------
    source : function
        Function to copy the docstring from.

    Returns
    -------
    wrapper : function
        The decorated method.

    Notes
    -----
    The parsing performed is very basic and will break easily on docstrings
    that are not formatted exactly according to the ``numpydoc`` standard.
    Always inspect the resulting docstring when using this decorator.

    Examples
    --------
    >>> def plot_function(object, a, b):
    ...     '''Docstring for plotting function.
    ...
    ...     Parameters
    ...     ----------
    ...     object : instance of object
    ...         The object to plot
    ...     a : int
    ...         Some parameter
    ...     b : int
    ...         Some parameter
    ...     '''
    ...     pass
    ...
    >>> class A:
    ...     @copy_function_doc_to_method_doc(plot_function)
    ...     def plot(self, a, b):
    ...         '''
    ...         Notes
    ...         -----
    ...         .. versionadded:: 0.13.0
    ...         '''
    ...         plot_function(self, a, b)
    >>> print(A.plot.__doc__)
    Docstring for plotting function.
    <BLANKLINE>
        Parameters
        ----------
        a : int
            Some parameter
        b : int
            Some parameter
    <BLANKLINE>
            Notes
            -----
            .. versionadded:: 0.13.0
    <BLANKLINE>
    """
    def wrapper(func):
        doc = source.__doc__.split('\n')
        if len(doc) == 1:
            doc = doc[0]
            if func.__doc__ is not None:
                doc += func.__doc__
            func.__doc__ = doc
            return func

        # Find parameter block
        for line, text in enumerate(doc[:-2]):
            if (text.strip() == 'Parameters' and
                    doc[line + 1].strip() == '----------'):
                parameter_block = line
                break
        else:
            # No parameter block found
            raise ValueError('Cannot copy function docstring: no parameter '
                             'block found. To simply copy the docstring, use '
                             'the @copy_doc decorator instead.')

        # Find first parameter
        for line, text in enumerate(doc[parameter_block:], parameter_block):
            if ':' in text:
                first_parameter = line
                parameter_indentation = len(text) - len(text.lstrip(' '))
                break
        else:
            raise ValueError('Cannot copy function docstring: no parameters '
                             'found. To simply copy the docstring, use the '
                             '@copy_doc decorator instead.')

        # Find end of first parameter
        for line, text in enumerate(doc[first_parameter + 1:],
                                    first_parameter + 1):
            # Ignore empty lines
            if len(text.strip()) == 0:
                continue

            line_indentation = len(text) - len(text.lstrip(' '))
            if line_indentation <= parameter_indentation:
                # Reach end of first parameter
                first_parameter_end = line

                # Of only one parameter is defined, remove the Parameters
                # heading as well
                if ':' not in text:
                    first_parameter = parameter_block

                break
        else:
            # End of docstring reached
            first_parameter_end = line
            first_parameter = parameter_block

        # Copy the docstring, but remove the first parameter
        doc = ('\n'.join(doc[:first_parameter]) + '\n' +
               '\n'.join(doc[first_parameter_end:]))
        if func.__doc__ is not None:
            doc += func.__doc__
        func.__doc__ = doc
        return func
    return wrapper


def copy_base_doc_to_subclass_doc(subclass):
    """Use the docstring from a parent class methods in derived class.

    The docstring of a parent class method is prepended to the
    docstring of the method of the class wrapped by this decorator.

    Parameters
    ----------
    subclass : wrapped class
        Class to copy the docstring to.

    Returns
    -------
    subclass : Derived class
        The decorated class with copied docstrings.
    """
    ancestors = subclass.mro()[1:-1]

    for source in ancestors:
        methodList = [method for method in dir(source)
                      if callable(getattr(source, method))]
        for method_name in methodList:
            # discard private methods
            if method_name[0] == '_':
                continue
            base_method = getattr(source, method_name)
            sub_method = getattr(subclass, method_name)
            if base_method is not None and sub_method is not None:
                doc = base_method.__doc__
                if sub_method.__doc__ is not None:
                    doc += '\n' + sub_method.__doc__
                sub_method.__doc__ = doc

    return subclass


def linkcode_resolve(domain, info):
    """Determine the URL corresponding to a Python object.

    Parameters
    ----------
    domain : str
        Only useful when 'py'.
    info : dict
        With keys "module" and "fullname".

    Returns
    -------
    url : str
        The code URL.

    Notes
    -----
    This has been adapted to deal with our "verbose" decorator.

    Adapted from SciPy (doc/source/conf.py).
    """
    import mne
    if domain != 'py':
        return None

    modname = info['module']
    fullname = info['fullname']

    submod = sys.modules.get(modname)
    if submod is None:
        return None

    obj = submod
    for part in fullname.split('.'):
        try:
            obj = getattr(obj, part)
        except Exception:
            return None
    # deal with our decorators properly
    while hasattr(obj, '__wrapped__'):
        obj = obj.__wrapped__

    try:
        fn = inspect.getsourcefile(obj)
    except Exception:
        fn = None
    if not fn:
        try:
            fn = inspect.getsourcefile(sys.modules[obj.__module__])
        except Exception:
            fn = None
    if not fn:
        return None
    fn = op.relpath(fn, start=op.dirname(mne.__file__))
    fn = '/'.join(op.normpath(fn).split(os.sep))  # in case on Windows

    try:
        source, lineno = inspect.getsourcelines(obj)
    except Exception:
        lineno = None

    if lineno:
        linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
    else:
        linespec = ""

    if 'dev' in mne.__version__:
        kind = 'main'
    else:
        kind = 'maint/%s' % ('.'.join(mne.__version__.split('.')[:2]))
    return "http://github.com/mne-tools/mne-python/blob/%s/mne/%s%s" % (
        kind, fn, linespec)


def open_docs(kind=None, version=None):
    """Launch a new web browser tab with the MNE documentation.

    Parameters
    ----------
    kind : str | None
        Can be "api" (default), "tutorials", or "examples".
        The default can be changed by setting the configuration value
        MNE_DOCS_KIND.
    version : str | None
        Can be "stable" (default) or "dev".
        The default can be changed by setting the configuration value
        MNE_DOCS_VERSION.
    """
    from .check import _check_option
    from .config import get_config
    if kind is None:
        kind = get_config('MNE_DOCS_KIND', 'api')
    help_dict = dict(api='python_reference.html', tutorials='tutorials.html',
                     examples='auto_examples/index.html')
    _check_option('kind', kind, sorted(help_dict.keys()))
    kind = help_dict[kind]
    if version is None:
        version = get_config('MNE_DOCS_VERSION', 'stable')
    _check_option('version', version, ['stable', 'dev'])
    webbrowser.open_new_tab('https://mne.tools/%s/%s' % (version, kind))


class _decorator:
    """Inject code or modify the docstring of a class, method, or function."""

    def __init__(self, extra):  # noqa: D102
        self.kind = self.__class__.__name__
        self.extra = extra
        self.msg = f'NOTE: {{}}() is a {self.kind} {{}}. {self.extra}.'

    def __call__(self, obj):  # noqa: D105
        """Call.

        Parameters
        ----------
        obj : object
            Object to call.

        Returns
        -------
        obj : object
            The modified object.
        """
        if inspect.isclass(obj):
            obj_type = 'class'
        else:
            # NB: detecting (bound and unbound) methods seems to be impossible
            assert inspect.isfunction(obj), f'decorator used on {type(obj)}'
            obj_type = 'function'
        msg = self.msg.format(obj.__name__, obj_type)
        if obj_type == 'class':
            obj.__init__ = self._make_fun(obj.__init__, msg)
            return obj
        return self._make_fun(obj, msg)

    def _make_fun(self, func, body):
        evaldict = dict(_function_=func)
        fm = FunctionMaker(
            func, None, None, None, None, func.__module__)
        attrs = dict(__wrapped__=func, __qualname__=func.__qualname__,
                     __globals__=func.__globals__)
        dep = fm.make(body, evaldict, addsource=True, **attrs)
        dep.__doc__ = self._update_doc(dep.__doc__)
        dep._deprecated_original = func
        return dep

    def _update_doc(self, olddoc):
        newdoc = f".. warning:: {self.kind.upper()}"
        if self.extra:
            newdoc = f'{newdoc}: {self.extra}'
        newdoc += '.'
        if olddoc:
            # Get the spacing right to avoid sphinx warnings
            n_space = 4
            for li, line in enumerate(olddoc.split('\n')):
                if li > 0 and len(line.strip()):
                    n_space = len(line) - len(line.lstrip())
                    break
            newdoc = f"{newdoc}\n\n{' ' * n_space}{olddoc}"
        return newdoc


# Following deprecated class copied from scikit-learn
class deprecated(_decorator):
    """Mark a function, class, or method as deprecated (decorator).

    Originally adapted from sklearn and
    http://wiki.python.org/moin/PythonDecoratorLibrary, then modified to make
    arguments populate properly following our verbose decorator methods based
    on decorator.

    Parameters
    ----------
    extra : str
        Extra information beyond just saying the class/function/method is
        deprecated. Should be a complete sentence (trailing period will be
        added automatically). Will be included in FutureWarning messages
        and in a sphinx warning box in the docstring.
    """

    def _make_fun(self, func, msg):
        body = f"""\
def %(name)s(%(signature)s):\n
    import warnings
    warnings.warn({repr(msg)}, category=FutureWarning)
    return _function_(%(shortsignature)s)"""
        return super()._make_fun(func=func, body=body)


def deprecated_alias(dep_name, func, removed_in=None):
    """Inject a deprecated alias into the namespace."""
    if removed_in is None:
        from .._version import __version__
        removed_in = __version__.split('.')[:2]
        removed_in[1] = str(int(removed_in[1]) + 1)
        removed_in = '.'.join(removed_in)
    # Inject a deprecated version into the namespace
    inspect.currentframe().f_back.f_globals[dep_name] = deprecated(
        f'{dep_name} has been deprecated in favor of {func.__name__} and will '
        f'be removed in {removed_in}.'
    )(deepcopy(func))


###############################################################################
# "legacy" decorator for parts of our API retained only for backward compat

class legacy(_decorator):
    """Mark a function, class, or method as legacy (decorator).

    Parameters
    ----------
    alt : str
        Description of the alternate, preferred way to achieve a comparable
        result.
    extra : str
        Extra information beyond just saying the class/function/method is
        legacy. Should be a complete sentence (trailing period will be
        added automatically). Will be included in logger.info messages
        and in a sphinx warning box in the docstring.
    """

    def __init__(self, alt, extra=''):  # noqa: D102
        period = '. ' if len(extra) else ''
        extra = f'New code should use {alt}{period}{extra}'
        super().__init__(extra=extra)

    def _make_fun(self, func, msg):
        body = f"""\
def %(name)s(%(signature)s):\n
    from mne.utils import logger
    logger.info({repr(msg)})
    return _function_(%(shortsignature)s)"""
        return super()._make_fun(func=func, body=body)

###############################################################################
# The following tools were adapted (mostly trimmed) from SciPy's doccer.py


def _docformat(docstring, docdict=None, funcname=None):
    """Fill a function docstring from variables in dictionary.

    Adapt the indent of the inserted docs

    Parameters
    ----------
    docstring : string
        docstring from function, possibly with dict formatting strings
    docdict : dict, optional
        dictionary with keys that match the dict formatting strings
        and values that are docstring fragments to be inserted.  The
        indentation of the inserted docstrings is set to match the
        minimum indentation of the ``docstring`` by adding this
        indentation to all lines of the inserted string, except the
        first

    Returns
    -------
    outstring : string
        string with requested ``docdict`` strings inserted
    """
    if not docstring:
        return docstring
    if docdict is None:
        docdict = {}
    if not docdict:
        return docstring
    lines = docstring.expandtabs().splitlines()
    # Find the minimum indent of the main docstring, after first line
    if len(lines) < 2:
        icount = 0
    else:
        icount = _indentcount_lines(lines[1:])
    indent = ' ' * icount
    # Insert this indent to dictionary docstrings
    indented = {}
    for name, dstr in docdict.items():
        lines = dstr.expandtabs().splitlines()
        try:
            newlines = [lines[0]]
            for line in lines[1:]:
                newlines.append(indent + line)
            indented[name] = '\n'.join(newlines)
        except IndexError:
            indented[name] = dstr
    funcname = docstring.split('\n')[0] if funcname is None else funcname
    try:
        return docstring % indented
    except (TypeError, ValueError, KeyError) as exp:
        raise RuntimeError('Error documenting %s:\n%s'
                           % (funcname, str(exp)))


def _indentcount_lines(lines):
    """Compute minimum indent for all lines in line list."""
    indentno = sys.maxsize
    for line in lines:
        stripped = line.lstrip()
        if stripped:
            indentno = min(indentno, len(line) - len(stripped))
    if indentno == sys.maxsize:
        return 0
    return indentno