The PulseFinder class is working horse of the ModularPulseFinderProcessor. More...

#include <PulseFinder.h>

Classes
struct	InternalSplitPulse
	Helper class to make more sense to the splitting phase: actually keep track of the "split" flag. More...

class	Pulse
	Helper class which combined PulseCharge and PulseTime. More...

class	PulseCharge
	Helper class to store the charge and it's error. More...

class	PulseTime
	Helper class to store the time and it's error. More...

Public Member Functions
	PulseFinder (float minimumPulseHeight, int minimumPulseLength, float pulseStartPedestalWidthFactor, float pulseEndPedestalWidthFactor, float noiseValuePedestalWidthFactor, PedestalListener const pedestalListener, ADCElectronicsListener const adcElectronicsListener, int saveNBinsBeforeStart=0, int saveNBinsAfterEnd=0, int timeCalculationMode=INFLEXION_POINT, double timeCalculationParameter=0.9, int chargeCalculationMode=SUMQ)
	The constructor. More...

std::vector< TrackerPulse * >	findPulses (TrackerData *inputData)
	Create TrackerPulses from the TrackerData input. More...

Pulse	calculatePulseTimeAndCharge (const EVENT::TrackerData *tracker_data)
	This wrapper function handles the calculation of the pulse time and the pulse charge. More...

void	setMaxADCValueOverride (float maxADCValue)
	Set an overide value for the maximal ADC value.

void	setPedestalValueOverride (float pedestalValue)
	Set an overide value for the pedestal value (in ADC counts).

void	setPedestalWidthOverride (float pedestalWidth)
	Set an overide value for the pedestal width (in ADC counts).

void	setReadoutFrequencyOverride (float readoutFrequency)
	Set an override value for the readout frequency in MHz.

void	set_isPedestalSubtractedOverride (bool isPedestalSubtracted)
	Set an override value whether the pedestal has been subtracted.

void	setPolarityOverride (int polarity)
	Set an override value for the polarity. More...

void	setForceSpectrumSave (bool doSave=true)
	Flag whether the spectrum is always stored. More...

void	setSwitchOffSplitting (bool doNotSplit=false)
	Flag whether to try to split pulses.

void	setPlateauCutOff (int maxPlateauLength)
	Set he maximum length of a plateau allowed within a pulse in time bins. More...

Static Public Member Functions
static std::string	getRevisionNumber ()
	Log the revision number.

Static Public Attributes
static const int	INFLEXION_POINT = 0
	Time is the inflexion point of the rising slope.

static const int	FIT_PARABOLA = 1
	Time and/or charge is determined by parabolic fit.

static const int	CENTRE_OF_GRAVITY = 2
	Time is the center of gravity of the charge.

static const int	FIRST_ABOVE_THRESHOLD = 3
	Time is the first sample above the start threshold.

static const int	AT_MAXIMUM = 4
	Time is the first sample at the maximum.

static const int	CONSTANT_FRACTION = 5
	Time is at the constant fraction of the maximum pulse.

static const int	GAMMA_FIT = 6
	Time from a Gamma_4 function fit to the pulse.

static const int	COG_ATMAX = 7
	COG for 2 bin range around maximum.

static const int	BOX = 8
	Box Method.

static const int	GAUSSIAN_INFLEXION = 9
	Inflexion point of a gaussian fit.

static const int	SUMQ = 0
	Charge is the sum of all ADC counts.

static const int	MAXQ = 2
	Charge is the maximal ADC value.

Protected Member Functions
void	findPulseCandidates (lcio::TrackerData thisData, std::vector< std::pair< lcio::TrackerDataImpl , int > > *tempPulse)
	Find pulses by threshold in the ADC information and closer inspection. More...

void	brutePulseSearch (TrackerData const inputTrackerData, std::vector< std::pair< std::vector< float >::const_iterator, std::vector< float >::const_iterator > > theCandidatePulses)
	The first function that is called during the pulse finding, it simply looks for values above the start threshold and below the end thresholds, the start and end positions are stored by their iterators in the original TrackerData ADC value vector. More...

std::vector< InternalSplitPulse >	splitMultiplePulses (std::vector< std::pair< std::vector< float >::const_iterator, std::vector< float >::const_iterator > > *theCandidatePulses, float noiseThreshold)
	The second part in the pulse finding process. More...

Pulse	calculatePulseWithFit (const EVENT::TrackerData *tracker_data)
	This function calculates the pulse time and charge by fitting a parabola to the log of the data surrounding the extreme point. More...

