Add validation of function default values in the documentation build

doc/conf.py

@@ -20,6 +20,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, '..')
+sys.path.insert(0, os.path.abspath('_ext'))
 
 # -- numpydoc validation compatibility patch -----------------------------
 # Property descriptors do not always expose __module__.  numpydoc's
@@ -60,6 +61,7 @@ def _safe_mangle_docstrings(app, what, name, obj, options, lines):
     'numpydoc',
     'nbsphinx',
     'sphinx_tabs.tabs',
+    'defaults_validation',  # Custom extension: validate default values
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -256,6 +258,18 @@ def _safe_mangle_docstrings(app, what, name, obj, options, lines):
 # see here https://github.com/phn/pytpm/issues/3#issuecomment-12133978
 numpydoc_show_class_members = False
 
+
+# --- Options for custom validations -----------------------------------
+
+# Objects excluded from the `defaults` validation. An entry is a fully
+# qualified name and also covers everything below it, so a module or a
+# class name excludes its members.
+defaults_ignore = [
+    'elephant.statistics.cv',  # re-export of scipy.stats.variation
+    'elephant.trials',         # TODO: addressed in PR 673
+]
+
+
 # --- Options for bibtex -----------------------------------------------
 
 # path to bibtex-bibfiles.

doc/style_guide.rst

@@ -51,7 +51,7 @@ throughout Elephant.
                          min_threshold, n_bins, n_surrogates, bin_size, max_size,
                          time_limits, time_range, t_start, t_stop, period, order,
                          error, capacity, source_matrix, cov_matrix,
