7.4.1. Variable Manager Output¶

A common task is to write out information to a ROOT file to analyse it outside of the basf2 framework (e.g. to perform a fit, and extract a physical observable).

There are several modules which write out variables in one form or another. And several helpful functions to set up your output TTree in a format you like.

VariablesToNtuple¶

Writes out Variables to a flat ROOT TTree (it is also possible to write out several trees to one file).

Note

New since release-03: event, run, and experiment numbers are now automatically included. If you have are writing candidates, you will also see a candidate counter and the number of candidates (ncandidates).

Candidate-wise¶

For each candidate in the given ParticleList, there will be one entry in the TTree containing the desired Variables. In other words, this produces a candidate-based ROOT file. Here is an example of use:

from modularAnalysis import variablesToNtuple
list_of_interesting_variables = [
        'E', 'px', 'py', 'pz', 'isSignal',  # related to the candidate
        'nTracks', # related to the event
]
variablesToNtuple('pi+:all', list_of_interesting_variables, path=mypath)

Event-wise¶

This module will also work even when provided with no ParticleList name. In this case it will be filled once per event. Here is an example of event-wise usage:

from modularAnalysis import variablesToNtuple
list_of_interesting_event_variables = [
        'L1Trigger', 'HighLevelTrigger', 'nTracks' # purely event
]
variablesToNtuple('', list_of_interesting_event_variables, path=mypath)

Multiple TTress¶

You can write several trees to the same file by calling the module several times with the different treename and the same filename.

from modularAnalysis import variablesToNtuple
variablesToNtuple('', list_of_interesting_event_variables,
                  treename="event", filename="myoutput.root",
                  path=mypath)
variablesToNtuple('pi+:all', list_of_interesting_variables,
                  treename='pions', filename='myoutput.root', # <-- same file
                  path=mypath)
variablesToNtuple('K+:all', list_of_interesting_variables,
                  treename='kaons', filename='anotheroutput.root', # <-- different file
                  path=mypath)

As with many modules, there is a modularAnalysis convenience function:

modularAnalysis.variablesToNtuple(decayString, variables, treename='variables', filename='ntuple.root', path=None)[source]

Creates and fills a flat ntuple with the specified variables from the VariableManager. If a decayString is provided, then there will be one entry per candidate (for particle in list of candidates). If an empty decayString is provided, there will be one entry per event (useful for trigger studies, etc).

Parameters

decayString (str) – specifies type of Particles and determines the name of the ParticleList
variables (list(str)) – the list of variables (which must be registered in the VariableManager)
treename (str) – name of the ntuple tree
filename (str) – which is used to store the variables
path (basf2.Path) – the basf2 path where the analysis is processed

VariablesToEventBasedTree¶

Writes out Variables to a structured ROOT TTree. For each event an entry is written into the Tree containing one array (for each Particle in the ParticleList) for each Variable.

VariablesToHistogram¶

Writes out Variables to a ROOT TH1F or TH2F histogram. Here is an example of use:

from modularAnalysis import variablesToHistogram
list_of_variables_and_bins = [
        ('pt', 100, 0, 1),
        ('E', 100, 0, 4)
]
variablesToHistogram('pi+:all', list_of_variables_and_bins)

Here is the full function documentation of the modularAnalysis convenience function:

modularAnalysis.variablesToHistogram(decayString, variables, variables_2d=None, filename='ntuple.root', path=None, *, directory=None, prefixDecayString=False)[source]

Creates and fills a flat ntuple with the specified variables from the VariableManager

Parameters

decayString (str) – specifies type of Particles and determines the name of the ParticleList
variables (list(tuple))) – variables + binning which must be registered in the VariableManager
variables_2d (list(tuple)) – pair of variables + binning for each which must be registered in the VariableManager
filename (str) – which is used to store the variables
path (basf2.Path) – the basf2 path where the analysis is processed
directory (str) – directory inside the output file where the histograms should be saved. Useful if you want to have different histograms in the same file to separate them.
prefixDecayString (bool) – If True the decayString will be prepended to the directory name to allow for more programmatic naming of the structure in the file.

VariablesToHDF5¶

Writes out variables to a flat HDF5 format file (for use with pandas.DataFrame tools). Analogous to VariablesToNtuple.

Note

There is currently no modularAnalysis convenience function. Instead you can add the module to your path explicitly (it only takes two lines).

from b2pandas_utils import VariablesToHDF5
v2hdf5 = VariablesToHDF5("pi+:all", list_of_interesting_variables,
                         filename="variables.hdf5")
mypath.add_module(v2hdf5)

class b2pandas_utils.VariablesToHDF5(listname, variables, filename)[source]¶

Dump variables directly to HDF5

This Module is the equivalent of VariablesToNtuple but creates an hdf5 file instead of a root file. It is slower as it is implemented in pure python and should currently be considered a proof of concept.

event()[source]¶: Create a new row in the hdf5 file with for each particle in the list

initialize()[source]¶: Create the hdf5 file and list of variable objects to be used during event processing.

terminate()[source]¶: save and close the output