legenddataflowscripts.par.geds.dsp package

Submodules

legenddataflowscripts.par.geds.dsp.dplms module

legenddataflowscripts.par.geds.dsp.dplms.par_geds_dsp_dplms()

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 par_geds_dsp_evtsel().

The coefficients are computed by 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-fileliststr

Path to a text file listing the FFT raw LH5 input files.

--peak-filestr

LH5 file containing preselected calibration peak events.

--inplotsstr, optional

Existing pickle plot file to update with DPLMS plots.

--databasestr

Path to the existing DSP parameter database (JSON/YAML).

--logstr, optional

Path to the log file.

--log-configstr, optional

Logging configuration file.

--processing-chainlist of str

Processing chain configuration file(s).

--config-filelist of str

DPLMS configuration file(s). Must contain run_dplms (bool), n_baselines (int), and peaks_kev (list).

--channelstr

Channel identifier; used as the HDF5 group name in lh5-path.

--raw-table-namestr

LH5 table path within the raw and peak files.

--dsp-parsstr

Output path for the updated DSP parameter database (JSON/YAML).

--lh5-pathstr

Output LH5 file path for the DPLMS filter coefficients.

--plot-pathstr, optional

Output path for diagnostic plots (pickle).

legenddataflowscripts.par.geds.dsp.eopt module

legenddataflowscripts.par.geds.dsp.eopt.par_geds_dsp_eopt()

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

LH5 file containing preselected calibration peak events (output of par-geds-dsp-evtsel).

--decay-conststr

JSON/YAML file with the current DSP parameter database (PZ constants, etc.).

--inplotsstr, optional

Existing pickle plot file to update with new optimisation plots.

--logstr, optional

Path to the log file.

--processing-chainlist of str

Processing chain configuration file(s).

--config-filelist 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-configstr, optional

Logging configuration file.

--raw-table-namestr

LH5 table path within the peak file.

--final-dsp-parsstr

Output path for the optimised DSP parameter database (JSON/YAML).

--qbb-grid-pathstr

Output path for the serialised optimiser objects (pickle).

--plot-pathstr, optional

Output path for diagnostic plots (pickle).

--plot-save-pathstr, optional

Alternative save path for plots.

legenddataflowscripts.par.geds.dsp.evtsel module

legenddataflowscripts.par.geds.dsp.evtsel.get_out_data(raw_data, dsp_data, cut_dict, e_lower_lim, e_upper_lim, ecal_pars, raw_dict, peak, 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 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.

legenddataflowscripts.par.geds.dsp.evtsel.par_geds_dsp_evtsel()

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 par_geds_dsp_eopt() and par_geds_dsp_dplms().

Notes

Command-line arguments

--raw-filelistlist of str

Raw LH5 input file(s) or a single .filelist file.

--pulser-filestr, optional

Path to the pulser mask file.

-p / --no-pulse

Flag indicating that no pulser is present.

--decay-conststr

JSON/YAML file with the current DSP parameter database.

--raw-cal-curvelist of str, optional

Pre-computed raw calibration curve file(s). When provided, the --channel argument is also required.

--channelstr, optional (required with --raw-cal-curve)

Channel identifier used to extract the calibration curve.

--logstr, optional

Path to the log file.

--processing-chainlist of str

Processing chain configuration file(s).

--config-filelist 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-configstr, optional

Logging configuration file.

--raw-table-namestr

LH5 table path within the raw file.

--peak-filestr

Output LH5 file path for selected peak events.

legenddataflowscripts.par.geds.dsp.nopt module

legenddataflowscripts.par.geds.dsp.nopt.par_geds_dsp_nopt()

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 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-fileliststr

Path to a text file listing the raw LH5 input files (one per line).

--databasestr

Path to the existing DSP parameter database (JSON/YAML).

--inplotsstr, optional

Existing pickle plot file to update with new noise-optimisation plots.

--logstr, optional

Path to the log file.

--processing-chainlist of str

Processing chain configuration file(s).

--config-filelist of str

Noise optimisation configuration file(s). Must contain run_nopt (bool), n_events (int), and cut_pars.

--log-configstr, optional

Logging configuration file.

--raw-table-namestr

LH5 table path within the raw file.

--dsp-parsstr

Output path for the merged DSP parameter database (JSON/YAML).

--plot-pathstr, optional

Output path for diagnostic plots (pickle).

legenddataflowscripts.par.geds.dsp.pz module

legenddataflowscripts.par.geds.dsp.pz.par_geds_dsp_pz()

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 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-chainlist of str

Processing chain configuration file(s).

--config-filelist 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-configstr, optional

Logging configuration file.

--raw-table-namestr

LH5 table path within the raw file (e.g. ch1057600/raw).

--plot-pathstr, optional

Output path for the diagnostic pickle file.

--output-filestr

Output path for the fitted PZ parameters (JSON/YAML).

--pulser-filestr, optional

Path to the pulser mask file.

-p / --no-pulse

Flag indicating that no pulser is present; skips pulser masking.

--raw-fileslist of str

Raw LH5 input file(s).

--pz-fileslist of str, optional

Alternative input file(s) used instead of --raw-files when present (e.g. preselected PZ calibration events).

--logstr, optional

Path to the log file.

legenddataflowscripts.par.geds.dsp.svm module

legenddataflowscripts.par.geds.dsp.svm.par_geds_dsp_svm()

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

--logstr, optional

Path to the log file.

--output-filestr

Output path for the updated DSP parameter file (JSON/YAML).

--input-filestr

Input DSP parameter file (JSON/YAML) to update.

--svm-filestr

Path to the serialised SVM model pickle file.

legenddataflowscripts.par.geds.dsp.svm_build module

legenddataflowscripts.par.geds.dsp.svm_build.par_geds_dsp_svm_build()

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

--logstr, optional

Path to the log file.

--log-configstr, optional

Logging configuration file.

--output-filestr

Output path for the serialised SVM model (pickle).

--train-datalist of str, optional

LH5 file(s) containing training data under ml_train/dsp.

--train-hyperparslist of str, optional

JSON/YAML file(s) with SVM hyperparameters: random_state, kernel, decision_function_shape, class_weight, C, and gamma.