PulseTime	calcPulseTimeWithGammaFit (const lcio::TrackerData *thisPulse)
	This function calculates the pulse time and charge by fitting a Gamma_n to the pulse. More...

PulseTime	calcPulseTimeInflexionPoint (const lcio::TrackerData *thisPulse)
	Calculate the time information as the inflextion point of the rising slope. More...

PulseTime	calcPulseTimeAtMaximum (const lcio::TrackerData *thisPulse)
	Calculate the time information as the time of the bin with pulse maximum.

PulseTime	calcPulseTimeAtConstantFraction (const lcio::TrackerData *thisPulse)
	Calculate the time information as the time of crossing the threshold set by a fraction of the max. More...

PulseTime	calcPulseTimeCentreOfGravity (const lcio::TrackerData *thisPulse)
	Calculate the time information as centre of gravity.

PulseTime	calcPulseTimeCOGAtMaximum (const lcio::TrackerData *thisPulse)
	Calculate the time information as the cog for 2 bin range around the maximum.

PulseTime	calcPulseTimeFirstBinAboveThreshold (const lcio::TrackerData *thisPulse)
	Calculate the time information as the first bin above threshold.

PulseTime	calcPulseTimeBoxMethod (const lcio::TrackerData *thisPulse)
	Calculate the time information from the box method.

PulseTime	calcuPulseTimeGaussianInflexion (const lcio::TrackerData *thisPulse)
	Calculate the time information from the inflexion point of a gausssian fit.

PulseCharge	calcPulseChargeSumQ (const lcio::TrackerData *thisPulse)
	Calculate the integrated charge of the given pulse by summing up all bins of the ADC spectrum. More...

PulseCharge	calcPulseChargeMaxQ (const lcio::TrackerData *thisPulse)
	Use the maximum value as pulse charge. More...

float	getPedestalValue (const int hardware_channel, const int readout_group)
	Returns the pedestal value for a given TrackerData / TrackerPulse object taking into consideration whether it should be overwritten by the override parameter.

float	getPedestalWidth (const int hardware_channel, const int readout_group)
	Returns the pedestal width for a given TrackerData / TrackerPulse object taking into consideration whether it should be overwritten by the override parameter.

bool	isPedestalSubtracted (const int readout_group)
	Returns if the data has been pedestal subtracted in the read-out electronics or not.

int	getPolarity (const int readout_group)
	Returns the polarity of a TrackerData / TrackerPulse object taking into consideration whether is should be overwritten by the override parameter.

float	getReadoutFrequency (const int readout_group)
	Returns the readout frequency of a readout group (in Mhz) taking into consideration whether it should be overwritten by the override parameter.

float	getMaxADCValue (const int readout_group)
	Returns the maximum ADC value of a readout group taking into consideration whether it should be overwritten by the override parameter.

Protected Attributes
float	_pulseStartPedestalWidthFactor
	factor to calculate the start threshold

float	_pulseEndPedestalWidthFactor
	factor to calculate the end threshold

float	_noiseValuePedestalWidthFactor
	factor to calculate noise value

int	_timeCalculationMode
	The mode used for time calculation.

int	_COGAtMaxParameter
	parameters for time methods

double	_ConstFracParameter
	parameters for time methods

int	_chargeCalculationMode
	The mode used for charge calculation.

float	_minimumPulseHeight
	minimal value for the pulse maximum in adc counts

int	_minimumPulseLength
	minimal length for a pulse in number of time bins

int	_saveNBinsBeforeStart
	of bins stored before the start threshold

int	_saveNBinsAfterEnd
	of bins stored after the end threshold

PedestalListener const *	_pedestalListener
	the recommended way of providing the access to the pedestal values:

ADCElectronicsListener const *	_adcElectronicsListener
	the recommended way to access the electronics parameters

bool	_usePedestalValueOverride

bool	_usePedestalWidthOverride

bool	_use_isPedestalSubtractedOverride

bool	_usePolarityOverride

bool	_useReadoutFrequencyOverride

bool	_useMaxADCValueOverride

float	_maximumADCValueOverride
	maximum adc value, needed to determine if a pulse is maxed out

float	_readoutFrequencyOverride
	The readout frequency of every readout group (in MHz). More...

float	_pedestalValueOverride
	The default pedestal value which is used if the pedestalListener is not set.

float	_pedestalWidthOverride
	The default pedestal width which is used if the pedestalListener is not set.

bool	_isPedestalSubtractedOverride
	Sets, if the data is already pedestal subtracted in the read-out electronics. More...

