legend-dataflow-scripts 0.3.0a5__tar.gz → 0.3.0a6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: legend-dataflow-scripts
-Version: 0.3.0a5
+Version: 0.3.0a6
 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: legend-dataflow-scripts
-Version: 0.3.0a5
+Version: 0.3.0a6
 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

{legend_dataflow_scripts-0.3.0a5 → legend_dataflow_scripts-0.3.0a6}/src/legenddataflowscripts/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0a5'
-__version_tuple__ = version_tuple = (0, 3, 0, 'a5')
+__version__ = version = '0.3.0a6'
+__version_tuple__ = version_tuple = (0, 3, 0, 'a6')
 
-__commit_id__ = commit_id = 'g2f2cce849'
+__commit_id__ = commit_id = 'g66e026ac8'

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

@@ -15,6 +15,55 @@ 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)

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

@@ -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)

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

@@ -34,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)
@@ -82,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(

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

@@ -16,6 +16,44 @@ 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)

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

@@ -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(

legend_dataflow_scripts-0.3.0a6/src/legenddataflowscripts/par/geds/dsp/svm.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from dbetto.catalog import Props
+
+
+def par_geds_dsp_svm() -> None:
+    """Register a pre-trained SVM model file in the DSP parameter database.
+
+    CLI entry point registered as ``par-geds-dsp-svm``.  Reads an existing
+    DSP parameter file from *input-file*, appends a ``svm`` key that points to
+    the SVM model pickle file via a ``loadlh5``-compatible path template, and
+    writes the result to *output-file*.
+
+    The model path is stored as a relative reference using the ``$_``
+    directory variable so the parameter file remains portable when the
+    production directory is relocated.
+
+    Notes
+    -----
+    **Command-line arguments**
+
+    ``--log`` : str, optional
+        Path to the log file.
+    ``--output-file`` : str
+        Output path for the updated DSP parameter file (JSON/YAML).
+    ``--input-file`` : str
+        Input DSP parameter file (JSON/YAML) to update.
+    ``--svm-file`` : str
+        Path to the serialised SVM model pickle file.
+    """
+    argparser = argparse.ArgumentParser()
+    argparser.add_argument("--log", help="log file", type=str)
+    argparser.add_argument(
+        "--output-file", help="output par file", type=str, required=True
+    )
+    argparser.add_argument(
+        "--input-file", help="input par file", type=str, required=True
+    )
+    argparser.add_argument("--svm-file", help="svm file", required=True)
+    args = argparser.parse_args()
+
+    par_data = Props.read_from(args.input_file)
+
+    file = f"'$_/{Path(args.svm_file).name}'"
+
+    par_data["svm"] = {"model_file": file}
+
+    Path(args.output_file).parent.mkdir(parents=True, exist_ok=True)
+    Props.write_to(args.output_file, par_data)

{legend_dataflow_scripts-0.3.0a5 → legend_dataflow_scripts-0.3.0a6}/src/legenddataflowscripts/par/geds/dsp/svm_build.py

@@ -12,6 +12,36 @@ from ....utils import build_log
 
 
 def par_geds_dsp_svm_build() -> None:
+    """Train a Support Vector Machine (SVM) classifier for HPGe pulse-shape discrimination.
+
+    CLI entry point registered as ``par-geds-dsp-svm-build``.  Loads
+    pre-processed training data from LH5 files (table ``ml_train/dsp``),
+    extracts the normalised discrete wavelet transform features
+    (``dwt_norm``) and class labels (``dc_label``), trains a
+    :class:`sklearn.svm.SVC` with configurable hyperparameters, and serialises
+    the trained model to *output-file* as a pickle file.
+
+    When no training data files are provided (``--train-data`` is empty or
+    absent) the output file is written with ``None`` as the model, acting as a
+    placeholder.
+
+    Notes
+    -----
+    **Command-line arguments**
+
+    ``--log`` : str, optional
+        Path to the log file.
+    ``--log-config`` : str, optional
+        Logging configuration file.
+    ``--output-file`` : str
+        Output path for the serialised SVM model (pickle).
+    ``--train-data`` : list of str, optional
+        LH5 file(s) containing training data under ``ml_train/dsp``.
+    ``--train-hyperpars`` : list of str, optional
+        JSON/YAML file(s) with SVM hyperparameters: ``random_state``,
+        ``kernel``, ``decision_function_shape``, ``class_weight``, ``C``,
+        and ``gamma``.
+    """
     argparser = argparse.ArgumentParser()
     argparser.add_argument("--log", help="log file", type=str)
 

{legend_dataflow_scripts-0.3.0a5 → legend_dataflow_scripts-0.3.0a6}/src/legenddataflowscripts/par/geds/hit/aoe.py

@@ -28,6 +28,21 @@ warnings.filterwarnings(action="ignore", category=RuntimeWarning)
 
 
 def get_results_dict(aoe_class):
+    """Extract serialisable results from a calibrated :class:`~pygama.pargen.AoE_cal.CalAoE` object.
+
+    Parameters
+    ----------
+    aoe_class : pygama.pargen.AoE_cal.CalAoE
+        Calibrated A/E object after calling :meth:`~pygama.pargen.AoE_cal.CalAoE.calibrate`.
+
+    Returns
+    -------
+    dict
+        Mapping of run timestamp → results dictionary.  Each entry contains
+        the calibration energy parameter, drift-time parameter, correction
+        fit results, low-side and two-sided survival fractions (both overall
+        and per-run), and the A/E cut values.
+    """
     result_dict = {}
     for tstamp in aoe_class.low_side_sfs_by_run:
         result_dict[tstamp] = {
@@ -58,6 +73,52 @@ def run_aoe_calibration(
     debug_mode=False,
     override_dict=None,
 ):
+    """Run the A/E calibration and update all output dictionaries.
+
+    Instantiates :class:`~pygama.pargen.AoE_cal.CalAoE` and calls
+    :meth:`~pygama.pargen.AoE_cal.CalAoE.calibrate` on *data*.  All input
+    mapping arguments are keyed by run timestamp and the corresponding output
+    mappings are returned with the A/E results merged in.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame
+        Event-level data containing the energy, current-amplitude, and
+        drift-time parameters required by the A/E calibration.
+    cal_dicts : dict
+        ``{timestamp: operations_dict}`` mapping of existing hit-level
+        calibration operations.  Updated in-place with the A/E cut
+        expressions.
+    results_dicts : dict
+        ``{timestamp: results_dict}`` mapping of calibration results from
+        preceding steps (energy calibration, partition calibration).
+    object_dicts : dict
+        ``{timestamp: object_dict}`` mapping of pickled calibration objects
+        from preceding steps.
+    plot_dicts : dict
+        ``{timestamp: plot_dict}`` mapping of existing plot dictionaries.
+    config : dict or str or list
+        A/E calibration configuration.  Must contain ``run_aoe`` (bool),
+        ``current_param``, ``energy_param``, ``cal_energy_param``,
+        ``cut_field``, and ``threshold``.
+    debug_mode : bool
+        Activates additional diagnostic output in :class:`~pygama.pargen.AoE_cal.CalAoE`.
+        Defaults to ``False``.
+    override_dict : dict, optional
+        Per-detector override parameters passed to
+        :meth:`~pygama.pargen.AoE_cal.CalAoE.calibrate`.
+
+    Returns
+    -------
+    cal_dicts : dict
+        Updated calibration operations mappings.
+    out_result_dicts : dict
+        Updated results mappings including A/E results.
+    out_object_dicts : dict
+        Updated object mappings including the ``CalAoE`` instance.
+    out_plot_dicts : dict
+        Updated plot mappings including A/E diagnostic figures.
+    """
     if isinstance(config, str | list):
         config = Props.read_from(config)
 
@@ -182,6 +243,55 @@ def run_aoe_calibration(
 
 
 def par_geds_hit_aoe() -> None:
+    """Calibrate the A/E (current-amplitude over energy) pulse-shape discriminant.
+
+    CLI entry point registered as ``par-geds-hit-aoe``.  Loads DSP data for a
+    single detector channel, applies energy and pulser masks, and runs
+    :func:`run_aoe_calibration` to derive the A/E mean, width, and cut
+    values as a function of energy and (optionally) drift time.  Results are
+    written to *hit-pars* (JSON/YAML) and the calibration object is serialised
+    to *aoe-results* (pickle).
+
+    Notes
+    -----
+    **Command-line arguments**
+
+    ``files`` : list of str
+        One or more file lists (``.filelist``) containing DSP LH5 paths.
+    ``--pulser-file`` : str, optional
+        Path to the pulser mask file.
+    ``--tcm-filelist`` : str, optional
+        Unused placeholder.
+    ``--ecal-file`` : str
+        Energy calibration output file (JSON/YAML with ``pars`` and
+        ``results`` keys).
+    ``--eres-file`` : str
+        Energy calibration pickle file containing calibration objects.
+    ``--inplots`` : str, optional
+        Existing pickle plot file to merge with A/E plots.
+    ``--timestamp`` : str
+        Run timestamp label (default ``"20000101T000000Z"``).
+    ``--log`` : str, optional
+        Path to the log file.
+    ``--log-config`` : str, optional
+        Logging configuration file.
+    ``--config-file`` : list of str
+        A/E calibration configuration file(s).
+    ``--table-name`` : str
+        LH5 table path within the DSP files.
+    ``--detector`` : str, optional
+        Detector name used to look up override parameters.
+    ``--override-files`` : list of str, optional
+        JSON/YAML file(s) with detector-specific override parameters.
+    ``--plot-file`` : str, optional
+        Output path for diagnostic plots (pickle).
+    ``--hit-pars`` : str
+        Output path for the A/E hit parameters (JSON/YAML).
+    ``--aoe-results`` : str
+        Output path for the serialised A/E calibration object (pickle).
+    ``-d`` / ``--debug``
+        Enable debug mode for additional diagnostic output.
+    """
     argparser = argparse.ArgumentParser()
     argparser.add_argument("files", help="files", nargs="*", type=str)
     argparser.add_argument(
@@ -294,8 +404,8 @@ def par_geds_hit_aoe() -> None:
 
         data["run_timestamp"] = args.timestamp
 
-        if args.override.files:
-            override_dict = Props.read_from(args.override.files)
+        if args.override_files:
+            override_dict = Props.read_from(args.override_files)
             override_dict = override_dict.get(args.detector, None)
 
         cal_dict, results_dicts, object_dicts, plot_dicts = run_aoe_calibration(