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, basketsize=1600, signalSideParticleList='', filenameSuffix='', useFloat=False, storeEventType=True)

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

• basketsize (int) – size of baskets in the output ntuple in bytes

• signalSideParticleList (str) – The name of the signal-side ParticleList. Only valid if the module is called in a for_each loop over the RestOfEvent.

• filenameSuffix (str) – suffix to be appended to the filename before .root.

• useFloat (bool) – Use single precision (float) instead of double precision (double) for floating-point numbers.

• storeEventType (bool) – if true, the branch __eventType__ is added for the MC event type information. The information is available from MC16 on.

Tip

The output filename can be overridden using the -o argument of basf2.

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.

See also

More information for working event-wise is given in the section about Event based analysis.

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, filenameSuffix='')

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.

• filenameSuffix (str) – suffix to be appended to the filename before .root.

Tip

The output filename can be overridden using the -o argument of basf2.

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)

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()

Create a new row in the hdf5 file with for each particle in the list

initialize()

Create the hdf5 file and list of variable objects to be used during event processing.

terminate()

save and close the output