int	_polarityOverride
	the polarity of all readout groups, overrides LCCD

bool	_forceSpectrumSave
	flag whether to always save the spectrum

bool	_switchOffSplitting
	flag whether to try to split pulses

int	_maxPlateauLength
	The maximum length of a plateau within a pulse in time bins.

Friends
class	PulseFinderTester

Detailed Description

The PulseFinder class is working horse of the ModularPulseFinderProcessor.

It contains the finding and splitting algorithms which are used in the processor. This allows for unit testing of the methods which is not possible if they are members of the processor, as processors cannot be instantiated outside of Marlin.

First the pulses are searched using a threshold based method, where the start and end thresholds are calculated from the pedestal widths and the PedestalWidthFactor parameters. Then these candidates are further processed by splitting multiple pulses. In a last step quality flags are assigned to account for

multiple pulses (changed shape/charge information)
overflows, where the ADC values are saturated
anomalous shape, currently only pulses with a long plateau which has been cut off
whether a pulse has been split

There are different modes to calculate the pulse time or the pulse charge:

Pulse charge:

SUMQ The sum of all ADC values on the pulse (the default value).
FIT_PARABOLA Parabolic fit around the maximum of the pulse.
MAXQ The maximal ADC value in the pulse.

Pulse time:

INFELXION_POINT The infexion point on the rising slope (the default value). (In fact it is the COG of the derivatives. Is this really the infelxion point? MK)
FIT_PARABOLA Parabolic fit around the maximum of the pulse.
CENTRE_OF_GRAVITY The centre of grafity of all charge in the pulse.
FIRST_ABOVE_THRESHOLD The first value abve the threshold. This method has a jitter and a walk due to threshold effects
AT_MAXIMUM Time of the sample with the maximumal value in the pulse.
CONSTANT_FRACTION Signal crossing at a constant fraction of the maximal pulse height.
GAMMA_FIT Fits a Gamma_4 function to the pulses
COG_ATMAX Center of gravity around maximum.

parameter for time methods: (default 0.9 for constant fraction)

fraction for constant fraction,
no. of neighboring bins for center of gravity at maxbin

By default also the initial TrackerData (=ADC) spectrum is stored. By setting the forceSectrumSave flag to false one can choose to store the spectrum only when one of the quality flags is set. This feature is always on.

Author: Ch. Rosemann, DESY (original author of the methods); Martin Killenberg (implementation as a separate class)

Constructor & Destructor Documentation

marlintpc::PulseFinder::PulseFinder	(	float	minimumPulseHeight,
		int	minimumPulseLength,
		float	pulseStartPedestalWidthFactor,
		float	pulseEndPedestalWidthFactor,
		float	noiseValuePedestalWidthFactor,
		PedestalListener const *	pedestalListener,
		ADCElectronicsListener const *	adcElectronicsListener,
		int	saveNBinsBeforeStart = `0`,
		int	saveNBinsAfterEnd = `0`,
		int	timeCalculationMode = `INFLEXION_POINT`,
		double	timeCalculationParameter = `0.9`,
		int	chargeCalculationMode = `SUMQ`
	)

The constructor.

Parameters

minimumPulseHeight	The minimum pulse height in adc count
minimumPulseLength	The minimum pulse length in time samples
pulseStartPedestalWidthFactor	The start threshold is calculated as pulseStartPedestalWidthFactor * pedestalWidth. pedestal should be added if not already subtracted
pulseEndPedestalWidthFactor	The end threshold is calculated as pulseEndPedestalWidthFactor * pedestalWidth. pedestal should be added if not already subtracted
NoiseValuePedestalWidthFactor	The noise value is calculated as noiseValuePedestalWidthFactor * pedestalWidth.
pedestalListener	Pointer to the pedestal listener. If you do not have a pedestal listener you can set it to NULL. In this case you have to provide override parameters for pedestalValue and pedestalWidth.
adcElectronicsListener	Pointer to the electronics listener. If you do not have an electronics listener you can set it to NULL. In this case you have to provide override values for maximumADCValue, readoutFrequency, isPedestalSubtracted and polarity.
saveNBinsBeforeStart	Store n bins before the first bin which is above the start threshold (default 0).
saveNBinsAfterEnd	Store n bins after the last bin which is above the end threshold (default 0).
timeCalculationMode	The mode used to calculate the pulse time (default INFELXION_POINT)
timeCalculationParameter	parameter for time methods: fraction for constant fraction, no. of neighboring bins for center of gravity at maxbin (default 0.9 for constant fraction)
chargeCalculationMode	The mode used to calculate the pulse charge (default SUMQ).