-                         selection_method='aic'
+                         selection_method='bic'
                          ):
         r"""
         Full example of the docstring and naming conventions.
@@ -88,15 +88,15 @@ throughout Elephant.
             underscore because Neo does not use underscore, and Elephant must keep
             compatibility. Do not use names such as `sts`, `spks`, or
             `spike_trains`.
-        spiketrain: neo.SpikeTrain
+        spiketrain : neo.SpikeTrain
             If the function EXPLICITLY requires only a single spike train, then
             the parameter should be named in singular (i.e., `spiketrain`). Do
             not use names such as `st`, `spk`, or `spike_train`.
         reference_spiketrain : neo.SpikeTrain
             If a function uses more than one parameter with single spike trains,
             then each parameter name begins with a meaningful name,
             followed by "_spiketrain" in singular form.
-        target_spiketrain: neo.SpikeTrain
+        target_spiketrain : neo.SpikeTrain
             Second parameter that is a single spike train. Note that the difference
             from `reference_spiketrain` is indicated by a meaningful name at the
             beginning.
@@ -128,15 +128,15 @@ throughout Elephant.
         max_size : float
             Another example showing that words should be separated by underscores.
             This intersects with the naming convention for a maximum value.
-        time_limits: list or tuple
+        time_limits : list or tuple
             For parameters that define minimum and maximum values as a list or
             tuple (e.g., [-2, 2]), the parameter must start with a meaningful
             word followed by the suffix "_limits". Preferentially, one should use
             two separated parameters (e.g., `max_time` and `min_time` following
             the convention for maximum and minimum already mentioned). But should
             the function require the definition of limits in this form, use the
             name `_limits` and not `_range` (see next parameter).
-        time_range: list
+        time_range : list
             For parameters that behave like a Python range (e.g. [1, 2, 3, 4])), in
             the sense that it is a sequence, not only the lower and upper limits
             as in the example above, the parameter should start with a meaningful
@@ -186,10 +186,10 @@ throughout Elephant.
             (such as `C` for capacity), always use the meaning
             of the letter. Therefore, the parameter should be named `capacity`,
             not `C`. Acknowledge this in the docstring as already mentioned.
-        source_matrix: np.ndarray
+        source_matrix : np.ndarray
             Parameters that are matrices should end with the suffix "_matrix", and
             start with a meaningful name.
-        cov_matrix: np.ndarray
+        cov_matrix : np.ndarray
             A few exceptions allow the use of abbreviations instead of full words
             in the name of the parameter. These are:
             * "cov" for "covariance" (e.g., `cov_matrix`)
@@ -200,15 +200,14 @@ throughout Elephant.
             `calculate_covariance_matrix`. If the function name becomes very long,
             then an alias may be created and described appropriately in the "Notes"
             section, as mentioned above. For aliases, see example below.
-        selection_method : {'aic', 'bic'}
+        selection_method : {'aic', 'bic'}, optional
+            <!-- Note that the default value that comes in the last line is
+            followed by a short explanation in parentheses to provide the
+            needed reasoning for defining the default `selection_method`. -->
             Metric for selecting the autoregressive model.
             If 'aic', uses the Akaike Information Criterion (AIC).
             If 'bic', uses Bayesian Information Criterion (BIC).
-            Default: 'bic', because it is more reliable than AIC due to the
-            mathematical properties (see Notes [3]).
-            <!-- Note that the default value that comes in the last line is
-            followed by comma and a brief reasoning for defining the default
-            `selection_method`). -->
+            Default: 'bic' (more reliable than AIC; see Notes [3])
 
         <!-- Other remarks:
         1. Do not use general parameter names, such as `data` or `matrix`.
@@ -334,22 +333,24 @@ Class docstrings follow function docstring format. Here is an example.
             Colon omitted if the type is absent.
         x : float
             The X coordinate.
-        y : float
+        y : float, optional
+            <!-- Do not describe defaults with "Default is 1.0.", and
+            do not end the line with a trailing period -->
             The Y coordinate.
-            Default: 1.0.  <!-- not "Default is 1.0." (it is just a convention) -->
+            Default: 1.0
         z : float or int or pq.Quantity
             This is Z coordinate.
             If it can take multiple types, separate them by "or", do not use commas
             (numpy style).
             If different actions will happen depending on the type of `z`, explain
             it briefly here, not in the main text of the function/class docstring.
-        s : {'valid', 'full', 'other'}
+        s : {'valid', 'full', 'other'}, optional
             This is the way to describe a list of possible argument values, if the
             list is discrete and predefined (typically concerns strings).
             If 'valid', the function performs some action.
             If 'full', the function performs another action.
             If 'other', the function will ignore the value defined in `z`.
-            Default: 'valid'.
+            Default: 'valid'
         spiketrains : neo.SpikeTrain or list of neo.SpikeTrain or np.ndarray
             When the parameter can be a container (such as list or tuple), you can
             specify the type of elements using "of". But use the Python type name
@@ -361,15 +362,15 @@ Class docstrings follow function docstring format. Here is an example.
             the number of rows and `M` to the number of columns. Refer to the same
             `N` and `M` to describe the dimensions of the returned values when
             they are determined by the dimensions of the parameter.
-        is_true : bool
+        is_true : bool, optional
             True, if 1.
             False, if 0.
-            Default: True.
-        other_parameter : int
+            Default: True
+        other_parameter : int or None, optional
             Some value.
             If value is None and the function takes some specific action (e.g.,
             calculate some value based on the other inputs), describe here.
-            Default: None.
+            Default: None
 
         Attributes
         ----------

elephant/asset/asset.py

@@ -587,6 +587,7 @@ class _GPUBackend:
         to simulate scenarios when the input matrix is so large that it cannot
         fit into GPU memory. Setting this parameter manually can resolve GPU
         memory errors in case automatic parameters adjustment fails.
+        Default: None
 
     Notes
     -----
@@ -1989,12 +1990,16 @@ class ASSET(object):
 
     Parameters
     ----------
-    spiketrains_i, spiketrains_j : list of neo.SpikeTrain
-        Input spike trains for the first and second time dimensions,
-        respectively, to compute the p-values from.
-        If `spiketrains_y` is None, it's set to `spiketrains`.
+    spiketrains_i : list of neo.SpikeTrain
+        The input spike trains for the first time dimension, from which the
+        p-values are computed.
+    spiketrains_j : list of neo.SpikeTrain, optional
+        The input spike trains for the second time dimension. If None,
+        `spiketrains_i` is used for the second dimension as well.
+        Default: None
     bin_size : pq.Quantity, optional
         The width of the time bins used to compute the probability matrix.
+        Default: 3 * pq.ms
     t_start_i, t_start_j : pq.Quantity, optional
         The start time of the binning for the first and second axes,
         respectively.
@@ -2206,15 +2211,22 @@ def probability_matrix_montecarlo(self, n_surrogates, imat=None,
             time was discretized in.
             If None, the output of :func:`ASSET.intersection_matrix` is used.
             Default: None
-        surrogate_method : {'dither_spike_train', 'dither_spikes',
-            'jitter_spikes', 'randomise_spikes', 'shuffle_isis',
-            'joint_isi_dithering'}, optional
-
-            The method to generate surrogate spike trains. Refer to the
-            :func:`spike_train_surrogates.surrogates` documentation for more
-            information about each surrogate method. Note that some of these
-            methods need `surrogate_dt` parameter, others ignore it.
-            Default: 'dither_spike_train'
+        surrogate_method : str, optional
+            The method to generate surrogate spike trains. The following are
+            supported:
+
+            * 'dither_spike_train'
+            * 'dither_spikes'
+            * 'jitter_spikes'
+            * 'randomise_spikes'
+            * 'shuffle_isis'
+            * 'joint_isi_dithering'
+
+            Refer to the :func:`spike_train_surrogates.surrogates`
+            documentation for more information about each surrogate method.
+            Note that some of these methods need the `surrogate_dt` parameter,
+            others ignore it.
+            Default: 'dither_spikes'
         surrogate_dt : pq.Quantity, optional
             For surrogate methods shifting spike times randomly around their
             original time ('dither_spike_train', 'dither_spikes') or replacing
@@ -2330,7 +2342,7 @@ def probability_matrix_analytical(self, imat=None,
             time was discretized in.
             If None, the output of :func:`ASSET.intersection_matrix` is used.
             Default: None
-        firing_rates_x, firing_rates_y : list of neo.AnalogSignal or 'estimate'
+        firing_rates_x, firing_rates_y : list of neo.AnalogSignal or 'estimate', optional
             If a list, `firing_rates[i]` is the firing rate of the spike train
             `spiketrains[i]`.
             If 'estimate', firing rates are estimated by simple boxcar kernel

elephant/causality/granger.py

@@ -336,11 +336,11 @@ def _optimal_vector_arm(signals, dimension, max_order,
         dimensionality of the data
     max_order : int
         maximal order to consider
-    information_criterion : str
+    information_criterion : str, optional
         A function to compute the information criterion:
             `bic` for Bayesian information_criterion,
             `aic` for Akaike information criterion
-        Default: aic
+        Default: 'aic'
 
     Returns
     -------
@@ -465,7 +465,7 @@ def _spectral_factorization(cross_spectrum, num_iterations, term_crit=1e-12):
         function
     num_iterations : int
         Maximal number of iterations of iterative algorithm
-    term_crit : float
+    term_crit : float, optional
         Termination criterion for iteration step in spectral matrix
         factorization
         Default: 1e-12
@@ -813,13 +813,13 @@ def pairwise_spectral_granger(signal_i, signal_j, fs=1, nw=4, num_tapers=None,
         must be identical. When `signal_i` and `signal_j` are not
         `neo.AnalogSignal`, sampling frequency should be specified through the
         keyword argument `fs`. Otherwise, the default value is used
-        (`fs` = 1.0).
+        (`fs` = 1).
     fs : float, optional
         Specifies the sampling frequency of the input time series
-        Default: 1.0
+        Default: 1
     nw : float, optional
         Time bandwidth product
-        Default: 4.0
+        Default: 4
     num_tapers : int, optional
         Number of tapers used in 1. to obtain estimate of PSD. By default,
         [2*nw] - 1 is chosen.
@@ -829,7 +829,7 @@ def pairwise_spectral_granger(signal_i, signal_j, fs=1, nw=4, num_tapers=None,
         Fine peak resolution --> low numerical value --> low number of tapers
         High peak resolution --> high numerical value --> high number of tapers
         When given as a `float`, it is taken as frequency in Hz.
-        Default: None.
+        Default: None
     n_segments : int, optional
         Number of segments. The length of segments is adjusted so that
         overlapping segments cover the entire stretch of the given data. This
@@ -850,12 +850,12 @@ def pairwise_spectral_granger(signal_i, signal_j, fs=1, nw=4, num_tapers=None,
         Overlap between segments represented as a float number between 0 (no
         overlap) and 1 (complete overlap).
         Default: 0.5 (half-overlapped)
-    num_iterations : int
+    num_iterations : int, optional
         Number of iterations for algorithm to estimate spectral factorization.
         Default: 300
-    term_crit : float
+    term_crit : float, optional
         Termination criterion for iteration step in spectral matrix
-        factorization
+        factorization.
         Default: 1e-12
 
     Returns

elephant/cell_assembly_detection.py

@@ -128,7 +128,7 @@ def cell_assembly_detection(binned_spiketrain, max_lag, reference_lag=2,
         Minimal number of occurrences required for an assembly
         (all assemblies, even if significant, with fewer occurrences
         than min_occurrences are discarded).
-        Default: 0
+        Default: 1
     size_chunks : int, optional
         Size (in bins) of chunks in which the spike trains are divided
         to compute the variance (to reduce non stationarity effects
@@ -137,7 +137,7 @@ def cell_assembly_detection(binned_spiketrain, max_lag, reference_lag=2,
     max_spikes : int, optional
         Maximal assembly order (the algorithm will return assemblies
         composed of maximum `max_spikes` elements).
-        Default: `np.inf`
+        Default: np.inf
     significance_pruning : bool, optional
         If True, the method performs significance pruning among
         the detected assemblies.

elephant/conversion.py

@@ -832,7 +832,7 @@ def to_spike_trains(self, spikes="random", as_array=False,
               * "random": generate spikes from a homogenous Poisson process;
                 it's the fastest mode.
 
-            Default: "random"
+            Default: 'random'
         as_array : bool, optional
             If True, numpy arrays are returned; otherwise, wrap the arrays in
             `neo.SpikeTrain`.
@@ -894,7 +894,7 @@ def get_num_of_spikes(self, axis=None):
             If `None`, compute the total num. of spikes.
             Otherwise, compute num. of spikes along axis.
             If axis is `1`, compute num. of spikes per spike train (row).
-            Default is `None`.
+            Default: None
 
         Returns
         -------