Improve docstrings

src/dspeed/processing_chain.py

@@ -2245,45 +2245,46 @@ def build_processing_chain(
         A dictionary or YAML/JSON filename containing the recipes for computing DSP
         parameter from raw parameters. The format is as follows:
 
-        .. code-block:: json
-            :force:
-
-            {
-                "name1, name2" : {
-                    "function" : "func1"
-                    "module" : "mod1"
-                    "args" : ["arg1", 3, "arg2"]
-                    "kwargs" : {"key1": "val1"}
-                    "init_args" : ["arg1", 3, "arg2"]
-                    "unit" : ["u1", "u2"]
-                    "defaults" : {"arg1": "defval1"}
-                },
-                ...
-            }
+        .. code-block:: yaml
+
+            outputs: [par1, par2]
+            processors:
+              "name1, name2":
+                function: func1
+                module: mod1
+                args: [arg1, 3, arg2]
+                kwargs:
+                  key1: val1
+                init_args: [arg1, 3, arg2]
+                unit: [u1 u2]
+                defaults:
+                  arg1: defval1
 
         - ``name1, name2`` -- dictionary. key contains comma-separated
           names of parameters computed
 
-          - ``function`` -- string, name of function to call.  Function
-            should implement the :class:`numpy.gufunc` interface, a factory
-            function returning a ``gufunc``, or an arbitrary function that
-            can be mapped onto a ``gufunc``
-          - ``module`` -- string, name of module containing function
-          - ``args``-- list of strings or numerical values. Contains
-            list of names of computed and input parameters or
-            constant values used as inputs to function. Note that
-            outputs should be fed by reference as args! Arguments read
-            from the database are prepended with ``db``.
-          - ``kwargs`` -- dictionary. Keyword arguments for
-            :meth:`ProcesssingChain.add_processor`.
-          - ``init_args`` --  list of strings or numerical values. List
-            of names of computed and input parameters or constant values
-            used to initialize a :class:`numpy.gufunc` via a factory
-            function
-          - ``unit`` -- list of strings. Units for parameters
-          - ``defaults`` -- dictionary. Default value to be used for
-            arguments read from the database
-        - The dictionary can also be nested in another, keyed as ``processors``
+          - ``name1, name2`` -- dictionary. key contains comma-separated
+            names of parameters computed
+
+            - ``function`` -- string, name of function to call.  Function
+              should implement the :class:`numpy.gufunc` interface, a factory
+              function returning a ``gufunc``, or an arbitrary function that
+              can be mapped onto a ``gufunc``
+            - ``module`` -- string, name of module containing function
+            - ``args``-- list of strings or numerical values. Contains
+              list of names of computed and input parameters or
+              constant values used as inputs to function. Note that
+              outputs should be fed by reference as args! Arguments read
+              from the database are prepended with ``db``.
+            - ``kwargs`` -- dictionary. Keyword arguments for
+              :meth:`ProcessingChain.add_processor`.
+            - ``init_args`` --  list of strings or numerical values. List
+              of names of computed and input parameters or constant values
+              used to initialize a :class:`numpy.gufunc` via a factory
+              function
+            - ``unit`` -- list of strings. Units for parameters
+            - ``defaults`` -- dictionary. Default value to be used for
+              arguments read from the database
 
     tb_in
         input table. This table will be linked to use as inputs when

src/dspeed/processors/bl_subtract.py

@@ -1,3 +1,5 @@
+"""DSP processors for subtracting a constant baseline from waveforms."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/convolutions.py

@@ -1,3 +1,5 @@
+"""Convolution-based waveform filter processors."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/dwt.py

@@ -1,3 +1,5 @@
+"""Discrete wavelet transform processors for waveform analysis."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/energy_kernels.py

@@ -1,3 +1,5 @@
+"""Energy estimation kernels for DSP pipelines."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/fixed_time_pickoff.py

@@ -1,3 +1,5 @@
+"""Processors computing fixed-time pick-off metrics."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/gaussian_filter1d.py

@@ -1,3 +1,5 @@
+"""Processors applying one-dimensional Gaussian smoothing filters."""
+
 # Copyright (C) 2003-2005 Peter J. Verveer
 #
 # Redistribution and use in source and binary forms, with or without

src/dspeed/processors/get_multi_local_extrema.py

@@ -1,3 +1,5 @@
+"""Processors finding multiple local extrema in waveforms."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/get_wf_centroid.py

@@ -1,3 +1,5 @@
+"""Processors estimating waveform centroids."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/histogram.py

@@ -1,3 +1,5 @@
+"""Histogramming utilities for waveform-derived quantities."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/histogram_stats.py

@@ -1,3 +1,5 @@
+"""Processors computing summary statistics from histograms."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/iir_filter.py

@@ -1,3 +1,5 @@
+"""Helpers for constructing IIR filter processors."""
+
 from __future__ import annotations
 
 from collections.abc import Collection

src/dspeed/processors/inject_ringing.py

@@ -1,3 +1,5 @@
+"""Processors injecting damped oscillatory ringing into waveforms."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/inl_correction.py

@@ -1,3 +1,5 @@
+"""Integral non-linearity correction processors."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/kernels.py

@@ -1,3 +1,5 @@
+"""Kernel generator utilities for DSP filters."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/linear_slope_fit.py

@@ -1,3 +1,5 @@
+"""Processors for fitting a linear slope to waveform segments."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/log_check.py

@@ -1,3 +1,5 @@
+"""Processors performing logarithmic consistency checks on waveforms."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/min_max.py

@@ -1,3 +1,5 @@
+"""Processors computing minimum and maximum waveform statistics."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/ml.py

@@ -46,9 +46,7 @@
     **nb_kwargs,
 )
 def relu(x_in: np.ndarray, x_out: np.ndarray) -> None:
-    """
-    relu activation function 0 if x_in < 0 else x_in
-    """
+    """Apply the rectified linear unit activation function."""
     x_out[:] = x_in * (x_in > 0)
 
 
@@ -58,9 +56,7 @@ def relu(x_in: np.ndarray, x_out: np.ndarray) -> None:
     **nb_kwargs,
 )
 def leaky_relu(x_in: np.ndarray, x_out: np.ndarray) -> None:
-    """
-    leaky relu activation function 0 if x_in < 0 else 0.01 x_in
-    """
+    """Apply a leaky ReLU activation with a 0.01 negative slope."""
     x_out[:] = x_in * (x_in > 0) + 0.01 * x_in * (x_in < 0)
 
 
@@ -70,9 +66,7 @@ def leaky_relu(x_in: np.ndarray, x_out: np.ndarray) -> None:
     **nb_kwargs,
 )
 def sigmoid(x_in: np.ndarray, x_out: np.ndarray) -> None:
-    """
-    sigmoid activation function
-    """
+    """Apply the logistic sigmoid activation function."""
     x_out[:] = 1 / (1 + np.exp(-x_in))
 
 
@@ -82,9 +76,7 @@ def sigmoid(x_in: np.ndarray, x_out: np.ndarray) -> None:
     **nb_kwargs,
 )
 def softmax(x_in: np.ndarray, x_out: np.ndarray) -> None:
-    """
-    softmax activation function
-    """
+    """Apply a numerically stable softplus-style activation."""
     x_out[:] = np.log(1 + np.exp(x_in))
 
 
@@ -100,24 +92,20 @@ def softmax(x_in: np.ndarray, x_out: np.ndarray) -> None:
 def dense_layer_no_bias(
     x_in: np.ndarray, kernel: np.ndarray, activation_func: np.int8, x_out: np.ndarray
 ) -> None:
-    """
-    Basic dense neural network layer with no bias, f(x.W)
+    """Dense neural network layer without a bias term.
 
     Parameters
     ----------
-    w_in
-        the input waveform shape n.
+    x_in
+        Input vector with length ``n``.
     kernel
-        the matrix of weights shape (n x m).
+        Matrix of weights with shape ``(n, m)``.
     activation_func
-        the activation function to use specify with char:
-        s - sigmoid
-        r - relu
-        l - leaky relu
-        m - softmax
-        t - tanh
+        Character flag indicating which activation to apply. Supported values
+        are ``s`` (sigmoid), ``r`` (ReLU), ``l`` (leaky ReLU), ``m`` (softplus),
+        and ``t`` (hyperbolic tangent).
     x_out
-        the output vector shape m.
+        Output vector with length ``m``.
 
     YAML Configuration Example
     --------------------------
@@ -169,26 +157,22 @@ def dense_layer_with_bias(
     activation_func: np.int8,
     x_out: np.ndarray,
 ) -> None:
-    """
-    Basic dense neural network layer with bias added f(x.W+b)
+    """Dense neural network layer with an additive bias term.
 
     Parameters
     ----------
-    w_in
-        the input waveform shape n.
+    x_in
+        Input vector with length ``n``.
     kernel
-        the matrix of weights shape (n x m).
+        Matrix of weights with shape ``(n, m)``.
     bias
-        the bias with shape m.
+        Bias vector with length ``m``.
     activation_func
-        the activation function to use specify with char:
-        s - sigmoid
-        r - relu
-        l - leaky relu
-        m - softmax
-        t - tanh
+        Character flag indicating which activation to apply. Supported values
+        are ``s`` (sigmoid), ``r`` (ReLU), ``l`` (leaky ReLU), ``m`` (softplus),
+        and ``t`` (hyperbolic tangent).
     x_out
-        the output vector shape m.
+        Output vector with length ``m``.
 
     YAML Configuration Example
     --------------------------

src/dspeed/processors/moving_windows.py

@@ -1,3 +1,5 @@
+"""Processors for applying moving window average convolution to waveforms."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/multi_a_filter.py

@@ -1,3 +1,5 @@
+"""Processors for identifying multiple maxima and their amplitudes in a waveform."""
+
 import numpy as np
 from numba import guvectorize
 

src/dspeed/processors/multi_t_filter.py

@@ -1,3 +1,5 @@
+"""Processors for identifying multiple leading edges in waveforms."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/nnls.py

@@ -1,3 +1,5 @@
+"""Helpers for running non-negative least-squares optimizations."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/optimize.py

@@ -1,3 +1,5 @@
+"""Processors for identifying optimal pole-zero coefficients."""
+
 from __future__ import annotations
 
 from typing import Callable

src/dspeed/processors/param_lookup.py

@@ -1,3 +1,5 @@
+"""Processors for looking up parameters from calibration tables."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/peak_snr_threshold.py

@@ -1,3 +1,5 @@
+"""Processors for identifying significant local minima."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/pmt_pulse_injector.py

@@ -1,3 +1,5 @@
+"""Processors that inject parameterized photomultiplier pulses into waveforms."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/pole_zero.py

@@ -1,3 +1,5 @@
+"""Pole-zero cancellation processors for waveform shaping."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/poly_fit.py

@@ -1,3 +1,5 @@
+"""Polynomial fitting processors for waveforms."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/presum.py

@@ -1,3 +1,5 @@
+"""Processors for down-sampling waveform using pre-summing."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/pulse_injector.py

@@ -1,3 +1,5 @@
+"""Processors that inject analytic pulses into waveforms."""
+
 from __future__ import annotations
 
 from math import exp, log

src/dspeed/processors/rc_cr2.py

@@ -1,3 +1,5 @@
+"""Processors implementing RC-CR^2 shaping filters."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/recursive_filter.py

@@ -1,3 +1,5 @@
+"""Generic processors used to implement recursive digital filters from poles and zeros."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/round_to_nearest.py

@@ -1,3 +1,5 @@
+"""Processors for rounding values to multiples of provided value."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/saturation.py

@@ -1,3 +1,5 @@
+"""Processors that check for samples at saturation limit."""
+
 from __future__ import annotations
 
 import numpy as np

src/dspeed/processors/soft_pileup_corr.py

@@ -1,3 +1,5 @@
+"""Processors implementing soft pile-up corrections."""
+
 from __future__ import annotations
 
 import numpy as np