legend-dataflow-scripts 0.2.3__tar.gz → 0.3.0__tar.gz

{legend_dataflow_scripts-0.2.3/src/legend_dataflow_scripts.egg-info → legend_dataflow_scripts-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: legend-dataflow-scripts
-Version: 0.2.3
+Version: 0.3.0
 Summary: Python package for the processing scripts for LEGEND-200 data
 Author-email: George Marshall <ggmarsh@uw.edu>, Luigi Pertoldi <gipert@pm.me>
 Maintainer: The LEGEND Collaboration
@@ -19,10 +19,10 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: colorlog
 Requires-Dist: dbetto>=1.2.3
-Requires-Dist: pygama>=2.1
-Requires-Dist: dspeed>=1.6
+Requires-Dist: pygama>=2.3.8
+Requires-Dist: dspeed>=2.0
 Requires-Dist: pylegendmeta>=1.2.5
-Requires-Dist: legend-pydataobj>=1.11
+Requires-Dist: legend-pydataobj>=1.16
 Requires-Dist: pip
 Provides-Extra: test
 Requires-Dist: legend-dataflow-scripts; extra == "test"

{legend_dataflow_scripts-0.2.3 → legend_dataflow_scripts-0.3.0}/pyproject.toml

@@ -52,10 +52,10 @@ dynamic = ["version"]
 dependencies = [
     "colorlog",
     "dbetto>=1.2.3",
-    "pygama>=2.1",
-    "dspeed>=1.6",
+    "pygama>=2.3.8",
+    "dspeed>=2.0",
     "pylegendmeta>=1.2.5",
-    "legend-pydataobj>=1.11",
+    "legend-pydataobj>=1.16",
     "pip",
 ]
 # "legend-daq2lh5 @  file:///${PROJECT_ROOT}/software/python/src/legend-daq2lh5

{legend_dataflow_scripts-0.2.3 → legend_dataflow_scripts-0.3.0/src/legend_dataflow_scripts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: legend-dataflow-scripts
-Version: 0.2.3
+Version: 0.3.0
 Summary: Python package for the processing scripts for LEGEND-200 data
 Author-email: George Marshall <ggmarsh@uw.edu>, Luigi Pertoldi <gipert@pm.me>
 Maintainer: The LEGEND Collaboration
@@ -19,10 +19,10 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: colorlog
 Requires-Dist: dbetto>=1.2.3
-Requires-Dist: pygama>=2.1
-Requires-Dist: dspeed>=1.6
+Requires-Dist: pygama>=2.3.8
+Requires-Dist: dspeed>=2.0
 Requires-Dist: pylegendmeta>=1.2.5
-Requires-Dist: legend-pydataobj>=1.11
+Requires-Dist: legend-pydataobj>=1.16
 Requires-Dist: pip
 Provides-Extra: test
 Requires-Dist: legend-dataflow-scripts; extra == "test"

{legend_dataflow_scripts-0.2.3 → legend_dataflow_scripts-0.3.0}/src/legend_dataflow_scripts.egg-info/requires.txt

@@ -1,9 +1,9 @@
 colorlog
 dbetto>=1.2.3
-pygama>=2.1
-dspeed>=1.6
+pygama>=2.3.8
+dspeed>=2.0
 pylegendmeta>=1.2.5
-legend-pydataobj>=1.11
+legend-pydataobj>=1.16
 pip
 
 [dev]

legend_dataflow_scripts-0.3.0/src/legenddataflowscripts/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = 'gfec5983ae'

{legend_dataflow_scripts-0.2.3 → legend_dataflow_scripts-0.3.0}/src/legenddataflowscripts/par/geds/dsp/dplms.py

@@ -9,12 +9,63 @@ import numpy as np
 import pygama.math.distributions as pmd  # noqa: F401
 from dbetto.catalog import Props
 from lgdo import Array, Table, lh5
+from pygama.pargen.data_cleaning import generate_cuts
 from pygama.pargen.dplms_ge_dict import dplms_ge_dict
+from pygama.pargen.dsp_optimize import run_one_dsp
 
 from ....utils import build_log, convert_dict_np_to_float
 
 
 def par_geds_dsp_dplms() -> None:
+    """Compute DPLMS optimal filter coefficients for HPGe detectors.
+
+    CLI entry point registered as ``par-geds-dsp-dplms``.  The *Discrete
+    Prolate Laplacian Maximum Signal* (DPLMS) filter is constructed from two
+    data samples:
+
+    1. **FFT baselines** - low-energy (``daqenergy <= 10`` ADC) events from
+       dedicated FFT run files used to characterise the noise power spectrum.
+    2. **Calibration peak events** - gamma-line events read from the
+       *peak-file* produced by :func:`par_geds_dsp_evtsel`.
+
+    The coefficients are computed by
+    :func:`pygama.pargen.dplms_ge_dict.dplms_ge_dict` and written to an LH5
+    file at *lh5-path* (so that the DSP chain can load them with
+    ``loadlh5(...)``).  The DSP parameter database is updated with the filter
+    configuration and written to *dsp-pars*.
+
+    Notes
+    -----
+    **Command-line arguments**
+
+    ``--fft-raw-filelist`` : str
+        Path to a text file listing the FFT raw LH5 input files.
+    ``--peak-file`` : str
+        LH5 file containing preselected calibration peak events.
+    ``--inplots`` : str, optional
+        Existing pickle plot file to update with DPLMS plots.
+    ``--database`` : str
+        Path to the existing DSP parameter database (JSON/YAML).
+    ``--log`` : str, optional
+        Path to the log file.
+    ``--log-config`` : str, optional
+        Logging configuration file.
+    ``--processing-chain`` : list of str
+        Processing chain configuration file(s).
+    ``--config-file`` : list of str
+        DPLMS configuration file(s).  Must contain ``run_dplms`` (bool),
+        ``n_baselines`` (int), and ``peaks_kev`` (list).
+    ``--channel`` : str
+        Channel identifier; used as the HDF5 group name in *lh5-path*.
+    ``--raw-table-name`` : str
+        LH5 table path within the raw and peak files.
+    ``--dsp-pars`` : str
+        Output path for the updated DSP parameter database (JSON/YAML).
+    ``--lh5-path`` : str
+        Output LH5 file path for the DPLMS filter coefficients.
+    ``--plot-path`` : str, optional
+        Output path for diagnostic plots (pickle).
+    """
     argparser = argparse.ArgumentParser()
     argparser.add_argument("--fft-raw-filelist", help="fft_raw_filelist", type=str)
     argparser.add_argument("--peak-file", help="tcm_filelist", type=str, required=True)
@@ -65,12 +116,12 @@ def par_geds_dsp_dplms() -> None:
         energies = lh5.read_as(
             f"{args.raw_table_name}/daqenergy", fft_files, library="np"
         )
-        idxs = np.where(energies == 0)[0]
+        eidxs = np.where(energies <= 10)[0]
         raw_fft = lh5.read(
             args.raw_table_name,
             fft_files,
             n_rows=dplms_dict["n_baselines"],
-            idx=idxs,
+            idx=eidxs,
         )
         t1 = time.time()
         msg = f"Time to load fft data {(t1 - t0):.2f} s, total events {len(raw_fft)}"
@@ -93,30 +144,43 @@ def par_geds_dsp_dplms() -> None:
         if isinstance(dsp_config, str | list):
             dsp_config = Props.read_from(dsp_config)
 
+        dsp_fft = run_one_dsp(raw_fft, dsp_config, db_dict=db_dict)
+
+        cut_dict = generate_cuts(dsp_fft, cut_dict=dplms_dict["bls_cut_pars"])
+        log.debug("Cuts are %s", cut_dict)
+        idxs = np.full(len(dsp_fft), True, dtype=bool)
+        for outname, info in cut_dict.items():
+            outcol = dsp_fft.eval(info["expression"], info.get("parameters", None))
+            dsp_fft.add_column(outname, outcol)
+        for cut in cut_dict:
+            idxs = dsp_fft[cut].nda & idxs
+
+        selected_eidxs = eidxs[: len(dsp_fft)]
+        raw_fft = lh5.read(
+            args.raw_table_name,
+            fft_files,
+            n_rows=dplms_dict["n_baselines"],
+            idx=selected_eidxs[idxs],
+        )
+
+        log.debug("Applied Cuts")
+
+        out_dict, plot_dict = dplms_ge_dict(
+            raw_fft,
+            raw_cal,
+            dsp_config,
+            db_dict,
+            dplms_dict,
+            fom_func=eval(dplms_dict.get("fom_func", "pmd.gauss_on_step")),
+            display=1 if args.plot_path else 0,
+        )
         if args.plot_path:
-            out_dict, plot_dict = dplms_ge_dict(
-                raw_fft,
-                raw_cal,
-                dsp_config,
-                db_dict,
-                dplms_dict,
-                fom_func=eval(dplms_dict.get("fom_func", "pmd.gauss_on_step")),
-                display=1,
-            )
             if args.inplots:
                 with Path(args.inplots).open("rb") as r:
                     inplot_dict = pkl.load(r)
                 inplot_dict.update({"dplms": plot_dict})
-
-        else:
-            out_dict = dplms_ge_dict(
-                raw_fft,
-                raw_cal,
-                dsp_config,
-                db_dict,
-                dplms_dict,
-                fom_func=eval(dplms_dict.get("fom_func", "pmd.gauss_on_step")),
-            )
+            else:
+                inplot_dict = {"dplms": plot_dict}
 
         coeffs = out_dict["dplms"].pop("coefficients")
         dplms_pars = Table(col_dict={"coefficients": Array(coeffs)})
@@ -128,7 +192,7 @@ def par_geds_dsp_dplms() -> None:
     else:
         out_dict = {}
         dplms_pars = Table(col_dict={"coefficients": Array([])})
-        if args.inplots:
+        if args.plot_path and args.inplots:
             with Path(args.inplots).open("rb") as r:
                 inplot_dict = pkl.load(r)
         else:
@@ -143,7 +207,6 @@ def par_geds_dsp_dplms() -> None:
         lh5_file=args.lh5_path,
         wo_mode="overwrite",
     )
-
     Path(args.dsp_pars).parent.mkdir(parents=True, exist_ok=True)
     Props.write_to(args.dsp_pars, convert_dict_np_to_float(db_dict))
 

{legend_dataflow_scripts-0.2.3 → legend_dataflow_scripts-0.3.0}/src/legenddataflowscripts/par/geds/dsp/eopt.py

@@ -10,13 +10,13 @@ import numpy as np
 import pygama.pargen.energy_optimisation as om  # noqa: F401
 import sklearn.gaussian_process.kernels as ker
 from dbetto.catalog import Props
+from dspeed import build_dsp
 from dspeed.units import unit_registry as ureg
 from lgdo import lh5
 from pygama.math.distributions import hpge_peak
 from pygama.pargen.dsp_optimize import (
     BayesianOptimizer,
     run_bayesian_optimisation,
-    run_one_dsp,
 )
 
 from ....utils import build_log
@@ -29,6 +29,55 @@ except AttributeError:  # np < 2
 
 
 def par_geds_dsp_eopt() -> None:
+    """Optimise DSP filter parameters for energy resolution using Bayesian optimisation.
+
+    CLI entry point registered as ``par-geds-dsp-eopt``.  Reads calibration
+    peak events from an LH5 file produced by :func:`par_geds_dsp_evtsel` and
+    jointly optimises the shaping parameters (``sigma`` for CUSP and ZAC
+    filters, ``rise`` for the trapezoidal filter) and the charge-trapping
+    correction coefficient (``alpha``) for each filter type.
+
+    Optimisation uses a Gaussian-process surrogate model
+    (:class:`pygama.pargen.dsp_optimize.BayesianOptimizer`) with a configurable
+    acquisition function.  Initial samples are evaluated first; subsequent
+    iterations are selected by the acquisition function.  The optimal filter
+    parameters and CTC coefficients are written to *final-dsp-pars*, and the
+    trained optimiser objects are serialised to *qbb-grid-path*.
+
+    Notes
+    -----
+    **Command-line arguments**
+
+    ``--peak-file`` : str
+        LH5 file containing preselected calibration peak events (output of
+        ``par-geds-dsp-evtsel``).
+    ``--decay-const`` : str
+        JSON/YAML file with the current DSP parameter database (PZ constants,
+        etc.).
+    ``--inplots`` : str, optional
+        Existing pickle plot file to update with new optimisation plots.
+    ``--log`` : str, optional
+        Path to the log file.
+    ``--processing-chain`` : list of str
+        Processing chain configuration file(s).
+    ``--config-file`` : list of str
+        Energy optimisation configuration file(s).  Must contain ``run_eopt``
+        (bool), ``peaks`` (list of keV values), ``kev_widths``, ``fom``,
+        ``fom_field``, ``fom_err_field``, ``initial_samples``, ``acq_func``,
+        ``batch_size``, and ``n_iter``.
+    ``--log-config`` : str, optional
+        Logging configuration file.
+    ``--raw-table-name`` : str
+        LH5 table path within the peak file.
+    ``--final-dsp-pars`` : str
+        Output path for the optimised DSP parameter database (JSON/YAML).
+    ``--qbb-grid-path`` : str
+        Output path for the serialised optimiser objects (pickle).
+    ``--plot-path`` : str, optional
+        Output path for diagnostic plots (pickle).
+    ``--plot-save-path`` : str, optional
+        Alternative save path for plots.
+    """
     argparser = argparse.ArgumentParser()
 
     argparser.add_argument("--peak-file", help="tcm_filelist", type=str, required=True)
@@ -127,7 +176,7 @@ def par_geds_dsp_eopt() -> None:
 
         dsp_config["outputs"] = ["tp_99", "tp_0_est", "dt_eff"]
 
-        init_data = run_one_dsp(tb_data, dsp_config, db_dict=db_dict, verbosity=0)
+        init_data = build_dsp(raw_in=tb_data, dsp_config=dsp_config, database=db_dict)
         full_dt = (init_data["tp_99"].nda - init_data["tp_0_est"].nda)[idx_list[-1]]
         flat_val = np.ceil(1.1 * np.nanpercentile(full_dt, 99) / 100) / 10
 
@@ -193,7 +242,7 @@ def par_geds_dsp_eopt() -> None:
             msg = f"Initialising values {i + 1} : {db_dict}"
             log.info(msg)
 
-            tb_out = run_one_dsp(tb_data, dsp_config, db_dict=db_dict, verbosity=0)
+            tb_out = build_dsp(raw_in=tb_data, dsp_config=dsp_config, database=db_dict)
 
             res = fom(tb_out, kwarg_dict[0])
             results_cusp.append(res)
@@ -367,7 +416,7 @@ def par_geds_dsp_eopt() -> None:
 
         Path(args.qbb_grid_path).parent.mkdir(parents=True, exist_ok=True)
         with Path(args.qbb_grid_path).open("wb") as f:
-            pkl.dump(optimisers, f)
+            pkl.dump({"eopt": optimisers}, f, protocol=pkl.HIGHEST_PROTOCOL)
 
     else:
         Path(args.qbb_grid_path).touch()

{legend_dataflow_scripts-0.2.3 → legend_dataflow_scripts-0.3.0}/src/legenddataflowscripts/par/geds/dsp/evtsel.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import sys
 import time
 import warnings
 from bisect import bisect_left
@@ -12,9 +13,9 @@ import numpy as np
 import pygama.math.histogram as pgh
 import pygama.pargen.energy_cal as pgc
 from dbetto.catalog import Props
+from dspeed import build_dsp
 from lgdo import lh5
 from pygama.pargen.data_cleaning import generate_cuts, get_keys
-from pygama.pargen.dsp_optimize import run_one_dsp
 
 from ....utils import build_log, get_pulser_mask
 
@@ -33,6 +34,50 @@ def get_out_data(
     final_cut_field="is_valid_cal",
     energy_param="trapTmax",
 ):
+    """Apply cuts and assemble a calibration output table for a single gamma peak.
+
+    Evaluates the expressions in *cut_dict* on *dsp_data* and *raw_dict* on
+    *raw_data*, selects events within the energy window
+    [*e_lower_lim*, *e_upper_lim*] that also pass the *final_cut_field* flag,
+    and returns a :class:`lgdo.Table` containing both the raw waveforms and
+    key reconstructed quantities.
+
+    Parameters
+    ----------
+    raw_data : lgdo.Table
+        Raw-tier data buffer for the current batch of events.
+    dsp_data : lgdo.Table
+        DSP-tier data for the same batch.
+    cut_dict : dict
+        Mapping of ``{column_name: {"expression": str, "parameters": dict}}``
+        defining quality-cut columns to add to *dsp_data*.
+    e_lower_lim : float
+        Lower ADC bound for energy window selection.
+    e_upper_lim : float
+        Upper ADC bound for energy window selection.
+    ecal_pars : float
+        ADC-to-keV conversion factor applied to ``trapTmax``.
+    raw_dict : dict
+        Mapping of ``{column_name: {"expression": str, "parameters": dict}}``
+        defining derived columns to add to *raw_data* (e.g. calibrated DAQ
+        energy).
+    peak : float
+        Nominal gamma-line energy in keV stored as a label column.
+    final_cut_field : str
+        Boolean column name in *dsp_data* used as the final event selection
+        mask.  Defaults to ``"is_valid_cal"``.
+    energy_param : str
+        DSP energy parameter used for the window selection.  Defaults to
+        ``"trapTmax"``.
+
+    Returns
+    -------
+    out_tbl : lgdo.Table
+        Table of selected events containing windowed and pre-summed waveforms
+        plus scalar quantities (timestamp, baseline, energies, peak label).
+    n_events : int
+        Number of events in *out_tbl*.
+    """
     for outname, info in cut_dict.items():
         outcol = dsp_data.eval(info["expression"], info.get("parameters", None))
         dsp_data.add_column(outname, outcol)
@@ -81,6 +126,49 @@ def get_out_data(
 
 
 def par_geds_dsp_evtsel() -> None:
+    """Select calibration peak events for DSP parameter optimisation.
+
+    CLI entry point registered as ``par-geds-dsp-evtsel``.  Scans raw LH5
+    files, applies pulser and discharge-recovery masks, performs a rough
+    energy calibration (or uses a provided calibration curve), and collects
+    events near each specified gamma-line energy.  For each peak the data are
+    run through the DSP chain to derive quality cuts, and the surviving
+    waveforms together with reconstructed quantities are written to *peak-file*
+    in LH5 format for consumption by :func:`par_geds_dsp_eopt` and
+    :func:`par_geds_dsp_dplms`.
+
+    Notes
+    -----
+    **Command-line arguments**
+
+    ``--raw-filelist`` : list of str
+        Raw LH5 input file(s) or a single ``.filelist`` file.
+    ``--pulser-file`` : str, optional
+        Path to the pulser mask file.
+    ``-p`` / ``--no-pulse``
+        Flag indicating that no pulser is present.
+    ``--decay-const`` : str
+        JSON/YAML file with the current DSP parameter database.
+    ``--raw-cal-curve`` : list of str, optional
+        Pre-computed raw calibration curve file(s).  When provided, the
+        ``--channel`` argument is also required.
+    ``--channel`` : str, optional (required with ``--raw-cal-curve``)
+        Channel identifier used to extract the calibration curve.
+    ``--log`` : str, optional
+        Path to the log file.
+    ``--processing-chain`` : list of str
+        Processing chain configuration file(s).
+    ``--config-file`` : list of str
+        Event selection configuration file(s).  Must contain ``run_selection``
+        (bool), ``peaks`` (list of keV), ``kev_widths``, ``cut_parameters``,
+        ``n_events``, and ``final_cut_field``.
+    ``--log-config`` : str, optional
+        Logging configuration file.
+    ``--raw-table-name`` : str
+        LH5 table path within the raw file.
+    ``--peak-file`` : str
+        Output LH5 file path for selected peak events.
+    """
     argparser = argparse.ArgumentParser()
     argparser.add_argument("--raw-filelist", help="raw_filelist", type=str, nargs="*")
     argparser.add_argument(
@@ -99,6 +187,12 @@ def par_geds_dsp_evtsel() -> None:
         required=False,
     )
 
+    argparser.add_argument(
+        "--channel",
+        type=str,
+        help="Channel to process; required if --raw-cal-curve is set",
+        required="--raw-cal-curve" in sys.argv,
+    )
     argparser.add_argument("--log", help="log_file", type=str)
 
     argparser.add_argument(
@@ -247,7 +341,7 @@ def par_geds_dsp_evtsel() -> None:
         ]
 
         log.debug("Processing data")
-        tb_data = run_one_dsp(input_data, dsp_config, db_dict=db_dict)
+        tb_data = build_dsp(raw_in=input_data, dsp_config=dsp_config, database=db_dict)
 
         if cut_parameters is not None:
             cut_dict = generate_cuts(tb_data, cut_parameters)
@@ -297,8 +391,10 @@ def par_geds_dsp_evtsel() -> None:
                         peak_dict["obj_buf_start"] += n_rows_read_i
                     if peak_dict["n_rows_read"] >= 10000 or file == raw_files[-1]:
                         if "e_lower_lim" not in peak_dict:
-                            tb_out = run_one_dsp(
-                                peak_dict["obj_buf"], dsp_config, db_dict=db_dict
+                            tb_out = build_dsp(
+                                raw_in=peak_dict["obj_buf"],
+                                dsp_config=dsp_config,
+                                database=db_dict,
                             )
                             energy = tb_out[energy_parameter].nda
 
@@ -396,8 +492,10 @@ def par_geds_dsp_evtsel() -> None:
                             peak_dict["obj_buf"] is not None
                             and len(peak_dict["obj_buf"]) > 0
                         ):
-                            tb_out = run_one_dsp(
-                                peak_dict["obj_buf"], dsp_config, db_dict=db_dict
+                            tb_out = build_dsp(
+                                raw_in=peak_dict["obj_buf"],
+                                dsp_config=dsp_config,
+                                database=db_dict,
                             )
                             out_tbl, n_wfs = get_out_data(
                                 peak_dict["obj_buf"],

{legend_dataflow_scripts-0.2.3 → legend_dataflow_scripts-0.3.0}/src/legenddataflowscripts/par/geds/dsp/nopt.py

@@ -8,14 +8,52 @@ from pathlib import Path
 import numpy as np
 import pygama.pargen.noise_optimization as pno
 from dbetto.catalog import Props
+from dspeed import build_dsp
 from lgdo import lh5
 from pygama.pargen.data_cleaning import generate_cuts, get_cut_indexes
-from pygama.pargen.dsp_optimize import run_one_dsp
 
 from ....utils import build_log
 
 
 def par_geds_dsp_nopt() -> None:
+    """Optimise DSP filter parameters for noise performance.
+
+    CLI entry point registered as ``par-geds-dsp-nopt``.  Selects low-energy
+    baseline events (``daqenergy ≤ 10`` ADC) from raw LH5 files, applies
+    quality cuts derived from the preliminary DSP output, and passes the clean
+    baseline sample to :func:`pygama.pargen.noise_optimization.noise_optimization`
+    to determine optimal filter shaping parameters for noise rejection.
+
+    The resulting noise-optimisation parameters are merged with the existing
+    DSP parameter database and written to *dsp-pars*.  Optionally, diagnostic
+    plots are serialised to *plot-path*.
+
+    Notes
+    -----
+    **Command-line arguments**
+
+    ``--raw-filelist`` : str
+        Path to a text file listing the raw LH5 input files (one per line).
+    ``--database`` : str
+        Path to the existing DSP parameter database (JSON/YAML).
+    ``--inplots`` : str, optional
+        Existing pickle plot file to update with new noise-optimisation plots.
+    ``--log`` : str, optional
+        Path to the log file.
+    ``--processing-chain`` : list of str
+        Processing chain configuration file(s).
+    ``--config-file`` : list of str
+        Noise optimisation configuration file(s).  Must contain ``run_nopt``
+        (bool), ``n_events`` (int), and ``cut_pars``.
+    ``--log-config`` : str, optional
+        Logging configuration file.
+    ``--raw-table-name`` : str
+        LH5 table path within the raw file.
+    ``--dsp-pars`` : str
+        Output path for the merged DSP parameter database (JSON/YAML).
+    ``--plot-path`` : str, optional
+        Output path for diagnostic plots (pickle).
+    """
     argparser = argparse.ArgumentParser()
     argparser.add_argument("--raw-filelist", help="raw_filelist", type=str)
     argparser.add_argument("--database", help="database", type=str, required=True)
@@ -63,7 +101,7 @@ def par_geds_dsp_nopt() -> None:
         energies = lh5.read_as(
             f"{args.raw_table_name}/daqenergy", raw_files, library="np"
         )
-        idxs = np.where(energies == 0)[0]
+        idxs = np.where(energies <= 10)[0]
         tb_data = lh5.read(
             args.raw_table_name, raw_files, n_rows=opt_dict["n_events"], idx=idxs
         )
@@ -73,7 +111,7 @@ def par_geds_dsp_nopt() -> None:
 
         msg = f"Select baselines {len(tb_data)}"
         log.info(msg)
-        dsp_data = run_one_dsp(tb_data, dsp_config)
+        dsp_data = build_dsp(raw_in=tb_data, dsp_config=dsp_config)
         cut_dict = generate_cuts(dsp_data, cut_dict=opt_dict.pop("cut_pars"))
         cut_idxs = get_cut_indexes(dsp_data, cut_dict)
         tb_data = lh5.read(

{legend_dataflow_scripts-0.2.3 → legend_dataflow_scripts-0.3.0}/src/legenddataflowscripts/par/geds/dsp/pz.py

@@ -7,9 +7,9 @@ from pathlib import Path
 
 import numpy as np
 from dbetto.catalog import Props
+from dspeed import build_dsp
 from lgdo import lh5
 from pygama.pargen.data_cleaning import get_cut_indexes
-from pygama.pargen.dsp_optimize import run_one_dsp
 from pygama.pargen.pz_correct import PZCorrect
 
 from ....utils import (
@@ -20,6 +20,48 @@ from ....utils import (
 
 
 def par_geds_dsp_pz() -> None:
+    """Determine the pole-zero (PZ) decay constant(s) for HPGe waveforms.
+
+    CLI entry point registered as ``par-geds-dsp-pz``.  Selects high-energy
+    events from raw LH5 files (above an ADC threshold, excluding pulser and
+    discharge-recovery events), processes them through a preliminary DSP chain,
+    and uses :class:`pygama.pargen.pz_correct.PZCorrect` to fit either a
+    single- or double-exponential decay model to the waveform tails.
+
+    The fitted time constant(s) are written to *output-file* in JSON/YAML
+    format.  Optionally, diagnostic waveform and slope plots are serialised to
+    a pickle file at *plot-path*.
+
+    Notes
+    -----
+    **Command-line arguments**
+
+    ``--processing-chain`` : list of str
+        Processing chain configuration file(s).
+    ``--config-file`` : list of str
+        PZ calibration configuration file(s).  Must contain ``run_tau``
+        (bool), ``threshold`` (ADC), ``n_events`` (int), ``wf_field`` (str),
+        and ``mode`` (``"single"`` or ``"double"``).
+    ``--log-config`` : str, optional
+        Logging configuration file.
+    ``--raw-table-name`` : str
+        LH5 table path within the raw file (e.g. ``ch1057600/raw``).
+    ``--plot-path`` : str, optional
+        Output path for the diagnostic pickle file.
+    ``--output-file`` : str
+        Output path for the fitted PZ parameters (JSON/YAML).
+    ``--pulser-file`` : str, optional
+        Path to the pulser mask file.
+    ``-p`` / ``--no-pulse``
+        Flag indicating that no pulser is present; skips pulser masking.
+    ``--raw-files`` : list of str
+        Raw LH5 input file(s).
+    ``--pz-files`` : list of str, optional
+        Alternative input file(s) used instead of ``--raw-files`` when
+        present (e.g. preselected PZ calibration events).
+    ``--log`` : str, optional
+        Path to the log file.
+    """
     argparser = argparse.ArgumentParser()
     argparser.add_argument("--log", help="log file", type=str)
     argparser.add_argument(
@@ -134,7 +176,7 @@ def par_geds_dsp_pz() -> None:
         if "frac" in dsp_config["outputs"]:
             dsp_config_optimise_removed["outputs"].remove("frac")
 
-        tb_out = run_one_dsp(tb_data, dsp_config_optimise_removed)
+        tb_out = build_dsp(raw_in=tb_data, dsp_config=dsp_config_optimise_removed)
         log.debug("Processed Data")
         cut_parameters = kwarg_dict.get("cut_parameters", None)
         if cut_parameters is not None: