[DOC] Clean up docstring formatting (#283)

Co-authored-by: Daniel McCloy <[email protected]>

doc/conf.py

@@ -133,6 +133,8 @@
     "n_events",
     "n_cons",
     "max_n_chans",
+    "n_seeds",
+    "n_targets",
     "n_unique_seeds",
     "n_unique_targets",
     "variable",

mne_connectivity/datasets/frequency.py

@@ -14,11 +14,11 @@ def make_signals_in_freq_bands(
     freq_band,
     n_epochs=10,
     n_times=200,
-    sfreq=100,
-    trans_bandwidth=1,
+    sfreq=100.0,
+    trans_bandwidth=1.0,
     snr=0.7,
     connection_delay=5,
-    tmin=0,
+    tmin=0.0,
     ch_names=None,
     ch_types="eeg",
     rng_seed=None,
@@ -31,17 +31,17 @@ def make_signals_in_freq_bands(
         Number of seed channels to simulate.
     n_targets : int
         Number of target channels to simulate.
-    freq_band : tuple of int or float
+    freq_band : tuple of float
         Frequency band where the connectivity should be simulated, where the first entry
         corresponds to the lower frequency, and the second entry to the higher
         frequency.
     n_epochs : int (default 10)
         Number of epochs in the simulated data.
     n_times : int (default 200)
         Number of timepoints each epoch of the simulated data.
-    sfreq : int | float (default 100)
+    sfreq : float (default 100.0)
         Sampling frequency of the simulated data, in Hz.
-    trans_bandwidth : int | float (default 1)
+    trans_bandwidth : float (default 1.0)
         Transition bandwidth of the filter to apply to isolate activity in
         ``freq_band``, in Hz. These are passed to the ``l_bandwidth`` and
         ``h_bandwidth`` keyword arguments in :func:`mne.filter.create_filter`.
@@ -51,23 +51,24 @@ def make_signals_in_freq_bands(
         Number of timepoints for the delay of connectivity between the seeds and
         targets. If > 0, the target data is a delayed form of the seed data. If < 0, the
         seed data is a delayed form of the target data.
-    tmin : int | float (default 0)
+    tmin : float (default 0.0)
         Earliest time of each epoch.
     ch_names : list of str | None (default None)
-        Names of the channels in the simulated data. If `None`, the channels are named
+        Names of the channels in the simulated data. If ``None``, the channels are named
         according to their index and the frequency band of interaction. If specified,
         must be a list of ``n_seeds + n_targets`` channel names.
-    ch_types : str | list of str (default "eeg")
-        Types of the channels in the simulated data. If specified as a list, must be a
+    ch_types : str | list of str (default ``'eeg'``)
+        Types of the channels in the simulated data. Must be a recognised data channel
+        type (see :term:`mne:data channels`). If specified as a list, must be a
         list of ``n_seeds + n_targets`` channel names.
     rng_seed : int | None (default None)
-        Seed to use for the random number generator. If `None`, no seed is specified.
+        Seed to use for the random number generator. If ``None``, no seed is specified.
 
     Returns
     -------
-    epochs : mne.EpochsArray of shape (n_epochs, ``n_seeds + n_targets``, n_times)
-        The simulated data stored in an `mne.EpochsArray` object. The channels are
-        arranged according to seeds, then targets.
+    epochs : ~mne.EpochsArray, shape (n_epochs, n_seeds + n_targets, n_times)
+        The simulated data stored in an :class:`mne.EpochsArray` object. The channels
+        are arranged according to seeds, then targets.
 
     Notes
     -----

mne_connectivity/datasets/surrogate.py

@@ -3,7 +3,7 @@
 # License: BSD (3-clause)
 
 import numpy as np
-from mne.time_frequency import EpochsSpectrum, EpochsSpectrumArray
+from mne.time_frequency import EpochsSpectrum
 from mne.utils import _validate_type
 
 
@@ -12,25 +12,25 @@ def make_surrogate_data(data, n_shuffles=1000, rng_seed=None, return_generator=T
 
     Parameters
     ----------
-    data : ~mne.time_frequency.EpochsSpectrum | ~mne.time_frequency.EpochsSpectrumArray
+    data : ~mne.time_frequency.EpochsSpectrum
         The Fourier coefficients to create the null hypothesis surrogate data for. Can
         be generated from :meth:`mne.Epochs.compute_psd` with ``output='complex'``
         (requires ``mne >= 1.8``).
     n_shuffles : int (default 1000)
         The number of surrogate datasets to create.
     rng_seed : int | None (default None)
-        The seed to use for the random number generator. If `None`, no seed is
+        The seed to use for the random number generator. If ``None``, no seed is
         specified.
     return_generator : bool (default True)
-        Whether or not to return the surrogate data as a :term:`generator` object
-        instead of a :class:`list`. This allows iterating over the surrogates without
-        having to keep them all in memory.
+        Whether or not to return the surrogate data as a generator object instead of a
+        list. This allows iterating over the surrogates without having to keep them all
+        in memory.
 
     Returns
     -------
     surrogate_data : list of ~mne.time_frequency.EpochsSpectrum
         The surrogate data for the null hypothesis with ``n_shuffles`` entries. Returned
-        as a :term:`generator` if ``return_generator=True``.
+        as a generator if ``return_generator=True``.
 
     Notes
     -----
@@ -78,7 +78,7 @@ def make_surrogate_data(data, n_shuffles=1000, rng_seed=None, return_generator=T
     # Validate inputs
     _validate_type(
         data,
-        (EpochsSpectrum, EpochsSpectrumArray),
+        (EpochsSpectrum),
         "data",
         "mne.time_frequency.EpochsSpectrum or mne.time_frequency.EpochsSpectrumArray",
     )

mne_connectivity/decoding/decomposition.py

@@ -62,17 +62,17 @@ class CoherencyDecomposition(BaseEstimator, TransformerMixin):
     Once fit, the filters can be used to transform data into the underlying connectivity
     components. Connectivity can be computed on this transformed data using the
     bivariate coherency-based methods of the
-    `mne_connectivity.spectral_connectivity_epochs` and
-    `mne_connectivity.spectral_connectivity_time` functions. These bivariate methods
-    are:
+    :func:`~mne_connectivity.spectral_connectivity_epochs` and
+    :func:`~mne_connectivity.spectral_connectivity_time` functions. These bivariate
+    methods are:
 
     * ``"cohy"`` and ``"coh"`` for CaCoh :footcite:`VidaurreEtAl2019`
     * ``"imcoh"`` for MIC :footcite:`EwaldEtAl2012`
 
     The approach taken here is to optimise the connectivity in a given frequency band.
     Frequency bin-wise optimisation is offered in the multivariate coherency-based
-    methods of the `mne_connectivity.spectral_connectivity_epochs` and
-    `mne_connectivity.spectral_connectivity_time` functions.
+    methods of the :func:`~mne_connectivity.spectral_connectivity_epochs` and
+    :func:`~mne_connectivity.spectral_connectivity_time` functions.
 
     References
     ----------
@@ -131,7 +131,7 @@ def __init__(
         mt_adaptive=False,
         mt_low_bias=True,
         cwt_freqs=None,
-        cwt_n_cycles=7,
+        cwt_n_cycles=7.0,
         n_components=None,
         rank=None,
         n_jobs=1,
@@ -277,7 +277,7 @@ def fit(self, X, y=None):
 
         Parameters
         ----------
-        X : array, shape=(n_epochs, n_signals, n_times)
+        X : array, shape (n_epochs, n_signals, n_times)
             The input data which the connectivity decomposition filters should be fit
             to.
         y : None
@@ -397,12 +397,12 @@ def transform(self, X):
 
         Parameters
         ----------
-        X : array, shape=((n_epochs, ) n_signals, n_times)
+        X : array, shape ([n_epochs,] n_signals, n_times)
             The data to be transformed by the connectivity decomposition filters.
 
         Returns
         -------
-        X_transformed : array, shape=((n_epochs, ) n_components*2, n_times)
+        X_transformed : array, shape ([n_epochs,] n_components*2, n_times)
             The transformed data. The first ``n_components`` channels are the
             transformed seeds, and the last ``n_components`` channels are the
             transformed targets.
@@ -424,7 +424,7 @@ def fit_transform(self, X, y=None, **fit_params):
 
         Parameters
         ----------
-        X : array, shape=(n_epochs, n_signals, n_times)
+        X : array, shape (n_epochs, n_signals, n_times)
             The input data which the connectivity decomposition filters should be fit to
             and subsequently transformed.
         y : None
@@ -435,7 +435,7 @@ def fit_transform(self, X, y=None, **fit_params):
 
         Returns
         -------
-        X_transformed : array, shape=(n_epochs, n_components*2, n_times)
+        X_transformed : array, shape (n_epochs, n_components*2, n_times)
             The transformed data. The first ``n_components`` channels are the
             transformed seeds, and the last ``n_components`` channels are the
             transformed targets.
@@ -449,11 +449,11 @@ def get_transformed_indices(self):
         Returns
         -------
         indices_transformed : tuple of array
-            Indices of seeds and targets in the transformed data with the form (seeds,
-            targets) to be used when passing the data to
-            `~mne_connectivity.spectral_connectivity_epochs` and
-            `~mne_connectivity.spectral_connectivity_time`. Entries of the indices are
-            arranged such that connectivity would be computed between the first seed
+            Indices of seeds and targets in the transformed data with the form ``(seeds,
+            targets)`` to be used when passing the data to
+            :func:`~mne_connectivity.spectral_connectivity_epochs` and
+            :func:`~mne_connectivity.spectral_connectivity_time`. Entries of the indices
+            are arranged such that connectivity would be computed between the first seed
             component and first target component, second seed component and second
             target component, etc...
         """
@@ -495,8 +495,8 @@ def plot_patterns(
     ):
         """Plot topographic patterns of components.
 
-        The patterns explain how the measured data was generated from the
-        neural sources (a.k.a. the forward model) :footcite:`HaufeEtAl2014`.
+        The patterns explain how the measured data was generated from the neural sources
+        (a.k.a. the forward model) :footcite:`HaufeEtAl2014`.
 
         Seed and target patterns are plotted separately.
 

mne_connectivity/effective.py

@@ -35,68 +35,66 @@ def phase_slope_index(
 ):
     """Compute the Phase Slope Index (PSI) connectivity measure.
 
-    The PSI is an effective connectivity measure, i.e., a measure which can
-    give an indication of the direction of the information flow (causality).
-    For two time series, and one computes the PSI between the first and the
-    second time series as follows
+    The PSI is an effective connectivity measure, i.e., a measure which can give an
+    indication of the direction of the information flow (causality). For two time
+    series, and one computes the PSI between the first and the second time series as
+    follows::
 
-    indices = (np.array([0]), np.array([1]))
-    psi = phase_slope_index(data, indices=indices, ...)
+        indices = (np.array([0]), np.array([1]))
+        psi = phase_slope_index(data, indices=indices, ...)
 
-    A positive value means that time series 0 is ahead of time series 1 and
-    a negative value means the opposite.
+    A positive value means that time series 0 is ahead of time series 1 and a negative
+    value means the opposite.
 
     The PSI is computed from the coherency (see :func:`spectral_connectivity_epochs`),
     details can be found in :footcite:`NolteEtAl2008`.
 
     Parameters
     ----------
-    data : array-like, shape=(n_epochs, n_signals, n_times)
-        Can also be a list/generator of array, shape =(n_signals, n_times);
-        list/generator of SourceEstimate; or Epochs.
-        The data from which to compute connectivity. Note that it is also
-        possible to combine multiple signals by providing a list of tuples,
-        e.g., data = [(arr_0, stc_0), (arr_1, stc_1), (arr_2, stc_2)],
-        corresponds to 3 epochs, and arr_* could be an array with the same
-        number of time points as stc_*.
+    data : array_like, shape (n_epochs, n_signals, n_times) | ~mne.Epochs | generator
+        Can also be a list/generator of arrays, shape ``(n_signals, n_times)``;
+        list/generator of :class:`mne.SourceEstimate`; or :class:`mne.Epochs`. The
+        data from which to compute connectivity. Note that it is also possible to
+        combine multiple signals by providing a list of tuples, e.g., ``data = [(arr_0,
+        stc_0), (arr_1, stc_1), (arr_2, stc_2)]``, corresponds to 3 epochs, and
+        ``arr_*`` could be an array with the same number of time points as ``stc_*``.
     %(names)s
-    indices : tuple of array | None
-        Two arrays with indices of connections for which to compute
-        connectivity. If None, all connections are computed.
+    indices : tuple of array_like | None
+        Two array-likes with indices of connections for which to compute connectivity.
+        If ``None``, all connections are computed. See Notes of
+        :func:`~mne_connectivity.spectral_connectivity_epochs` for details.
     sfreq : float
         The sampling frequency.
-    mode : str
-        Spectrum estimation mode can be either: 'multitaper', 'fourier', or
-        'cwt_morlet'.
+    mode : ``'multitaper'`` | ``'fourier'`` | ``'cwt_morlet'``
+        Spectrum estimation mode.
     fmin : float | tuple of float
-        The lower frequency of interest. Multiple bands are defined using
-        a tuple, e.g., (8., 20.) for two bands with 8Hz and 20Hz lower freq.
-        If None the frequency corresponding to an epoch length of 5 cycles
-        is used.
+        The lower frequency of interest. Multiple bands are defined using a tuple, e.g.,
+        (8., 20.) for two bands with 8 Hz and 20 Hz lower freq. If ``None`` the
+        frequency corresponding to an epoch length of 5 cycles is used.
     fmax : float | tuple of float
-        The upper frequency of interest. Multiple bands are dedined using
-        a tuple, e.g. (13., 30.) for two band with 13Hz and 30Hz upper freq.
+        The upper frequency of interest. Multiple bands are defined using a tuple, e.g.,
+        (13., 30.) for two bands with 13 Hz and 30 Hz upper freq.
     tmin : float | None
         Time to start connectivity estimation.
     tmax : float | None
         Time to end connectivity estimation.
     mt_bandwidth : float | None
-        The bandwidth of the multitaper windowing function in Hz.
-        Only used in 'multitaper' mode.
+        The bandwidth of the multitaper windowing function in Hz. Only used in
+        ``'multitaper'`` mode.
     mt_adaptive : bool
-        Use adaptive weights to combine the tapered spectra into PSD.
-        Only used in 'multitaper' mode.
+        Use adaptive weights to combine the tapered spectra into PSD. Only used in
+        ``'multitaper'`` mode.
     mt_low_bias : bool
         Only use tapers with more than 90 percent spectral concentration within
-        bandwidth. Only used in 'multitaper' mode.
-    cwt_freqs : array
-        Array of frequencies of interest. Only used in 'cwt_morlet' mode.
-    cwt_n_cycles : float | array of float
+        bandwidth. Only used in ``'multitaper'`` mode.
+    cwt_freqs : array_like
+        Array-like of frequencies of interest. Only used in ``'cwt_morlet'`` mode.
+    cwt_n_cycles : float | array_like
         Number of cycles. Fixed number or one per frequency. Only used in
-        'cwt_morlet' mode.
+        ``'cwt_morlet'`` mode.
     block_size : int
-        How many connections to compute at once (higher numbers are faster
-        but require more memory).
+        How many connections to compute at once (higher numbers are faster but require
+        more memory).
     n_jobs : int
         How many epochs to process in parallel.
     %(verbose)s
@@ -105,11 +103,12 @@ def phase_slope_index(
     -------
     conn : instance of SpectralConnectivity or SpectroTemporalConnectivity
         Computed connectivity measure(s). Either a :class:`SpectralConnectivity`, or
-        :class:`SpectroTemporalConnectivity` container. The shape of each array is
-        either (n_signals ** 2, n_bands) mode: 'multitaper' or 'fourier' (n_signals **
-        2, n_bands, n_times) mode: 'cwt_morlet' when "indices" is None, or (n_con,
-        n_bands) mode: 'multitaper' or 'fourier' (n_con, n_bands, n_times) mode:
-        'cwt_morlet' when "indices" is specified and "n_con = len(indices[0])".
+        :class:`SpectroTemporalConnectivity` container. The shape of each array is:
+
+        - ``(n_cons, n_bands)`` for ``'multitaper'`` or ``'fourier'`` modes
+        - ``(n_cons, n_bands, n_times)`` for ``'cwt_morlet'`` mode
+        - ``n_cons = n_signals ** 2`` when ``indices=None``
+        - ``n_cons = len(indices[0])`` when ``indices`` is supplied
 
     See Also
     --------