References _chargeCalculationMode, _COGAtMaxParameter, _ConstFracParameter, _timeCalculationMode, AT_MAXIMUM, BOX, CENTRE_OF_GRAVITY, COG_ATMAX, CONSTANT_FRACTION, FIRST_ABOVE_THRESHOLD, FIT_PARABOLA, GAMMA_FIT, GAUSSIAN_INFLEXION, INFLEXION_POINT, MAXQ, and SUMQ.

Member Function Documentation

void marlintpc::PulseFinder::brutePulseSearch	(	TrackerData const *	inputTrackerData,
		std::vector< std::pair< std::vector< float >::const_iterator, std::vector< float >::const_iterator > > *	theCandidatePulses
	)

protected

The first function that is called during the pulse finding, it simply looks for values above the start threshold and below the end thresholds, the start and end positions are stored by their iterators in the original TrackerData ADC value vector.

Here already pulses which are too short are suppressed.

Parameters

ADCSpectrum	the ADC spectrum to be searched
theCandidatePulses	a vector of the pairs of start and end positions of the pulse candidates (as iterators)

References _minimumPulseHeight, _minimumPulseLength, _pulseEndPedestalWidthFactor, _pulseStartPedestalWidthFactor, getPedestalWidth(), and getPolarity().

Referenced by findPulseCandidates(), and marlintpc::PulseFinderTester::runAllTests().

PulseFinder::PulseCharge marlintpc::PulseFinder::calcPulseChargeMaxQ ( const lcio::TrackerData * thisPulse )

protected

Use the maximum value as pulse charge.

FIXME: Does not use polarity. I think negative polarity does not work anyway from reading the rest of the code. (MK)

References getMaxADCValue(), getPedestalValue(), getPedestalWidth(), getPolarity(), and isPedestalSubtracted().

Referenced by calculatePulseTimeAndCharge(), and marlintpc::PulseFinderTester::runAllTests().

PulseFinder::PulseCharge marlintpc::PulseFinder::calcPulseChargeSumQ ( const lcio::TrackerData * thisPulse )

protected

Calculate the integrated charge of the given pulse by summing up all bins of the ADC spectrum.

The polarity of the pulse is taken into acount

Parameters

thisPulse ADC spectrum for charge calculation

References getPedestalWidth(), and getPolarity().

Referenced by calculatePulseTimeAndCharge(), and marlintpc::PulseFinderTester::runAllTests().

PulseFinder::PulseTime marlintpc::PulseFinder::calcPulseTimeAtConstantFraction ( const lcio::TrackerData * thisPulse )

protected

Calculate the time information as the time of crossing the threshold set by a fraction of the max.

charge in a pulse.

References _ConstFracParameter, getPolarity(), and getReadoutFrequency().

Referenced by calculatePulseTimeAndCharge().

PulseFinder::PulseTime marlintpc::PulseFinder::calcPulseTimeInflexionPoint ( const lcio::TrackerData * thisPulse )

protected

Calculate the time information as the inflextion point of the rising slope.

This is the default way.

References _noiseValuePedestalWidthFactor, getPedestalWidth(), getPolarity(), and getReadoutFrequency().

Referenced by calculatePulseTimeAndCharge(), and marlintpc::PulseFinderTester::runAllTests().

PulseFinder::PulseTime marlintpc::PulseFinder::calcPulseTimeWithGammaFit ( const lcio::TrackerData * thisPulse )

protected

This function calculates the pulse time and charge by fitting a Gamma_n to the pulse.

Parameters

data	the pulse data

References getReadoutFrequency().

Referenced by calculatePulseTimeAndCharge().

PulseFinder::Pulse marlintpc::PulseFinder::calculatePulseTimeAndCharge ( const EVENT::TrackerData * tracker_data )

This wrapper function handles the calculation of the pulse time and the pulse charge.

They are combined into one function because it is faster to calculate both values at the same time if the fit method is used. It can also be modified to add new methods of calculating these values without modifying the main event loop. New addition: errors on all the values! Convention: first time and time error, then charge and charge error

Parameters

data	the pulse data

