MSADC hit-related standard handlers¶

This page lists handlers related to detectors based on (M)SADC chip (calorimeters, beam counters, etc).

Subjects: hit and SADC raw data structs¶

All the handlers listed below operate with the instances of the SADCHit C/C++ structure (and, optionally with RawDataSADC instance accessed by rawData attribute):

struct SADCHit¶

Representation of a hit on SADC-based detector entity.

GETTER:

rawData.sum – Computed sum of the waveform, number of channels (propagated from rawData:RawDataSADC, returns sum)
rawData.maxSample – Number of waveform’s sample considered as global maximum. (propagated from rawData:RawDataSADC, returns maxSample)
rawData.maxAmp – Maximum of the waveform in raw SADC units. (propagated from rawData:RawDataSADC, returns maxAmp)
rawData.maxAmpError – Error of the waveform amplitude max. in raw SADC units. (propagated from rawData:RawDataSADC, returns maxAmpError)
rawData.canBeZero – Zero probability measure (0-1) (propagated from rawData:RawDataSADC, returns canBeZero)
rawData.ledCorr – Correction by LED in use, ratio (propagated from rawData:RawDataSADC, returns ledCorr)
rawData.calibCoeff – Calibration coefficient in use, chan/MeV (propagated from rawData:RawDataSADC, returns calibCoeff)
rawData.ampThreshold – Peak-selection threshold, chan (propagated from rawData:RawDataSADC, returns ampThreshold)
rawData.pedestalEven – Returns even pedestal value (for sample 0, 2, 4 …) (propagated from custom getter rawData:RawDataSADC, returns pedestalEven)
rawData.pedestalOdd – Returns odd pedestal value (for sample 1, 3, 5 …) (propagated from custom getter rawData:RawDataSADC, returns pedestalOdd)
rawData.chargeVsMaxAmpRatio – Calculates ratio between sum and max. amplitude (propagated from custom getter rawData:RawDataSADC, returns chargeVsMaxAmpRatio)
eDep – Reconstructed energy deposition, MeV.
eDepError – Error estimation of reconstructed energy deposition (sigma), MeV
time – Reconstructed time of hit, nanoseconds
timeError – Estimateion of reconstructed time error (sigma), nanoseconds

Public Functions

SADCHit(LocalMemory&)¶: A ctr, needs the pool allocator instance to be bound with.

Public Members

mem::Ref<RawDataSADC> rawData¶: Hit raw data (as got from DDD digit)

float eDep¶: Reconstructed energy deposition, MeV.

float eDepError¶: Error estimation of reconstructed energy deposition (sigma), MeV.

float time¶: Reconstructed time of hit, nanoseconds.

float timeError¶: Estimateion of reconstructed time error (sigma), nanoseconds.

struct RawDataSADC¶

Raw SADC waveform and subsidiary related information.

GETTER:

getter for field RawDataSADC::wave disabled
getter for field RawDataSADC::pedestals disabled
sum – Computed sum of the waveform, number of channels
maxSample – Number of waveform’s sample considered as global maximum.
maxAmp – Maximum of the waveform in raw SADC units.
maxAmpError – Error of the waveform amplitude max. in raw SADC units.
canBeZero – Zero probability measure (0-1)
ledCorr – Correction by LED in use, ratio
calibCoeff – Calibration coefficient in use, chan/MeV
ampThreshold – Peak-selection threshold, chan
getter for field RawDataSADC::maxima disabled
pedestalEven – Returns even pedestal value (for sample 0, 2, 4 …)
pedestalOdd – Returns odd pedestal value (for sample 1, 3, 5 …)
chargeVsMaxAmpRatio – Calculates ratio between sum and max. amplitude

Public Functions

RawDataSADC(LocalMemory&)¶: A ctr, needs the pool allocator instance to be bound with.

Public Members

StdFloat_t wave[32]¶: Array of measured waveform samples.

mem::Ref<MSADCDFFTCoefficients> fft¶: Discrete Fourer transform results.

StdFloat_t pedestals[2]¶: ADC amplitude pedestal values (zeroes) for even and odd sampler.

StdFloat_t sum¶: Computed sum of the waveform, number of channels.

uint8_t maxSample¶: Number of waveform’s sample considered as global maximum.

StdFloat_t maxAmp¶: Maximum of the waveform in raw SADC units.

StdFloat_t maxAmpError¶: Error of the waveform amplitude max. in raw SADC units.

