Waveform processing pipeline: baseline, trigger, crop, features, cuts. More...

#include <WaveformProcessingUtils.hpp>

Public Member Functions
	WaveformProcessingUtils ()
	Construct with the FileProcessingConfig defaults.
	WaveformProcessingUtils (const FileProcessingConfig &config)
	Construct from an explicit configuration.
	~WaveformProcessingUtils ()
	Closes any open output file and releases the internal buffer.
void	SetPolarity (const Int_t polarity)
	Set the pulse polarity.
void	SetTriggerThreshold (Double_t threshold)
	Set the trigger level as a fraction of each waveform's peak.
void	SetNumberOfSamplesForBaseline (Int_t num_samples_baseline)
	Set how many leading samples are averaged for the baseline.
void	SetSampleWindows (Int_t pre_samples, Int_t post_samples)
	Set the crop window around the trigger.
void	SetGates (Int_t pre_gate, Int_t short_gate, Int_t long_gate)
	Set the integration gates, in samples.
void	SetMaxEvents (Int_t max_events)
	Cap the number of waveforms read per file.
void	SetVerbose (Bool_t verbose)
	Enable or disable progress and summary output.
void	SetStoreWaveforms (Bool_t store=kTRUE)
	Choose whether cropped waveforms are written to the output tree.
void	SetSaveSampleWaveforms (Int_t count)
	Set how many example waveforms are saved as figures.
void	SetAdcSaturationCode (Int_t adc_saturation_code)
	Set the ADC code that counts as full scale.
Bool_t	ProcessWaveform (const TArrayI &samples)
	Run one raw waveform through the whole pipeline.
void	SubtractBaseline (const TArrayI &samples)
	Estimate and remove the baseline, writing to the internal buffer.
Float_t	FindTrigger (const TArrayF &waveform)
	Find the first sample crossing the fractional trigger level.
void	CropWaveform (const TArrayF &waveform, Int_t trigger_pos)
	Cut the region of interest around the trigger.
WaveformFeatures	ExtractFeatures (const TArrayF &cropped_wf)
	Compute the per-waveform features of a cropped waveform.
Bool_t	ApplyQualityCuts (const WaveformFeatures &features)
	Decide whether a waveform survives the quality cuts.
void	SaveSampleWaveform (const TArrayF &waveform)
	Write one waveform out as a figure for visual inspection.
void	PrintAllStatistics () const
	Print the run statistics, including mean baseline RMS.
ProcessingStats	GetStats () const
	Snapshot of the current statistics.
Bool_t	ProcessFile (const TString filepath, const TString output_name)
	Process one input file end to end.

Static Public Member Functions
static void	ProcessFilesParallel (const std::vector< TString > &filepaths, const std::vector< TString > &output_names, const FileProcessingConfig &config, Int_t max_workers=4)
	Process many files concurrently, one instance per worker.

Detailed Description

Waveform processing pipeline: baseline, trigger, crop, features, cuts.

Typical use is to construct one from a FileProcessingConfig and call ProcessFile(), or to hand a list of files to ProcessFilesParallel().

Warning: The pipeline stages — SubtractBaseline(), FindTrigger(), CropWaveform(), ExtractFeatures() — are public but are not standalone utilities. They communicate through an internal waveform buffer that each stage overwrites, and they mutate the statistics counters. Call them in pipeline order, or call ProcessWaveform(), which sequences them and enforces the preconditions each one assumes.

Note: One instance is not safe to share across threads. ProcessFilesParallel() gives every worker its own instance for exactly this reason.

Definition at line 137 of file WaveformProcessingUtils.hpp.

Constructor & Destructor Documentation

◆ WaveformProcessingUtils() [1/2]

WaveformProcessingUtils::WaveformProcessingUtils ( )

Construct with the FileProcessingConfig defaults.

Definition at line 5 of file WaveformProcessingUtils.cpp.

Referenced by ProcessFilesParallel(), and WaveformProcessingUtils().

◆ WaveformProcessingUtils() [2/2]

WaveformProcessingUtils::WaveformProcessingUtils ( const FileProcessingConfig & config )

Construct from an explicit configuration.

Parameters

config Processing parameters; copied into the instance.

Definition at line 8 of file WaveformProcessingUtils.cpp.

◆ ~WaveformProcessingUtils()

WaveformProcessingUtils::~WaveformProcessingUtils ( )

Closes any open output file and releases the internal buffer.

Definition at line 22 of file WaveformProcessingUtils.cpp.

Member Function Documentation

◆ ApplyQualityCuts()

Bool_t WaveformProcessingUtils::ApplyQualityCuts ( const WaveformFeatures & features )

Decide whether a waveform survives the quality cuts.

Rejects, in order: a raw extremum sitting on the ADC rail (the saturation code for positive polarity, zero for negative); more than 50% of long-gate samples below zero, which indicates a bad baseline; and a non-positive long-gate integral.

Parameters

features Features to test. raw_pulse_height must already be set.

Returns: kTRUE if the waveform passes every cut.

Note: Increments the matching ProcessingStats rejection counter on failure.

Definition at line 236 of file WaveformProcessingUtils.cpp.

Referenced by ProcessWaveform().

◆ CropWaveform()

void WaveformProcessingUtils::CropWaveform	(	const TArrayF &	waveform,
		Int_t	trigger_pos )

Cut the region of interest around the trigger.

Keeps pre_samples before and post_samples after trigger_pos, and writes the result into the internal waveform buffer.

Parameters

waveform	Baseline-subtracted waveform.
trigger_pos	Trigger sample index, from FindTrigger().

Warning: trigger_pos must be at least pre_samples, and the waveform must extend more than post_samples beyond it. The start index is not clamped, so a smaller trigger position reads before the start of the array. ProcessWaveform() checks both bounds before calling this; a direct caller must do the same.

Definition at line 183 of file WaveformProcessingUtils.cpp.

Referenced by ProcessWaveform().

◆ ExtractFeatures()

WaveformFeatures WaveformProcessingUtils::ExtractFeatures ( const TArrayF & cropped_wf )

Compute the per-waveform features of a cropped waveform.

Integration starts at pre_samples - pre_gate within the crop and runs for short_gate and long_gate samples respectively, each clipped to the end of the waveform.

Parameters

cropped_wf Cropped, baseline-subtracted waveform.

Returns: The extracted features. raw_pulse_height is left unset here — ProcessWaveform() fills it from the raw trace, and the clipping cut depends on it.

Definition at line 199 of file WaveformProcessingUtils.cpp.

Referenced by ProcessWaveform().

◆ FindTrigger()

Float_t WaveformProcessingUtils::FindTrigger ( const TArrayF & waveform )

Find the first sample crossing the fractional trigger level.

The level is trigger_threshold times the waveform's own maximum, so it adapts to pulse amplitude rather than being an absolute ADC threshold.

Parameters

waveform Baseline-subtracted waveform.

Returns: Index of the first sample at or above the level, as a Float_t, or -1.0 if no sample reaches it.

Definition at line 167 of file WaveformProcessingUtils.cpp.

Referenced by ProcessWaveform().

◆ GetStats()

ProcessingStats WaveformProcessingUtils::GetStats ( ) const

inline

Snapshot of the current statistics.

Returns: A copy of the counters accumulated so far.

Definition at line 364 of file WaveformProcessingUtils.hpp.

◆ PrintAllStatistics()

void WaveformProcessingUtils::PrintAllStatistics ( ) const

Print the run statistics, including mean baseline RMS.

Reports the counters plus two means: baseline RMS over all processed waveforms, and over accepted ones only. The same summary is written to the .stats file alongside the output.

Definition at line 258 of file WaveformProcessingUtils.cpp.

Referenced by ProcessFile().

◆ ProcessFile()

Bool_t WaveformProcessingUtils::ProcessFile	(	const TString	filepath,
		const TString	output_name )

Process one input file end to end.

