5. Common Handler Parameters

This page covers parameters that are somewhat common for many handlers (including generic ones).

5.1. applyTo – select a detector

Many handlers that deal with certain entities within event’s collections offer an applyTo parameter that expects a string argument – a special logical expression that defines whether handler must be applied.

Considered collections are usually SADC or APV hits, clusters, track points, etc. What collection is considered by handler is usually clear from handler’s function (for instance, SADCSubtractPedestals operates with collection of SADCHit).

A syntax of logical expression used is pretty close to C/C++: one may use !=, &&, ||, ! for logical expression, round brackets to prioritize operations and exploit some “variables”:

• kin is set to current lement’s detector type (e.g. MM, GM, ECAL, HCAL, etc)

• number is set to station number and may be compared with integer.

There are also variables that will be defined for elements of certain type:

• projection is defined for APV detectors only, when hits or clusters are considered. Can be compared with X, Y, U, V

• xIdx, yIdx are defined only for SADC hits.

There are also additional variables that rarely needed – you may list them with -l,--list option of na64sw-pipe in “detector-id-definitions” paragraph.

With this simplistic expressions one may gain surprisingly flexible functionality. For instance:

• applyTo: kin == GM will make handler to be applied only to GEMs

• applyTo: kin == HCAL && number == 2 will apply handler to second HCAL module

• applyTo: kin == MM && X == projection will make handler to treat only X plane of all the micromegas

• applyTo: GM == kin && (number == 3 || projection != Y) will apply handler to all non-X GEMplanes except for 3rd station.

You may find a more complete reference on this domain specific language at the page dedicated to Detectors naming (advanced topic).

5.2. path, histName and variations

For most of the handlers that create objects in ROOT’s TFile a following set of parameters can be found usually:

• An object path that defines where the object is created in the hierarchy of TDirectory’ies. It is often defined as a template string – with placeholders in curly brackets, like {kin}/{number}/{hstName}

• The path usually refers to a TObject’s name created (so, the last token of this path is in fact a TObject name). For plotting handlers this path sometimes contains a {hist} that refers to auxiliary histName: ... YAML parameter.

• desc: ... YAML parameter is another string template commonly found for TObject-creating handlers. This parameter is used to provide input to description string of various plots where one can specify the title and axes labels.

Full list of placeholders available for string interpolation within path/desc parameters can be found in reference of append_subst_dict_for().

5.3. Examples of common parameters usage

Following examples show various usage scenarios of the common parameters described above in different handlers. Some of these handlers we did not cover in this tutorial yet, but it shall be possible to get the grasp so far:

• 1D histogram applied to beam counters only (S or T) depicting linear SADC waveform sum by path like sums/S2/linear-sum

  - _type: Histogram1D
    applyTo: "kin == S || kin == T"
    value: sadcHits.rawData.sum
    histName: "linear-sum"
    histDescr: "Linear waveform sum, {TBName}; sum, sample no ; samples"
    path: "sums/{kin}{statNum}/{hist}"
    nBins: 100
    range: [0, 25000]
  

• Sometimes applyTo: ... is anticipated for various analytic handlers. For instance, size requirement for clustering procedure differs for X and Y planes of MMs because of different distance from the galvanic mesh within a detector station. This way one can specify same handler twice, independently for X and Y projections:

  - _type: APVFindClusters
    applyTo: "kin == MM && projection == X"
    minWidth: 3
    minCharge: 100
    sparseness: 0
  - _type: APVFindClusters
    applyTo: "kin == MM && projection == Y"
    minWidth: 5
    minCharge: 100
    sparseness: 0
  

• Cross-typed generic handlers, like BiHitHistogr_Calo_Calo requires hit-selection criterion to pick up certain hit(s) from the collections. For that purpose applyTo: ... can be used as well:

  - _type: BiHitHistogram_Calo_Calo
    histName: ECAL-vs-HCAL
    histDescr: "ECAL edep vs HCAL edep ; ECAL, GeV ; HCAL, GeV"
  
    applyToX: "kin == ECAL"
    valueX: eDep
    nBinsX: 150
    rangeX: [0, 150]
  
    applyToY: "kin == HCAL"
    valueY: eDep
    nBinsY: 150
    rangeY: [0, 150]
  

  This handler produces famous NA64’s ECAL/HCAL biplot.

• Starting from 2018, NA64 often uses fourth module of HCAL as veto hadronic calorimeter. The calorimeter hits (instances of CaloHit) are build up from set of SADCHit according to certain rules by MakeCaloHit handler. One may restrict HCAL hit composition with applyTo: ... like follows:

  - _type: MakeCaloHit
    applyTo: "kin == HCAL && number < 3"
    detectors: [HCAL]