StdFloat_t canBeZero¶: Zero probability measure (0-1)

StdFloat_t ledCorr¶: Correction by LED in use, ratio.

StdFloat_t calibCoeff¶: Calibration coefficient in use, chan/MeV.

StdFloat_t ampThreshold¶: Peak-selection threshold, chan.

event::Map<int, MSADCPeak, MapTag::ordered_sparse> maxima¶: Peaks found in the waveform, used in reconstruction.

Note, that SADCHit may have its rawData reference unset. For instance, when events are read from Monte-Carlo data source.

Handlers list¶

This handlers deal with (M)SADC hits at the very basic level of DAQ digits.

group sadc-handlers

class PickMasterTime : public na64dp::AbstractHandler, public na64dp::calib::Handle<std::pair<std::string, float>>, public na64dp::calib::Handle<nameutils::DetectorNaming>¶

Copies time estimation from certain detector to a masterTime value.

Relies on (masterTimeDetName;std::string) “calibration” data type that provides name of the detector being used as one providing master time info. For each event will pick the time from hit’s time field and copy it to the Event::masterTime field.

- _type: PickMasterTime
  # Defines handler's reaction if no master time hit is found in an event.
  # Possible choices are: "omit", "drop", "emitError"; str, optional
  onNoHitInMaster: "emitError"
  # If set, forces handler to use this detector name string instead of
  # one brought by run information (calib info "masterTimeSource");
  # str, optional
  override: ""
  # Offset added to the extracted master time; opt, float
  offset: 0.

Depends on “naming” and “masterTimeSource” calibration data.

Todo:: Shall we here consider non-physical events with no master time?

Note

Currently, support only SADC detector as master time source (unclear, whether we will ever use one of another type).

class SADCAppendPeds : public na64dp::AbstractHitHandler<event::SADCHit>¶

Sums up pedestal value(s) and SADC waveform.

A MSADC handler that performs a reverse transformation with MSADC waveform with respect to SADCSubtractPedestals.

- _type: SADCAppendPeds

See also

SADCSubtractPedestals

class ApplySADCCalibsType1 : public na64dp::AbstractHitHandler<SADCHit>, public na64dp::calib::Handle<calib::Collection<calib::SADCCalib>>¶

Uses “standard” SADC calibrations from p348reco of SDC format.

- _type: ApplySADCCalibsType1
  # optional, hit selection expression
  applyTo: null
  # if set, will raise error if no calib data defined; bool, opt
  requireAllDefined: true
  # calibration data subclass; str, opt
  calibSubclass: "default"
  # Set this to apply LED corrections of type#1 (S.Donskov). Besides of
  # usual detector selection logic expression, accepts "none" (disables
  # LEDs corrections) and "all"; str, opt
  applyLEDType1To: none

May use LED corrections, if certain type is

Todo:: Currently selection expression for LEDs is not fully supported. Setting it to not “none” string will turn it on unconditionally

class SADCDirectSum : public na64dp::AbstractHitHandler<event::SADCHit>¶

Computes linear sum of SADC waveform.

This handler calculates the sum on the SADC hit waveform by summing up all the 32 samples.

- _type: SADCDirectSum
  # negative samples will be zeroed, bool, optional
  zeroNegativeValues: false

Accepts single parameter “zeroNegativeValues:bool” that, when set to true makes the handler to set negative samples to 0. Can be omitted, default value is false.

See also

SADCLinearSum

class SADCFindMaxima : public na64dp::AbstractHitHandler<event::SADCHit>¶

Finds local maxima in SADC waveform.

Usage:

- _type: SADCFindMaxima
  # optional, hit selection expression
  applyTo: ...
  # A type of criterion applied; str, opt
  criterion: simple
  # a threshold used by some criteria; double, optional
  threshold: 0.
  # if set, hits with zero amplitude or amp below the threshold will
  # be removed; bool, optional
  removeZeroLikeHits: false

Handler will iterates over 1-31 samples of SADC waveform (RawDataSADC::wave) finding ones which:

for criterion: simple – \(i\)-th sample where both \((i+1)\)-th and \((i-1)\)-th samples are below \(i\)-th and their average difference from \(i\)-th smaple is more than threshold value specified
for criterion: p348reco – \(i\)-th sample that is strictly above both \((i-1)\)-th and \((i+1)\)-th.

