Histogram Definition

In the previous section, we introduced the structure of the steering file, including a processor for drawing histograms. In online analysis, quickly displaying predefined histograms is essential. This section explains how histograms are defined and managed.

Steering File Block

To process histograms, the art::TTreeProjectionProcessor is used (unless a custom processor has been created for CRIB). Below is an example from steering/example/example.tmpl.yaml:

Processor:
  # skip
  - name: hist
    type: art::TTreeProjectionProcessor
    parameter:
      FileName: hist/example/example.hist.yaml
      OutputFilename: *histout
      Type: art::TTreeProjection
      Replace: |
        MAX: @MAX@

Key Parameters

• FileName: Points to the file with histogram definitions.
• OutputFilename: Specifies where the ROOT file containing the histogram objects will be saved. The YAML alias *histout is used here.
• Type: Defines the processing class, which should be art::TTreeProjection for histograms processed by art::TTreeProjectionProcessor.
• Replace: Substitutes placeholders (e.g., @MAX@) in the histogram definition file with specified values.

Note: YAML's | symbol ensures that line breaks are included as written. Though not critical in this case, it impacts multi-line text handling.

Histogram Definition File

The histogram definitions are stored in a separate file. For instance, hist/example/example.hist.yaml contains:

group:
  - name: test
    title: test
    contents:
      - name: hRndm
        title: random value
        x: ["random.fValue",100,0.,@MAX@]

include:
  - name: hist/example/example.inc.yaml
    replace:
      MAX: @MAX@
      SUFFIX: 2
      BRANCH: random

The file is divided into two main blocks: group and include.

group Block

The group block organizes histograms into logical units. Each group corresponds to an art::TTreeProjGroup object, which is referenced in the artemis command section:

artemis [] ls

 artemis
>   0 art::TTreeProjGroup test2           test (2)
    1 art::TTreeProjGroup test            test
    2 art::TAnalysisInfo analysisInfo

The name and title keys in the group block define the art::TTreeProjGroup object:

group:
  - name: test
    title: test

Defining Histogram Contents

Histograms within a group are defined under the contents key. Multiple histograms can be defined as an array. For example:

# skip
    contents:
      - name: hRndm
        title: random value
        x: ["random.fValue",100,0.,@MAX@]

      # you can add histograms here
      #- name: hRndm2

Key Parameters

variable in Histogram Definitions

Histograms generated by art::TTreeProjectionProcessor are created based on tree objects, similar to the ROOT command:

root [] tree->Draw("variable>>(100, -10.0, 10.0)", "variable2 > 1.0")

In this case:

• x: ["variable", 100, -10.0, 10.0]
• cut: "variable2 > 1.0;"

In artemis, data is accessed through the member variables or methods of branch objects rather than directly referencing branch names.

include Block

Histogram definition files can reference other files using the include keyword:

include:
  - name: hist/example/example.inc.yaml
    replace:
      MAX: @MAX@
      SUFFIX: 2
      BRANCH: random

• name: Specifies the path to the included file relative to the working directory.
• replace: Replaces placeholders in the included file with specified values.

Example of the referenced file hist/example/example.inc.yaml:

group:
  - name: test@SUFFIX@
    title: test (@SUFFIX@)
    contents:
      - name: hRndm@SUFFIX@
        title: random number
        x: ["@BRANCH@.fValue",100, 0., @MAX@]

The structure of the included file mirrors that of the main file. Conceptually, the included content is appended to the main file.

Summary

Histograms in artemis are defined through a combination of steering files and separate histogram definition files. The art::TTreeProjectionProcessor processes these definitions, enabling efficient creation and display of histograms during analysis.

Key points:

• The steering file specifies the histogram processor and its parameters.
• Histogram definition files use group blocks to logically organize histograms and include key parameters like x, y, and cut.
• External files can be included for reusability, but excessive inclusion should be avoided for clarity.