References _chargeCalculationMode, _timeCalculationMode, AT_MAXIMUM, BOX, calcPulseChargeMaxQ(), calcPulseChargeSumQ(), calcPulseTimeAtConstantFraction(), calcPulseTimeAtMaximum(), calcPulseTimeBoxMethod(), calcPulseTimeCentreOfGravity(), calcPulseTimeCOGAtMaximum(), calcPulseTimeFirstBinAboveThreshold(), calcPulseTimeInflexionPoint(), calcPulseTimeWithGammaFit(), calculatePulseWithFit(), calcuPulseTimeGaussianInflexion(), CENTRE_OF_GRAVITY, COG_ATMAX, CONSTANT_FRACTION, FIRST_ABOVE_THRESHOLD, FIT_PARABOLA, GAMMA_FIT, GAUSSIAN_INFLEXION, INFLEXION_POINT, MAXQ, and SUMQ.

Referenced by findPulses().

PulseFinder::Pulse marlintpc::PulseFinder::calculatePulseWithFit ( const EVENT::TrackerData * tracker_data )

protected

This function calculates the pulse time and charge by fitting a parabola to the log of the data surrounding the extreme point.

Parameters

data	the pulse data

References getPolarity(), and getReadoutFrequency().

Referenced by calculatePulseTimeAndCharge(), and marlintpc::PulseFinderTester::runAllTests().

void marlintpc::PulseFinder::findPulseCandidates	(	lcio::TrackerData *	thisData,
		std::vector< std::pair< lcio::TrackerDataImpl , int > >	tempPulse
	)

protected

Find pulses by threshold in the ADC information and closer inspection.

This is the somewhat "master" function that determines all aspects of the pulses, it calls some further functions for easier reading.

Parameters

thisData	'raw' data as TrackerData
tempPulse	a helper data construct, a pair of the TrackerData of a pulse and the quality bit
noiseValue	the width of the pedestal

References _maxPlateauLength, _minimumPulseHeight, _minimumPulseLength, _noiseValuePedestalWidthFactor, _saveNBinsAfterEnd, _saveNBinsBeforeStart, brutePulseSearch(), getMaxADCValue(), getPedestalValue(), getPedestalWidth(), getPolarity(), isPedestalSubtracted(), and splitMultiplePulses().

Referenced by findPulses(), and marlintpc::PulseFinderTester::runAllTests().

std::vector< TrackerPulse * > marlintpc::PulseFinder::findPulses ( TrackerData * inputData )

Create TrackerPulses from the TrackerData input.

It uses findPulseCandidates and composes TrackerPulse objects out of the TrackerData.

All TrackerPulses and the contained TrackerData objects have been created on the heap. Do not forget to store them in a collection or delete them to avoid memory leaks!

Attention: When storing the pulses do not forget to store the tracker data objects they contain to a collection! Check for NULL before adding to the collection!

References _forceSpectrumSave, calculatePulseTimeAndCharge(), and findPulseCandidates().

Referenced by marlintpc::PulseFinderTester::runAllTests().

void marlintpc::PulseFinder::setForceSpectrumSave ( bool doSave = true )

Flag whether the spectrum is always stored.

By default this only happend if the quality word is not 0.

References _forceSpectrumSave.

Referenced by marlintpc::PulseFinderTester::runAllTests().

void marlintpc::PulseFinder::setPlateauCutOff ( int maxPlateauLength )

Set he maximum length of a plateau allowed within a pulse in time bins.

This used to cut off strange pulses that go into a plateau.

References _maxPlateauLength.

Referenced by marlintpc::PulseFinderTester::PulseFinderTester().

void marlintpc::PulseFinder::setPolarityOverride ( int polarity )

Set an override value for the polarity.

It should be +1 or -1.

References _polarityOverride.

Referenced by marlintpc::PulseFinderTester::PulseFinderTester().

vector< PulseFinder::InternalSplitPulse > marlintpc::PulseFinder::splitMultiplePulses	(	std::vector< std::pair< std::vector< float >::const_iterator, std::vector< float >::const_iterator > > *	theCandidatePulses,
		float	noiseThreshold
	)

protected

The second part in the pulse finding process.

Check the pulse candidates for possible multiple pulses by looking more closely at the ADC spectrum. Then replace the /old/ pairs of start/end iterators with the appropriate new number of pairs. TODO: adjust the charges in the bins at the joined boundary of the split pulses

Parameters

theCandidatePulses	a vector of the pairs of start and end positions of the pulse candidates (as iterators)
noiseThreshold	Threshold to avoid splitting at minima caused by noise on flat signals. The threshold has to be given here because it cannot be determined from the cellID as only iterators are given to this function.

References _switchOffSplitting.

Referenced by findPulseCandidates(), and marlintpc::PulseFinderTester::runAllTests().