2. Tweaking pipeline configuration

This chapter demonstrates how existing pipeline configuration can be customized.

We use here a very basic level of DAQ digits got from MSADC detectors to refrain from complex analysis and demonstrate only the gist.

2.1. Changing Parameters

Let’s pick up some basic pipeline config file and tweak its parameters. To get a feeling we’ll start with a very short pipeline that performs subtraction of pedestals for MSADC detectors.

First, we copy a prepared (very short!) pipeline config file to a local dir for a change.

$ cp $NA64SW_PREFIX/etc/na64sw/share/tutorial/02-tweaking.yaml custom.yaml

One can edit this file with their favorite text editor. Its content shall be:

pipeline:

    - _type: SADCPlotWaveform
      baseName: "amps-raw"
      ampNBins: 500
      ampRange: [0, 2400]

    - _type: SADCGetPedestalsByFront
      nSamples: 4

    - _type: SADCSubtractPedestals

    - _type: SADCPlotWaveform
      baseName: "amps-pedCorrected"
      ampNBins: 200
      ampRange: [0, 4000]

This text file has following features:

• it is written in YAML language. The YAML syntax is known as being pretty intuitive (comments start with # symbol, lists defined with - marker, objects are defined as key: value line, etc).

• it describes one list of objects: a sequence of smaller parameter sets, each related to logically-isolated procedure (handlers starts with - _type: ... line in this config, blank lines do not matter).

• individual procedure (we further call it a handler) is designed to perform a very simple and clear task each. The configuration document makes na64sw-pipe to create a set of this handlers that are applied to every event in a oerdered way, just as listed in this file.

• For instance, one handler finds pedestals in a SADC waveform, another, say, performs lookup for maxima. A handler, depending on its C++ class (referred in config as _type: ...) can modify event information or can build a plot.

• The pipeline defined in your config file will mean that once NA64sw reads an event, this event will be handled passed by four procedures:

  1. SADCPlotWaveform – plots an MSADC waveform

  2. SADCGetPedestalsByFront – finds a pedestal in the sample

  3. SADCSubtractPedestals – subtracts a pedestal from waveform

  4. SADCPlotWaveform – plots an MSADC waveform again

• Note, that same handler may be applied multiple times, like SADCPlotWaveform in this example – first it will build SADC waveform plot before pedestals subtraction and second after. Technically, it is just two instances of the same class configured differently.

• Handlers pretty often anticipate some configuration parameters. A common case is the plotting handler that must be parameterised with name of the output histogram in ROOT TFile, limits and number of bins. You can see such an example in a SADCPlotWaveform handler of your custom.yaml.

So, for instance the SADCPlotWaveform handler has at least three parameters that must be provided by its configuration, besides of its class:

• The name of histogram that shall appear in the output ROOT file (called baseName),

• The number of vertical bins (ampNBins, is always 32 for MSADC detectors)

• the amplitude range to plot a waveform (ampRange).

You may change ampNBins in SADCPlotWaveform histogram to see how binning changes for appropriate histogram: change the number, save the file and re-run the application:

$ na64sw-pipe -N 1000 --run custom.yaml \
        /eos/experiment/na64/data/cdr/cdr01002-003292.dat

You can see the difference now in amps-raw or amps-pedCorrected histograms in ROOT’s TBrowser.

Important

To get usage information of certain handler, one may visit our handlers reference pages. The links like SADCPlotWaveform in this tutorial lead to this helpful pages.

2.2. Adding a handler to the pipeline

There are a number of handler classes provided by NA64sw by default. One may get the list of known handlers by calling na64sw-pipe application with -l option. It will make the application to dump list of known handlers (as well as other runtime extensions) into console.

$ na64sw-pipe -l

For instance, if you are intersted with, say, seeing the sum of SADC waveform, you may find appropriate handler with following command:

$ na64sw-pipe -l | grep sum

It will provide you with at least two results: SADCDirectSum and SADCLinearSum. They are almost identical, the only difference is that “linear” sums up the mean values between two adjacent samples while “direct” just sums up all the sample values.

One can add this handlers in the pipeline: just append pipeline: block with a line - _type: SADCDirectSum in custom.yaml file.

If one run the pipeline then, this handler will modify data in the event object (it will append every MSADC hit information with sum value), however no changes will be observable yet in processed.root output since none of the two histograms are affected by sum value appeared.

This is an important part of modular design. Each handler does a very simple, logically separable job, and tasks like calculating a sum and plotting a sum must be splitted across two individual handlers.

So, how to visualize sum distribution and what actually was affected by our change? One can think on a special handler that builds a plot like SADCPlotWaveform, but for sum value of MSADC hit. And there is one! Add the following block to the end of handlers list:

- _type: Histogram1D
  value: sadcHits.rawData.sum
  histName: "sum"
  histDescr: "Amplitude sum, {TBName} ; time, ns ; Events"
  nBins: 100
  range: [0, 5000]

Important

Beware of breaking up the indent. YAML is sensitive to that. Each handler parameters block shall start from - _type: ... line of the same indent and shall have its parameters listed on bigger indent.

You can observe the new histogram appeared in the processed.root output file.

In next section we will explain a bit technical aspect directly related to this plotting handler, that may appear a bit tedious for understanding. However, using these generic plotting handlers (together with shallow understanding of event-building) will save enormous amount of time for the analysis.