Generic Handlers

This page lists a generic handlers. These handlers must be specialized by certain type and/or a value to operate with.

Access to the subject data is then performed via a special access function referred further as getter.

Getters are listed in the corresponding section of the hit structure descriptions.

group generic-handlers

Typedefs

template<typename HitT>
using Histogram1D = handlers::GetterBasedROOTHistHandler<HitT, 1, TH1F>

A 1D histogram plotting handler.

A generic handler used to plot a single (optionally, weighted) variable distribution.

../_images/Histogram1D-example-1.png../_images/Histogram1D-example-2.png

Usage: 

- _type: Histogram1D
  # Specifies a getter to use to retrieve a value from subject
  # type; str, required
  value: ...
  # A base _type for the histogram; str, required
  histName: ...
  # A description string template; required, str
  histDescr: ...
  # Number of bins in the histogram; int, required
  nBins: ...
  # Axis range to use; list of two floats, required
  range: [..., ...]
  # A multiplication factor apply for the value. Useful to re-scale
  # histogram in different units (for instance, MeV to GeV); float, optional
  factor: 1.0
  # To plot weighted histograms, this parameter may refer to a value
  # (getter) to be considered as a weighting function; float, optional
  weight: null
  # A path template within a TFile for the histogram object. If not
  # specified (or empty), a default one for the collection type will be
  # used; optional, str
  path: ""

Possible subjects (see links for lists of available getters for value):

The ...-per-plane differs from its counterpart (like APVHit-per-plane from apvHits) in the sense that for -per-plnae version a one histogram per plane, while its counterpart bounds with an elementary sensitive element (e.g. wire for GEMs or MMs).

Users typically won’t need the -per-wire versions unless very fine granularity is need (e.g. cross-talk studies).

Note

Defined as a template alias to generic template GetterBasedROOTHistHandler

template<typename HitT>
using Histogram2D = handlers::GetterBasedROOTHistHandler<HitT, 2, TH1F>

A 2D histogram plotting handler.

A generic handler used to plot a pair (optionally, weighted) variable distribution, joint within certain hit type.

Usage: 

- _type: Histogram2D
  # A base _type for the histogram; str, required
  histName: ...
  # A description string template; required, str
  histDescr: ...
  # To plot weighted histograms, this parameter may refer to a value
  # (getter) to be considered as a weighting function; float, optional
  weight: null
  # A path template within a TFile for the histogram object. If not
  # specified (or empty), a default one for the collection type will be
  # used; optional, str
  path: ""
  # When enabled a TProfile is used instead of TH2F. Note, that second
  # (y) axis parameters will be ignored, but still required, if this
  # flag is set; optional, bool
  profile: flase

  # Specifies a getter to use to retrieve an abscissa value (horizontal
  # axis) from subject
  # type; str, required
  valueX: ...
  # Number of bins in the histogram (horizontal axis); int, required
  nBinsX: ...
  # A range to use by horizontal axis; list of two floats, required
  rangeX: [..., ...]
  # A multiplication factor apply for horizontal axis. Useful to
  # re-scale histogram in different units (for instance, MeV to
  # GeV); float, optional
  factorX: 1.0

  # Specifies a getter to use to retrieve an ordinate value (vertical
  # axis) from subject
  # type; str, required
  valueY: ...
  # Number of bins in the histogram (vertical axis); int, required
  nBinsY: ...
  # A range to use by vertical axis; list of two floats, required
  rangeY: [..., ...]
  # A multiplication factor apply for vertical axis; float, optional
  factorY: 1.0

Possible subjects (see links for lists of available getters for value):

Note

Track (na64dp::event::Track) is not supported yet

Note

Defined as a template alias to generic template GetterBasedROOTHistHandler

template<typename HitT>
class Discriminate : public na64dp::AbstractHitHandler<HitT>
#include <discriminate.hh>

Removes items from event and/or stops event propagation based on certain criterion.

Usage (generic form): 

- _type: Discriminate
  # Specifies a getter to use to retrieve a value tested by
  # criterion, the comparison operation and the value with wich to
  # compare; str, required
  expression: ...
  # Inverts meaning of above expression; str, optional
  invert: false
  # Whether to remove hit from event on match (if getter relates to a
  # hit); bool, optional
  removeHit: false
  # Whether to stop iterating of entities of the subject type within
  # current event; bool, optional
  abruptHitProcessing: false
  # Whether to stop propagating this event by pipeline; bool, optional
  discriminateEvent: false
  # optional, hit selection expression
  applyTo: ...

Using this handler in generic form may be tedious because of the boolean flags, and that’s why some shortcuts are available (this is the same handler, but with different defaults):

