dsp tests

.pre-commit-config.yaml

@@ -24,12 +24,6 @@ repos:
   - id: requirements-txt-fixer
   - id: trailing-whitespace
 
-- repo: https://github.com/Carreau/velin.git
-  rev: "0.0.12"
-  hooks:
-    - id: velin
-      args: ["--check", "--write"]
-
 - repo: https://github.com/asottile/setup-cfg-fmt
   rev: "v1.20.1"
   hooks:
@@ -41,7 +35,7 @@ repos:
   - id: isort
 
 - repo: https://github.com/asottile/pyupgrade
-  rev: "v2.34.0"
+  rev: "v2.37.1"
   hooks:
   - id: pyupgrade
     args: ["--py36-plus"]
@@ -87,3 +81,9 @@ repos:
   - id: rst-backticks
   - id: rst-directive-colons
   - id: rst-inline-touching-normal
+
+- repo: https://github.com/pre-commit/mirrors-prettier
+  rev: "v2.7.1"
+  hooks:
+    - id: prettier
+      types_or: [json]

docs/source/conf.py

@@ -64,7 +64,9 @@
 # enforce consistent usage of NumPy-style docstrings
 napoleon_numpy_docstring = True
 napoleon_google_docstring = False
-napoleon_use_rtype = False
+napoleon_use_ivar = True
+napoleon_custom_sections = ["JSON Configuration Example"]
+
 
 # intersphinx
 intersphinx_mapping = {

docs/source/manuals/build_dsp.rst

@@ -39,6 +39,8 @@ Writing custom processors
 
     # 1) Import Python modules
     #
+    from __future__ import annotations
+
     import numpy as np
     from numba import guvectorize
 
@@ -67,14 +69,46 @@ Writing custom processors
     # - Use "w_" for waveforms, "t_" for indexes, "a_" for amplitudes
     # - Use underscore casing for the name of the processor and variables, e.g.,
     #   "a_trap_energy_in" or "t_trigger_in"
+    # - use type annotations
     #
-    def the_processor_template(w_in, t_in, a_in, w_out, t_out):
+    def the_processor_template(w_in: np.ndarray,
+                               t_in: float,
+                               a_in: float,
+                               w_out: np.ndarray,
+                               t_out: float) -> None:
 
         # 4) Document the algorithm
         #
-        """
-        Add here a complete description of what the processor does, including the
-        meaning of input and output variables.
+        """One-liner description of the processor.
+
+        Add here a more detailed description of what the processor does.
+        Document input parameters in the "Parameters" section. Add a JSON
+        example for ProcessingChain configuration in the last section.
+
+        Parameters
+        ----------
+        w_in
+            the input waveform.
+        t_in
+            a scalar parameter in the time domain
+        a_in
+            a scalar parameter in the amplitude domain
+        w_out
+            the output waveform
+        t_out
+            an output scalar value in the time domain
+
+        JSON Configuration Example
+        --------------------------
+
+        .. code-block :: json
+
+            "wf_bl": {
+                "function": "the_processor_template",
+                "module": "pygama.dsp.processors",
+                "args": ["waveform", "t_a", "a_b", "wf_filtered", "t_result"],
+                "unit": "ADC"
+            }
         """
 
         # 5) Initialize output parameters

src/pygama/dsp/__init__.py

@@ -1,14 +1,13 @@
-"""
+r"""
 The pygama signal processing framework is contained in the :mod:`.dsp`
 submodule. This code is responsible for running a variety of discrete signal
 processors on data, producing tier 2 (dsp) files from tier 1 (raw) files. The
 main contents of this submodule are:
 
 * :mod:`.processors`: A collection of Numba functions that perform individual
-  DSP transforms and reductions on our data. Individual processors are held in
-  the ``_processors`` directory, which is where contributors will write new
-  processors for inclusion in the analysis. Available processors include all
-  numpy ufuncs as well.
+  DSP transforms and reductions on our data. Here is where contributors will
+  write new processors for inclusion in the analysis. Available processors
+  include all :class:`numpy.ufunc`\ s as well.
 * :class:`.ProcessingChain`: A class that manages and efficiently runs a list
   of DSP processors
 * :func:`.build_processing_chain`: A function that builds a :class:`.ProcessingChain`