Variable Manager Output

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)

Metadata#

The module will also collect all the relevant FileMetaData attributes and write them out to the output file(s) in persistent tree. Additional information can be added to the metadata by setting the dataDescription parameter:

from modularAnalysis import variablesToNtuple
variablesToNtuple('pi+:all', list_of_interesting_variables,
                  treename='pions', filename='myoutput.root',
                  dataDescription={'mcEventType':'mixed'}, # <-- multiple key:value pairs can be passed here
                  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, ignoreCommandLineOverride=False)[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

  • 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.

  • ignoreCommandLineOverride (bool) – if true, ignore override of file name via command line argument -o.

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='', ignoreCommandLineOverride=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.

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

  • ignoreCommandLineOverride (bool) – if true, ignore override of file name via command line argument -o.

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, hdf_table_name: str | None = None)[source]#

Legacy class to not break existing code

Contents