Found samples numbers (“maxima”) will populate RawDataSADC::maxima field, delimiting end with max value for uint8_t type. Note that this handler won’t set maximaTimes yet – the nSample-to-time conversion is the subject of dedicate handlers as algoritm may not be trivial. For instance, see SADCTimeAtMaxByCoM, SADCTimeAtMaxByRisingEdge, etc.

YAML config accepts standard

Todo:: Document criteria

See also

commonApplyTo argument.

Note

With “p348reco” peak-slection criterion is equivalent to Cell::searchPeaks() procedure of p348reco.

class SADCFindMaxSimple : public na64dp::AbstractHitHandler<event::SADCHit>¶

Finds maximum sample in SADC waveform.

This is simple straightforward max finder. Iterates over 32 samples finding the greatest amplitude and writes this value and corresponding sample number to maxValue and maxSample fields of SADC hit.

- _type: SADCFindMaxSimple
  # optional, hit selection expression
  applyTo: ...

YAML config only accepts standard detector-by-name selection argument.

Todo:: remove this simple one in favour of more generic selectMax

class SADCGetPedestalsByFront : public na64dp::AbstractHitHandler<event::SADCHit>¶

#include <getPedestalsByFront.hh>

Takes into account first N samples assuming mean values as pedestals.

Parameterized by number of samples nSamples taken for each SADC channel. E.g. for nSamples: 4, 4*2=8 initial values (from 32) will be taken. Two mean values for SADCHit::pedestals[0,1] will be then written in corresponding hit at RawDataSADC::pedestals.

Usaeg:

- _type: SADCGetPedestalsByFront
# Number of samples per each channel to consider; int, opt
nSamples: 4
# Threshold value in raw ADC scale that, if set to non-zero and exceeded
# makes the handler to take minimal value per channel instead of
# mean; int, opt
useMinIfDeltaExceeds: 20

Parameter maxPedestalSpanning, if greater than zero, sets threshold for min/max difference among the considered samples. If this threshold is exceeded, the pedestal considered as one affected by the event pile-up and minimal value will be then searched among all the 16 samples for this channel. Setting maxPedestalSpanning to 0 disables this behaviour.

This handler does not perform subtraction. Use dedicated handler to apply pedestal subtraction afterwards (e.g. SADCSubtractPedestals).

Result of applying the subtraction with pedestals derived with this handler can be demonstrated visually by means of SADCAmpHists handler. Before subtracting pedestals:

../_images/sadc-amp-before.png

After subtraction:

../_images/sadc-amp-after.png

YAML config node examples:

- _type: SADCGetPedestalsByFront

or

- _type: SADCGetPedestalsByFront
  nSamples: 4

See also

SADCSubtractPedestals

Subclassed by na64dp::handlers::SADCMovStatPeds

class SADCLinearSum : public na64dp::AbstractHitHandler<event::SADCHit>¶

Computes linear sum of SADC waveform.

This handler calculates the integral approximation (“sum”) on the SADC hit waveform by taking mean values between two adjacent sample values. It may be assumed as more precise estimation of the waveform integral than direct sum of samples.

- _type: SADCLinearSum
  # negative samples will be zeroed, bool, optional
  zeroNegativeValues: true

Accepts single parameter “zeroNegativeValues:bool” that, when set to true makes the handler to set negative samples to 0. Can be omitted, default value is false.

See also

SADCDirectSum

class SADCMovStatPeds : public na64dp::handlers::SADCGetPedestalsByFront, public na64dp::calib::Handle<calib::Pedestals>¶

Moving statistics pedestals calculus.

This handler implements more robust pedestals derivation than straightforward algorithm SADCGetPedestalsByFront by involving windowed (rolling, sliding) statistical state that takes into account some fixed amount of pedestals being previously calculated. Particular implementation of the sliding statistics is choosen by iMovStats implementation supplied by ctr.

- _type: SADCMovStatPeds
  applyTo: "kin == HCAL"
  nSamples: 4
  dropOutlierEvent: true
  scorer:
    type: klein
    window: 500
    excludeOutliers: true
    recacheOutliers: true
    recachingFrac: 0.

YAML parameters:

