Spaces:
Running
Running
| """The documentation functions.""" | |
| # Authors: The MNE-Python contributors. | |
| # License: BSD-3-Clause | |
| # Copyright the MNE-Python contributors. | |
| 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 | |
| # # # WARNING # # # | |
| # This list must also be updated in doc/_templates/autosummary/class.rst if it | |
| # is changed here! | |
| _doc_special_members = ( | |
| "__contains__", | |
| "__getitem__", | |
| "__iter__", | |
| "__len__", | |
| "__add__", | |
| "__sub__", | |
| "__mul__", | |
| "__div__", | |
| "__neg__", | |
| ) | |
| 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(rf".{{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 | |
| tfr_arithmetics_return_template = """ | |
| Returns | |
| ------- | |
| tfr : instance of RawTFR | instance of EpochsTFR | instance of AverageTFR | |
| {} | |
| """ | |
| tfr_add_sub_template = """ | |
| Parameters | |
| ---------- | |
| other : instance of RawTFR | instance of EpochsTFR | instance of AverageTFR | |
| The TFR instance to {}. Must have the same type as ``self``, and matching | |
| ``.times`` and ``.freqs`` attributes. | |
| {} | |
| """ | |
| tfr_mul_truediv_template = """ | |
| Parameters | |
| ---------- | |
| num : int | float | |
| The number to {} by. | |
| {} | |
| """ | |
| tfr_arithmetics_return = tfr_arithmetics_return_template.format( | |
| "A new TFR instance, of the same type as ``self``." | |
| ) | |
| tfr_inplace_arithmetics_return = tfr_arithmetics_return_template.format( | |
| "The modified TFR instance." | |
| ) | |
| docdict["__add__tfr"] = tfr_add_sub_template.format("add", tfr_arithmetics_return) | |
| docdict["__iadd__tfr"] = tfr_add_sub_template.format( | |
| "add", tfr_inplace_arithmetics_return | |
| ) | |
| docdict["__imul__tfr"] = tfr_mul_truediv_template.format( | |
| "multiply", tfr_inplace_arithmetics_return | |
| ) | |
| docdict["__isub__tfr"] = tfr_add_sub_template.format( | |
| "subtract", tfr_inplace_arithmetics_return | |
| ) | |
| docdict["__itruediv__tfr"] = tfr_mul_truediv_template.format( | |
| "divide", tfr_inplace_arithmetics_return | |
| ) | |
| docdict["__mul__tfr"] = tfr_mul_truediv_template.format( | |
| "multiply", tfr_arithmetics_return | |
| ) | |
| docdict["__sub__tfr"] = tfr_add_sub_template.format("subtract", tfr_arithmetics_return) | |
| docdict["__truediv__tfr"] = tfr_mul_truediv_template.format( | |
| "divide", tfr_arithmetics_return | |
| ) | |
| 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 | |
| (i.e. sensor space data), see :func:`mne.channels.find_ch_adjacency` or | |
| :func:`mne.spatial_inter_hemi_adjacency`. For source space data, see | |
| :func:`mne.spatial_src_adjacency` or | |
| :func:`mne.spatio_temporal_src_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_2d"] = """ | |
| allow_2d : bool | |
| If True, allow 2D data as input (i.e. n_samples, n_features). | |
| """ | |
| 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 {applies_to} defined in ``picks``. | |
| The {data_type} 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 {applies_to} in | |
| ``picks``).{preload} | |
| .. 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( | |
| applies_to="channels", data_type="epochs", preload=applyfun_preload | |
| ) | |
| docdict["applyfun_summary_evoked"] = applyfun_summary.format( | |
| applies_to="channels", data_type="evoked", preload="" | |
| ) | |
| docdict["applyfun_summary_raw"] = applyfun_summary.format( | |
| applies_to="channels", data_type="raw", preload=applyfun_preload | |
| ) | |
| docdict["applyfun_summary_stc"] = applyfun_summary.format( | |
| applies_to="vertices", data_type="source estimate", 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 ``auto`` uses ``aparc+aseg`` | |
| if available and ``wmparc`` if not. This may be any anatomical | |
| segmentation file in the mri subdirectory of the Freesurfer subject | |
| directory. | |
| .. versionchanged:: 1.8 | |
| Added support for the new default ``'auto'``. | |
| """ | |
| 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 = """\ | |
| {param} : instance of Axes | {allowed}None | |
| The axes to plot into. If ``None``, a new :class:`~matplotlib.figure.Figure` | |
| will be created{created}. {list_extra}{extra}Default is ``None``. | |
| """ | |
| _axes_list = _axes_base.format( | |
| param="{param}", | |
| allowed="list of Axes | ", | |
| created=" with the correct number of axes", | |
| list_extra="""If :class:`~matplotlib.axes.Axes` | |
| are provided (either as a single instance or a :class:`list` of axes), | |
| the number of axes provided must {must}. """, | |
| extra="{extra}", | |
| ) | |
| _match_chtypes_present_in = "match the number of channel types present in the {}object." | |
| docdict["ax_plot_psd"] = _axes_list.format( | |
| param="ax", must=_match_chtypes_present_in.format(""), extra="" | |
| ) | |
| docdict["axes_cov_plot_topomap"] = _axes_list.format( | |
| param="axes", must="be length 1", extra="" | |
| ) | |
| docdict["axes_evoked_plot_topomap"] = _axes_list.format( | |
| param="axes", | |
| must="match the number of ``times`` provided (unless ``times`` is ``None``)", | |
| extra="", | |
| ) | |
| docdict["axes_montage"] = """ | |
| axes : instance of Axes | instance of Axes3D | None | |
| Axes to draw the sensors to. If ``kind='3d'``, axes must be an instance | |
| of Axes3D. If None (default), a new axes will be created. | |
| """ | |
| docdict["axes_plot_projs_topomap"] = _axes_list.format( | |
| param="axes", | |
| must="match the number of projectors", | |
| extra="", | |
| ) | |
| docdict["axes_plot_topomap"] = _axes_base.format( | |
| param="axes", | |
| allowed="", | |
| created="", | |
| list_extra="", | |
| extra="", | |
| ) | |
| docdict["axes_spectrum_plot"] = _axes_list.format( | |
| param="axes", | |
| must=_match_chtypes_present_in.format(":class:`~mne.time_frequency.Spectrum` "), | |
| extra="", | |
| ) | |
| docdict["axes_spectrum_plot_topo"] = _axes_list.format( | |
| param="axes", | |
| must="be length 1 (for efficiency, subplots for each channel are simulated " | |
| "within a single :class:`~matplotlib.axes.Axes` object)", | |
| extra="", | |
| ) | |
| docdict["axes_spectrum_plot_topomap"] = _axes_list.format( | |
| param="axes", must="match the length of ``bands``", extra="" | |
| ) | |
| docdict["axes_tfr_plot"] = _axes_list.format( | |
| param="axes", | |
| must="match the number of picks", | |
| extra="""If ``combine`` is not None, | |
| ``axes`` must either be an instance of Axes, or a list of length 1. """, | |
| ) | |
| 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 data. | |
| 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["baseline_tfr_attr"] = """ | |
| baseline : array-like, shape (2,) | |
| The start and end times of the baseline period, in seconds.""" | |
| 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_topo"] = """ | |
| border : str | |
| Matplotlib border style to be used for each sensor plot. | |
| """ | |
| 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. | |
| """ | |
| docdict["brain_kwargs"] = """ | |
| brain_kwargs : dict | None | |
| Additional arguments to the :class:`mne.viz.Brain` constructor (e.g., | |
| ``dict(silhouette=True)``). | |
| """ | |
| docdict["brain_update"] = """ | |
| update : bool | |
| Force an update of the plot. Defaults to 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_names_tfr_attr"] = """ | |
| ch_names : list | |
| The channel names.""" | |
| 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. | |
| """ | |
| _cmap_template = """ | |
| cmap : matplotlib colormap | str{allowed} | |
| The :class:`~matplotlib.colors.Colormap` to use. If a :class:`str`, must be a | |
| valid Matplotlib colormap name. Default is {default}. | |
| """ | |
| docdict["cmap"] = _cmap_template.format( | |
| allowed=" | None", | |
| default="``None``, which will use the Matplotlib default colormap", | |
| ) | |
| docdict["cmap_tfr_plot_topo"] = _cmap_template.format( | |
| allowed="", default='``"RdBu_r"``' | |
| ) | |
| 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 :ref:`Matplotlib docs <matplotlib: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"] = """\ | |
| colorbar : bool | |
| Whether to add a colorbar to the plot. Default is ``True``. | |
| """ | |
| docdict["colorbar_tfr_plot_joint"] = """ | |
| colorbar : bool | |
| Whether to add a colorbar to the plot (for the topomap annotations). Not compatible | |
| with user-defined ``axes``. Default is ``True``. | |
| """ | |
| 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. | |
| """ | |
| _combine_template = """ | |
| combine : 'mean' | {literals} | callable{none} | |
| How to aggregate across channels. {none_sentence}If a string, | |
| ``"mean"`` uses :func:`numpy.mean`, {other_string}. | |
| If :func:`callable`, it must operate on an :class:`array <numpy.ndarray>` | |
| of shape ``({shape})`` and return an array of shape | |
| ``({return_shape})``. {example}{notes}Defaults to {default}. | |
| """ | |
| _example = """For example:: | |
| combine = lambda data: np.median(data, axis=1) | |
| """ # ← the 4 trailing spaces are intentional here! | |
| _median_std_gfp = """``"median"`` computes the `marginal median | |
| <https://en.wikipedia.org/wiki/Median#Marginal_median>`__, ``"std"`` | |
| uses :func:`numpy.std`, and ``"gfp"`` computes global field power | |
| for EEG channels and RMS amplitude for MEG channels""" | |
| _none_default = dict(none=" | None", default="``None``") | |
| docdict["combine_plot_compare_evokeds"] = _combine_template.format( | |
| literals="'median' | 'std' | 'gfp'", | |
| **_none_default, | |
| none_sentence="""If ``None``, channels are combined by | |
| computing GFP/RMS, unless ``picks`` is a single channel (not channel type) | |
| or ``axes="topo"``, in which cases no combining is performed. """, | |
| other_string=_median_std_gfp, | |
| shape="n_evokeds, n_channels, n_times", | |
| return_shape="n_evokeds, n_times", | |
| example=_example, | |
| notes="", | |
| ) | |
| docdict["combine_plot_epochs_image"] = _combine_template.format( | |
| literals="'median' | 'std' | 'gfp'", | |
| **_none_default, | |
| none_sentence="""If ``None``, channels are combined by | |
| computing GFP/RMS, unless ``group_by`` is also ``None`` and ``picks`` is a | |
| list of specific channels (not channel types), in which case no combining | |
| is performed and each channel gets its own figure. """, | |
| other_string=_median_std_gfp, | |
| shape="n_epochs, n_channels, n_times", | |
| return_shape="n_epochs, n_times", | |
| example=_example, | |
| notes="See Notes for further details. ", | |
| ) | |
| docdict["combine_tfr_plot"] = _combine_template.format( | |
| literals="'rms'", | |
| **_none_default, | |
| none_sentence="If ``None``, plot one figure per selected channel. ", | |
| shape="n_channels, n_freqs, n_times", | |
| return_shape="n_freqs, n_times", | |
| other_string='``"rms"`` computes the root-mean-square', | |
| example="", | |
| notes="", | |
| ) | |
| docdict["combine_tfr_plot_joint"] = _combine_template.format( | |
| literals="'rms'", | |
| none="", | |
| none_sentence="", | |
| shape="n_channels, n_freqs, n_times", | |
| return_shape="n_freqs, n_times", | |
| other_string='``"rms"`` computes the root-mean-square', | |
| example="", | |
| notes="", | |
| default='``"mean"``', | |
| ) | |
| _comment_template = """ | |
| comment : str{or_none} | |
| Comment on the data, e.g., the experimental condition(s){avgd}.{extra}""" | |
| docdict["comment_averagetfr"] = _comment_template.format( | |
| or_none=" | None", | |
| avgd="averaged", | |
| extra="""Default is ``None`` | |
| which is replaced with ``inst.comment`` (for :class:`~mne.Evoked` instances) | |
| or a comma-separated string representation of the keys in ``inst.event_id`` | |
| (for :class:`~mne.Epochs` instances).""", | |
| ) | |
| docdict["comment_averagetfr_attr"] = _comment_template.format( | |
| or_none="", avgd=" averaged", extra="" | |
| ) | |
| docdict["comment_tfr_attr"] = _comment_template.format(or_none="", avgd="", extra="") | |
| 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 scale. If ``True``, plots | |
| 10 × log₁₀({quantity}){ampl}{caveat}.{extra} | |
| """ | |
| _psd = "spectral_power/Hz" | |
| # for the legacy func/methods: | |
| docdict["dB_plot_psd"] = """\ | |
| dB : bool | |
| Plot power spectral density (PSD) in units (dB/Hz) if ``dB=True`` and | |
| ``estimate='power'``. 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'``. | |
| Plot ASD in units (dB/sqrt(Hz)) if ``dB=True`` and ``estimate='amplitude'``. | |
| """ | |
| docdict["dB_plot_topomap"] = _dB.format( | |
| quantity=_psd, | |
| ampl="", | |
| caveat=", following the application of ``agg_fun``", | |
| extra=" Ignored if ``normalize=True``.", | |
| ) | |
| docdict["dB_spectrum_plot"] = _dB.format( | |
| quantity=_psd, | |
| ampl=", or 20 × log₁₀(spectral amplitude/√Hz) if ``amplitude=True``", | |
| caveat="", | |
| extra="", | |
| ) | |
| docdict["dB_spectrum_plot_topo"] = _dB.format( | |
| quantity=_psd, ampl="", caveat="", extra="" | |
| ) | |
| docdict["dB_tfr_plot"] = _dB.format(quantity="data", ampl="", caveat="", extra="") | |
| _data_template = """ | |
| data : ndarray, shape ({}) | |
| The data. | |
| """ | |
| docdict["data_tfr"] = _data_template.format("n_channels, n_freqs, n_times") | |
| 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. | |
| See :ref:`resampling-and-decimating` for more information. | |
| """ | |
| 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 | |
| Decimation factor, applied *after* time-frequency decomposition. | |
| - if :class:`int`, returns ``tfr[..., ::decim]`` (keep only every Nth | |
| sample along the time axis). | |
| - if :class:`slice`, returns ``tfr[..., decim]`` (keep only the specified | |
| slice along the time axis). | |
| .. 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 : path-like | array-like, shape (3,) | instance of Transform | None | |
| The destination location for the head. Can be: | |
| ``None`` | |
| Will not change the head position. | |
| :class:`~mne.transforms.Transform` | |
| A MEG device<->head transformation, e.g. ``info["dev_head_t"]``. | |
| :class:`numpy.ndarray` | |
| 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). | |
| ``path-like`` | |
| A path to a FIF file containing the destination MEG device<->head transformation. | |
| """ | |
| 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 | "auto" | None | |
| The distance from the camera rendering the view to the focalpoint | |
| in plot units (either m or mm). If "auto", the bounds of visible objects will be | |
| used to set a reasonable distance. | |
| .. versionchanged:: 1.6 | |
| ``None`` will no longer change the distance, use ``"auto"`` instead. | |
| """ | |
| 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["edf_resamp_note"] = """ | |
| :class:`mne.io.Raw` only stores signals with matching sampling frequencies. | |
| Therefore, if mixed sampling frequency signals are requested, all signals | |
| are upsampled to the highest loaded sampling frequency. In this case, using | |
| preload=True is recommended, as otherwise, edge artifacts appear when | |
| slices of the signal are requested. | |
| """ | |
| docdict["eeg"] = """ | |
| eeg : bool | str | list | dict | |
| 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 a dict to specify the alpha values | |
| to use, e.g. ``dict(original=0.2, projected=0.8)``. | |
| .. versionchanged:: 1.6 | |
| Added support for specifying alpha values as a dict. | |
| """ | |
| 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 absolute 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 90° 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. | |
| - ``None`` | |
| No aggregation is performed, and an array of shape ``(n_vertices, n_times)`` is | |
| returned. | |
| .. 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["encoding_nihon"] = """ | |
| encoding : str | |
| Text encoding of Nihon Kohden annotations. See :ref:`standard-encodings`. | |
| """ | |
| docdict["encoding_nirx"] = """ | |
| encoding : str | |
| Text encoding of the NIRX header file. See :ref:`standard-encodings`. | |
| """ | |
| 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["equalize_events_method"] = """ | |
| method : ``'truncate'`` | ``'mintime'`` | ``'random'`` | |
| If ``'truncate'``, events will be truncated from the end of each event | |
| list. If ``'mintime'``, timing differences between each event list will be | |
| minimized. If ``'random'``, events will be randomly selected from each event | |
| list. | |
| .. versionadded:: 1.8 | |
| """ | |
| docdict["estimate_plot_psd"] = """\ | |
| estimate : str, {'power', 'amplitude'} | |
| Can be "power" for power spectral density (PSD; default), "amplitude" for | |
| amplitude spectrum density (ASD). | |
| """ | |
| 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 | str | list of str | 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 of int, all :term:`events` with the IDs specified in the list | |
| are used. If a str or list of str, ``events`` must be ``None`` to use annotations | |
| and then the IDs must be the name(s) of the annotations to use. | |
| If None, all :term:`events` will be used and a dict is created | |
| with string integer names corresponding to the event id integers.""" | |
| _event_id_template = """ | |
| event_id : dict{or_none} | |
| Mapping from condition descriptions (strings) to integer event codes.{extra}""" | |
| docdict["event_id_attr"] = _event_id_template.format(or_none="", extra="") | |
| docdict["event_id_ecg"] = """ | |
| event_id : int | |
| The index to assign to found ECG events. | |
| """ | |
| docdict["event_id_epochstfr"] = _event_id_template.format( | |
| or_none=" | None", | |
| extra="""If ``None``, | |
| all events in ``events`` will be included, and the ``event_id`` attribute | |
| will be a :class:`dict` mapping a string version of each integer event ID | |
| to the corresponding integer.""", | |
| ) | |
| 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 | |
| """ | |
| _events_template = """ | |
| events : ndarray of int, shape (n_events, 3){or_none} | |
| The identity and timing of experimental events, around which the epochs were | |
| created. See :term:`events` for more information.{extra} | |
| """ | |
| docdict["events"] = _events_template.format(or_none="", extra="") | |
| docdict["events_attr"] = """ | |
| events : ndarray of int, shape (n_events, 3) | |
| The events array.""" | |
| docdict["events_epochs"] = _events_template.format( | |
| or_none="", | |
| extra="""Events that don't match | |
| the events of interest as specified by ``event_id`` will be marked as | |
| ``IGNORED`` in the drop log.""", | |
| ) | |
| docdict["events_epochstfr"] = _events_template.format( | |
| or_none=" | None", | |
| extra="""If ``None``, all integer | |
| event codes are set to ``1`` (i.e., all epochs are assumed to be of the same | |
| type) and their corresponding sample numbers are set as arbitrary, equally | |
| spaced sample numbers with a step size of ``len(times)``.""", | |
| ) | |
| 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["evoked_ylim_plot"] = """ | |
| ylim : dict | None | |
| Y-axis limits for plots (after scaling has been applied). :class:`dict` | |
| keys should match channel types; valid keys are for instance ``eeg``, ``mag``, | |
| ``grad``, ``misc``, ``csd``, .. (example: ``ylim=dict(eeg=[-20, 20])``). If | |
| ``None``, the y-axis limits will be set automatically by matplotlib. Defaults to | |
| ``None``.""" | |
| docdict["exclude_after_unique"] = """ | |
| exclude_after_unique : bool | |
| If True, exclude channels are searched for after they have been made | |
| unique. This is useful to choose channels that have been made unique | |
| by adding a suffix. If False, the original names are checked. | |
| .. versionchanged:: 1.7 | |
| """ | |
| 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 ``{}info['bads']`` are excluded; pass an empty list to | |
| include all channels (including "bad" channels, if any). | |
| """ | |
| docdict["exclude_psd"] = _exclude_spectrum.format("", "") | |
| docdict["exclude_spectrum_get_data"] = _exclude_spectrum.format("", "spectrum.") | |
| docdict["exclude_spectrum_plot"] = _exclude_spectrum.format( | |
| " from being drawn", "spectrum." | |
| ) | |
| docdict["export_edf_note"] = """ | |
| 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 :meth:`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 :meth:`mne.io.Raw.set_montage`. | |
| The physical range of the signals is determined by signal type by default | |
| (``physical_range="auto"``). However, if individual channel ranges vary significantly | |
| due to the presence of e.g. drifts/offsets/biases, setting | |
| ``physical_range="channelwise"`` might be more appropriate. This will ensure a maximum | |
| resolution for each individual channel, but some tools might not be able to handle this | |
| appropriately (even though channel-wise ranges are covered by the EDF standard). | |
| """ | |
| 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"] = f""" | |
| fmt : 'auto' | 'eeglab' | |
| {_export_fmt_params_base} | |
| """ | |
| docdict["export_fmt_params_evoked"] = f""" | |
| fmt : 'auto' | 'mff' | |
| {_export_fmt_params_base} | |
| """ | |
| docdict["export_fmt_params_raw"] = f""" | |
| fmt : 'auto' | 'brainvision' | 'edf' | 'eeglab' | |
| {_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 `edfio <https://github.com/the-siesta-group/edfio>`_) | |
| """ # 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. | |
| """ | |
| docdict["eyelink_apply_offsets"] = """ | |
| apply_offsets : bool (default False) | |
| Adjusts the onset time of the :class:`~mne.Annotations` created from Eyelink | |
| experiment messages, if offset values exist in the ASCII file. If False, any | |
| offset-like values will be prepended to the annotation description. | |
| """ | |
| docdict["eyelink_create_annotations"] = """ | |
| create_annotations : bool | list (default True) | |
| Whether to create :class:`~mne.Annotations` from occular events | |
| (blinks, fixations, saccades) and experiment messages. If a list, must | |
| contain one or more of ``['fixations', 'saccades',' blinks', messages']``. | |
| If True, creates :class:`~mne.Annotations` for both occular events and | |
| experiment messages. | |
| """ | |
| docdict["eyelink_find_overlaps"] = """ | |
| find_overlaps : bool (default False) | |
| Combine left and right eye :class:`mne.Annotations` (blinks, fixations, | |
| saccades) if their start times and their stop times are both not | |
| separated by more than overlap_threshold. | |
| """ | |
| docdict["eyelink_fname"] = """ | |
| fname : path-like | |
| Path to the eyelink file (``.asc``).""" | |
| docdict["eyelink_overlap_threshold"] = """ | |
| overlap_threshold : float (default 0.05) | |
| Time in seconds. Threshold of allowable time-gap between both the start and | |
| stop times of the left and right eyes. If the gap is larger than the threshold, | |
| the :class:`mne.Annotations` will be kept separate (i.e. ``"blink_L"``, | |
| ``"blink_R"``). If the gap is smaller than the threshold, the | |
| :class:`mne.Annotations` will be merged and labeled as ``"blink_both"``. | |
| Defaults to ``0.05`` seconds (50 ms), meaning that if the blink start times of | |
| the left and right eyes are separated by less than 50 ms, and the blink stop | |
| times of the left and right eyes are separated by less than 50 ms, then the | |
| blink will be merged into a single :class:`mne.Annotations`. | |
| """ | |
| # %% | |
| # 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_background"] = """ | |
| fig_background : None | array | |
| A background image for the figure. This must be a valid input to | |
| :func:`matplotlib.pyplot.imshow`. Defaults to ``None``. | |
| """ | |
| 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"] = """ | |
| flat : dict | str | None | |
| Reject epochs based on **minimum** peak-to-peak signal amplitude (PTP) | |
| or a custom function. Valid **keys** can be any channel type present | |
| in the object. If using PTP, **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. If a custom function is used than ``flat`` can be | |
| used to reject epochs based on any criteria (including maxima and | |
| minima). | |
| 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_fmax_tfr"] = _fmin_fmax.format( | |
| """``None`` | |
| which is equivalent to ``fmin=0, fmax=np.inf`` (spans all frequencies | |
| present in the data).""" | |
| ) | |
| 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["fname_fwd"] = """ | |
| fname : path-like | |
| File name to save the forward solution to. It should end with | |
| ``-fwd.fif`` or ``-fwd.fif.gz`` to save to FIF, or ``-fwd.h5`` to save to | |
| HDF5. | |
| """ | |
| docdict["fnirs"] = """ | |
| fnirs : str | list | dict | 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',)``. A dict can also be used to specify | |
| alpha values (but only "channels" and "pairs" will be used), e.g. | |
| ``dict(channels=0.2, pairs=0.7)``. | |
| .. versionchanged:: 1.6 | |
| Added support for specifying alpha values as a dict. | |
| """ | |
| docdict["focalpoint"] = """ | |
| focalpoint : tuple, shape (3,) | str | None | |
| The focal point of the camera rendering the view: (x, y, z) in | |
| plot units (either m or mm). When ``"auto"``, it is set to the center of | |
| mass of the visible bounds. | |
| """ | |
| docdict["font_color"] = """ | |
| font_color : color | |
| The color of tick labels in the colorbar. Defaults to white. | |
| """ | |
| docdict["forward_set_eeg_reference"] = """ | |
| forward : instance of Forward | None | |
| Forward solution to use. Only used with ``ref_channels='REST'``. | |
| .. versionadded:: 0.21 | |
| """ | |
| _freqs_tfr_template = """ | |
| freqs : array-like |{auto} None | |
| The frequencies at which to compute the power estimates. | |
| {stockwell} be an array of shape (n_freqs,). ``None`` (the | |
| default) only works when using ``__setstate__`` and will raise an error otherwise. | |
| """ | |
| docdict["freqs_tfr"] = _freqs_tfr_template.format(auto="", stockwell="Must") | |
| docdict["freqs_tfr_array"] = """ | |
| freqs : ndarray, shape (n_freqs,) | |
| The frequencies in Hz. | |
| """ | |
| docdict["freqs_tfr_attr"] = """ | |
| freqs : array | |
| Frequencies at which power has been computed.""" | |
| docdict["freqs_tfr_epochs"] = _freqs_tfr_template.format( | |
| auto=" 'auto' | ", | |
| stockwell="""If ``method='stockwell'`` this must be a length 2 iterable specifying lowest | |
| and highest frequencies, or ``'auto'`` (to use all available frequencies). | |
| For other methods, must""", # noqa E501 | |
| ) | |
| 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. | |
| .. note:: | |
| If ``channel_wise=True``, one can optionally access the index and/or the | |
| name of the currently processed channel within the applied function. | |
| This can enable tailored computations for different channels. | |
| To use this feature, add ``ch_idx`` and/or ``ch_name`` as | |
| additional argument(s) to your function definition. | |
| """ | |
| 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["fun_applyfun_stc"] = applyfun_fun_base.format( | |
| " because it will apply vertex-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""" | |
| Convolution of a signal with a Morlet wavelet will impose temporal smoothing | |
| that is determined by the duration of the wavelet. In MNE-Python, the duration | |
| of the wavelet is determined by the ``sigma`` parameter, which gives the | |
| standard deviation of the wavelet's Gaussian envelope (our wavelets extend to | |
| ±5 standard deviations to ensure values very close to zero at the endpoints). | |
| Some authors (e.g., :footcite:t:`Cohen2019`) recommend specifying and reporting | |
| wavelet duration in terms of the full-width half-maximum (FWHM) of the | |
| wavelet's Gaussian envelope. The FWHM is related to ``sigma`` by the following | |
| identity: :math:`\mathrm{FWHM} = \sigma \times 2 \sqrt{2 \ln{2}}` (or the | |
| equivalent in Python code: ``fwhm = sigma * 2 * np.sqrt(2 * np.log(2))``). | |
| If ``sigma`` is not provided, it is computed from ``n_cycles`` as | |
| :math:`\frac{\mathtt{n\_cycles}}{2 \pi f}` where :math:`f` is the frequency of | |
| the wavelet oscillation (given by ``freqs``). Thus when ``sigma=None`` the FWHM | |
| will be given by | |
| .. math:: | |
| \mathrm{FWHM} = \frac{\mathtt{n\_cycles} \times \sqrt{2 \ln{2}}}{\pi \times f} | |
| (cf. eq. 4 in :footcite:`Cohen2019`). To create wavelets with a chosen FWHM, | |
| one can compute:: | |
| n_cycles = desired_fwhm * np.pi * np.array(freqs) / np.sqrt(2 * np.log(2)) | |
| to get an array of values for ``n_cycles`` that yield the desired FWHM at each | |
| frequency in ``freqs``. If you want different FWHM values at each frequency, | |
| do the same computation with ``desired_fwhm`` as an array of the same shape as | |
| ``freqs``. | |
| """ | |
| # %% | |
| # 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_spectrum_base = """ | |
| data : ndarray | |
| The selected spectral data. Shape will be | |
| ``({n_epo}n_channels, n_freqs)`` for normal power spectra, | |
| ``({n_epo}n_channels, n_freqs, n_segments)`` for unaggregated | |
| Welch estimates, or ``({n_epo}n_channels, n_tapers, n_freqs)`` | |
| for unaggregated multitaper estimates. | |
| """ | |
| _getitem_tfr_base = """ | |
| data : ndarray | |
| The selected time-frequency data. Shape will be | |
| ``({n_epo}n_channels, n_freqs, n_times)`` for Morlet, Stockwell, and aggregated | |
| (``output='power'``) multitaper methods, or | |
| ``({n_epo}n_channels, n_tapers, n_freqs, n_times)`` for unaggregated | |
| (``output='complex'``) multitaper method. | |
| """ | |
| n_epo = "n_epochs, " | |
| docdict["getitem_epochspectrum_return"] = _getitem_spectrum_base.format(n_epo=n_epo) | |
| docdict["getitem_epochstfr_return"] = _getitem_tfr_base.format(n_epo=n_epo) | |
| docdict["getitem_spectrum_return"] = _getitem_spectrum_base.format(n_epo="") | |
| docdict["getitem_tfr_return"] = _getitem_tfr_base.format(n_epo="") | |
| 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 | path-like | dict | tuple | array | |
| Path to 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["helmet_upsampling"] = """ | |
| upsampling : int | |
| The upsampling factor to use for the helmet mesh. The default (1) does no | |
| upsampling. Larger integers lead to more densely sampled helmet surfaces, and | |
| the number of vertices increases as a factor of ``4**(upsampling-1)``. | |
| """ | |
| 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))) # doctest: +SKIP | |
| 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=None`` and ``method="iir"``, 4th order Butterworth will be used. | |
| For more information, see :func:`mne.filter.construct_iir_filter`. | |
| """ | |
| docdict["image_args"] = """ | |
| image_args : dict | None | |
| Keyword arguments to pass to :meth:`mne.time_frequency.AverageTFR.plot`. ``axes`` | |
| and ``show`` are ignored. Defaults to ``None`` (i.e., and empty :class:`dict`). | |
| """ | |
| 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 | |
| ``pandas.Index``{} 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["inst_tfr"] = """ | |
| inst : instance of RawTFR, EpochsTFR, or AverageTFR | |
| """ | |
| 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'``. | |
| """ | |
| docdict["item"] = """ | |
| item : int | slice | array-like | str | |
| """ | |
| # %% | |
| # 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["kit_badcoils"] = """ | |
| bad_coils : array-like of int | None | |
| Indices of (up to two) bad marker coils to be removed. | |
| These marker coils must be present in the elp and mrk files. | |
| """ | |
| docdict["kit_elp"] = """ | |
| elp : path-like | array of shape (8, 3) | None | |
| Digitizer points representing the location of the fiducials and the | |
| marker coils with respect to the digitized head shape, or path to a | |
| file containing these points. | |
| """ | |
| docdict["kit_hsp"] = """ | |
| hsp : path-like | array of shape (n_points, 3) | None | |
| Digitizer head shape points, or path to head shape file. If more than | |
| 10,000 points are in the head shape, they are automatically decimated. | |
| """ | |
| docdict["kit_mrk"] = """ | |
| mrk : path-like | array of shape (5, 3) | list | None | |
| Marker points representing the location of the marker coils with | |
| respect to the MEG sensors, or path to a marker file. | |
| If list, all of the markers will be averaged together. | |
| """ | |
| docdict["kit_slope"] = r""" | |
| slope : ``'+'`` | ``'-'`` | |
| How to interpret values on KIT trigger channels when synthesizing a | |
| Neuromag-style stim channel. With ``'+'``\, a positive slope (low-to-high) | |
| is interpreted as an event. With ``'-'``\, a negative slope (high-to-low) | |
| is interpreted as an event. | |
| """ | |
| docdict["kit_stim"] = r""" | |
| stim : list of int | ``'<'`` | ``'>'`` | None | |
| Channel-value correspondence when converting KIT trigger channels to a | |
| Neuromag-style stim channel. For ``'<'``\, the largest values are | |
| assigned to the first channel (default). For ``'>'``\, the largest | |
| values are assigned to the last channel. Can also be specified as a | |
| list of trigger channel indexes. If None, no synthesized channel is | |
| generated. | |
| """ | |
| docdict["kit_stimcode"] = """ | |
| stim_code : ``'binary'`` | ``'channel'`` | |
| How to decode trigger values from stim channels. ``'binary'`` read stim | |
| channel events as binary code, 'channel' encodes channel number. | |
| """ | |
| docdict["kit_stimthresh"] = """ | |
| stimthresh : float | None | |
| The threshold level for accepting voltage changes in KIT trigger | |
| channels as a trigger event. If None, stim must also be set to None. | |
| """ | |
| 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. | |
| """ | |
| 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_scale"] = """ | |
| layout_scale : float | |
| Scaling factor for adjusting the relative size of the layout on the canvas. | |
| """ | |
| 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 (if possible). | |
| """ | |
| 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_alpha_tfr_plot"] = """ | |
| mask_alpha : float | |
| Relative opacity of the masked region versus the unmasked region, given as a | |
| :class:`float` between 0 and 1 (i.e., 0 means masked areas are not visible at all). | |
| Defaults to ``0.1``. | |
| """ | |
| docdict["mask_cmap_tfr_plot"] = """ | |
| mask_cmap : matplotlib colormap | str | None | |
| Colormap to use for masked areas of the plot. If a :class:`str`, must be a valid | |
| Matplotlib colormap name. If None, ``cmap`` is used for both masked and unmasked | |
| areas. Ignored if ``mask`` is ``None``. Default is ``'Greys'``. | |
| """ | |
| 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_style_tfr_plot"] = """ | |
| mask_style : None | 'both' | 'contour' | 'mask' | |
| How to distinguish the masked/unmasked regions of the plot. If ``"contour"``, a | |
| line is drawn around the areas where the mask is ``True``. If ``"mask"``, areas | |
| where the mask is ``False`` will be (partially) transparent, as determined by | |
| ``mask_alpha``. If ``"both"``, both a contour and transparency are used. Default is | |
| ``None``, which is silently ignored if ``mask`` is ``None`` and is interpreted like | |
| ``"both"`` otherwise. | |
| """ | |
| docdict["mask_tfr_plot"] = """ | |
| mask : ndarray | None | |
| An :class:`array <numpy.ndarray>` of :class:`boolean <bool>` values, of the same | |
| shape as the data. Data that corresponds to ``False`` entries in the mask are | |
| plotted differently, as determined by ``mask_style``, ``mask_alpha``, and | |
| ``mask_cmap``. Useful for, e.g., highlighting areas of statistical significance. | |
| """ | |
| 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_dist_ieeg"] = """ | |
| max_dist : float | |
| The maximum distance to project a sensor to the pial surface in meters. | |
| Sensors that are greater than this distance from the pial surface will | |
| not be assigned locations. Projections can be done to the inflated or | |
| flat brain. | |
| """ | |
| 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["maxwell_mc_interp"] = """ | |
| mc_interp : str | |
| Interpolation to use between adjacent time points in movement | |
| compensation. Can be "zero" (used by MaxFilter), | |
| "linear", or "hann" (default in 1.11). | |
| .. versionadded:: 1.10 | |
| """ | |
| 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 | dict | 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')``. Can also be a dict to specify alpha values, | |
| e.g. ``{"helmet": 0.1, "sensors": 0.8}``. | |
| .. versionchanged:: 1.6 | |
| Added support for specifying alpha values as a dict. | |
| """ | |
| _metadata_attr_template = """ | |
| metadata : instance of pandas.DataFrame | None | |
| A :class:`pandas.DataFrame` specifying metadata about each epoch{or_none}.{extra} | |
| """ | |
| _metadata_template = _metadata_attr_template.format( | |
| or_none="", | |
| extra=""" | |
| If not ``None``, ``len(metadata)`` must equal ``len(events)``. For | |
| save/load compatibility, the :class:`~pandas.DataFrame` may only contain | |
| :class:`str`, :class:`int`, :class:`float`, and :class:`bool` values. | |
| If not ``None``, then pandas-style queries may be used to select | |
| subsets of data, see :meth:`mne.Epochs.__getitem__`. When the {obj} object | |
| is subsetted, the metadata is subsetted accordingly, and the row indices | |
| will be modified to match ``{obj}.selection``.""", | |
| ) | |
| docdict["metadata_attr"] = _metadata_attr_template.format( | |
| or_none=" (or ``None``)", extra="" | |
| ) | |
| docdict["metadata_epochs"] = _metadata_template.format(obj="Epochs") | |
| docdict["metadata_epochstfr"] = _metadata_template.format(obj="EpochsTFR") | |
| docdict["method_fir"] = """ | |
| method : str | |
| ``'fir'`` will use overlap-add FIR filtering, ``'iir'`` will use IIR | |
| forward-backward filtering (via :func:`~scipy.signal.filtfilt`). | |
| """ | |
| _method_kw_tfr_template = """ | |
| **method_kw | |
| Additional keyword arguments passed to the spectrotemporal estimation function | |
| (e.g., ``n_cycles, use_fft, zero_mean`` for Morlet method{stockwell} | |
| or ``n_cycles, use_fft, zero_mean, time_bandwidth`` for multitaper method). | |
| See :func:`~mne.time_frequency.tfr_array_morlet`{stockwell_crossref} | |
| and :func:`~mne.time_frequency.tfr_array_multitaper` for additional details. | |
| """ | |
| docdict["method_kw_epochs_tfr"] = _method_kw_tfr_template.format( | |
| stockwell=", ``n_fft, width`` for Stockwell method,", | |
| stockwell_crossref=", :func:`~mne.time_frequency.tfr_array_stockwell`,", | |
| ) | |
| 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. Note | |
| that for Welch method if ``n_fft`` is unspecified its default will be | |
| the smaller of ``2048`` or the number of available time samples (taking into | |
| account ``tmin`` and ``tmax``), not ``256`` as in | |
| :func:`~mne.time_frequency.psd_array_welch`. | |
| """ | |
| docdict["method_kw_tfr"] = _method_kw_tfr_template.format( | |
| stockwell="", stockwell_crossref="" | |
| ) | |
| _method_psd = """ | |
| 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["method_resample"] = """ | |
| method : str | |
| Resampling method to use. Can be ``"fft"`` (default) or ``"polyphase"`` | |
| to use FFT-based on polyphase FIR resampling, respectively. These wrap to | |
| :func:`scipy.signal.resample` and :func:`scipy.signal.resample_poly`, respectively. | |
| """ | |
| _method_tfr_template = """ | |
| method : ``'morlet'`` | ``'multitaper'``{literals} | None | |
| Spectrotemporal power estimation method. ``'morlet'`` uses Morlet wavelets, | |
| ``'multitaper'`` uses DPSS tapers :footcite:p:`Slepian1978`{cites}. ``None`` (the | |
| default) only works when using ``__setstate__`` and will raise an error otherwise. | |
| """ | |
| docdict["method_tfr"] = _method_tfr_template.format(literals="", cites="") | |
| docdict["method_tfr_array"] = """ | |
| method : str | None | |
| Comment on the method used to compute the data, e.g., ``"hilbert"``. | |
| Default is ``None``. | |
| """ | |
| docdict["method_tfr_attr"] = """ | |
| method : str | |
| The method used to compute the spectra (e.g., ``"morlet"``, ``"multitaper"`` | |
| or ``"stockwell"``). | |
| """ | |
| docdict["method_tfr_epochs"] = _method_tfr_template.format( | |
| literals=" | ``'stockwell'``", | |
| cites=", and ``'stockwell'`` uses the S-transform " | |
| ":footcite:p:`Stockwell2007,MoukademEtAl2014,WheatEtAl2010,JonesEtAl2006`", | |
| ) | |
| 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["mode_tfr_plot"] = """ | |
| mode : 'mean' | 'ratio' | 'logratio' | 'percent' | 'zscore' | 'zlogratio' | |
| Perform baseline correction by | |
| - subtracting the mean of baseline values ('mean') (default) | |
| - dividing by the mean of baseline values ('ratio') | |
| - dividing by the mean of baseline values and taking the log | |
| ('logratio') | |
| - subtracting the mean of baseline values followed by dividing by | |
| the mean of baseline values ('percent') | |
| - subtracting the mean of baseline values and dividing by the | |
| standard deviation of baseline values ('zscore') | |
| - dividing by the mean of baseline values, taking the log, and | |
| dividing by the standard deviation of log baseline values | |
| ('zlogratio') | |
| """ | |
| 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_reference"] = """ | |
| The Morlet wavelets follow the formulation in :footcite:t:`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 :class:`joblib:joblib.parallel_config` 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["n_proj_vectors"] = """ | |
| n_grad : int | float between ``0`` and ``1`` | |
| Number of vectors for gradiometers. Either an integer or a float between 0 and 1 | |
| to select the number of vectors to explain the cumulative variance greater than | |
| ``n_grad``. | |
| n_mag : int | float between ``0`` and ``1`` | |
| Number of vectors for magnetometers. Either an integer or a float between 0 and | |
| 1 to select the number of vectors to explain the cumulative variance greater | |
| than ``n_mag``. | |
| n_eeg : int | float between ``0`` and ``1`` | |
| Number of vectors for EEG channels. Either an integer or a float between 0 and 1 | |
| to select the number of vectors to explain the cumulative variance greater than | |
| ``n_eeg``. | |
| """ | |
| 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["nave_tfr_attr"] = """ | |
| nave : int | |
| The number of epochs that were averaged to yield the result. This may reflect | |
| epochs averaged *before* time-frequency analysis (as in | |
| ``epochs.average(...).compute_tfr(...)``) or *after* time-frequency analysis (as | |
| in ``epochs.compute_tfr(...).average(...)``). | |
| """ | |
| 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_spectrum_array"] = """ | |
| If the data passed in is real-valued, it is assumed to represent spectral *power* (not | |
| amplitude, phase, etc), and downstream methods (such as | |
| :meth:`~mne.time_frequency.SpectrumArray.plot`) assume power data. If you pass in | |
| real-valued data that is not power, axis labels will be incorrect. | |
| If the data passed in is complex-valued, it is assumed to represent Fourier | |
| coefficients. Downstream plotting methods will treat the data as such, attempting to | |
| convert this to power before visualisation. If you pass in complex-valued data that is | |
| not Fourier coefficients, axis labels will be incorrect. | |
| """ | |
| docdict["notes_timefreqs_tfr_plot_joint"] = """ | |
| ``timefreqs`` has three different modes: tuples, dicts, and auto. For (list of) tuple(s) | |
| mode, each tuple defines a pair (time, frequency) in s and Hz on the TFR plot. | |
| For example, to look at 10 Hz activity 1 second into the epoch and 3 Hz activity 300 ms | |
| into the epoch, :: | |
| timefreqs=((1, 10), (.3, 3)) | |
| If provided as a dictionary, (time, frequency) tuples are keys and (time_window, | |
| frequency_window) tuples are the values — indicating the width of the windows (centered | |
| on the time and frequency indicated by the key) to be averaged over. For example, :: | |
| timefreqs={(1, 10): (0.1, 2)} | |
| would translate into a window that spans 0.95 to 1.05 seconds and 9 to 11 Hz. If | |
| ``None``, a single topomap will be plotted at the absolute peak across the | |
| time-frequency representation. | |
| """ | |
| 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["npad_resample"] = ( | |
| docdict["npad"] | |
| + """ | |
| Only used when ``method="fft"``. | |
| """ | |
| ) | |
| 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_bad_hpi_match"] = """ | |
| on_bad_hpi_match : str | |
| Can be ``'raise'`` to raise an error, ``'warn'`` (default) to emit a | |
| warning, or ``'ignore'`` to ignore when there is poor matching of HPI coordinates | |
| (>10mm difference) for device - head transform. | |
| """ | |
| 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["ordered"] = """ | |
| ordered : bool | |
| If True (default), ensure that the order of the channels in | |
| the modified instance matches the order of ``ch_names``. | |
| .. versionadded:: 0.20.0 | |
| .. versionchanged:: 1.7 | |
| The default changed from False in 1.6 to True in 1.7. | |
| """ | |
| 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["output_compute_tfr"] = """ | |
| output : str | |
| What kind of estimate to return. Allowed values are ``"complex"``, ``"phase"``, | |
| and ``"power"``. Default is ``"power"``. | |
| """ | |
| 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 = """ | |
| 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_fir"] = ( | |
| """ | |
| pad : str | |
| The type of padding to use. Supports """ | |
| + _pad_base | |
| + """\ | |
| Only used for ``method='fir'``. | |
| """ | |
| ) | |
| docdict["pad_resample"] = ( # used when default is not "auto" | |
| """ | |
| pad : str | |
| The type of padding to use. When ``method="fft"``, supports """ | |
| + _pad_base | |
| + """\ | |
| When ``method="polyphase"``, supports all modes of :func:`scipy.signal.upfirdn`. | |
| """ | |
| ) | |
| docdict["pad_resample_auto"] = ( # used when default is "auto" | |
| docdict["pad_resample"] | |
| + """\ | |
| The default ("auto") means ``'reflect_limited'`` for ``method='fft'`` and | |
| ``'reflect'`` for ``method='polyphase'``. | |
| """ | |
| ) | |
| 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. | |
| When ``method='fir'``, symmetric linear-phase FIR filters are constructed | |
| with the following behaviors when ``method="fir"``: | |
| ``"zero"`` (default) | |
| The delay of this filter is compensated for, making it non-causal. | |
| ``"minimum"`` | |
| A minimum-phase filter will be constructed by decomposing the zero-phase filter | |
| into a minimum-phase and all-pass systems, and then retaining only the | |
| minimum-phase system (of the same length as the original zero-phase filter) | |
| via :func:`scipy.signal.minimum_phase`. | |
| ``"zero-double"`` | |
| *This is a legacy option for compatibility with MNE <= 0.13.* | |
| The filter is applied twice, once forward, and once backward | |
| (also making it non-causal). | |
| ``"minimum-half"`` | |
| *This is a legacy option for compatibility with MNE <= 1.6.* | |
| A minimum-phase filter will be reconstructed from the zero-phase filter with | |
| half the length of the original filter. | |
| When ``method='iir'``, ``phase='zero'`` (default) or equivalently ``'zero-double'`` | |
| constructs and applies IIR filter twice, once forward, and once backward (making it | |
| non-causal) using :func:`~scipy.signal.filtfilt`; ``phase='forward'`` will apply | |
| the filter once in the forward (causal) direction using | |
| :func:`~scipy.signal.lfilter`. | |
| .. versionadded:: 0.13 | |
| .. versionchanged:: 1.7 | |
| The behavior for ``phase="minimum"`` was fixed to use a filter of the requested | |
| length and improved suppression. | |
| """ | |
| docdict["physical_range_export_params"] = """ | |
| physical_range : str | tuple | |
| The physical range of the data. If 'auto' (default), the physical range is inferred | |
| from the data, taking the minimum and maximum values per channel type. If | |
| 'channelwise', the range will be defined per channel. If a tuple of minimum and | |
| maximum, this manual physical range 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. | |
| eyetrack : bool | str | |
| Eyetracking channels. If True include all eyetracking channels. If False | |
| (default) include none. If string it can be 'eyegaze' (to include | |
| eye position channels) or 'pupil' (to include pupil-size | |
| 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_types = """channel *type* strings (e.g., ``['meg', 'eeg']``) will | |
| pick channels of those types,""" | |
| _picks_str_names = """channel *name* strings (e.g., ``['MEG0111', 'MEG2623']`` | |
| will pick the given channels.""" | |
| _picks_str_values = """Can also be the string values ``'all'`` to pick | |
| all channels, or ``'data'`` to pick :term:`data channels`.""" | |
| _picks_str = f"""In lists, {_picks_str_types} {_picks_str_names} | |
| {_picks_str_values} | |
| None (default) will pick""" | |
| _picks_str_notypes = f"""In lists, {_picks_str_names} | |
| 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}""" | |
| picks_base_notypes = f"""picks : list of int | list of str | slice | None | |
| {_picks_desc} {_picks_int} {_picks_str_notypes}""" | |
| 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_all_notypes"] = _reflow_param_docstring( | |
| f"{picks_base_notypes} all channels. {reminder}" | |
| ) | |
| 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_layout"] = """ | |
| picks : array-like of str or int | slice | ``'all'`` | None | |
| Channels to include in the layout. Slices and lists of integers will be interpreted | |
| as channel indices. Can also be the string value ``'all'`` to pick all channels. | |
| None (default) will pick all channels. | |
| """ | |
| 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"] = """ | |
| projs : list of Projection | |
| List of computed projection vectors. | |
| """ | |
| 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_full"] = _rank_base + "\n The default is ``'full'``." | |
| 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 | dict | |
| Can be: | |
| - The name(s) of the channel(s) used to construct the reference for | |
| every channel of ``ch_type``. | |
| - ``'average'`` to apply an average reference (default) | |
| - ``'REST'`` to use the Reference Electrode Standardization Technique | |
| infinity reference :footcite:`Yao2001`. | |
| - A dictionary mapping names of data channels to (lists of) names of | |
| reference channels. For example, {'A1': 'A3'} would replace the | |
| data in channel 'A1' with the difference between 'A1' and 'A3'. To take | |
| the average of multiple channels as reference, supply a list of channel | |
| names as the dictionary value, e.g. {'A1': ['A2', 'A3']} would replace | |
| channel A1 with ``A1 - mean(A2, A3)``. | |
| - 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. | |
| """ | |
| ) | |
| docdict["reject_by_annotation_tfr"] = """ | |
| reject_by_annotation : bool | |
| Whether to omit bad spans of data before spectrotemporal power | |
| estimation. If ``True``, spans with annotations whose description | |
| begins with ``bad`` will be represented with ``np.nan`` in the | |
| time-frequency representation. | |
| """ | |
| _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"] = """\ | |
| reject : dict | str | None | |
| Reject epochs based on **maximum** peak-to-peak signal amplitude (PTP) | |
| or custom functions. Peak-to-peak signal amplitude is defined as | |
| 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) | |
| ) | |
| Custom rejection criteria can be also be used by passing a callable, | |
| e.g., to check for 99th percentile of absolute values of any channel | |
| across time being bigger than :unit:`1 mV`. The callable must return a | |
| ``(good, reason)`` tuple: ``good`` must be :class:`bool` and ``reason`` | |
| must be :class:`str`, :class:`list`, or :class:`tuple` where each entry | |
| is a :class:`str`:: | |
| reject = dict( | |
| eeg=lambda x: ( | |
| (np.percentile(np.abs(x), 99, axis=1) > 1e-3).any(), | |
| "signal > 1 mV somewhere", | |
| ) | |
| ) | |
| .. note:: If 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. | |
| .. note:: If ``reject`` is a callable, than **any** criteria can be | |
| used to reject epochs (including maxima and minima). | |
| If ``reject`` is ``None``, no rejection is performed. If ``'existing'`` | |
| (default), then the rejection parameters set at instantiation are used. | |
| """ # noqa: E501 | |
| 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["remove_dc"] = """ | |
| remove_dc : bool | |
| If ``True``, the mean is subtracted from each segment before computing | |
| its spectrum. | |
| """ | |
| 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 to 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["selection_attr"] = """ | |
| selection : ndarray | |
| Array of indices of *selected* epochs (i.e., epochs that were not rejected, dropped, | |
| or ignored).""" | |
| docdict["sensor_colors"] = """ | |
| sensor_colors : array-like of color | dict | None | |
| Colors to use for the sensor glyphs. Can be None (default) to use default colors. | |
| A dict should provide the colors (values) for each channel type (keys), e.g.:: | |
| dict(eeg=eeg_colors) | |
| Where the value (``eeg_colors`` above) can be broadcast to an array of colors with | |
| length that matches the number of channels of that type, i.e., is compatible with | |
| :func:`matplotlib.colors.to_rgba_array`. A few examples of this for the case above | |
| are the string ``"k"``, a list of ``n_eeg`` color strings, or an NumPy ndarray of | |
| shape ``(n_eeg, 3)`` or ``(n_eeg, 4)``. | |
| """ | |
| docdict["sensor_scales"] = """ | |
| sensor_scales : int | float | array-like | dict | None | |
| Scale to use for the sensor glyphs. Can be None (default) to use default scale. | |
| A dict should provide the Scale (values) for each channel type (keys), e.g.:: | |
| dict(eeg=eeg_scales) | |
| Where the value (``eeg_scales`` above) can be broadcast to an array of values with | |
| length that matches the number of channels of that type. A few examples of this | |
| for the case above are the value ``10e-3``, a list of ``n_eeg`` values, or an NumPy | |
| ndarray of shape ``(n_eeg,)``. | |
| """ | |
| 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. | |
| - Different references for different channels | |
| Set ``ref_channels`` to a dictionary mapping source channel names (str) | |
| to the reference channel names (str or list of str). Unlike the other | |
| approaches where the same reference is applied globally, you can set | |
| different references for different channels with this method. For example, | |
| to re-reference channel 'A1' to 'A2' and 'B1' to the average of 'B2' and | |
| 'B3', set ``ref_channels={'A1': 'A2', 'B1': ['B2', 'B3']}``. Warnings are | |
| issued when a mapping involves bad channels or channels of different types. | |
| 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["sfreq_tfr_attr"] = """ | |
| sfreq : int | float | |
| The sampling frequency (read from ``info``).""" | |
| docdict["shape_tfr_attr"] = """ | |
| shape : tuple of int | |
| The shape of the data.""" | |
| 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"] = """ | |
| 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. Only used if ``inst`` is raw. | |
| """ | |
| 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"] = """\ | |
| spatial_colors : bool | 'auto' | |
| If True, the lines are color coded by mapping physical sensor | |
| coordinates into color values. Spatially similar channels will have | |
| similar colors. Bad channels will be dotted. If False, the good | |
| channels are plotted black and bad channels red. If ``'auto'``, uses | |
| True if channel locations are present, and False if channel locations | |
| are missing or if the data contains only a single channel. Defaults to | |
| ``'auto'``. | |
| """ | |
| 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 of float | instance of ConductorModel | str | list of str | None | |
| 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. | |
| Can also be a ``str``, in which case: | |
| - ``'auto'``: the sphere is fit to external digitization points first, and to | |
| external + EEG digitization points if the former fails. | |
| - ``'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'``). | |
| - ``'extra'``: the sphere is fit to external digitization points. | |
| - ``'eeg'``: the sphere is fit to EEG digitization points. | |
| - ``'cardinal'``: the sphere is fit to cardinal digitization points. | |
| - ``'hpi'``: the sphere is fit to HPI coil digitization points. | |
| Can also be a list of ``str``, in which case the sphere is fit to the specified | |
| digitization points, which can be any combination of ``'extra'``, ``'eeg'``, | |
| ``'cardinal'``, and ``'hpi'``, as specified above. | |
| ``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. | |
| .. versionchanged:: 1.11 Added ``'extra'``, ``'eeg'``, ``'cardinal'``, ``'hpi'`` and | |
| list of ``str`` options. | |
| """ # noqa E501 | |
| docdict["splash"] = """ | |
| splash : bool | |
| If True (default), a splash screen is shown during the application startup. Only | |
| applicable to the ``qt`` backend. | |
| """ | |
| 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``, and so on. For ``'bids'``, | |
| a filename is expected to consist of parts separated by underscores, like | |
| ``<part-1>_<part-N>_<suffix>.fif``, and the according split naming will | |
| return filenames like ``<part-1>_<part-N>_split-01_<suffix>.fif``, | |
| ``<part-1>_<part-N>_split-02_<suffix>.fif``, and so on. | |
| """ | |
| 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_intro"] = """ | |
| In spectrotemporal analysis (as with traditional fourier methods), | |
| the temporal and spectral resolution are interrelated: longer temporal windows | |
| allow more precise frequency estimates; shorter temporal windows "smear" | |
| frequency estimates while providing more precise timing information. | |
| 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>`_. | |
| """ # noqa: E501 | |
| docdict["temporal_window_tfr_morlet_notes"] = r""" | |
| In MNE-Python, the length of the Morlet wavelet is affected by the arguments | |
| ``freqs`` and ``n_cycles``, which define the frequencies of interest | |
| and the number of cycles, respectively. For the time-frequency representation, | |
| the length of the wavelet is defined such that both tails of | |
| the wavelet extend five standard deviations from the midpoint of its Gaussian | |
| envelope and that there is a sample at time zero. | |
| The length of the wavelet is thus :math:`10\times\mathtt{sfreq}\cdot\sigma-1`, | |
| which is equal to :math:`\frac{5}{\pi} \cdot \frac{\mathtt{n\_cycles} \cdot | |
| \mathtt{sfreq}}{\mathtt{freqs}} - 1`, where | |
| :math:`\sigma = \frac{\mathtt{n\_cycles}}{2\pi f}` corresponds to the standard | |
| deviation of the wavelet's Gaussian envelope. Note that the length of the | |
| wavelet must not exceed the length of your signal. | |
| For more information on the Morlet wavelet, see :func:`mne.time_frequency.morlet`. | |
| """ | |
| docdict["temporal_window_tfr_multitaper_notes"] = r""" | |
| In MNE-Python, the multitaper temporal window length is defined by the arguments | |
| ``freqs`` and ``n_cycles``, respectively defining the frequencies of interest | |
| and the number of cycles: :math:`T = \frac{\mathtt{n\_cycles}}{\mathtt{freqs}}` | |
| A fixed number of cycles for all frequencies will yield a temporal window which | |
| decreases with frequency. For example, ``freqs=np.arange(1, 6, 2)`` and | |
| ``n_cycles=2`` yields ``T=array([2., 0.7, 0.4])``. | |
| To use a temporal window with fixed length, the number of cycles has to be | |
| defined based on the frequency. For example, ``freqs=np.arange(1, 6, 2)`` and | |
| ``n_cycles=freqs / 2`` yields ``T=array([0.5, 0.5, 0.5])``. | |
| """ | |
| _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, | |
| `qdarkstyle <https://github.com/ColinDuquesnoy/QDarkStyleSheet>`__ 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`` unless specified otherwise. | |
| """ | |
| 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["timefreqs"] = """ | |
| timefreqs : None | list of tuple | dict of tuple | |
| The time-frequency point(s) for which topomaps will be plotted. See Notes. | |
| """ | |
| docdict["times"] = """ | |
| times : ndarray, shape (n_times,) | |
| The time values in seconds. | |
| """ | |
| docdict["title_none"] = """ | |
| title : str | None | |
| The title of the generated figure. If ``None`` (default), no title is | |
| displayed. | |
| """ | |
| docdict["title_stc"] = """ | |
| title : str | None | |
| Title for the figure window. If ``None``, the subject name will be used. | |
| """ | |
| docdict["title_tfr_plot"] = """ | |
| title : str | 'auto' | None | |
| Title for the plot. If ``"auto"``, will use the channel name (if ``combine`` is | |
| ``None``) or state the number and method of combined channels used to generate the | |
| plot. If ``None``, no title is shown. Default is ``None``. | |
| """ | |
| docdict["tmax_raw"] = """ | |
| tmax : float | None | |
| End time of the raw data to use in seconds (cannot exceed data duration). | |
| If ``None`` (default), the current end of the data is used. | |
| """ | |
| docdict["tmin"] = """ | |
| tmin : scalar | |
| Time point of the first sample in data. | |
| """ | |
| docdict["tmin_epochs"] = """ | |
| tmin : float | |
| Start time before event. If nothing provided, defaults to 0. | |
| """ | |
| 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`. | |
| """ | |
| _topomap_args_template = """ | |
| {param} : dict | None | |
| Keyword arguments to pass to {func}.{extra} | |
| """ | |
| docdict["topomap_args"] = _topomap_args_template.format( | |
| param="topomap_args", | |
| func=":func:`mne.viz.plot_topomap`", | |
| extra=" ``axes`` and ``show`` are ignored. If ``times`` is not in this dict, " | |
| "automatic peak detection is used. Beyond that, if ``None``, no customizable " | |
| "arguments will be passed. Defaults to ``None`` (i.e., an empty :class:`dict`).", | |
| ) | |
| docdict["topomap_kwargs"] = _topomap_args_template.format( | |
| param="topomap_kwargs", func="the topomap-generating functions", extra="" | |
| ) | |
| _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 | ``"fsaverage"`` | None | |
| {_trans_base} | |
| If trans is None, an identity matrix is assumed. | |
| """ | |
| docdict["trans_not_none"] = f""" | |
| trans : str | dict | instance of Transform | |
| {_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["ui_event_name_source"] = """ | |
| name : str | |
| The name of the event (same as its class name but in snake_case). | |
| source : matplotlib.figure.Figure | Figure3D | |
| The figure that published the event. | |
| """ | |
| 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{joint_param} | |
| Lower and upper bounds of the colormap, typically a numeric value in the same | |
| units as the data. {callable} | |
| If both entries are ``None``, the bounds are set at {bounds}. | |
| Providing ``None`` for just one entry will set the corresponding boundary at the | |
| min/max of the data. {extra}Defaults to ``(None, None)``. | |
| """ | |
| _joint_param = ' | "joint"' | |
| _callable_sentence = """Elements of the :class:`tuple` may also be callable functions | |
| which take in a :class:`NumPy array <numpy.ndarray>` and return a scalar. | |
| """ | |
| _bounds_symmetric = """± the maximum absolute value | |
| of the data (yielding a colormap with midpoint at 0)""" | |
| _bounds_minmax = "``(min(data), max(data))``" | |
| _bounds_norm = "``(0, max(abs(data)))``" | |
| _bounds_contingent = f"""{_bounds_symmetric}, or {_bounds_norm} | |
| if the (possibly baselined) data are all-positive""" | |
| _joint_sentence = """If ``vlim="joint"``, will compute the colormap limits | |
| jointly across all {what}s of the same channel type (instead of separately | |
| for each {what}), using the min/max of the data for that channel type. | |
| {joint_extra}""" | |
| docdict["vlim_plot_topomap"] = _vlim.format( | |
| joint_param="", callable="", bounds=_bounds_minmax, extra="" | |
| ) | |
| docdict["vlim_plot_topomap_proj"] = _vlim.format( | |
| joint_param=_joint_param, | |
| callable=_callable_sentence, | |
| bounds=_bounds_contingent, | |
| extra=_joint_sentence.format( | |
| what="projector", | |
| joint_extra='If vlim is ``"joint"``, ``info`` must not be ``None``. ', | |
| ), | |
| ) | |
| docdict["vlim_plot_topomap_psd"] = _vlim.format( | |
| joint_param=_joint_param, | |
| callable=_callable_sentence, | |
| bounds=_bounds_contingent, | |
| extra=_joint_sentence.format(what="topomap", joint_extra=""), | |
| ) | |
| docdict["vlim_tfr_plot"] = _vlim.format( | |
| joint_param="", callable="", bounds=_bounds_contingent, extra="" | |
| ) | |
| docdict["vlim_tfr_plot_joint"] = _vlim.format( | |
| joint_param="", | |
| callable="", | |
| bounds=_bounds_contingent, | |
| extra="""To specify the colormap separately for the topomap annotations, | |
| see ``topomap_args``. """, | |
| ) | |
| _vmin_vmax_template = """ | |
| vmin, vmax : float | {allowed}None | |
| Lower and upper bounds of the colormap, in the same units as the data. | |
| If ``vmin`` and ``vmax`` are both ``None``, the bounds are set at | |
| {bounds}. If only one of ``vmin``, ``vmax`` is ``None``, will use | |
| ``min(data)`` or ``max(data)``, respectively.{extra} | |
| """ | |
| # ↓↓↓ this one still used, needs helper func refactor before we can migrate to `vlim` | |
| docdict["vmin_vmax_tfr_plot_topo"] = _vmin_vmax_template.format( | |
| allowed="", bounds=_bounds_symmetric, extra="" | |
| ) | |
| # ↓↓↓ this one still used in Evoked.animate_topomap(), should migrate to `vlim` | |
| docdict["vmin_vmax_topomap"] = _vmin_vmax_template.format( | |
| allowed="callable | ", | |
| bounds=_bounds_symmetric, | |
| extra=""" If callable, should accept | |
| a :class:`NumPy array <numpy.ndarray>` of data and return a :class:`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["weights_tfr_array"] = """ | |
| weights : array, shape (n_tapers, n_freqs) | None | |
| The weights for each taper. Must be provided if ``data`` has a taper dimension, such | |
| as for complex or phase multitaper data. | |
| .. versionadded:: 1.10.0 | |
| """ | |
| docdict["weights_tfr_attr"] = """ | |
| weights : array, shape (n_tapers, n_freqs) | None | |
| The weights used for each taper in the time-frequency estimates. | |
| """ | |
| docdict["window_psd"] = """\ | |
| window : str | float | tuple | |
| Windowing function to use. See :func:`scipy.signal.get_window`. | |
| """ | |
| docdict["window_resample"] = """ | |
| window : str | tuple | |
| When ``method="fft"``, this is the *frequency-domain* window to use in resampling, | |
| and should be the same length as the signal; see :func:`scipy.signal.resample` | |
| for details. When ``method="polyphase"``, this is the *time-domain* linear-phase | |
| window to use after upsampling the signal; see :func:`scipy.signal.resample_poly` | |
| for details. The default ``"auto"`` will use ``"boxcar"`` for ``method="fft"`` and | |
| ``("kaiser", 5.0)`` for ``method="polyphase"``. | |
| """ | |
| # %% | |
| # X | |
| docdict["xscale_plot_psd"] = """\ | |
| xscale : 'linear' | 'log' | |
| Scale of the frequency axis. Default is ``'linear'``. | |
| """ | |
| # %% | |
| # Y | |
| docdict["yscale_tfr_plot"] = """ | |
| yscale : 'auto' | 'linear' | 'log' | |
| The scale of the y (frequency) axis. 'linear' gives linear y axis, 'log' gives | |
| log-spaced y axis and 'auto' detects if frequencies are log-spaced and if so sets | |
| the y axis to 'log'. Default is 'auto'. | |
| """ | |
| # %% | |
| # 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(f"Error documenting {funcname}:\n{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. | |
| Docstrings are processed by :func:`python:inspect.cleandoc` before being used. | |
| 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 += f"\n{inspect.cleandoc(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. | |
| Docstrings are parsed by :func:`python:inspect.cleandoc` before being used. | |
| If indentation and newlines are important, make the first line ``.``, and the dot | |
| will be removed and all following lines dedented jointly. | |
| 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 | |
| """ # noqa: D410, D411, D214, D215 | |
| def wrapper(func): | |
| # Work with cleandoc'ed sources (py3.13-compat) | |
| doc = inspect.cleandoc(source.__doc__).split("\n") | |
| if func.__doc__ is not None: | |
| func_doc = inspect.cleandoc(func.__doc__) | |
| if func_doc[:2] == ".\n": | |
| func_doc = func_doc[2:] | |
| func_doc = f"\n{func_doc}" | |
| else: | |
| func_doc = "" | |
| if len(doc) == 1: | |
| func.__doc__ = f"{doc[0]}{func_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 + 1 | |
| 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:]) | |
| ) | |
| func.__doc__ = f"{doc}{func_doc}" | |
| return func | |
| return wrapper | |
| 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 = f"#L{lineno}-L{lineno + len(source) - 1}" | |
| else: | |
| linespec = "" | |
| if "dev" in mne.__version__: | |
| kind = "main" | |
| else: | |
| kind = "maint/" + ".".join(mne.__version__.split(".")[:2]) | |
| return f"http://github.com/mne-tools/mne-python/blob/{kind}/mne/{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(f"https://mne.tools/{version}/{kind}") | |
| class _decorator: | |
| """Inject code or modify the docstring of a class, method, or function.""" | |
| def __init__(self, extra): | |
| 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 .. 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=""): | |
| 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(f"Error documenting {funcname}:\n{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 | |