Fix docstrings (mne-tools#6385)

* docstring deduplication

* more n_jobs

* fix: import fill_doc

* fix crossrefs; deduplicate docdict def for random_state

mne/cov.py

@@ -378,8 +378,7 @@ def compute_raw_covariance(raw, tmin=0, tmax=None, tstep=0.2, reject=None,
         at the same unit.
 
         .. versionadded:: 0.12
-    n_jobs : int (default 1)
-        Number of jobs to run in parallel.
+    %(n_jobs)s
 
         .. versionadded:: 0.12
     return_estimators : bool (default False)
@@ -627,8 +626,7 @@ def compute_covariance(epochs, keep_sample_mean=True, tmin=None, tmax=None,
         Defaults to ``dict(mag=1e15, grad=1e13, eeg=1e6)``.
         These defaults will scale data to roughly the same order of
         magnitude.
-    n_jobs : int (default 1)
-        Number of jobs to run in parallel.
+    %(n_jobs)s
     return_estimators : bool (default False)
         Whether to return all estimators or the best. Only considered if
         method equals 'auto' or is a list of str. Defaults to False

mne/decoding/base.py

@@ -11,7 +11,7 @@
 import numbers
 from ..parallel import parallel_func
 from ..fixes import BaseEstimator, is_classifier
-from ..utils import check_version, logger, warn
+from ..utils import check_version, logger, warn, fill_doc
 
 
 class LinearModel(BaseEstimator):
@@ -366,6 +366,7 @@ def get_coef(estimator, attr='filters_', inverse_transform=False):
     return coef
 
 
+@fill_doc
 def cross_val_multiscore(estimator, X, y=None, groups=None, scoring=None,
                          cv=None, n_jobs=1, verbose=0, fit_params=None,
                          pre_dispatch='2*n_jobs'):
@@ -405,9 +406,7 @@ def cross_val_multiscore(estimator, X, y=None, groups=None, scoring=None,
         either binary or multiclass,
         :class:`sklearn.model_selection.StratifiedKFold` is used. In all
         other cases, :class:`sklearn.model_selection.KFold` is used.
-    n_jobs : int, optional
-        The number of CPUs to use to do the computation. -1 means
-        'all CPUs'.
+    %(n_jobs)s
     verbose : int, optional
         The verbosity level.
     fit_params : dict, optional

mne/decoding/ems.py

@@ -123,8 +123,7 @@ def compute_ems(epochs, conditions=None, picks=None, n_jobs=1, cv=None,
         well as the number of conditions supported by the objective_function.
         If None keys in epochs.event_id are used.
     %(picks_good_data)s
-    n_jobs : int, default 1
-        Number of jobs to run in parallel.
+    %(n_jobs)s
     cv : cross-validation object | str | None, default LeaveOneOut
         The cross-validation scheme.
     %(verbose)s

mne/decoding/search_light.py

@@ -30,7 +30,7 @@ class SlidingEstimator(BaseEstimator, TransformerMixin):
         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).
-    n_jobs : int, optional (default=1)
+    %(n_jobs)s
         The number of jobs to run in parallel for both `fit` and `predict`.
         If -1, then the number of jobs is set to the number of cores.
     %(verbose)s
@@ -436,7 +436,7 @@ class GeneralizingEstimator(SlidingEstimator):
         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).
-    n_jobs : int, optional (default=1)
+    %(n_jobs)s
         The number of jobs to run in parallel for both `fit` and `predict`.
         If -1, then the number of jobs is set to the number of cores.
     %(verbose)s

mne/decoding/time_frequency.py

@@ -48,7 +48,7 @@ class TimeFrequency(TransformerMixin, BaseEstimator):
         * 'complex' : single trial complex.
         * 'power' : single trial power.
         * 'phase' : single trial phase.
-    n_jobs : int, default 1
+    %(n_jobs)s
         The number of epochs to process at the same time. The parallelization
         is implemented across channels.
     %(verbose)s

mne/dipole.py

@@ -1011,9 +1011,8 @@ def fit_dipole(evoked, cov, bem, trans=None, min_dist=5., n_jobs=1,
         Must be positive. Note that because this is a constraint passed to
         a solver it is not strict but close, i.e. for a ``min_dist=5.`` the
         fits could be 4.9 mm from the inner skull.
-    n_jobs : int
-        Number of jobs to run in parallel (used in field computation
-        and fitting).
+    %(n_jobs)s
+        It is used in field computation and fitting.
     pos : ndarray, shape (3,) | None
         Position of the dipole to use. If None (default), sequential
         fitting (different position and orientation for each time instance)

mne/epochs.py

@@ -2482,15 +2482,15 @@ def _get_epoch_from_raw(self, idx, verbose=None):
         return data
 
 
+@fill_doc
 def bootstrap(epochs, random_state=None):
     """Compute epochs selected by bootstrapping.
 
     Parameters
     ----------
     epochs : Epochs instance
         epochs data to be bootstrapped
-    random_state : None | int | np.random.RandomState
-        To specify the random generator state
+    %(random_state)s
 
     Returns
     -------

mne/forward/_compute_forward.py

@@ -19,7 +19,7 @@
 from ..surface import fast_cross_3d, _project_onto_surface
 from ..io.constants import FIFF, FWD
 from ..transforms import apply_trans
-from ..utils import logger, verbose, _pl, warn
+from ..utils import logger, verbose, _pl, warn, fill_doc
 from ..parallel import parallel_func
 from ..io.compensator import get_current_comp, make_compensator
 from ..io.pick import pick_types
@@ -59,6 +59,7 @@ def _check_coil_frame(coils, coord_frame, bem):
     return coils, coord_frame
 
 
+@fill_doc
 def _lin_field_coeff(surf, mult, rmags, cosmags, ws, bins, n_jobs):
     """Parallel wrapper for _do_lin_field_coeff to compute linear coefficients.
 
@@ -77,8 +78,7 @@ def _lin_field_coeff(surf, mult, rmags, cosmags, ws, bins, n_jobs):
         Weights for MEG coil integration points
     bins : ndarray, shape (n_integration_points,)
         The sensor assignments for each rmag/cosmag/w.
-    n_jobs : int
-        Number of jobs to run in parallel
+    %(n_jobs)s
 
     Returns
     -------
@@ -169,6 +169,7 @@ def _concatenate_coils(coils):
     return rmags, cosmags, ws, bins
 
 
+@fill_doc
 def _bem_specify_coils(bem, coils, coord_frame, mults, n_jobs):
     """Set up for computing the solution at a set of MEG coils.
 
@@ -182,8 +183,7 @@ def _bem_specify_coils(bem, coils, coord_frame, mults, n_jobs):
         Class constant identifying coordinate frame
     mults : ndarray, shape (1, n_BEM_vertices)
         Multiplier for every vertex in BEM
-    n_jobs : int
-        Number of jobs to run in parallel
+    %(n_jobs)s
 
     Returns
     -------
@@ -381,6 +381,7 @@ def _bem_inf_fields(rr, rmag, cosmag):
     return np.rollaxis(x / diff_norm, 1)
 
 
+@fill_doc
 def _bem_pot_or_field(rr, mri_rr, mri_Q, coils, solution, bem_rr, n_jobs,
                       coil_type):
     """Calculate the magnetic field or electric potential forward solution.
@@ -403,8 +404,7 @@ def _bem_pot_or_field(rr, mri_rr, mri_Q, coils, solution, bem_rr, n_jobs,
         Comes from _bem_specify_coils
     bem_rr : ndarray, shape (n_BEM_vertices, 3)
         3D vertex positions for all surfaces in the BEM
-    n_jobs : int
-        Number of jobs to run in parallel
+    %(n_jobs)s
     coil_type : str
         'meg' or 'eeg'
 
@@ -686,8 +686,7 @@ def _prep_field_computation(rr, bem, fwd_data, n_jobs, verbose=None):
     fwd_data : dict
         Dict containing sensor information. Gets updated here with BEM and
         sensor information for later forward calculations
-    n_jobs : int
-        Number of jobs to run in parallel
+    %(n_jobs)s
     %(verbose)s
     """
     bem_rr = mults = mri_Q = head_mri_t = None
@@ -769,8 +768,7 @@ def _compute_forwards_meeg(rr, fd, n_jobs, verbose=None):
         3D dipole positions in head coordinates
     fd : dict
         Dict containing forward data after update in _prep_field_computation
-    n_jobs : int
-        Number of jobs to run in parallel
+    %(n_jobs)s
     %(verbose)s
 
     Returns
@@ -840,8 +838,7 @@ def _compute_forwards(rr, bem, coils_list, ccoils_list, infos, coil_types,
         Optional list of MEG compensation information
     coil_types : list of str
         Sensor types. May contain 'meg' and/or 'eeg'
-    n_jobs: int
-        Number of jobs to run in parallel
+    %(n_jobs)s
     infos : list, len(2)
         infos[0] is MEG info, infos[1] is EEG info
 

mne/forward/_lead_dots.py

@@ -12,7 +12,7 @@
 
 from ..fixes import einsum
 from ..parallel import parallel_func
-from ..utils import logger, verbose, _get_extra_data_path
+from ..utils import logger, verbose, _get_extra_data_path, fill_doc
 
 
 ##############################################################################
@@ -284,6 +284,7 @@ def _fast_sphere_dot_r0(r, rr1_orig, rr2s, lr1, lr2s, cosmags1, cosmags2s,
     return out
 
 
+@fill_doc
 def _do_self_dots(intrad, volume, coils, r0, ch_type, lut, n_fact, n_jobs):
     """Perform the lead field dot product integrations.
 
@@ -304,8 +305,7 @@ def _do_self_dots(intrad, volume, coils, r0, ch_type, lut, n_fact, n_jobs):
         Look-up table for evaluating Legendre polynomials.
     n_fact : array
         Coefficients in the integration sum.
-    n_jobs : int
-        Number of jobs to run in parallel.
+    %(n_jobs)s
 
     Returns
     -------
@@ -400,6 +400,7 @@ def _do_cross_dots(intrad, volume, coils1, coils2, r0, ch_type,
     return products
 
 
+@fill_doc
 def _do_surface_dots(intrad, volume, coils, surf, sel, r0, ch_type,
                      lut, n_fact, n_jobs):
     """Compute the map construction products.
@@ -425,8 +426,7 @@ def _do_surface_dots(intrad, volume, coils, surf, sel, r0, ch_type,
         Look-up table for Legendre polynomials.
     n_fact : array
         Coefficients in the integration sum.
-    n_jobs : int
-        Number of jobs to run in parallel.
+    %(n_jobs)s
 
     Returns
     -------

mne/forward/_make_forward.py

@@ -533,8 +533,7 @@ def make_forward_solution(info, trans, src, bem, meg=True, eeg=True,
         If True, do not include reference channels in compensation. This
         option should be True for KIT files, since forward computation
         with reference channels is not currently supported.
-    n_jobs : int
-        Number of jobs to run in parallel.
+    %(n_jobs)s
     %(verbose)s
 
     Returns
@@ -648,8 +647,7 @@ def make_forward_dipole(dipole, bem, info, trans=None, n_jobs=1, verbose=None):
     trans : str | None
         The head<->MRI transform filename. Must be provided unless BEM
         is a sphere model.
-    n_jobs : int
-        Number of jobs to run in parallel (used in making forward solution).
+    %(n_jobs)s
     %(verbose)s
 
     Returns

mne/inverse_sparse/mxne_debiasing.py

@@ -7,9 +7,10 @@
 import numpy as np
 from scipy import linalg
 
-from ..utils import check_random_state, logger, verbose
+from ..utils import check_random_state, logger, verbose, fill_doc
 
 
+@fill_doc
 def power_iteration_kron(A, C, max_iter=1000, tol=1e-3, random_state=0):
     """Find the largest singular value for the matrix kron(C.T, A).
 
@@ -23,8 +24,7 @@ def power_iteration_kron(A, C, max_iter=1000, tol=1e-3, random_state=0):
         An array
     max_iter : int
         Maximum number of iterations
-    random_state : int | RandomState | None
-        Random state for random number generation
+    %(random_state)s
 
     Returns
     -------

mne/label.py

@@ -486,8 +486,7 @@ def smooth(self, subject=None, smooth=2, grade=None,
             a label filling the surface, use None.
         subjects_dir : str, or None
             Path to SUBJECTS_DIR if it is not set in the environment.
-        n_jobs : int
-            Number of jobs to run in parallel
+        %(n_jobs)s
         %(verbose_meth)s
 
         Returns
@@ -536,8 +535,7 @@ def morph(self, subject_from=None, subject_to=None, smooth=5, grade=None,
             a label filling the surface, use None.
         subjects_dir : str, or None
             Path to SUBJECTS_DIR if it is not set in the environment.
-        n_jobs : int
-            Number of jobs to run in parallel.
+        %(n_jobs)s
         %(verbose_meth)s
 
         Returns
@@ -1462,6 +1460,7 @@ def _grow_labels(seeds, extents, hemis, names, dist, vert, subject):
     return labels
 
 
+@fill_doc
 def grow_labels(subject, seeds, extents, hemis, subjects_dir=None, n_jobs=1,
                 overlap=True, names=None, surface='white'):
     """Generate circular labels in source space with region growing.
@@ -1489,10 +1488,9 @@ def grow_labels(subject, seeds, extents, hemis, subjects_dir=None, n_jobs=1,
         Hemispheres to use for the labels (0: left, 1: right).
     subjects_dir : string
         Path to SUBJECTS_DIR if not set in the environment.
-    n_jobs : int
-        Number of jobs to run in parallel. Likely only useful if tens
-        or hundreds of labels are being expanded simultaneously. Does not
-        apply with ``overlap=False``.
+    %(n_jobs)s
+        Likely only useful if tens or hundreds of labels are being expanded
+        simultaneously. Does not apply with ``overlap=False``.
     overlap : bool
         Produce overlapping labels. If True (default), the resulting labels
         can be overlapping. If False, each label will be grown one step at a
@@ -1649,6 +1647,7 @@ def _grow_nonoverlapping_labels(subject, seeds_, extents_, hemis, vertices_,
     return labels
 
 
+@fill_doc
 def random_parcellation(subject, n_parcel, hemi, subjects_dir=None,
                         surface='white', random_state=None):
     """Generate random cortex parcellation by growing labels.
@@ -1671,11 +1670,7 @@ def random_parcellation(subject, n_parcel, hemi, subjects_dir=None,
         Path to SUBJECTS_DIR if not set in the environment.
     surface : string
         The surface used to grow the labels, defaults to the white surface.
-    random_state : None | int | instance of ~numpy.random.mtrand.RandomState
-        If ``random_state`` is an :class:`int`, it will be used as a seed for
-        ~numpy.random.mtrand.RandomState. If ``None``, the seed will be
-        obtained from the operating system (see
-        ~numpy.random.mtrand.RandomState for details). Default is ``None``.
+    %(random_state)s
 
     Returns
     -------
@@ -2436,6 +2431,7 @@ def write_labels_to_annot(labels, subject=None, parc=None, overwrite=False,
         _write_annot(fname, annot, ctab, hemi_names)
 
 
+@fill_doc
 def select_sources(subject, label, location='center', extent=0.,
                    grow_outside=True, subjects_dir=None, name=None,
                    random_state=None, surf='white'):
@@ -2463,8 +2459,7 @@ def select_sources(subject, label, location='center', extent=0.,
         Path to SUBJECTS_DIR if not set in the environment.
     name : None | str
         Assign name to the new label.
-    random_state : None | int | ~numpy.random.mtrand.RandomState
-        To specify the random generator state.
+    %(random_state)s
     surf : string
         The surface used to simulated the label, defaults to the white surface.