name — see AbstractHitHandler
applyTo — see AbstractHitHandler
nSamples — number of samples within the waveform to use (see SADCGetPedestalsByFront)
dropOutlierEvent — whether to discard the hit and stop event propagation if hit is identified as an outlier.
scorer — type of scorer to use. Possible values: double for plain scorer, fast but prone to catastrophic cancellation error or klein for more precise but slower one.
- window — number of hits stored for sliding stats calculus
- excludeOutliers — whether to exclude outliers ( \(x_i - \mu > 3 \sigma\)) from statistics calculus
- recacheOutliers — whether to re-cache sums when accounted outliers leave the window of moving statistics
- recachingFrac — part (in the units of window) of stored events that makes scorer to recalculate moving statistics. E.g. for recachingFrac=1.5 of window=100, every 150 events will cause re-caching of sums. Used as a side measure to circumvent the catastrophic cancellation. Set to 0 to prevent from this type of movstat recaching.

Todo:: Support for savedScorers parameter — a template path string denoting the place where the scorer state has to be saved. Useful for reentrant usage to stabilize sliding statistics during the initial read-out.

See also

SADCGetPedestalsByFront

class SADCPlotPeakMult : public na64dp::util::GenericTDirAdapter<DetID>, public na64dp::AbstractHitHandler<event::SADCHit>¶

1D histogram depicting maxima multiplicity (per hit)

This handler is somewhat useful to tune threshold-parameters for max-finding algorithms.

- _type: SADCPlotPeakMult
  # optional, hit selection expression
  applyTo: null
  # histogram base name; str, opt
  baseName: "maxMult"

class SADCPlotMaxs : public na64dp::util::GenericTDirAdapter<DetID>, public na64dp::AbstractHitHandler<event::SADCHit>¶

Combined plot of the time estimations for maxima.

- _type: SADCPlotMaxs
  # number of bins for vertical axis of 2D histogram; int, required
  ampNBins: ...
  # histogram range for vertical axis; list of two floats, required
  ampRange: [..., ...]
  # histogram's base name; str required
  baseName: ...

class SADCPlotWaveform : public na64dp::util::GenericTDirAdapter<DetID>, public na64dp::AbstractHitHandler<event::SADCHit>¶

Combined plot of the sampled amplitude from SADC detectors.

This handler depicts a somewhat combined image of multiple waveforms from SADC detector in a single histogram. It might be useful for various qualitative checks and assurance considerations.

- _type: SADCPlotWaveform
  # if set, a TProfile is used instead of TH2F. When set handler
  # constructor will ignore `ampNBins` and `ampRange`
  # parameters; optional, bool
  profile: false
  # optional, hit selection expression
  applyTo: null
  # histogram base name; str, required
  baseName: "amps-pedCorrected"
  # number of bins by vertical axis; int, required
  ampNBins: 200
  # histogram range by vertical axis; list of two floats, required
  ampRange: [0, 4000]

SADC typically provides a time-descrete measurement of the voltage/current waveform produced by PMT or SiPM detector as an array of 32 measurements. Each time detector entity was triggered this handler puts all 32 digits onto the 2D histogram. After number of events processed, a somwhat of “averaged” picture can be observed for qualitative checks. For example, the picture below indicates that previous handlers did not apply any pedestals subtraction to the waveform leading to what whan may call “saw-shape”.

../_images/sadc-amp-before.png

Cf. with the same picture (produced by the same handler) after dynamic pedestals subtraction handler (DynSubtractPeds) applied:

../_images/sadc-amp-after.png

Since SADC detectors in NA64 always produce 32 samples per hit, this value is hardcoded within this handler implementation.

This handler uses TDirAdapter class to put the particular histogram into approprite TDirectory instance within ROOT’s TFile.

Other types of histograms considering some scalar hit-related properties may be produced with templated version of the 1D/2D histogram, — see HitHistogram1D and HitHistogram2D, but for this type of plot it required a standalone handler.

See also

TDirAdapter

class SADCSelectMax : public na64dp::AbstractHitHandler<SADCHit>, public na64dp::calib::Handle<calib::Collection<calib::SADCCalib>>¶

Takes maximum (peak) value from SADC waveform.

Retrieves the global maximum peak position within a given SADC waveform (globally, within required samples range only, or within range given by timing sigma from calib info) and writes it to RawDataSADC::maxAmp and its sample to RawDataSADC::maxSample of SADCHit’s SADCHit::rawData.

- _type: SADCSelectMax
  # optional, hit selection expression
  applyTo: null
  # Which methods to apply to pick up certain maximum, in order of
  # preference; list of strings, required
  methods: [...]
  # What to do if none of the methods succeed with maximum selection.
  # Possible choices: "ignore", "warn", "removeHit", "discriminateEvent",
  # "emitError"; str, optional
  onFailure: "emitError"
  # When set, makes handler do nothing in events when no master time
  # is set; bool, optional
  tolerateNoMaster: false
  # Makes handler to consider only maxima values in this range (sample
  # number); list of two ints, optional
  lookupRange: [0, 255]

