[MRG] Improve docstring format and support floats for conductivity in make_bem_model (mne-tools#12020)

Co-authored-by: Daniel McCloy <dan@mccloy.info>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

Author: 4 people

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

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

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