Documentation

hps-analysis code documentation

The hps-analysis code creates flat ntuple style ROOT files, which can be relatively easily analyzed in a number of different ways with either ROOT or Python (using PyROOT). The main advantage of these ROOT ntuples is that they allow for a lot of flexibility. Existing code will not break if a variable is added, or if a variable is omitted (unless of course you needed that variable.) Also, you can use these ROOT files without needing any library to read them, though for some methods of analysis the libMiniDst library can be advantageous.

---

The following chapters in this Wiki discuss the different ways of doing analysis with these ROOT files.

Using C++ and/or the ROOT command line:

The following chapters show how you can analyze the data in the ROOT files with C++, in order of sophistication:

1. Using TTree directly. (TTree->Draw()).

2. Using the TTree in a code loop.

3. Using RDataFrame

Using Python and PyROOT and/or the ipython command line:

The following chapters show how you can analyze the data in the ROOT files with Python. Note that when you do ROOT analysis using Python you can often not completely forgo any C++ knowledge. Some specific operation will still require bits of C++ code. In order of code sophistication:

1. Using TTree directly (with TTree.Draw()).

2. Using the TTree in a code loop.

3. Using RDataFrame

---

Mini-, Micro-, Nano-DSTs

The idea is to create easy to use ROOT files that have a very simple structure. The basic structure of the ROOT files is a set of basic values (int, double), columns of values (vector or vector) or, for a few items, columns of columns (vector<vector >,vector<vector >).

This design makes the ROOT files easy to read with simple TTree or RDataFrame commands, yet still allows for a full, sophisticated analysis. Having such a simple structure makes is very easy to trim the data set to only those variables you actually need in your analysis, saving space and time. Code that uses such trimmed (micro-, nano-) DSTs are still compatible with ROOT files that have a larger subset of data in them. Code that requires a larger set of variables can make use of the friend tree mechanism to add additional information without the need to re-write the base files.

A quick example of how to make a "pico-DST" from a larger one (eg mini-DST):

using namespace ROOT;
TChain ch("MiniDST");
ch.Add("minidst_*.root"); // Load all the available minidst root files.
RDataFrame df(ch);        // Open the TChain in an RDataFrame
df.Snapshot("NanoDST","nano_dst.root", // Write a select set of items to a nano dst.
        {"v0_mass", "v0_px", "v0_py", "v0_pz", "v0_vertex_x", "v0_vertex_y", "v0_vertex_z"})

Note that the output goes into a single file, which can be quite large if you had a lot of input files!

More details on RDataFrame are found in the ROOT manual pages: RDataFrame

Event Structure:

The event structure details are found in the file MiniDst.h where the TTree Branches are set and given a name. A quick way to get the available columns is to ask the RDataFrame:

using namespace ROOT;
TChain ch("MiniDST");
ch.Add("minidst_*.root"); // Load all the available minidst root files.
RDataFrame df(ch);        // Open the TChain in an RDataFrame
auto column_list = df.GetColumnNames(); // Get a list of all the column names.

There are only a few items in the list that are vectors of vectors. These are, for instance, the indexes from a track to the hits on the track, where you can have N tracks in the event with M(n) hits each, requiring a 2-dimensional array to store the integers.

---