diff --git a/doc/_includes/bem_model.rst b/doc/_includes/bem_model.rst index 1985d85fc31..9770d36a7fe 100644 --- a/doc/_includes/bem_model.rst +++ b/doc/_includes/bem_model.rst @@ -17,7 +17,7 @@ Using the watershed algorithm The watershed algorithm [Segonne *et al.*, 2004] is part of the FreeSurfer software. -The name of the program is mri_watershed . +The name of the program is ``mri_watershed``. Its use in the MNE environment is facilitated by the script :ref:`mne watershed_bem`. @@ -39,6 +39,7 @@ a file called :file:`bem/watershed/ws.mgz` which contains the brain MRI volume. Furthermore, ``mne watershed_bem`` script converts the scalp surface to fif format and saves the result to :file:`bem/{}-head.fif`. +.. _bem_flash_algorithm: Using FLASH images ~~~~~~~~~~~~~~~~~~ @@ -50,7 +51,7 @@ reconstructions but it is strongly recommended that they are collected at the same time with the MPRAGEs or at least with the same scanner. For easy co-registration, the images should have FOV, matrix, slice thickness, gap, and slice orientation as the MPRAGE data. For information on suitable pulse -sequences, see :footcite:`FischlEtAl2004`. +sequences, see :footcite:t:`FischlEtAl2004`. Creation of the BEM meshes using this method involves the following steps: diff --git a/doc/_includes/forward.rst b/doc/_includes/forward.rst index fecee06d918..f92632f8220 100644 --- a/doc/_includes/forward.rst +++ b/doc/_includes/forward.rst @@ -27,7 +27,7 @@ MEG/EEG and MRI coordinate systems :class:`~mne.SourceSpaces`, etc), information about the coordinate frame is encoded as a constant integer value. The meaning of those integers is determined `in the source code - `__. + `__. The coordinate systems used in MNE software (and FreeSurfer) and their relationships are depicted in :ref:`coordinate_system_figure`. Except for the diff --git a/doc/_includes/ssp.rst b/doc/_includes/ssp.rst index 90b46d99c33..f28c91ddd5c 100644 --- a/doc/_includes/ssp.rst +++ b/doc/_includes/ssp.rst @@ -80,7 +80,7 @@ the brain, it is necessary to apply the projection to the forward solution in the course of inverse computations. For more information on SSP, please consult the references listed in -:footcite:`TescheEtAl1995,UusitaloIlmoniemi1997`. +:footcite:t:`TescheEtAl1995,UusitaloIlmoniemi1997`. Estimation of the noise subspace ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/mne/bem.py b/mne/bem.py index aa67c7f1fbf..1affb10f502 100644 --- a/mne/bem.py +++ b/mne/bem.py @@ -86,7 +86,11 @@ class ConductorModel(dict): - """BEM or sphere model.""" + """BEM or sphere model. + + See :func:`~mne.make_bem_model` and :func:`~mne.make_bem_solution` to create a + :class:`mne.bem.ConductorModel`. + """ def __repr__(self): # noqa: D105 if self["is_sphere"]: @@ -646,30 +650,32 @@ def make_bem_model( ): """Create a BEM model for a subject. + Use :func:`~mne.make_bem_solution` to turn the returned surfaces into a + :class:`~mne.bem.ConductorModel` suitable for forward calculation. + .. note:: To get a single layer bem corresponding to the --homog flag in the command line tool set the ``conductivity`` parameter - to a list/tuple with a single value (e.g. [0.3]). + to a float (e.g. ``0.3``). Parameters ---------- - subject : str - The subject. + %(subject)s ico : int | None The surface ico downsampling to use, e.g. ``5=20484``, ``4=5120``, ``3=1280``. If None, no subsampling is applied. - conductivity : array of int, shape (3,) or (1,) + conductivity : float | array of float of shape (3,) or (1,) The conductivities to use for each shell. Should be a single element for a one-layer model, or three elements for a three-layer model. Defaults to ``[0.3, 0.006, 0.3]``. The MNE-C default for a - single-layer model would be ``[0.3]``. + single-layer model is ``[0.3]``. %(subjects_dir)s %(verbose)s Returns ------- surfaces : list of dict - The BEM surfaces. Use `make_bem_solution` to turn these into a - `~mne.bem.ConductorModel` suitable for forward calculation. + The BEM surfaces. Use :func:`~mne.make_bem_solution` to turn these into a + :class:`~mne.bem.ConductorModel` suitable for forward calculation. See Also -------- @@ -682,9 +688,11 @@ def make_bem_model( ----- .. versionadded:: 0.10.0 """ - conductivity = np.array(conductivity, float) + conductivity = np.atleast_1d(conductivity).astype(float) if conductivity.ndim != 1 or conductivity.size not in (1, 3): - raise ValueError("conductivity must be 1D array-like with 1 or 3 " "elements") + raise ValueError( + "conductivity must be a float or a 1D array-like with 1 or 3 elements" + ) subjects_dir = get_subjects_dir(subjects_dir, raise_error=True) subject_dir = subjects_dir / subject bem_dir = subject_dir / "bem" @@ -851,7 +859,8 @@ def make_sphere_model( center will be calculated from the digitization points in info. head_radius : float | str | None If float, compute spherical shells for EEG using the given radius. - If 'auto', estimate an appropriate radius from the dig points in Info, + If ``'auto'``, estimate an appropriate radius from the dig points in the + :class:`~mne.Info` provided by the argument ``info``. If None, exclude shells (single layer sphere model). %(info)s Only needed if ``r0`` or ``head_radius`` are ``'auto'``. relative_radii : array-like @@ -1200,6 +1209,8 @@ def make_watershed_bem( ): """Create BEM surfaces using the FreeSurfer watershed algorithm. + See :ref:`bem_watershed_algorithm` for additional information. + Parameters ---------- subject : str @@ -1209,9 +1220,9 @@ def make_watershed_bem( volume : str Defaults to T1. atlas : bool - Specify the --atlas option for mri_watershed. + Specify the ``--atlas option`` for ``mri_watershed``. gcaatlas : bool - Specify the --brain_atlas option for mri_watershed. + Specify the ``--brain_atlas`` option for ``mri_watershed``. preflood : int Change the preflood height. show : bool @@ -1425,7 +1436,7 @@ def read_bem_surfaces( patch_stats : bool, optional (default False) Calculate and add cortical patch statistics to the surfaces. s_id : int | None - If int, only read and return the surface with the given s_id. + If int, only read and return the surface with the given ``s_id``. An error will be raised if it doesn't exist. If None, all surfaces are read and returned. %(on_defects)s @@ -1436,7 +1447,7 @@ def read_bem_surfaces( Returns ------- surf: list | dict - A list of dictionaries that each contain a surface. If s_id + A list of dictionaries that each contain a surface. If ``s_id`` is not None, only the requested surface will be returned. See Also @@ -1964,8 +1975,7 @@ def convert_flash_mris( Parameters ---------- - subject : str - Subject name. + %(subject)s flash30 : bool | list of SpatialImage or path-like | SpatialImage | path-like If False do not use 30-degree flip angle data. The list of flash 5 echos to use. If True it will look for files @@ -2084,10 +2094,11 @@ def make_flash_bem( ): """Create 3-Layer BEM model from prepared flash MRI images. + See :ref:`bem_flash_algorithm` for additional information. + Parameters ---------- - subject : str - Subject name. + %(subject)s overwrite : bool Write over existing .surf files in bem folder. show : bool diff --git a/mne/cov.py b/mne/cov.py index 9566b6fd487..4fa6fe44e6c 100644 --- a/mne/cov.py +++ b/mne/cov.py @@ -980,8 +980,8 @@ def compute_covariance( Returns ------- cov : instance of Covariance | list - The computed covariance. If method equals 'auto' or is a list of str - and return_estimators equals True, a list of covariance estimators is + The computed covariance. If method equals ``'auto'`` or is a list of str + and ``return_estimators=True``, a list of covariance estimators is returned (sorted by log-likelihood, from high to low, i.e. from best to worst). @@ -1009,16 +1009,14 @@ def compute_covariance( .. versionadded:: 0.16 * ``'ledoit_wolf'`` The Ledoit-Wolf estimator, which uses an - empirical formula for the optimal shrinkage value - :footcite:`LedoitWolf2004`. + empirical formula for the optimal shrinkage value :footcite:`LedoitWolf2004`. * ``'oas'`` The OAS estimator :footcite:`ChenEtAl2010`, which uses a different empricial formula for the optimal shrinkage value. .. versionadded:: 0.16 * ``'shrunk'`` - Like 'ledoit_wolf', but with cross-validation - for optimal alpha. + Like 'ledoit_wolf', but with cross-validation for optimal alpha. * ``'pca'`` Probabilistic PCA with low rank :footcite:`TippingBishop1999`. * ``'factor_analysis'`` @@ -1040,7 +1038,7 @@ def compute_covariance( The ``method`` parameter allows to regularize the covariance in an automated way. It also allows to select between different alternative estimation algorithms which themselves achieve regularization. - Details are described in :footcite:`EngemannGramfort2015`. + Details are described in :footcite:t:`EngemannGramfort2015`. For more information on the advanced estimation methods, see :ref:`the sklearn manual `. diff --git a/mne/forward/_make_forward.py b/mne/forward/_make_forward.py index 491f1dc5e9c..8bd50339529 100644 --- a/mne/forward/_make_forward.py +++ b/mne/forward/_make_forward.py @@ -626,13 +626,15 @@ def make_forward_solution( src : path-like | instance of SourceSpaces Either a path to a source space file or a loaded or generated :class:`~mne.SourceSpaces`. - bem : path-like | dict + bem : path-like | ConductorModel Filename of the BEM (e.g., ``"sample-5120-5120-5120-bem-sol.fif"``) to - use, or a loaded sphere model (dict). + use, or a loaded :class:`~mne.bem.ConductorModel`. See + :func:`~mne.make_bem_model` and :func:`~mne.make_bem_solution` to create a + :class:`mne.bem.ConductorModel`. meg : bool - If True (Default), include MEG computations. + If True (default), include MEG computations. eeg : bool - If True (Default), include EEG computations. + If True (default), include EEG computations. mindist : float Minimum distance of sources from inner skull surface (in mm). ignore_ref : bool diff --git a/mne/minimum_norm/inverse.py b/mne/minimum_norm/inverse.py index 0af04a9d07d..e505b155490 100644 --- a/mne/minimum_norm/inverse.py +++ b/mne/minimum_norm/inverse.py @@ -1896,15 +1896,17 @@ def make_inverse_operator( %(info_not_none)s Specifies the channels to include. Bad channels (in ``info['bads']``) are not used. - forward : dict - Forward operator. + forward : instance of Forward + Forward operator. See :func:`~mne.make_forward_solution` to create the operator. noise_cov : instance of Covariance - The noise covariance matrix. + The noise covariance matrix. See :func:`~mne.compute_raw_covariance` and + :func:`~mne.compute_covariance` to compute the noise covariance matrix on + :class:`~mne.io.Raw` and :class:`~mne.Epochs` respectively. %(loose)s %(depth)s fixed : bool | 'auto' Use fixed source orientations normal to the cortical mantle. If True, - the loose parameter must be "auto" or 0. If 'auto', the loose value + the loose parameter must be ``"auto"`` or ``0``. If ``'auto'``, the loose value is used. %(rank_none)s %(use_cps)s @@ -1951,7 +1953,7 @@ def make_inverse_operator( and without this information. For depth weighting, 0.8 is generally good for MEG, and between 2 and 5 - is good for EEG, see :footcite:`LinEtAl2006a`. + is good for EEG, see :footcite:t:`LinEtAl2006a`. References ---------- diff --git a/mne/source_space/_source_space.py b/mne/source_space/_source_space.py index 3e5f2eb91f3..653645a59ed 100644 --- a/mne/source_space/_source_space.py +++ b/mne/source_space/_source_space.py @@ -119,18 +119,17 @@ class SourceSpaces(list): ---------- source_spaces : list A list of dictionaries containing the source space information. - info : dict + info : dict | None Dictionary with information about the creation of the source space - file. Has keys 'working_dir' and 'command_line'. + file. Has keys ``'working_dir'`` and ``'command_line'``. Attributes ---------- - kind : str - The kind of source space, one of - ``{'surface', 'volume', 'discrete', 'mixed'}``. + kind : ``'surface'`` | ``'volume'`` | ``'discrete'`` | ``'mixed'`` + The kind of source space. info : dict Dictionary with information about the creation of the source space - file. Has keys 'working_dir' and 'command_line'. + file. Has keys ``'working_dir'`` and ``'command_line'``. See Also -------- @@ -510,7 +509,7 @@ def save(self, fname, overwrite=False, *, verbose=None): Parameters ---------- fname : path-like - File to write. + File to write, which should end with ``-src.fif`` or ``-src.fif.gz``. %(overwrite)s %(verbose)s """ @@ -540,8 +539,8 @@ def export_volume( include_discrete : bool If True, include discrete source spaces. dest : ``'mri'`` | ``'surf'`` - If 'mri' the volume is defined in the coordinate system of the - original T1 image. If 'surf' the coordinate system of the + If ``'mri'`` the volume is defined in the coordinate system of the + original T1 image. If ``'surf'`` the coordinate system of the FreeSurfer surface is used (Surface RAS). trans : dict, str, or None Either a transformation filename (usually made using mne_analyze) @@ -559,7 +558,7 @@ def export_volume( source point. .. versionchanged:: 0.21.0 - Support for "sparse" was added. + Support for ``"sparse"`` was added. use_lut : bool If True, assigns a numeric value to each source space that corresponds to a color on the freesurfer lookup table. @@ -1653,6 +1652,8 @@ def setup_volume_source_space( add_interpolator=True, sphere_units="m", single_volume=False, + *, + n_jobs=None, verbose=None, ): """Set up a volume source space with grid spacing or discrete source space. @@ -1662,12 +1663,12 @@ def setup_volume_source_space( subject : str | None Subject to process. If None, the path to the MRI volume must be absolute to get a volume source space. If a subject name - is provided the T1.mgz file will be found automatically. + is provided the ``T1.mgz`` file will be found automatically. Defaults to None. pos : float | dict Positions to use for sources. If float, a grid will be constructed with the spacing given by ``pos`` in mm, generating a volume source - space. If dict, pos['rr'] and pos['nn'] will be used as the source + space. If dict, ``pos['rr']`` and ``pos['nn']`` will be used as the source space locations (in meters) and normals, respectively, creating a discrete source space. @@ -1679,21 +1680,24 @@ def setup_volume_source_space( volume source space can then be morphed onto the MRI volume using this interpolator. If pos is a dict, this cannot be None. If subject name is provided, ``pos`` is a float or ``volume_label`` - are not provided then the ``mri`` parameter will default to 'T1.mgz' + are not provided then the ``mri`` parameter will default to ``'T1.mgz'`` or ``aseg.mgz``, respectively, else it will stay None. sphere : ndarray, shape (4,) | ConductorModel | None Define spherical source space bounds using origin and radius given - by (ox, oy, oz, rad) in ``sphere_units``. + by ``(Ox, Oy, Oz, rad)`` in ``sphere_units``. Only used if ``bem`` and ``surface`` are both None. Can also be a spherical ConductorModel, which will use the origin and radius. None (the default) uses a head-digitization fit. bem : path-like | None | ConductorModel Define source space bounds using a BEM file (specifically the inner - skull surface) or a ConductorModel for a 1-layer of 3-layers BEM. + skull surface) or a :class:`~mne.bem.ConductorModel` for a 1-layer of 3-layers + BEM. See :func:`~mne.make_bem_model` and :func:`~mne.make_bem_solution` to + create a :class:`~mne.bem.ConductorModel`. If provided, ``surface`` must be + None. surface : path-like | dict | None Define source space bounds using a FreeSurfer surface file. Can also be a dictionary with entries ``'rr'`` and ``'tris'``, such as - those returned by :func:`mne.read_surface`. + those returned by :func:`mne.read_surface`. If provided, ``bem`` must be None. mindist : float Exclude points closer than this distance (mm) to the bounding surface. exclude : float @@ -1725,6 +1729,9 @@ def setup_volume_source_space( when many labels are used. .. versionadded:: 0.21 + %(n_jobs)s + + .. versionadded:: 1.6 %(verbose)s Returns @@ -1781,7 +1788,7 @@ def setup_volume_source_space( ) if bem is not None and surface is not None: - raise ValueError('Only one of "bem" and "surface" should be ' "specified") + raise ValueError("Only one of 'bem' and 'surface' should be specified.") if mri is None and subject is not None: if volume_label is not None: @@ -1908,6 +1915,7 @@ def setup_volume_source_space( mindist, mri, volume_label, + n_jobs=n_jobs, vol_info=vol_info, single_volume=single_volume, ) diff --git a/mne/time_frequency/multitaper.py b/mne/time_frequency/multitaper.py index b5e63b62682..a3ccad28080 100644 --- a/mne/time_frequency/multitaper.py +++ b/mne/time_frequency/multitaper.py @@ -341,7 +341,7 @@ def psd_array_multitaper( r"""Compute power spectral density (PSD) using a multi-taper method. The power spectral density is computed with DPSS - tapers\ :footcite:p:`Slepian1978`. + tapers :footcite:p:`Slepian1978`. Parameters ---------- diff --git a/mne/utils/docs.py b/mne/utils/docs.py index 9367562c7a1..53a394022a3 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -2542,8 +2542,8 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): _method_psd = r""" method : ``'welch'`` | ``'multitaper'``{} Spectral estimation method. ``'welch'`` uses Welch's - method\ :footcite:p:`Welch1967`, ``'multitaper'`` uses DPSS - tapers\ :footcite:p:`Slepian1978`.{} + method :footcite:p:`Welch1967`, ``'multitaper'`` uses DPSS + tapers :footcite:p:`Slepian1978`.{} """ docdict["method_plot_psd_auto"] = _method_psd.format( " | ``'auto'``", @@ -4660,7 +4660,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): docdict[ "trans" ] = f""" -trans : path-like | dict | instance of Transform | None +trans : path-like | dict | instance of Transform | ``"fsaverage"`` | None {_trans_base} If trans is None, an identity matrix is assumed. """ diff --git a/mne/viz/evoked.py b/mne/viz/evoked.py index c222400f0e3..34a9d60dfe3 100644 --- a/mne/viz/evoked.py +++ b/mne/viz/evoked.py @@ -1623,14 +1623,19 @@ def whitened_gfp(x, rank=None): _validate_type(axes, (list, tuple, np.ndarray, None), "axes") if axes is None: _, axes = plt.subplots( - n_rows, n_columns, sharex=True, sharey=False, figsize=(8.8, 2.2 * n_rows) + n_rows, + n_columns, + sharex=True, + sharey=False, + figsize=(8.8, 2.2 * n_rows), + constrained_layout=True, ) else: axes = np.array(axes) for ai, ax in enumerate(axes.flat): _validate_type(ax, plt.Axes, "axes.flat[%d]" % (ai,)) if axes.shape != want_shape: - raise ValueError(f"axes must have shape {want_shape}, got " f"{axes.shape}") + raise ValueError(f"axes must have shape {want_shape}, got {axes.shape}.") fig = axes.flat[0].figure if n_columns > 1: suptitle = ( @@ -1724,12 +1729,6 @@ def whitened_gfp(x, rank=None): ) else: ax.legend(loc="upper right", prop=dict(size=10)) - params = dict( - top=[0.69, 0.82, 0.87][n_rows - 1], bottom=[0.22, 0.13, 0.09][n_rows - 1] - ) - if has_sss: - params["hspace"] = 0.49 - fig.subplots_adjust(**params) fig.canvas.draw() plt_show(show) diff --git a/tutorials/forward/90_compute_covariance.py b/tutorials/forward/90_compute_covariance.py index 71052ec33f6..20992900e73 100644 --- a/tutorials/forward/90_compute_covariance.py +++ b/tutorials/forward/90_compute_covariance.py @@ -109,8 +109,8 @@ # available. Unfortunately it is not easy to tell the effective number of # samples, hence, to choose the appropriate regularization. # In MNE-Python, regularization is done using advanced regularization methods -# described in :footcite:p:`EngemannGramfort2015`. For this the 'auto' option -# can be used. With this option cross-validation will be used to learn the +# described in :footcite:t:`EngemannGramfort2015`. For this the ``'auto'`` option +# can be used. With this option, cross-validation will be used to learn the # optimal regularization: noise_cov_reg = mne.compute_covariance(epochs, tmax=0.0, method="auto", rank=None) @@ -160,14 +160,12 @@ evoked.plot_white(noise_covs, time_unit="s") -############################################################################## +# %% # This will plot the whitened evoked for the optimal estimator and display the # :term:`GFP` for all estimators as separate lines in the related panel. - - -############################################################################## +# # Finally, let's have a look at the difference between empty room and -# event related covariance, hacking the "method" option so that their types +# event related covariance, hacking the ``"method"`` option so that their types # are shown in the legend of the plot. evoked_meg = evoked.copy().pick("meg") @@ -175,13 +173,12 @@ noise_cov_baseline["method"] = "baseline" evoked_meg.plot_white([noise_cov_baseline, noise_cov], time_unit="s") -############################################################################## +# %% # Based on the negative log-likelihood, the baseline covariance # seems more appropriate. Improper regularization can lead to overestimation of # source amplitudes, see :footcite:p:`EngemannGramfort2015` for more # information and examples. - -# %% +# # References # ---------- # diff --git a/tutorials/inverse/30_mne_dspm_loreta.py b/tutorials/inverse/30_mne_dspm_loreta.py index d77f0f98985..90d688eafc9 100644 --- a/tutorials/inverse/30_mne_dspm_loreta.py +++ b/tutorials/inverse/30_mne_dspm_loreta.py @@ -90,13 +90,18 @@ ) del fwd -# You can write it to disk with:: -# -# >>> from mne.minimum_norm import write_inverse_operator -# >>> write_inverse_operator('sample_audvis-meg-oct-6-inv.fif', -# inverse_operator) - # %% +# .. note:: +# +# You can write the inverse operator to disk with: +# +# .. code-block:: +# +# from mne.minimum_norm import write_inverse_operator +# write_inverse_operator( +# "sample_audvis-meg-oct-6-inv.fif", inverse_operator +# ) +# # Compute inverse solution # ------------------------ # We can use this to compute the inverse solution and obtain source time