MarlinTPC  1.2.0
Classes | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | Friends | List of all members
marlintpc::PulseFinder Class Reference

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

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

Pulse charge:

Pulse time:

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

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
minimumPulseHeightThe minimum pulse height in adc count
minimumPulseLengthThe minimum pulse length in time samples
pulseStartPedestalWidthFactorThe start threshold is calculated as pulseStartPedestalWidthFactor * pedestalWidth. pedestal should be added if not already subtracted
pulseEndPedestalWidthFactorThe end threshold is calculated as pulseEndPedestalWidthFactor * pedestalWidth. pedestal should be added if not already subtracted
NoiseValuePedestalWidthFactorThe noise value is calculated as noiseValuePedestalWidthFactor * pedestalWidth.
pedestalListenerPointer 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.
adcElectronicsListenerPointer 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.
saveNBinsBeforeStartStore n bins before the first bin which is above the start threshold (default 0).
saveNBinsAfterEndStore n bins after the last bin which is above the end threshold (default 0).
timeCalculationModeThe mode used to calculate the pulse time (default INFELXION_POINT)
timeCalculationParameterparameter for time methods: fraction for constant fraction, no. of neighboring bins for center of gravity at maxbin (default 0.9 for constant fraction)
chargeCalculationModeThe 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
ADCSpectrumthe ADC spectrum to be searched
theCandidatePulsesa 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
thisPulseADC 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
datathe 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
datathe 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
datathe 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
tempPulsea helper data construct, a pair of the TrackerData of a pulse and the quality bit
noiseValuethe 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
theCandidatePulsesa vector of the pairs of start and end positions of the pulse candidates (as iterators)
noiseThresholdThreshold 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().

Member Data Documentation

bool marlintpc::PulseFinder::_isPedestalSubtractedOverride
protected

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

This overrides any information provided by LCCD

Referenced by isPedestalSubtracted(), and set_isPedestalSubtractedOverride().

float marlintpc::PulseFinder::_readoutFrequencyOverride
protected

The readout frequency of every readout group (in MHz).

This overrides any information provided by LCCD

Referenced by getReadoutFrequency(), and setReadoutFrequencyOverride().


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