[MRG] Improve docstring format and support floats for conductivity in make_bem_model

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/{<subject>}-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:
 

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
-    <https://github.com/mne-tools/mne-python/blob/main/mne/io/constants.py#L186-L197>`__.
+    <https://github.com/mne-tools/mne-python/blob/079c868240a898204bf82b2f1bf0e04cdee75da1/mne/_fiff/constants.py#L263-L275>`__.
 
 The coordinate systems used in MNE software (and FreeSurfer) and their
 relationships are depicted in :ref:`coordinate_system_figure`. Except for the

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

mne/cov.py

@@ -883,7 +883,7 @@ def compute_covariance(
     rank=None,
     verbose=None,
 ):
-    """Estimate noise covariance matrix from epochs.
+    r"""Estimate noise covariance matrix from epochs.
 
     The noise covariance is typically estimated on pre-stimulus periods
     when the stimulus onset is defined from events.
@@ -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 <sklearn:covariance>`.

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

mne/minimum_norm/inverse.py

@@ -922,7 +922,7 @@ def apply_inverse(
     use_cps=True,
     verbose=None,
 ):
-    """Apply inverse operator to evoked data.
+    r"""Apply inverse operator to evoked data.
 
     Parameters
     ----------
@@ -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 : 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
+        :classl:`~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
     ----------

mne/source_space/_source_space.py

@@ -1653,6 +1653,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 +1664,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 +1681,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 +1730,7 @@ def setup_volume_source_space(
         when many labels are used.
 
         .. versionadded:: 0.21
+    %(n_jobs)s
     %(verbose)s
 
     Returns
@@ -1781,7 +1787,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 +1914,7 @@ def setup_volume_source_space(
             mindist,
             mri,
             volume_label,
+            n_jobs=n_jobs,
             vol_info=vol_info,
             single_volume=single_volume,
         )

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

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.
 """