Shortcut to remove hits (all hits iterated, event propagated further), not available for Event subject (1st level getters cause error): 

- _type: RemoveHits
  # Specifies a criterion and sets handler in the state when hits
  # that does not match to criterion will be removed. Mutually exclusive
  # with `ifDoesNotMatch`; str, required one of
  ifDoesNotMatch: ...
  # Specifies a criterion and sets handler in the state when only hits
  # that passes criterion will be left in an event. Mutually exclusive
  # with `ifMatches`; str, required one of
  ifDoesNotMatch: ...
  # optional, hit selection expression
  applyTo: ...

Examples for expression/ifMatches/… field:

  • binary comparison: sadcHits.eDep > 1.5, 23 == apvHits.rawData.rawData, etc.

  • ternanry (ranged) comparison: 10 <= caloHit.eDep < 100

If condition in expression is satisfied, the effect defined in following parameters will take place (in order of precedence):

  • if removeHit is set, hit will be deleted from basic event’s collection;

  • if abruptHitProcessing no hit in this collection will be considered in the pipeline anymore (say, no more SADC hits checked in current event);

  • if discriminateEvent is set, event won’t propagate further by the pipeline.

Please, take note that removing an item (a hit) from event does not necessarily mean it will be removed from collections that indirectly refer it. For instance, if APVHit is part of APVCluster and it is “removed” by this handler with removeHit: true, this hit will remain in the cluster, but none of subsequent handlers operating at the event level will see it.

Todo:

This handler will be probably removed in favour of more generic one, once the JIT-compiled DSL for value selection will be implemented.

Warning

Note that NaN value results false for every comparison expression (“equals”, “less than” etc), so if your configuration is meant to remove also NaN values, a formulation with invert may come in handy.

class EventIDSwitch : public na64dp::AbstractHandler

Enables handlers for certain events range.

This handler conditionally forwards event to one of its descendants, based on current event ID. Used for conditional execution of certain reconstruction routine, depending on run ID, data taking period, etc. Resembles switch/case clause from imperative languages.

- _type: EventIDSwitch
  switch:
     - case: ['123.1.1', '123.1.2', '124.*.*', '125.1.1-127.3.4']
       pipeline:
         # ...
     - case: "./selected-events.txt"
       pipeline:
         # ...
  # how to forward steering flags from sub-pipelines
  onStop: forward          # "forward"/"ignore"/"discriminate"
  onDiscriminate: forward  # "forward"/"ignore"/"stop"
  # fallback cases
  # - no match found
  onNoMatch: error         # "ignore"/"discriminate"/"error" or define fallback in pipeline
  # - selection overlaps
  onMultipleMatch: error   # "applyAll"/"applyNone"/"discriminate"/"error" or define fallback in pipeline
class Subpipe : public na64dp::AbstractHandler, public na64dp::Pipeline
#include <sub.hh>

A recurrent pipeline.

Provides a way to embed a pipeline within another pipeline.

Usage note: embedded handlers list shall be provided in pipeline property as either a list of objects (similar to usual pipeline list) or as a filename or path fragment that will be searched in the items of what is given under environment variable named NA64SW_RUN_CFG_PATH_ENVVAR column-separated list of paths.

- _type: Subpipe
  # How to handle "stop processing" flag raised by one of the handlers.
  # str, opt
  onStop: "forward"  # forward / ignore / discriminate
  # How to handle "discriminate event" flag raised by one of the
  # handlers; str, opt
  onDiscriminate: "forward"  # forward / ignore / stop
  # Usual pipeline object OR path string goes here
  pipeline:
     - _type ...
       ...
template<typename HitT>
class TimeSeries : public na64dp::AbstractHitHandler<HitT>, public na64dp::util::GenericTDirAdapter<DetID>

Template implementation for time series analyzing handler.

Common use case of this handler is restricted rather by raw data as it is expected to track value changes over contigious series of events.

Usage: 

- _type: TimeSeries
  # Specifies particular hit type to iterate over; str, required
  subject: ...
  # Specifies a getter to use to retrieve a value; str, required
  value: ...
  # A base name for the histogram; str, required
  histName: ...
  # Break up types. Variants: "fixed", "half", "spill",
  # "periodic"; string, required
  breakBy: ...
  # Number of samples to consider (meaning depends on break type);
  # int, optional
  nSamples: 0
  # Whether to exclude outliers from consideration ; bool, optional
  trimOutliers: false
  # optional, hit selection expression
  applyTo: null

Todo:

Support different output destinations

Note

currently supports only the hardcoded CSV output; foresee file name parameterisation, ROOT output or whatsoever