Requires set of maxima (SADCHit’s RawData::maxima) to be filled (for instance, by handler SADCFindMaxima). If time-selection method is involved, peak timing info must be available in the hit as well (RawDataSADC::maximaTimes, filled, for instance with SADCTimeAtMaxByRisingEdge handler).

Methods:

“closestTime” — tries to use calibration information about average peak position with respect to master time/own mean time of the detector. Note, that if master time is not set and corresponding calibration time relies on it, behaviour varies depending on option “onFailure” parameter. Affected by “lookupRange”.
”maxAmp” — just takes maximum peak position (in “lookupRange”, if set).

Todo:: (minor opt) Respect “applyTo” in handle_update()

Note

Somewhat analoguous to Cell::peak_BestTiming() and Cell::peak_Best() of p348reco.

Note

sets SADCHit::time to uncalibrated value (in sample units). This was decided because some peak selection algorithms sometimes provide a good timing estimation with precision better than integer sample number.

class SADCSubtractPedestals : public na64dp::AbstractHitHandler<event::SADCHit>¶

#include <subtractPedestals.hh>

Subtracts SADC pedestal values written in hit instance from waveform.

This handler relies on presence of pedestal values in pedestal field of SADCHit class. It will subtract corresponding (even or odd) pedestal value from waveform entries of SADCHit, modifying its value.

Use SADCGetPedestalsByFront, MovStatPeds or similar handler to retreive the pedestal values for the hit(s).

- _type: SADCSubtractPedestals
  # negative samples to zero; bool, optional
  nullifyNegative: true
  # opt, generates error if pedestal value is missed; bool, optional
  errorOnMissed: true

See also

SADCAppendPeds reverse transformation

See also

SADCGetPedestalsByFront a handler assuming pedestals based on first N samples

See also

MovStatPeds a handler finding avrg pedestals in “moving window”

class SADCTimeAtMaxByCoM : public na64dp::AbstractHitHandler<SADCHit>¶

Calculates time estimations for the peak maxima for SADC waveform by “center of mass” algorithm.

Relies on RawDataSADC::maxima field of SADC hit to find out time estimations (in number-of-sample units) for the mixima (peaks) of sadc waveform.

- _type: SADCTimeAtMaxByCoM
  # optional, hit selection expression
  applyTo: null
  # Take into account samples in this range; list of two ints, optional
  signalRange: [15, 32]
  # Whether time estimation is relative wrt max value; bool, opt
  isRelative: false
  # Use this value as time interval between two samples (nanoseconds);
  # float, optional
  nsPerSample: 12.5

Time estimations are in nanoseconds, the scaling unit (nanoseconds per sample) is defined by parameter “nsPerSample”. “isRelative” parameter defines whether or not search window is defined in scale absolute or relative to max, i.e. “isRelateve=false” for “signalRange”=[15,32] will mean that weighted mean will be computed from 15 to 32 sample while “isRelative=true” for “signalRange”=[-3,2] will mean that weigthed mean is computed within in a window relative to current max that starts 3 samples before and ends 2 samples after max being considered.

,

class SADCTimeAtMaxByRisingEdge : public na64dp::AbstractHitHandler<SADCHit>¶

Calculates time estimations for the peak maxima for SADC waveform by “rising edge” algorithm.

Relies on RawDataSADC::maxima field of SADC hit to find out time estimations for the mixima (peaks) of sadc waveform.

- _type: SADCTimeAtMaxByRisingEdge
  # optional, hit selection expression
  applyTo: null
  # A threshold for rising edge. Maxima with lower inclination won't be
  # considered; float, opt
  risingEdgeThreshold: 0.5
  # enables "half height" mode; bool, opt
  halfHeight: false
  # Use this value as time interval between two samples (nanoseconds);
  # float, optional
  nsPerSample: 12.5

Time estimations are in nanoseconds, the scaling unit (nanoseconds per sample) is defined by parameter “nsPerSample”.

May set NaN for those peaks where algorithm failed to find rising edge with given threshold.

,

class SADCWfAnalyze : public na64dp::AbstractHitHandler<event::SADCHit>¶

Development handler.

This handler is not intended for general usage; it’s a development prototype for finer waveform inspection.

Note

To be (re)moved.