Merge pull request #236 from scottclowe/doc_docstrings

DOC: Improve docstrings

fissa/core.py

@@ -146,11 +146,14 @@ def separate_trials(
         - ``1``: Print separation progress.
 
     max_iter : int, default=20000
-        Number of maximally allowed iterations.
+        Maximum number of iterations before timing out on an attempt.
+
     tol : float, default=1e-4
-        Error tolerance for termination.
+        Tolerance of the stopping condition.
+
     max_tries : int, default=1
-        Maximum number of tries before algorithm should terminate.
+        Maximum number of random initial states to try. Each random state will
+        be optimized for `max_iter` iterations before timing out.
 
     Returns
     -------
@@ -283,17 +286,18 @@ class Experiment:
         remove regularization. Default is ``0.1``.
 
     max_iter : int, default=20000
-        Number of maximally allowed iterations of separation algorithm.
+        Maximum number of iterations before timing out on an attempt.
 
         .. versionadded:: 1.0.0
 
     tol : float, default=1e-4
-        Error tolerance for termination of separation algorithm.
+        Tolerance of the stopping condition.
 
         .. versionadded:: 1.0.0
 
     max_tries : int, default=1
-        Maximum number of tries before separation algorithm should terminate.
+        Maximum number of random initial states to try. Each random state will
+        be optimized for `max_iter` iterations before timing out.
 
         .. versionadded:: 1.0.0
 
@@ -380,7 +384,7 @@ class Experiment:
         and the :attr:`nRegions` neuropil regions by
         ``experiment.roi_polys[i_roi][i_trial][1 + i_region][0]``.
 
-    means : list of n_trials :class:`numpy.ndarray`s, each shaped ``(height, width)``
+    means : list of `n_trials` :class:`numpy.ndarray`, each shaped ``(height, width)``
         The temporal-mean image for each trial (i.e. for each TIFF file,
         the average image over all of its frames).
 
@@ -655,7 +659,6 @@ def load(self, path=None):
 
         .. versionadded:: 1.0.0
 
-
         Parameters
         ----------
         path : str, optional

fissa/neuropil.py

@@ -50,34 +50,40 @@ def separate(
         method, ``n`` is the number of input signals; for the ICA method,
         we use PCA to estimate how many components would explain at least 99%
         of the variance and adopt this value for ``n``.
+
     max_iter : int, default=10000
-        Number of maximally allowed iterations. Default is ``10000``.
+        Maximum number of iterations before timing out on an attempt.
 
         .. versionchanged:: 1.0.0
             Argument `maxiter` renamed to `max_iter`.
 
     tol : float, default=1e-4
-        Error tolerance for termination. Default is ``1e-4``.
+        Tolerance of the stopping condition.
+
     random_state : int or None, default=892
         Initial state for the random number generator. Set to ``None`` to use
-        the numpy.random default. Default seed is ``892``.
+        the :mod:`numpy.random` default. Default seed is ``892``.
+
     max_tries : int, default=10
-        Maximum number of tries before algorithm should terminate.
-        Default is ``10``.
+        Maximum number of random initial states to try. Each random state will
+        be optimized for `max_iter` iterations before timing out.
 
         .. versionchanged:: 1.0.0
             Argument `maxtries` renamed to `max_tries`.
 
     W0 : :term:`array_like`, optional
         Optional starting condition for ``W`` in NMF algorithm.
         (Ignored when using the ICA method.)
+
     H0 : :term:`array_like`, optional
         Optional starting condition for ``H`` in NMF algorithm.
         (Ignored when using the ICA method.)
+
     alpha : float, default=0.1
         Sparsity regularizaton weight for NMF algorithm. Set to zero to
         remove regularization. Default is ``0.1``.
         (Ignored when using the ICA method.)
+
     verbosity : int, default=1
         Level of verbosity. The options are:
 
@@ -88,11 +94,14 @@ def separate(
     -------
     S_sep : :class:`numpy.ndarray` shaped (signals, observations)
         The raw separated traces.
+
     S_matched : :class:`numpy.ndarray` shaped (signals, observations)
         The separated traces matched to the primary signal, in order
         of matching quality (see Notes below).
+
     A_sep : :class:`numpy.ndarray` shaped (signals, signals)
         Mixing matrix.
+
     convergence : dict
         Metadata for the convergence result, with the following keys and
         values: