WaveformAnalysisRAVEN Class Reference

Ratpac-two: RAT::WaveformAnalysisRAVEN Class Reference

Ratpac-two

Perform reverse sparse non-negative least squares fitting and NPE likelihood estimation on digitized waveforms. More...

#include <WaveformAnalysisRAVEN.hh>

Inheritance diagram for RAT::WaveformAnalysisRAVEN:

Public Member Functions
	WaveformAnalysisRAVEN (std::string config_name)

void	BuildDictionaryMatrix (int nsamples, double digitizer_period)

void	Configure (const std::string &config_name) override

void	SetD (std::string param, double value) override

void	SetI (std::string param, int value) override

Public Member Functions inherited from RAT::WaveformAnalyzerBase
	WaveformAnalyzerBase ()=delete

	WaveformAnalyzerBase (std::string _procname, std::string config_name)

virtual void	SetS (std::string param, std::string value) override

virtual void	RunAnalysis (DS::DigitPMT digitpmt, int pmtID, Digitizer fDigitizer)

virtual void	RunAnalysis (DS::DigitPMT digitpmt, int pmtID, DS::Digit dsdigit)

Processor::Result	Event (DS::Root ds, DS::EV ev) override

virtual std::string	GetAnalyzerName () const

Public Member Functions inherited from RAT::Processor
	Processor (std::string _name)

virtual	~Processor ()

std::string	GetName () const

virtual void	SetF (std::string param, float value)

virtual Processor::Result	DSEvent (DS::Root *ds)

virtual void	BeginOfRun (DS::Run *run)

virtual void	EndOfRun (DS::Run *run)

Protected Member Functions
void	DoAnalysis (DS::DigitPMT *digitpmt, const std::vector< UShort_t > &digitWfm) override

TVectorD	Thresholded_rsNNLS (const TMatrixD &W_region, const TVectorD &voltVec, const double threshold, double &chi2ndf_out, int &iterations_out)
	Perform reverse sparse NNLS with iterative thresholding on a region submatrix.

std::vector< std::pair< int, int > >	FindThresholdRegions (const std::vector< double > &voltWfm, double threshold, int region_padding)
	Find threshold crossing regions in waveform for efficient processing.

void	ProcessThresholdRegion (const std::vector< double > &voltWfm, int start_sample, int end_sample, DS::WaveformAnalysisResult *fit_result, double gain_calibration)
	Process a single threshold crossing region with rsNNLS.

void	ExtractPhotoelectrons (const TVectorD &region_weights, int dict_start, int dict_cols, int start_sample, int end_sample, double chi2ndf, int iterations_ran, DS::WaveformAnalysisResult *fit_result, double gain_calibration)
	Extract photoelectrons from significant weights in the region.

std::vector< std::pair< double, double > >	MergeNearbyWeights (const TVectorD &region_weights, int dict_start, int dict_cols, double merge_window)

Protected Attributes
DBLinkPtr	fDigit

bool	process_threshold_crossing
	Whether to use threshold crossing region processing.

double	voltage_threshold
	Voltage threshold for threshold crossing region detection.

int	threshold_region_padding
	Number of samples to pad around threshold crossing regions.

int	template_type
	Template type: 0=lognormal, 1=gaussian.

double	lognormal_scale
	LogNormal 'm' parameter for SPE template.

double	lognormal_shape
	LogNormal 'sigma' parameter for SPE template.

double	gaussian_width
	Gaussian 'sigma' parameter for SPE template.

double	vpe_charge
	Nominal charge of single PE in pC.

TMatrixD	fW
	Dictionary matrix for NNLS (nsamples × dict_size)

double	epsilon
	NNLS convergence tolerance.

size_t	max_iterations
	Maximum iterations for iterative thresholding.

double	upsample_factor
	Dictionary upsampling factor for sub-sample resolution.

double	weight_threshold
	Minimum weight threshold for component significance.

double	weight_merge_window
	Time window (ns) for merging nearby weights before NPE estimation.

bool	npe_estimate
	Whether to perform NPE estimation on resolved wave packets.

double	npe_estimate_charge_width
	Width of Gaussian single-PE charge distribution.

size_t	npe_estimate_max_pes
	Upper limit for NPE estimation.

bool	dictionary_built
	Flag to track if dictionary has been built.

int	cached_nsamples
	Cached number of samples for dictionary.

double	cached_digitizer_period
	Cached digitizer period for dictionary.

Protected Attributes inherited from RAT::WaveformAnalyzerBase
double	fTimeStep

double	fVoltageRes

double	fTermOhms

double	fMinTotalCharge = std::numeric_limits<double>::lowest()

double	fMaxTotalCharge = std::numeric_limits<double>::max()

Protected Attributes inherited from RAT::Processor
std::string	name

Additional Inherited Members
Public Types inherited from RAT::Processor
enum	Result { OK = 0 , FAIL = 1 , ABORT = 2 }

Detailed Description

Perform reverse sparse non-negative least squares fitting and NPE likelihood estimation on digitized waveforms.

Author: Ravi Carpen Pitelka rpite.nosp@m.lka@.nosp@m.sas.u.nosp@m.penn.nosp@m..edu

REVISION HISTORY:
12 Sep 2025: Initial commit 12 Nov 2025: Added to ratpac-two 15 Jan 2026: Added region-based processing and NPE estimation features 09 Feb 2026: Renamed to RAVEN

RAVEN (Reverse Analysis of Voltage Events with Nonegativity) is a waveform analysis algorithm that performs reverse sparse non-negative least squares (rsNNLS) analysis, followed by NPE likelihood estimation on digitized PMT waveforms to reconstruct photoelectron times and charges.

The algorithm uses region-based processing for improved efficiency:

Builds a dictionary matrix of time-shifted templates
Identifies threshold crossing regions in the waveform for localized processing
For each region, extracts relevant dictionary submatrix and applies NNLS fitting
Uses iterative thresholding to remove low-weight components and redistribute weights
Extracts PE times and charges from remaining significant weights

Template types supported:

Lognormal
Gaussian

Member Function Documentation

◆ Configure()

void RAT::WaveformAnalysisRAVEN::Configure ( const std::string & config_name )

overridevirtual

Configure the processor. This method will be called upon processor instantiation.

Parameters

config_name An index that is typically used to index table DIGITIZER_ANALYSIS in ratdb. Although technically you can use it for anything. In the base class this does nothing for now. But stuff can be added in the future if we would like to set parameters for all processors.

Reimplemented from RAT::WaveformAnalyzerBase.

◆ DoAnalysis()

void RAT::WaveformAnalysisRAVEN::DoAnalysis	(	DS::DigitPMT *	digitpmt,
		const std::vector< UShort_t > &	digitwfm
	)

overrideprotectedvirtual

Implementation of the waveform analysis.

Parameters

digitpmt	Pointer to the digitpmt where analysis results are written to.
digitwfm	Waveform to analyze, in ADC units.

See WaveformAnalysisLognormal for a concrete example. In order to write results, instantiate a RAT::DS::WaveformAnalysisResult object via digitpmt->GetOrCreateWaveformAnalysisResult("procName").

Implements RAT::WaveformAnalyzerBase.

◆ MergeNearbyWeights()

std::vector< std::pair< double, double > > RAT::WaveformAnalysisRAVEN::MergeNearbyWeights	(	const TVectorD &	region_weights,
		int	dict_start,
		int	dict_cols,
		double	merge_window
	)

protected

Merge nearby weights within a time window to prevent PE overcounting Returns vector of (time, merged_weight) pairs

◆ SetD()

void RAT::WaveformAnalysisRAVEN::SetD	(	std::string	param,
		double	value
	)

overridevirtual

Functions that gets called for /procset lines in the macro. Base class does nothing.

Reimplemented from RAT::WaveformAnalyzerBase.

◆ SetI()

void RAT::WaveformAnalysisRAVEN::SetI	(	std::string	param,
		int	value
	)

overridevirtual

Set integer parameter.

Parameters

[in]	param	Name of parameter.
[in]	value	Value of parameter.

Exceptions

ParamUnknown	if param is not recognized.
ParamInvalid	if value is not allowed for param.

Reimplemented from RAT::WaveformAnalyzerBase.

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

/home/docs/checkouts/readthedocs.org/user_builds/ratpac/checkouts/latest/src/daq/include/RAT/WaveformAnalysisRAVEN.hh
/home/docs/checkouts/readthedocs.org/user_builds/ratpac/checkouts/latest/src/daq/src/WaveformAnalysisRAVEN.cc

WaveformAnalysisRAVEN Class Reference

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ Configure()

◆ DoAnalysis()

◆ MergeNearbyWeights()

◆ SetD()

◆ SetI()