Opens the input in the configured InputFormat, creates the output tree, runs every waveform through ProcessWaveform(), then writes the tree, the sample figures, and the .stats summary.

Parameters

filepath	Path to the input file.
output_name	Output basename, without extension, resolved against the ROOT files base directory.

Returns: kTRUE on success; kFALSE if the input could not be opened or the output could not be written.

Definition at line 340 of file WaveformProcessingUtils.cpp.

Referenced by ProcessFilesParallel().

◆ ProcessFilesParallel()

void WaveformProcessingUtils::ProcessFilesParallel	(	const std::vector< TString > &	filepaths,
		const std::vector< TString > &	output_names,
		const FileProcessingConfig &	config,
		Int_t	max_workers = 4 )

static

Process many files concurrently, one instance per worker.

Enables ROOT thread safety and IO::SetThreadSafe(), then dispatches the files in batches of max_workers, waiting for each batch to finish before starting the next. Every worker constructs its own WaveformProcessingUtils from config, so no state is shared.

Parameters

filepaths	Input files.
output_names	Output basenames, positionally matched to `filepaths`. Must be the same length.
config	Configuration copied into every worker.
max_workers	Concurrent workers. 4 by default; a value of 0 or less means hardware concurrency. Capped at the number of files.

Note: Batches are synchronous, so one slow file holds up the start of the next batch. Per-file success or failure is printed as each completes; there is no aggregate return value.

Warning: Enables ROOT thread safety process-wide as a side effect, which cannot be undone.

Definition at line 467 of file WaveformProcessingUtils.cpp.

◆ ProcessWaveform()

Bool_t WaveformProcessingUtils::ProcessWaveform ( const TArrayI & samples )

Run one raw waveform through the whole pipeline.

Subtracts the baseline, finds the trigger, crops, extracts features, applies the quality cuts, and on success fills the output tree. Updates the statistics counters in every case.

Parameters

samples Raw digitiser samples for one waveform, in ADC counts.

Returns: kTRUE if the waveform was accepted and written; kFALSE if it was empty, failed to trigger, sat too close to an end of the record to crop, or failed a quality cut. The specific cause is recorded in the corresponding ProcessingStats counter.

Note: Requires an open output tree, so it is only meaningful between the setup and teardown performed by ProcessFile().

Definition at line 37 of file WaveformProcessingUtils.cpp.

Referenced by ProcessFile().

◆ SaveSampleWaveform()

void WaveformProcessingUtils::SaveSampleWaveform ( const TArrayF & waveform )

Write one waveform out as a figure for visual inspection.

Parameters

waveform Waveform to plot, normally the cropped one.

Note: Serialised across threads on an internal mutex, because ROOT canvas creation is not concurrency-safe. Stops having any effect once sample_waveforms_to_save figures have been written.

Definition at line 100 of file WaveformProcessingUtils.cpp.

Referenced by ProcessWaveform().

◆ SetAdcSaturationCode()

void WaveformProcessingUtils::SetAdcSaturationCode ( Int_t adc_saturation_code )

inline

Set the ADC code that counts as full scale.

Parameters

adc_saturation_code Full-scale code, e.g. 16384 for a 14-bit digitiser. Used only for the clipping cut.

Definition at line 242 of file WaveformProcessingUtils.hpp.

◆ SetGates()

void WaveformProcessingUtils::SetGates	(	Int_t	pre_gate,
		Int_t	short_gate,
		Int_t	long_gate )

inline

Set the integration gates, in samples.

Parameters

pre_gate	Offset back from pre_samples at which integration starts.
short_gate	Width of the short gate.
long_gate	Width of the long gate. Should exceed `short_gate`; the PSD ratio is meaningless otherwise.

Definition at line 214 of file WaveformProcessingUtils.hpp.

◆ SetMaxEvents()

void WaveformProcessingUtils::SetMaxEvents ( Int_t max_events )

inline

Cap the number of waveforms read per file.

Parameters

max_events Maximum count, or -1 for no limit.

Definition at line 222 of file WaveformProcessingUtils.hpp.

◆ SetNumberOfSamplesForBaseline()

void WaveformProcessingUtils::SetNumberOfSamplesForBaseline ( Int_t num_samples_baseline )

inline

Set how many leading samples are averaged for the baseline.

Parameters

num_samples_baseline Sample count. Must be at least 2 for a baseline RMS to be computed; with 1 the baseline is still subtracted but no RMS is recorded.

Definition at line 196 of file WaveformProcessingUtils.hpp.

◆ SetPolarity()

void WaveformProcessingUtils::SetPolarity ( const Int_t polarity )

inline

Set the pulse polarity.

Parameters

polarity -1 for negative-going pulses, +1 for positive-going.

Definition at line 182 of file WaveformProcessingUtils.hpp.

◆ SetSampleWindows()

void WaveformProcessingUtils::SetSampleWindows	(	Int_t	pre_samples,
		Int_t	post_samples )

inline

Set the crop window around the trigger.

Parameters

pre_samples	Samples kept before the trigger.
post_samples	Samples kept after the trigger.

Definition at line 203 of file WaveformProcessingUtils.hpp.

◆ SetSaveSampleWaveforms()

void WaveformProcessingUtils::SetSaveSampleWaveforms ( Int_t count )

inline

Set how many example waveforms are saved as figures.

Parameters

count Number of figures to write, for visual inspection.

Definition at line 235 of file WaveformProcessingUtils.hpp.

◆ SetStoreWaveforms()

void WaveformProcessingUtils::SetStoreWaveforms ( Bool_t store = kTRUE )

inline

Choose whether cropped waveforms are written to the output tree.

Parameters

store kTRUE (default) to store them. Turning this off leaves only the scalar features and shrinks the output substantially.

Definition at line 231 of file WaveformProcessingUtils.hpp.

◆ SetTriggerThreshold()

void WaveformProcessingUtils::SetTriggerThreshold ( Double_t threshold )

inline

Set the trigger level as a fraction of each waveform's peak.

Parameters

threshold Fraction in (0, 1]. Larger values trigger later on the rising edge.

Definition at line 187 of file WaveformProcessingUtils.hpp.

◆ SetVerbose()

void WaveformProcessingUtils::SetVerbose ( Bool_t verbose )

inline

Enable or disable progress and summary output.

Parameters

verbose kTRUE to print.

Definition at line 226 of file WaveformProcessingUtils.hpp.

◆ SubtractBaseline()

void WaveformProcessingUtils::SubtractBaseline ( const TArrayI & samples )

Estimate and remove the baseline, writing to the internal buffer.

Averages the first num_samples_baseline samples, subtracts that level, and inverts the result when polarity is -1 so the pulse is positive either way. Also computes the baseline RMS and folds it into the statistics.

Parameters

samples Raw digitiser samples, in ADC counts.

Note: Writes the result into the internal waveform buffer, replacing whatever was there. The baseline RMS is only computed when at least two baseline samples are available.

Definition at line 131 of file WaveformProcessingUtils.cpp.

Referenced by ProcessWaveform().

The documentation for this class was generated from the following files:

include/WaveformProcessingUtils.hpp
src/WaveformProcessingUtils.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ WaveformProcessingUtils() [1/2]

◆ WaveformProcessingUtils() [2/2]

◆ ~WaveformProcessingUtils()

Member Function Documentation

◆ ApplyQualityCuts()

◆ CropWaveform()

◆ ExtractFeatures()

◆ FindTrigger()

◆ GetStats()

◆ PrintAllStatistics()

◆ ProcessFile()

◆ ProcessFilesParallel()

◆ ProcessWaveform()

◆ SaveSampleWaveform()

◆ SetAdcSaturationCode()

◆ SetGates()

◆ SetMaxEvents()

◆ SetNumberOfSamplesForBaseline()

◆ SetPolarity()

◆ SetSampleWindows()

◆ SetSaveSampleWaveforms()

◆ SetStoreWaveforms()

◆ SetTriggerThreshold()

◆ SetVerbose()

◆ SubtractBaseline()