7. Analysis

The analysis package collects modules and tools for high-level analysis of Belle II data. With analysis modules you are able to open mdst format files, create final state particles, and build more complicated decays. With these particle decay candidates, you can use high level tools such as Tree Fitter, Flavor Tagger, and the Full event interpretation (FEI).

Tip

For a series of hands-on introductory lessons, take a look at Section 3.4.

The core data objects of the basf2 analysis package, are the Particle class, and the ParticleList class. Almost all analysis modules are concerned with the manipulation of ParticleList s.

Examples of analysis steering files can be found in tutorial directory of analysis package:

ls $BELLE2_RELEASE_DIR/analysis/examples/tutorials

7.1. Particles

Particles in basf2 are created from reconstructed dataobjects: Tracks, tracking vertices (V0s), ECLClusters, and KLMClusters. The Particle class, provides a unified way to treat different objects at a high level interpreting them as phsical particles. All of the Particle s in an event that fall within certain criteria are collected into ParticleList s.

The Belle II physics performance group already has several predefined ParticleList s. To use them you need to use functions described in the standard particle lists.

Creation of new particle lists by combination of particles is essential part of almost any analysis job. The syntax used during this procedure is the DecayString and is described below:

It is often desirable to apply selections to ParticleList s, and events. This is done with cut strings.

7.2. Modular analysis convenience functions

The general idea of basf2 modules is described in the section on Modules and Paths. The analysis package provides pre-defined python wrapper functions designed to simplify users python code. For vertex-fitter functions see the later section on Vertex (and kinematic) fitting.

There are also some more specialised python wrapper functions for dealing with photons.

7.3. Variables

While basf2 operates on ParticleList s, it is also important to calculate physics quantities associated with a given candidate or event.

In basf2 analysis, variables are handled by the VariableManager. There are many variables available for use in analysis. Probably the most obvious, and useful are: p, E, Mbc, and deltaE.

You can search the variables in an alphabetical basf2 Variable Index, or browse Variables by group.

7.4. Output for offline analysis

You can save information from analysis jobs directly from the VariableManager (e.g. for offline analysis using python tools such as pandas)

7.4.2. (Advanced) user mDST files

You can also save events to your own mDST or user-defined dst (uDST) output files. These files are also created by the Skims but the functional code is part of Analysis.

7.5. Vertex (and kinematic) fitting

There are a number of vertex-fitting and kinematic fitter libraries interfaced and available for use in basf2.

By default, Tree Fitter is recommended even for simple single-vertex use-cases, however there are use cases where a better-performing or specialist tool is needed.

These fitters can be added to your basf2 path using a set of the convenient pre-defined python wrapper functions.

7.6. Event-based analysis

7.7. Truth-matching

7.8. Advanced Topics

7.9. Full list of analysis modules

The Belle II physics analysis software follows the logic of the general Belle II Analysis Software Framework (basf2) where independent modules solve relatively small problems, where practically all communication between modules happens in the form of data objects. Modules are executed in a linear fashion inside a module path, and can make objects available “downstream” by saving them in the DataStore.

Typical physics analysis performed at B factories can be separated into well defined analysis actions. For example, in a measurement of time-dependent CP violation in B0 → φKS0 decays we need to execute the following actions:

  1. create list of charged kaon candidates,

  2. create list of φ candidates by making combinations of two oppositely charged kaons,

  3. create list of KS0 candidates,

  4. create list of B0 candidates by making combinations of φ and KS0 candidates,

  5. calculate continuum suppression variables,

  6. determine the flavor of B0 candidates,

  7. determine the decay vertex of B0 candidates,

  8. determine the decay vertex of the other B meson in the event,

  9. write out all relevant info to ntuple for offline analysis.

A measurement of time-dependent CP violation in B0 decays to a different final state, e.g. \(J/\psi K_S^0,\ D^+D^−\) or \(K^{*0}\gamma\), would consist of conceptually identical analysis actions. Even within the same analysis sequence the same analysis action can appear several times. In the example above, the actions 2 and 4 are conceptually the same. In both cases new particle is created by combining others. The only difference is in the input. The only difference between different decay modes mentioned above is in the intermediate and final state particles. All other steps, like 5, 6, 7, 8, and 9 are in principle the same. The input is of course different, but the result is the same. Therefore, commonly used analysis tools need to be prepared in order to enable efficient and accurate data analysis. Each analysis action can then be performed by a separate analysis module, combined into an analysis sequence steered by a python script.

AllParticleCombiner

“This module combines all particles of the provided list to one mother particle.

Package

analysis

Library

libAllParticleCombiner.so

Parameters
  • cut (str, default=’’)

    Selection criteria for the output ParticleList

  • inputListNames (list(str), default=[])

    List of ParticleLists which are supposed to be combined

  • outputListName (str, default=’’)

    Name of the output list created by the combination of all particles in the input lists.

  • writeOut (bool, default=False)

    If true, the output ParticleList will be saved by RootOutput. If false, it will be ignored when writing the file.

AnalysisConfiguration

This is a supplementary module designed to configure other modules

Package

analysis

Library

libAnalysisConfiguration.so

Parameters
  • mcMatchingVersion (str, default=’BelleII’)

    Specifies what version of mc matching algorithm is going to be used. Possibilities are: BelleII (default) and Belle. The latter should be used when analysing Belle MC. The difference between the algorithms is only in the treatment (identification) of FSR photons. In Belle II MC it is possible to identify FSR photons via special flag set by the generator, while in case of Belle MC such information is not available.

  • tupleStyle (str, default=’default’)
    This parameter defines style of variables written by all other ntuples tools. n

    Possible styles on example of PX variable of pi0 from D in decay B->(D->pi0 pi) pi0:n ‘default’: B_D_pi0_PXn ‘semilaconic’: D_pi0_PXn ‘laconic’: pi01_PXn

BelleBremRecovery

Takes the charged particle from the given charged particle list (inputListName) and copies it to the output list (outputListName). The 4-vector of the nearest (all) photon(s) from gammaListName (considered as radiative) is added to the charged particle, if it is found inside the cone around the charged particle with the given maximum angle (angleThreshold).

Package

analysis

Library

libBremsCorrection.so

Required Parameters
  • gammaListName (str)

    The gammas list containing possibly radiative gammas, should already exist.

  • inputListName (str)

    The initial charged particle list containing the charged particles to correct, should already exist.

  • outputListName (str)

    The output charged particle list containing the corrected charged particles.

Parameters
  • angleThreshold (float, default=0.05)

    The maximum angle in radians between the charged particle and the (radiative) gamma to be accepted.

  • multiplePhotons (bool, default=True)

    If only the nearest photon to add then make it False otherwise true

  • writeOut (bool, default=False)

    Set to true if you want to write out the output list to a root file

BestCandidateSelection

Sort particles by the value of a given variable in the input list and optionally remove particles after the nth position.

Per default particles are sorted in descending order but it can be switched to an ascending order by setting selectLowest=True. The convenience functions modularAnalysis.rankByHighest and modularAnalysis.rankByLowest set this parameter automatically based on their names.

Particles will receive an extra-info field containing their rank as an integer starting at 1 (best). The name of this extra-info field defaults to ${variable}_rank but can be chosen freely using the outputVariable parameter.

The ranking also takes antiparticles into account, so there will only be one B+- candidate with rank=1. The remaining list is sorted from best to worst candidate (each charge, e.g. B+/B-, separately). The sorting is guaranteed to be stable between particle and anti particle list: particles with the same value for variable will keep their relative order. That is, a particle “A” which was before another particle “B” in the same list and has the same value for variable will also stay before “B” after sorting.

If allowMultiRank=False (the default) candidates with same value of variable will have different ranks. If allowMultiRank=True they will share the same rank.

IF numBest>0 only candidates with this rank or better will remain in the output list. If allowMultiRank=True that means that there can be more than numBest candidates in the output list if they share ranks.

Package

analysis

Library

libBestCandidateSelection.so

Required Parameters
  • outputVariable (str)

    Name for created variable, which contains the rank for the particle. If not provided, the standard name ${variable}_rank is used.

  • particleList (str)

    Name of the ParticleList to rank for best candidate

  • variable (str)

    Variable which defines the candidate ranking (see selectLowest for ordering)

Parameters
  • allowMultiRank (bool, default=False)

    If true, candidates with identical values get identical rank

  • cut (str, default=’’)

    Only candidates passing the cut will be ranked. The others will have rank -1.

  • numBest (int, default=0)

    Keep only particles with this rank or better. If allowMultiRank=False this is identical to the maximum amount of candidates left in the list. Otherwise there may be more candidates if some share the same rank (0: keep all)

  • selectLowest (bool, default=False)

    If true, candidate with lower values of variable are better, otherwise higher is better

BremsFinder

This module copies each particle in the inputList to the outputList and uses the results of the eclTrackBremFinder module to look for possible bremsstrahlung photons; if these photons exist, it adds their four momentum to the particle in the outputList. It also adds the original particle and these photons as daughters of the new, corrected particle. Track and PID information of the original particle are copied onto the new one to facilitate their access in the analysis scripts.

The eclTrackBremFinder module uses the lepton track PXD and SVD hits and extrapolates them to the ECL; then looks for ECL clusters with energies between 0.02 and 1 times the track energy and without associated tracks, and checks if the normalized distance between each of these clusters and the extrapolated hit is smaller than 0.05. If it is, a Bremsstrahlung weighted relation between said cluster and the track is established. The weight is determined as

\[\text{max}\left(\frac{\left|\phi_{\text{cluster}}-\phi_{\text{hit}}\right|}{\Delta\phi_{\text{cluster}}+\Delta\phi_{\text{hit}}}, \, \frac{\left|\theta_{\text{cluster}}-\theta_{\text{hit}}\right|}{\Delta\theta_{\text{cluster}}+\Delta\theta_{\text{hit}}}\right)\]

where \(\phi_i\) and \(\theta_i\) are the azimuthal and polar angles of the ECL cluster and the extrapolated hit, and \(\Delta x\) represents the uncertainty of the value \(x\). The details of the calculation of these quantities are here. By default, only relations with a weight smaller than 3.0 are stored. The user can further reduce the maximally allowed value of this weight to remove unwanted photons from the bremsstrahlung correction.

This module looks for photons in the gammaList whose clusters have a Bremsstrahlung relation with the track of one of the particles in the inputList, and adds their 4-momentum to the particle’s one. It also stores the value of each relation weight as extraInfo of the corrected particle, under the name "bremsWeightWithPhotonN", where N is the index of the photon as daughter of the corrected particle; thus "bremsWeightWithPhoton0" gives the weight of the Bremsstrahlung relation between the new, corrected particle, and the first photon daughter.

Warning:

Even in the event of no bremsstrahlung photons found, a new particle is still created, and the original one is still added as its daughter.

Warning:

Studies have shown that the requirements that the energy of the photon must be between 0.2 and 1 times the track energy and that only track-photon relations with a weight below three are considered, are too tight. Until these are relaxed and a new processing is done (MC15 and proc 13) it might be better to use the alternative BelleBremRecovery module.

See also:

eclTrackBremFinder module

Package

analysis

Library

libBremsCorrection.so

Required Parameters
  • gammaList (str)

    The photon list containing the preselected bremsstrahlung candidates. It should already exist and the particles in the list must be photons

  • inputList (str)

    The initial particle list name containing the particles to correct. It should already exist and the particles must have an associated track.

  • outputList (str)

    The output particle list name.

Parameters
  • maximumAcceptance (float, default=3.0)

    The maximum value of the relation weight between a bremsstrahlung cluster and a particle track

  • multiplePhotons (bool, default=False)

    If true, use all possible photons to correct the particle’s 4-momentum

  • usePhotonOnlyOnce (bool, default=False)

    If true, each brems candidate is used to correct maximum 1 particle (the one with the lowest relation weight among all in the inputList).

  • writeOut (bool, default=False)

    If true, the output ParticleList will be saved by RootOutput. If false, it will be ignored when writing the file.

BtubeCreator

BtubeCreator : This module creates Btube object, an object geometrically similar to a very long ellipsoid along a particular direction and can be used as a constraint in vertexing B particles. Upsilon4S decays to two Bs. the user selects one B with a ^ in decaystring. The order of daughters in reconstructdecay of Upsilon4S and this decaystring should be same. Using selected B as reference, the module calculates the direction in which the other B should fly and constructs a Btube object along that direction. In semi-leptonic analyses, the selected B is usually the fully reconstructed one, while for time dependent studies, the selected B is usually signal B which can be partially reconstructed

Package

analysis

Library

libBtubeCreator.so

Parameters
  • associateBtubeToBselected (bool, default=False)

    whether to associate the Btube with the selected B

  • confidenceLevel (float, default=0.001)

    Confidence level to accept the fit.

  • decayString (str, default=’’)

    decay string of the mother particle, the selected daughter specifies which daughter will be used as reference to create Btube

  • listName (str, default=’’)

    name of mother particle list

  • verbosity (bool, default=True)

    print statements

ChargedPidMVA

This module evaluates the response of an MVA trained for binary charged particle identification between two hypotheses, S and B. For a given input set of (S,B) mass hypotheses, it takes the Particle objects in the appropriate charged stable particle’s ParticleLists, calculates the MVA score using the appropriate xml weight file, and adds it as ExtraInfo to the Particle objects.

Package

analysis

Library

libChargedParticleIdentificator.so

Parameters
  • bkgHypoPDGCode (int, default=0)

    The input background mass hypothesis’ pdgId.

  • chargeIndependent (bool, default=False)

    Specify whether to use a charge-independent training of the MVA.

  • particleLists (list(str), default=[])

    The input list of ParticleList names.

  • payloadName (str, default=’ChargedPidMVAWeights’)

    The name of the database payload object with the MVA weights.

  • sigHypoPDGCode (int, default=0)

    The input signal mass hypothesis’ pdgId.

  • useECLOnlyTraining (bool, default=False)

    Specify whether to use an ECL-only training of the MVA.

ChargedPidMVAMulticlass

This module evaluates the response of a multi-class MVA trained for global charged particle identification.. It takes the Particle objects in the input charged stable particles’ ParticleLists, calculates the MVA per-class score using the appropriate xml weight file, and adds it as ExtraInfo to the Particle objects.

Package

analysis

Library

libChargedParticleIdentificator.so

Parameters
  • chargeIndependent (bool, default=False)

    Specify whether to use a charge-independent training of the MVA.

  • particleLists (list(str), default=[])

    The input list of ParticleList names.

  • payloadName (str, default=’ChargedPidMVAWeights’)

    The name of the database payload object with the MVA weights.

  • useECLOnlyTraining (bool, default=False)

    Specify whether to use an ECL-only training of the MVA.

ContinuumSuppressionBuilder

Creates for each Particle in the given ParticleLists a ContinuumSuppression dataobject and makes basf2 relation between them.

Package

analysis

Library

libContinuumSuppressionBuilder.so

Parameters
  • ROEMask (str, default=’all’)

    ROE mask

  • particleList (str, default=’’)

    Name of the ParticleList

CurlTagger

“Curl Tagger is a tool designed to identify and tag extra tracks caused by low pt particles curling around the detector. For further documentation please see ‘tagCurlTracks’ in modularAnalysis.”

Package

analysis

Library

libCurlTagger.so

Required Parameters
  • particleLists (list(str))

    input particle lists to check for curls or use for training

Parameters
  • belle (bool, default=False)

    flag to distinuguish Belle (true) from Belle II (false) data

  • mcTruth (bool, default=False)

    additionally bundles the particles using their genParticleIndex and tags them with extraInfo(isTruthCurl) and extraInfo(truthBundleSize).

  • ptCut (float, default=0.5)

    preselection pt Cut

  • responseCut (float, default=0.5)

    minimum allowed selector response for a match. If usePayloadCut is true the value will be overwritten with the cut stored in the payload.

  • selectorType (str, default=’cut’)

    the name of the selector to use when deciding if two reconstructed particles are the same true particle, available : ‘cut’, ‘mva’

  • train (bool, default=False)

    flag for training the MVA or other methods if needed

  • trainFilename (str, default=’CurlTagger_Training.root’)

    EXPERT: the name of the output root file created when running in training mode.

  • usePayloadCut (bool, default=True)

    flag for using the optimised cut value stored in the payload.

DistanceCalculator

Calculates distance between two vertices, distance of closest approach between a vertex and a track, distance of closest approach between two tracks, distance of closest approach between a vertex/track and Btube

Package

analysis

Library

libDistanceCalculator.so

Parameters

  • decayString (str, default=’’)

  • listName (str, default=’’)

  • mode (str, default=’vertextrack’)

    Specifies how the distance is calculated: vertextrack: calculate the distance of closest approach between a track and a vertex, taking the first candidate as vertex, default trackvertex: calculate the distance of closest approach between a track and a vertex, taking the first candidate as track, 2tracks: calculates the distance of closest approach between two tracks, 2vertices: calculates the distance between two vertices, vertexbtube: calculates the distance of closest approach between a vertex and a Btube, trackbtube: calculates the distance of closest approach between a track and a Btube

DuplicateVertexMarker

Identify duplicate vertices (distinct particles, but built from the same daughters) and mark the one with best chi2. Only works if the particle has exactly two daughters. Mainly used to deal when merging V0 vertices with hand-built ones.

Package

analysis

Library

libDuplicateVertexMarker.so

Required Parameters
  • particleList (str)

    Input ParticleList name

Parameters
  • extraInfoName (str, default=’highQualityVertex’)

    Extra-info field added to all particles in the input list. 1 for the best vertex, 0 for lower ranked ones.

  • prioritiseV0 (bool, default=True)

    If a vertex is a V0, select it over its duplicate even if chi2 is worse.

EnergyBiasCorrection

Module to modify energy from the lists. Include in your code as

mypath.add_module("EnergyBiasCorrection", particleLists=['gamma:cut'], scale=tableName_Weight)

The module modifies the input particleLists by scaling energy as given by the scale in the LookUpTable

Package

analysis

Library

libBiasCorrection.so

Required Parameters
  • particleLists (list(str))

    input particle lists

  • tableName (str)

    ID of table used for reweighing

EventKinematics

Module to compute global event kinematic attributes like missing momentum and energy.

Package

analysis

Library

libEventKinematics.so

Parameters
  • particleLists (list(str), default=[])

    List of the ParticleLists

  • usingMC (bool, default=False)

    is built using generated particles

EventShapeCalculator

Module to compute event shape attributes starting from particlelists. The core algorithms are not implemented in this module, but in dedicated basf2 classes.

Package

analysis

Library

libEventShapeCalculator.so

Parameters
  • checkForDuplicates (bool, default=False)

    Enables the check for duplicates in the input list. If a duplicate entry is found, the first one is kept.

  • enableAllMoments (bool, default=False)

    Enables the calculation of FW and harmonic moments from 5 to 8

  • enableCleoCones (bool, default=True)

    Enables the calculation of the CLEO cones.

  • enableCollisionAxis (bool, default=True)

    Enables the calculation of the quantities related to the collision axis.

  • enableFoxWolfram (bool, default=True)

    Enables the calculation of the Fox-Wolfram moments.

  • enableHarmonicMoments (bool, default=True)

    Enables the calculation of the Harmonic moments.

  • enableJets (bool, default=True)

    Enables the calculation of jet-related quantities.

  • enableSphericity (bool, default=True)

    Enables the calculation of the sphericity-related quantities.

  • enableThrust (bool, default=True)

    Enables the calculation of thust-related quantities.

  • particleListNames (list(str), default=[])

    List of the ParticleLists to be used for the calculation of the EventShapes.

ExtraInfoPrinter

Prints the names of all ExtraInfo set for each particle in the event. Useful for debugging and development.

Package

analysis

Library

libExtraInfoPrinter.so

Required Parameters
  • particleList (str)

    Name of the particle list (an empty string prints the EventExtraInfo)

Parameters
  • printOnce (bool, default=True)

    Print for the first event, or for all events (default true)

ExtraInfoRemover

Deletes the ExtraInfo from each particle in the given ParticleLists.

Package

analysis

Library

libExtraInfoRemover.so

Parameters
  • particleLists (list(str), default=[])

    List of ParticleLists

  • removeEventExtraInfo (bool, default=False)

    If True, also eventExtraInfo will be removed

FlavorTaggerInfoBuilder

Initializes the FlavorTaggerInfo DataObject that will be used during the Flavor Tagging. Filling is done in the FlavorTagger.py script

Package

analysis

Library

libFlavorTaggerInfoBuilder.so

FlavorTaggerInfoFiller

Creates a new flavorTaggerInfoMap DataObject for the specific methods. Saves there all the relevant information of the flavorTagger.

Package

analysis

Library

libFlavorTaggerInfoFiller.so

Parameters
  • DNNmlp (bool, default=False)

    Sets if DNN Tagger output will be saved or not

  • FANNmlp (bool, default=False)

    Sets if FANN Combiner output will be saved or not

  • TMVAfbdt (bool, default=False)

    Sets if FANN Combiner output will be saved or not

  • eventLevelParticleLists (list(tuple(str, str, str)), default=[])

    Used Flavor Tagger eventLevel Categories of the lists

  • istrueCategories (bool, default=False)

    Sets if individual MC truth for each category is saved or not

  • qpCategories (bool, default=False)

    Sets if individual categories output will be saved or not

  • targetProb (bool, default=False)

    Sets if individual Categories output will be saved or not

  • trackLevelParticleLists (list(tuple(str, str)), default=[])

    Used Flavor Tagger trackLevel Categories of the lists

  • trackPointers (bool, default=False)

    Sets if track pointers to target tracks are saved or not

HelixErrorScaler

scale the error of helix parameters

Creates a new charged particle list whose helix errors are scaled by constant factors. Different sets of scale factors are defined for tracks with/without a PXD hit. For tracks with a PXD hit, in order to avoid severe underestimation of d0 and z0 errors, lower limits (best resolution) can be set in a momentum-dependent form. The module also accepts a V0 Kshort particle list as input and applies the error correction to its daughters. Note the difference in impact parameter resolution between V0 daughters and tracks from IP, as V0 daughters are free from multiple scattering through the beam pipe.

Package

analysis

Library

libHelixErrorScaler.so

Parameters
  • d0MomentumThreshold (float, default=0.0)

    d0 best resolution is kept constant below this momentum.

  • d0ResolutionParameters (list(float), default=[0.0, 0.0])

    d0 best resolution parameters

  • inputListName (str, default=’’)

    The name of input particle list (charged stable or V0 Kshort)

  • outputListName (str, default=’’)

    The name of output charged particle list

  • scaleFactors_PXD (list(float), default=[1.0, 1.0, 1.0, 1.0, 1.0])

    vector of five scale factors for helix parameter errors (for tracks with a PXD hit)

  • scaleFactors_noPXD (list(float), default=[1.0, 1.0, 1.0, 1.0, 1.0])

    vector of five scale factors for helix parameter errors (for tracks without a PXD hit)

  • z0MomentumThreshold (float, default=0.0)

    z0 best resolution is kept constant below this momentum.

  • z0ResolutionParameters (list(float), default=[0.0, 0.0])

    z0 best resolution parameters

InclusiveBtagReconstruction

Inclusive Btag reconstruction

Package

analysis

Library

libInclusiveBtagReconstruction.so

Required Parameters
  • inputListsNames (list(str))

    List of names of the ParticleLists which are used to reconstruct Btag from

Parameters
  • bsigListName (str, default=’’)

    Name of the Bsig ParticleList

  • btagListName (str, default=’’)

    Name of the Btag ParticleList

  • upsilonListName (str, default=’Upsilon(4S)’)

    Name of the ParticleList to be filled with Upsilon(4S) -> B:sig anti-B:tag

InclusiveDstarReconstruction

Inclusive Dstar reconstruction by estimating the four vector using slow pions

Package

analysis

Library

libInclusiveDstarReconstruction.so

Parameters
  • DstarCut (str, default=’’)

    Cut for Dstar

  • decayString (str, default=’’)

    Input DecayDescriptor string

  • slowPionCut (str, default=’useCMSFrame(p) < 0.2’)

    Cut for slow pions

KlongDecayReconstructorExpert

This module is used to employ kinematic constraints to determine the momentum of Klongs for two body B decays containing a K_L0 and something else. The module creates a list of K_L0 candidates whose K_L0 momentum is reconstructed by combining the reconstructed direction (from either the ECL or KLM) of the K_L0 and kinematic constraints of the initial state.

Package

analysis

Library

libKlongDecayReconstructor.so

Required Parameters
  • decayString (str)

    Input DecayDescriptor string.

Parameters
  • cut (str, default=’’)

    Selection criteria to be applied

  • decayMode (int, default=0)

    User-specified decay mode identifier (saved in ‘decayModeID’ extra-info for each Particle)

  • maximumNumberOfCandidates (int, default=-1)

    Don’t reconstruct channel if more candidates than given are produced.

  • recoList (str, default=’_reco’)

    Suffix attached to the original K_L input list to identify the output list of the FindKlongMomentum module; this is the input for this module, if not defined it is set to ‘_reco’

  • writeOut (bool, default=False)

    If true, the output ParticleList will be saved by RootOutput. If false, it will be ignored when writing the file.

KlongMomentumCalculatorExpert

This module is used to employ kinematic constraints to determine the momentum of Klongs for two body B decays containing a K_L0 and something else. The module creates a list of K_L0 candidates whose K_L0 momentum is reconstructed by combining the reconstructed direction (from either the ECL or KLM) of the K_L0 and kinematic constraints of the intial state.

Package

analysis

Library

libKlongDecayReconstructor.so

Required Parameters
  • decayString (str)

    Input DecayDescriptor string.

Parameters
  • cut (str, default=’’)

    Selection criteria to be applied

  • decayMode (int, default=0)

    User-specified decay mode identifier (saved in ‘decayModeID’ extra-info for each Particle)

  • maximumNumberOfCandidates (int, default=-1)

    Don’t reconstruct channel if more candidates than given are produced.

  • recoList (str, default=’_reco’)

    Suffix attached to the output K_L list, if not defined it is set to ‘_reco’

  • writeOut (bool, default=False)

    If true, the output ParticleList will be saved by RootOutput. If false, it will be ignored when writing the file.

MCDecayFinder

Find decays in MCParticle list matching a given DecayString and create Particles from them.

Package

analysis

Library

libMCDecayFinder.so

Required Parameters
  • decayString (str)

    DecayDescriptor string.

  • listName (str)

    Name of the output particle list

Parameters
  • writeOut (bool, default=False)

    If true, the output ParticleList will be saved by RootOutput. If false, it will be ignored when writing the file.

MCMatcherParticles

Performs MC matching (sets relation Particle->MCParticle) for all particles (and its (grand)^N-daughter particles) in the ParticleList. The relation can be used in conjunction with MCMatching::MCErrorFlags flags, e.g. using the isSignal or mcPDG & mcErrors variables.

In addition to the usual mc matching algorithm the module can run also loose mc matching. The difference between loose and normal mc matching algorithm is that the loose algorithm will find the common mother of the majority of daughter particles while the normal algorithm finds the common mother of all daughters. The results of loose mc matching algorithm are stored to the following extraInfo items:

  • looseMCMotherPDG: PDG code of most common mother

  • looseMCMotherIndex: 1-based StoreArray<MCParticle> index of most common mother

  • looseMCWrongDaughterN: number of daughters that don’t originate from the most

    common mother

  • looseMCWrongDaughterPDG: PDG code of the daughter that doesn’t originate from

    the most common mother (only if looseMCWrongDaughterN = 1)

  • looseMCWrongDaughterBiB: 1 if the wrong daughter is Beam Induced Background

    Particle

Package

analysis

Library

libMCMatcherParticles.so

Required Parameters
  • listName (str)

    Name of the input ParticleList.

Parameters
  • looseMCMatching (bool, default=False)

    Perform loose mc matching

NeutralHadron4MomentumCalculator

Calculates 4-momentum of a neutral hadron in a given decay chain e.g. B0 -> J/Psi K_L0, or anti-B0 -> p+ K- anti-n0.

Package

analysis

Library

libNeutralHadron4MomentumCalculator.so

Parameters
  • allowGamma (bool, default=False)

    Whether allow the selected particle to be gamma

  • decayString (str, default=’’)

    Decay string for which one wants to perform the calculation

OnlyWriteOutParticleLists

Marks all objects in DataStore except those of type ParticleList as WrtieOut=False. Intedend to run before outputting an index file to remove unnecessary arrays.

Package

analysis

Library

libOnlyWriteOutParticleLists.so

ParticleCombiner

Makes particle combinations

Package

analysis

Library

libParticleCombiner.so

Required Parameters
  • decayString (str)

    Input DecayDescriptor string (see DecayString).

Parameters
  • allowChargeViolation (bool, default=False)

    If true the decay string does not have to conserve electric charge

  • chargeConjugation (bool, default=True)

    If true, the charge-conjugated mode will be reconstructed as well

  • cut (str, default=’’)

    Selection criteria to be applied

  • decayMode (int, default=0)

    User-specified decay mode identifier (saved in ‘decayModeID’ extra-info for each Particle)

  • ignoreIfTooManyCandidates (bool, default=True)

    Don’t reconstruct channel if more candidates than given by ‘maximumNumberOfCandidates’ are produced.

  • maximumNumberOfCandidates (int, default=10000)

    Max. number of candidates reconstructed. By default, if the limit is reached no candidates will be produced. This behaviour can be changed by ‘ignoreIfTooManyCandidates’ flag.

  • recoilParticleType (int, default=0)

    If not equal 0, the mother Particle is reconstructed in the recoil against the daughter particles. In the case of the following decay chain M -> D1 D2 … Dn and

    1. recoilParticleType = 1:

    • the mother momentum is given by: p(M) = p(e+e-) - p(D1) - p(D2) - … - p(DN)

    • D1, D2, …, DN are attached as daughters of M

    1. recoilParticleType = 2:

    • the mother momentum is given by: p(M) = p(D1) - p(D2) - … - p(DN)

    • D1, D2, …, DN are attached as daughters of M

  • writeOut (bool, default=False)

    If true, the output ParticleList will be saved by RootOutput. If false, it will be ignored when writing the file.

ParticleCombinerFromMC

Makes particle combinations

Package

analysis

Library

libParticleCombinerFromMC.so

Required Parameters
  • decayString (str)

    Input DecayDescriptor string (see DecayString).

Parameters
  • chargeConjugation (bool, default=True)

    If true, the charge-conjugated mode will be reconstructed as well

  • cut (str, default=’’)

    Selection criteria to be applied

  • decayMode (int, default=0)

    User-specified decay mode identifier (saved in ‘decayModeID’ extra-info for each Particle)

  • writeOut (bool, default=False)

    If true, the output ParticleList will be saved by RootOutput. If false, it will be ignored when writing the file.

ParticleCopier

Replaces each Particle in the ParticleList with its copy. Particle’s (grand)^n-daughter Particles are copied as well. The existing relations of the original Particle (or it’s (grand-)^n-daughters) are copied as well.

Package

analysis

Library

libParticleCopier.so

Parameters
  • inputListNames (list(str), default=[])

    list of input ParticleList names

ParticleKinematicFitter

Kinematic fitter for modular analysis

Package

analysis

Library

libParticleKinematicFitter.so

Parameters
  • add3CPhoton (bool, default=False)

    Add one photon with unmeasured energy (-1C).

  • addUnmeasuredPhoton (bool, default=False)

    Add one unmeasured photon (-3C).

  • debugFitter (bool, default=False)

    Switch on/off internal debugging output if available.

  • debugFitterLevel (int, default=10)

    Internal debugging output level if available.

  • decayString (str, default=’’)

    Specifies which daughter particles are included in the kinematic fit.

  • fixUnmeasuredToHER (bool, default=False)

    fix the momentum of the unmeasured photon to HER (+2C).

  • fixUnmeasuredToLER (bool, default=False)

    fix the momentum of the unmeasured photon to LER (+2C).

  • invMass (float, default=0.0)

    Invariant mass in GeV. Mass constraint only.

  • kinematicFitter (str, default=’OrcaKinFit’)

    Available: OrcaKinFit.

  • liftPhotonTheta (bool, default=False)

    Lift theta constraint of 3CPhoton. Valid when add3CPhoton is true.

  • listName (str, default=’’)

    Name of particle list.

  • orcaConstraint (str, default=’HardBeam’)

    OrcaKinFit constraint: HardBeam, RecoilMass.

  • orcaFitterEngine (str, default=’OPALFitterGSL’)

    OrcaKinFit engine: NewFitterGSL, NewtonFitterGSL, OPALFitterGSL.

  • orcaTracer (str, default=’None’)

    OrcaKinFit tracer: None, Text.

  • recoilMass (float, default=0.0)

    Recoil mass in GeV. RecoilMass constraint only.

  • updateDaughters (bool, default=False)

    Update the daughter kinematics.

  • updateMother (bool, default=True)

    Update the mother kinematics.

ParticleListManipulator

Manipulates ParticleLists: copies/merges/performs particle selection

Package

analysis

Library

libParticleListManipulator.so

Required Parameters
  • outputListName (str)

    Output ParticleList name

Parameters
  • cut (str, default=’’)

    Selection criteria to be applied

  • inputListNames (list(str), default=[])

    list of input ParticleList names

  • preferLowest (bool, default=True)

    If true, duplicate with lowest value of variable is accepted, otherwise higher one.

  • variable (str, default=’mdstIndex’)

    Variable which defines the best duplicate (see selectLowest for ordering)

  • writeOut (bool, default=False)

    If true, the output ParticleList will be saved by RootOutput. If false, it will be ignored when writing the file.

ParticleLoader

Loads MDST dataobjects as Particle objects to the StoreArray<Particle> and collects them in specified ParticleList.

Package

analysis

Library

libParticleLoader.so

Parameters
  • addDaughters (bool, default=False)

    If true, the particles from the bottom part of the selected particle’s decay chain will also be created in the datastore and mother-daughter relations are recursively set

  • decayStrings (list(str), default=[])

    List of decay strings (see DecayString for syntax) that specify all output ParticleLists to be created by the module.

  • enforceFitHypothesis (bool, default=False)

    If true, a Particle is only created if a track fit with the particle hypothesis passed to the ParticleLoader is available.

  • roeMaskName (str, default=’all’)

    ROE mask name to load

  • skipNonPrimary (bool, default=False)

    If true, the secondary MC particle will be skipped, default is false

  • skipNonPrimaryDaughters (bool, default=False)

    If true, the secondary MC daughters will be skipped, default is false

  • sourceParticleListName (str, default=’’)

    Particle list name from which we need to get ROEs

  • trackHypothesis (int, default=0)

    Track hypothesis to use when loading the particle. By default, use the particle’s own hypothesis.

  • useMCParticles (bool, default=False)

    Use MCParticles instead of reconstructed MDST dataobjects (tracks, ECL, KLM, clusters, V0s, …)

  • useMissing (bool, default=False)

    If true, the Particle List will be filled with missing momentum from the ROE and signal particle.

  • useROEs (bool, default=False)

    Use ROE instead of reconstructed MDST dataobjects (tracks, ECL, KLM, clusters, V0s, …)

  • writeOut (bool, default=False)

    If true, the output ParticleList will be saved by RootOutput. If false, it will be ignored when writing the file.

ParticleMCDecayString

Creates the Monte Carlo decay string of a Particle and its daughters. The MC decay string of the particle is hashed and saved as a 32bit pattern in the extra info field decayHash of the particle. The MC decay string of the particle + its daughters is hashed as well and saved as another 32bit pattern in the extra info field decayHashExtended of the particle. The mapping hash <-> MC decay string in saved in a TTree by this module. The 32bit pattern must be saved as a float (because our extra info field, variable manager and ntuple output only supports float) but they just represent 32 bits of a hash! The MC decay string can also be stored in an analysis ROOT file using the MCDecayString NtupleTool. Details on the MC decay string format can be found here: MC decay string

Package

analysis

Library

libParticleMCDecayString.so

Required Parameters
  • listName (str)

    Particles from these ParticleList are used as input.

Parameters
  • conciseString (bool, default=False)

    If set to true, the code will use a more concise format for the string.

  • fileName (str, default=’’)

    Filename in which the hash strings are saved, if empty the strings are not saved

  • identifiers (str, default=’abcdefghijklmnopqrstuvwxyz’)

    Identifiers used to identify particles in the concise format.

  • treeName (str, default=’hashtable’)

    Tree name in which the hash strings are saved

ParticleMassUpdater

This module replaces the mass of the particles inside the given particleLists with the invariant mass of the particle corresponding to the given pdgCode.

Package

analysis

Library

libParticleMassUpdater.so

Parameters
  • particleLists (list(str), default=[])

    List of ParticleLists

  • pdgCode (int, default=22)

    PDG code for mass reference

ParticlePrinter

Prints specified variables for all particles in the specified particle list to screen (useful for debugging). Event-based variables can be printed by not specifying the particle list (empty string).

Package

analysis

Library

libParticlePrinter.so

Parameters
  • fullPrint (bool, default=True)

    execute Particle’s internal print() function

  • listName (str, default=’’)

    name of ParticleList

  • variables (list(str), default=[])

    names of variables to be printed (see Variable::Manager)

ParticleSelector

Removes Particles from given ParticleList that do not pass specified selection criteria.

Package

analysis

Library

libParticleSelector.so

Required Parameters
  • decayString (str)

    Input ParticleList name (see DecayString).

Parameters
ParticleStats

Make a summary of specific ParticleLists.

Package

analysis

Library

libParticleStats.so

Parameters
  • outputFile (str, default=’’)

    Name of output file

  • particleLists (list(str), default=[])

    List of ParticleLists

  • printPassMatrix (bool, default=True)

    Should we also calculate and print the pass matrix?

ParticleVertexFitter

Vertex fitter for modular analysis

Package

analysis

Library

libParticleVertexFitter.so

Parameters
  • confidenceLevel (float, default=0.001)

    Confidence level to accept the fit. Particle candidates with p-value less than confidenceLevel are removed from the particle list. If set to -1, all candidates are kept; if set to 0, the candidates failing the fit are removed.

  • decayString (str, default=’’)

    specifies which daughter particles are included in the kinematic fit

  • fitType (str, default=’vertex’)

    type of the kinematic fit (vertex, massvertex, mass)

  • listName (str, default=’’)

    name of particle list

  • massConstraintList (list(int), default=[])

    Type::[int]. List of daughter particles to mass constrain with int = pdg code. (only for MassFourCKFit)

  • massConstraintListParticlename (list(str), default=[])

    Type::[string]. List of daughter particles to mass constrain with string = particle name. (only for MassFourCKFit)

  • recoilMass (float, default=0.0)

    recoil invariant mass (GeV)

  • smearing (float, default=0.002)

    smear IP tube width by given length

  • updateDaughters (bool, default=False)

    true: update the daughters after the vertex fit

  • vertexFitter (str, default=’KFit’)

    KFit or Rave

  • withConstraint (str, default=’’)

    additional constraint on vertex: ipprofile, iptube, mother, iptubecut, pointing, btube

ParticleWeighting

Weights particles according to LookUp table

Package

analysis

Library

libParticleWeighting.so

Required Parameters
  • particleList (str)

    Name of the ParticleList to reduce to the best candidates

  • tableName (str)

    ID of table used for reweighing

ParticleWeightingLookUpCreator

Creates test LookUp table

Package

analysis

Library

libParticleWeightingLookUpCreator.so

Required Parameters
  • experimentHigh (int)

    Interval of validity, ex.high

  • experimentLow (int)

    Interval of validity, ex.low

  • outOfRangeWeight (dict(str -> float))

    Weight info for out-of-range partiles

  • runHigh (int)

    Interval of validity, run high

  • runLow (int)

    Interval of validity, run low

  • tableName (str)

    Name of the LookUp table

Parameters
  • tableIDNotSpec (list(tuple(dict(str -> float), dict(str -> tuple(float, float)))), default=[])

    Bin:weight info map without specific bin-numbering scheme

  • tableIDSpec (list(tuple(tuple(dict(str -> float), dict(str -> tuple(float, float))), float)), default=[])

    Bin:weight info map with specific bin-numbering scheme

PhotonEfficiencySystematics

Module to include data/MC weights for photon detection efficiency. Include in your code as

mypath.add_module("PhotonEfficiencySystematics", particleLists=['gamma:cut'], tableName=tableName_Weight)
Package

analysis

Library

libPhotonEfficiencySystematics.so

Required Parameters
  • particleLists (list(str))

    input particle lists

  • tableName (str)

    ID of table used for reweighing

Pi0VetoEfficiencySystematics

Includes data/MC weights for pi0 veto efficiency as extraInfo for a given particle list. One must call writeP0EtaVeto function in advance. Weights and their errors will be provided for given mode and threshold.

Package

analysis

Library

libPi0VetoEfficiencySystematics.so

Parameters
  • decayString (str, default=’’)

    decay string

  • mode (str, default=’’)

    pi0 veto option name

  • particleLists (list(str), default=[])

    input particle lists

  • suffix (str, default=’’)

    suffix of extrainfo

  • tableName (str, default=’’)

    table name of the payloads

  • threshold (float, default=0.0)

    threshold of pi0 veto

PrintMCParticles

Print an MCParticle List

Package

analysis

Library

libPrintMCParticles.so

Parameters
  • maxLevel (int, default=-1)

    Show only up to specified depth level, -1 means no limit

  • onlyPrimaries (bool, default=True)

    Show only primary particles

  • showMomenta (bool, default=False)

    Show also the particle momenta

  • showProperties (bool, default=False)

    Show the basic particle properties

  • showStatus (bool, default=False)

    Show extendend status information of the particle

  • showVertices (bool, default=False)

    Show also the particle production vertices and times

  • storeName (str, default=’’)

    Name of the StoreArray to print

PseudoVertexFitter

Pseudo fitter adds a covariance matrix which is sum of the daughter covariance matrices.

Package

analysis

Library

libPseudoVertexFitter.so

Parameters
  • listName (str, default=’’)

    name of particle list

RemoveParticlesNotInLists

Removes all Particles that are not in one of the given ParticleLists (or daughters of Particles in the lists). All relations from/to Particles, daughter indices, and other ParticleLists are fixed. Note that this does not currently touch any data used to create final state particles, which might make up a large fraction of the total file size.

Package

analysis

Library

libRemoveParticlesNotInLists.so

Required Parameters
  • particleLists (list(str))

    Keep the Particles and their daughters in these ParticleLists.

RestOfEventBuilder

Creates for each Particle in the given ParticleList a RestOfEvent dataobject and makes basf2 relation between them.

Package

analysis

Library

libRestOfEventBuilder.so

Required Parameters
  • particleList (str)

    Name of the ParticleList

Parameters
  • createNestedROE (bool, default=False)

    A switch to create nested ROE

  • fromMC (bool, default=False)

    A switch to create MC ROE

  • mostLikely (bool, default=True)

    whether input particle lists contain most-likely lists

  • nestedROEMask (str, default=’’)

    A switch to create nested ROE

  • particleListsInput (list(str), default=[])

    List of the particle lists, which serve as a source of particles

  • useKLMEnergy (bool, default=False)

    A switch to create ROE with KLM energy included

RestOfEventInterpreter

Creates a mask (vector of boolean values) for tracks and clusters in RestOfEvent.

Package

analysis

Library

libRestOfEventInterpreter.so

Required Parameters
  • particleList (str)

    Name of the ParticleList

Parameters
  • ROEMasks (list(tuple(str, str, str, str)), default=[])

    List of (maskName, trackSelectionCut, eclClusterSelectionCut) tuples that specify all ROE masks of a specific particle to be created.

  • update (bool, default=False)

    Set true for updating a-priori charged stable fractions used in calculation of ROE 4-momentum

RestOfEventPrinter

Prints basic or detailed RestOfEvent info to screen. It is possible to print out ROEMasks for specific mask names as well.

Package

analysis

Library

libRestOfEventPrinter.so

Parameters
  • fullPrint (bool, default=False)

    If true, print whole masks content.

  • maskNames (list(str), default=[])

    List of all mask names for which the info will be printed.

  • unpackComposites (bool, default=True)

    If true, replace composites by their daughters

RestOfEventUpdater

Updates an existing mask (map of boolean values) for tracks or eclClusters in RestOfEvent with an available property (e.g. after performing training).

Package

analysis

Library

libRestOfEventUpdater.so

Required Parameters
  • particleList (str)

    Name of the ParticleList which contains information that will be used for updating

Parameters
  • cutString (str, default=’’)

    Cut string which will be used for updating masks

  • discard (bool, default=False)

    Update the ROE mask by passing or discarding particles in the provided particle list, default is to pass

  • updateMasks (list(str), default=[])

    List of all mask names which will be updated

SelectDaughters

SelectDaughters

Package

analysis

Library

libSelectDaughters.so

Parameters
  • decayString (str, default=’’)

    specifies which daughter particles will remain

  • listName (str, default=’’)

    name of particle list

SignalSideParticleFilter

The module returns true if the current RestOfEvent object is related to any of the Particles from the input ParticleList and passes selection criteria. The module should be executed only in the for_each ROE path.

Package

analysis

Library

libSignalSideParticleFilter.so

Parameters
  • particleLists (list(str), default=[])

    Input ParticleList name

  • selection (str, default=’’)

    Additional selection criteria

SignalSideParticleListCreator

The module creates a ParticleList and fills it with one of the daughter Particles.

Package

analysis

Library

libSignalSideParticleListCreator.so

Parameters
  • decayString (str, default=’’)

    DecayString specifying the daughter Particle to be included in the ParticleList

  • particleListName (str, default=’’)

    Name of the ParticleList to be created and filled with signal side daughter Particle

SignalSideVariablesToDaughterExtraInfo

The module writes properties (values of specified variables) of the particle related to the current ROE as an ExtraInfo to the single particle in the input ParticleList. This module is intended to be executed only in for_each ROE path.

Package

analysis

Library

libSignalSideVariablesToDaughterExtraInfo.so

Parameters
  • overwrite (int, default=0)

    -1/0/1/2: Overwrite if lower / don’t overwrite / overwrite if higher / always overwrite, in case if extra info with given name already exists

  • particleListName (str, default=’’)

    The input particleList name. This list should contain at most 1 particle

  • variablesToExtraInfo (dict(str -> str), default={})

    Dictionary of variables and extraInfo names to save in the extra-info field.

SignalSideVariablesToExtraInfo

The module writes property (value of specified variable) of single particle found in the input ParticleList as an ExtraInfo to the Particle related to the current ROE. This module is intended to be executed only in for_each ROE path.

Package

analysis

Library

libSignalSideVariablesToExtraInfo.so

Parameters
  • particleListName (str, default=’’)

    The input particleList name. This list should contain at most 1 particle

  • variableToExtraInfo (dict(str -> str), default={})

    Dictionary of variables and extraInfo names to save in the extra-info field.

SkimFilter

Filter based on ParticleLists, by setting return value to true if at least one of the given lists is not empty.

Package

analysis

Library

libSkimFilter.so

Parameters
  • particleLists (list(str), default=[])

    List of ParticleLists

TagUniqueSignal

Mark true (target=1) candidates from input list via extra-info field. Only the first true candidate associated with an MCParticle is marked.

Package

analysis

Library

libTagUniqueSignal.so

Required Parameters
  • particleList (str)

    Input ParticleList name

Parameters
  • extraInfoName (str, default=’uniqueSignal’)

    Extra-info field added to all particles in the input list. 1 for unique signal, 0 for background or duplicates.

  • target (str, default=’isSignal’)

    Variable which defines signal and background.

TagVertex

Tag side Vertex Fitter for modular analysis

Package

analysis

Library

libTagVertex.so

Parameters
  • MCAssociation (str, default=’breco’)

    ‘’: no MC association. breco: use standard Breco MC association. internal: use internal MC association

  • askMCInformation (bool, default=False)

    TRUE when requesting MC Information from the tracks performing the vertex fit

  • confidenceLevel (float, default=0.001)

    required confidence level of fit to keep particles in the list. Note that even with confidenceLevel == 0.0, errors during the fit might discard Particles in the list. confidenceLevel = -1 if an error occurs during the fit

  • constraintType (str, default=’IP’)

    Choose the type of the constraint: noConstraint, IP (tag tracks constrained to be within the beam spot), tube (long tube along the BTag line of flight, only for fully reconstruced B rec), boost (long tube along the Upsilon(4S) boost direction), (breco)

  • fitAlgorithm (str, default=’Rave’)

    Fitter used for the tag vertex fit: Rave or KFit

  • listName (str, default=’’)

    name of particle list

  • maskName (str, default=’all’)

    Choose ROE mask to get particles from

  • reqPXDHits (int, default=0)

    Minimum number of PXD hits for a track to be used in the vertex fit

  • trackFindingType (str, default=’standard_PXD’)

    Choose how to reconstruct the tracks on the tag side: standard, standard_PXD

  • useRollBack (bool, default=False)

    Use rolled back non-primary tracks

  • useTruthInFit (bool, default=False)

    Use the true track parameters in the vertex fit

TauDecayMarker

Module to identify generated tau pair decays, using MCParticle information. Each tau lepton decay channel is numbered following the order in the default KKMC decay table. Using this module, the channel number will be stored in the variables tauPlusMCMode, and tauMinusMCMode. Further details and usage can be found at Tau decay MC modes.

Package

analysis

Library

libTauDecayMarker.so

Parameters
  • printDecayInfo (bool, default=False)

    Print information of the tau pair decay from MC.

TauDecayMode

Module to identify generated tau pair decays, using MCParticle information.By default, each tau decay is numbered as TauolaBelle2DecayMode [Ref: BELLE2-NOTE-PH-2020-055]

Package

analysis

Library

libTauDecayMode.so

Parameters
  • file_minus (str, default=’’)

    Path for an alternative mapping for tau- decays

  • file_plus (str, default=’’)

    Path for an alternative mapping for tau+ decays

  • printmode (str, default=’default’)

    Printout more information from each event

TrackIsoCalculator

Calculate track isolation variables on the input ParticleList.

Package

analysis

Library

libTrackIsoCalculator.so

Required Parameters
  • detectorInnerSurface (str)

    The name of the detector at whose innermost layer we extrapolate each helix’s polar and azimuthal angle. Allowed values: {CDC, PID(=TOP/ARICH), ECL, KLM}.

  • particleList (str)

    The name of the input ParticleList. Must be a charged stable particle as defined in Const::chargedStableSet.

Parameters
  • use2DRhoPhiDist (bool, default=False)

    If true, will calculate the pair-wise track distance as the cord length on the (rho, phi) projection.

TrackingEfficiency

Module to remove tracks from the lists at random. Include in your code as

mypath.add_module("TrackingEfficiency", particleLists=['pi+:cut'], frac=0.01)

The module modifies the input particleLists by randomly removing tracks with the probability frac.

Package

analysis

Library

libTrackingSystematics.so

Required Parameters
  • particleLists (list(str))

    input particle lists

Parameters
  • frac (float, default=0.0)

    probability to remove the particle

TrackingMomentum

Module to modify momentum of tracks from the lists. Include in your code as

mypath.add_module("TrackingMomentum", particleLists=['pi+:cut'], scale=0.999)

The module modifies the input particleLists by scaling track momenta as given by the parameter scale

Package

analysis

Library

libTrackingSystematics.so

Required Parameters
  • particleLists (list(str))

    input particle lists

Parameters
  • payloadName (str, default=’’)

    ID of table used for reweighing

  • scale (float, default=nan)

    scale factor to be applied to 3-momentum

  • scalingFactorName (str, default=’’)

    Label for the scale factor in the look up table

  • smearingFactorName (str, default=’’)

    Label for the smearing factor in the look up table

TreeFitter

Tree Fitter module. Performs simultaneous fit of all vertices in a decay chain. Can also be used to just fit a single vertex.

Package

analysis

Library

libTreeFitter.so

Required Parameters
  • particleList (str)

    Type::[string]. Input mother of the decay tree to fit. For example ‘B0:myB0particleList’.

Parameters
  • autoSetGeoConstraintAndMergeVertices (bool, default=True)

    Type::bool, shall vertices of strong resonance be merged with their mothers? Can the particles vertex be constraint geometrically?

  • confidenceLevel (float, default=0.0)

    Type::[double]. Confidence level to accept fitted decay tree. Candidates with < confidenceLevel will be removed from the particle list! Typical Values: -1: keep all particle candidates, 0: remove all that fail the fit, 0.001: standard cut, 0.1: (too) tight cut. Optimise using a figure of merit (for example S/(sqrt{S+B}) ) for your analysis.

  • convergencePrecision (float, default=0.01)

    Type::[double]. Fractional upper limit for chi2 fluctuations to accept result. Larger value = less signal rejection but also less background rejection. Optimized for FOM on different topologies - don’t touch unless you REALLY want this.

  • customOriginConstraint (bool, default=False)

    Type::[bool]. Use a custom vertex as the production point of the highest hierarchy particle (register this as the mother of the list you specify). Like the beam constraint but you can specify the position its covariance yourself.

  • customOriginCovariance (list(float), default=[0.0048, 0.0, 0.0, 0.0, 0.003567, 0.0, 0.0, 0.0, 0.04])

    Type::[double]. List vertex covariance elements used in the custom origin constraint (as a vector). Default is meant for B0 decays and is taken from 100k generated B0 to mumu events.

  • customOriginVertex (list(float), default=[0.001, 0.0, 0.0116])

    Type::[double]. List of vertex coordinates to be used in the custom origin constraint.

  • expertMassConstraintType (int, default=0)

    Type::[int]. False(0): use particles parameters in mass constraint; True: use sum of daughter parameters for mass constraint. WAARNING not even guaranteed that it works.

  • expertRemoveConstraintList (list(str), default=[])

    Type::[string]. List of constraints that you do not want to be used in the fit. WARNING don’t use if you don’t know exactly what it does.

  • expertUseReferencing (bool, default=True)

    Type::[bool]. Use the Extended Kalman Filter. This implementation linearises around the previous state vector which gives smoother convergence.

  • geoConstraintList (list(int), default=[])

    Type::[int], if ‘autoSetGeoConstraintAndMergeVertices==False’ you can manually set the particles that will be geometrically constrained here.

  • inflationFactorCovZ (int, default=1)

    Inflate the covariance of the beamspot by this number so that the 3d beam constraint becomes weaker in Z.And: thisnumber->infinity : dim(beamspot constr) 3d->2d.

  • ipConstraint (bool, default=False)

    Type::[bool]. Use the IP as the origin of the tree. This registers an internal IP particle as the mother of the list you give. Or in other words forces the PRODUCTION vertex of your particle to be the IP and its covariance as specified in the database.

  • massConstraintList (list(int), default=[])

    Type::[int]. List of particles to mass constrain with int = pdg code. Note that the variables ‘M’: fit result for the particle and ‘InvM’: calculated from the daughter momenta, will look different (especially if you don’t update the daughters!).

  • massConstraintListParticlename (list(str), default=[])

    Type::[string]. List of particles to mass constrain with string = particle name.

  • originDimension (int, default=3)

    Type int, default 3. If origin or ip constraint used, specify the dimension of the constraint 3->x,y,z; 2->x,y. This also changes the dimension of the geometric constraints! So you might want to turn them off for some particles. (That means turn auto off and manually on for the ones you want to constrain)

  • sharedVertexList (list(int), default=[])

    Type::[int], if ‘autoSetGeoConstraintAndMergeVertices==False’ you can manually set the particles that share the vertex with their mother here.

  • updateAllDaughters (bool, default=False)

    Type::[bool]. Update all daughters (vertex position and momenta) in the tree. If not set only the 4-momenta for the head of the tree will be updated. We also update the vertex position of the daughters regardless of what you put here, because otherwise the default when the particle list is created is {0,0,0}.

V0DaughterMassUpdater

This module replaces the mass of two daughters of the selected V0 particles inside the given particleLists with masses of given pdgCode. The particle in selected particleList has to have 2 daughters.

Package

analysis

Library

libV0DaughterMassUpdater.so

Parameters
  • particleLists (list(str), default=[])

    List of ParticleLists

  • pdgCodeOfV0negDaughter (int, default=11)

    PDG code of daughter with negative charge

  • pdgCodeOfV0posDaughter (int, default=11)

    PDG code of daughter with positive charge

VariableToReturnValue

Calculate event-based variable specified by the user and sets return value of the module accordingly.

Package

analysis

Library

libVariableToReturnValue.so

Parameters
  • variable (str, default=’’)

    Variable taken from Variable::Manager, see output of ‘basf2 variables.py’.

VariablesToEventBasedTree

Calculate variables specified by the user for a given ParticleList and save them into a TTree. The Tree is event-based, meaning that the variables of each candidate for each event are saved in an array of a branch of the Tree.

Package

analysis

Library

libVariablesToEventBasedTree.so

Parameters
  • event_variables (list(str), default=[])

    List of variables (or collections) to save for each event. Variables are taken from Variable::Manager, and are identical to those available to e.g. ParticleSelector. Only event-based variables are allowed here.

  • fileName (str, default=’VariablesToEventBasedTree.root’)

    Name of ROOT file for output.

  • maxCandidates (unsigned int, default=100)

    The maximum number of candidates in the ParticleList per entry of the Tree.

  • particleList (str, default=’’)

    Name of particle list with reconstructed particles. An empty ParticleList is not supported. Use the VariablesToNtupleModule for this use-case

  • sampling (tuple(str, dict(int -> unsigned int)), default=(‘’, {}))

    Tuple of variable name and a map of integer values and inverse sampling rate. E.g. (signal, {1: 0, 0:10}) selects all signal events and every 10th background event. Variable must be event-based.

  • treeName (str, default=’tree’)

    Name of the NTuple in the saved file.

  • variables (list(str), default=[])

    List of variables (or collections) to save for each candidate. Variables are taken from Variable::Manager, and are identical to those available to e.g. ParticleSelector.

VariablesToEventExtraInfo

For each particle in the input list the selected variables are saved in an event-extra-info field with the given name. Can be used to save MC truth information, for example, in a ntuple of reconstructed particles.

Package

analysis

Library

libVariablesToEventExtraInfo.so

Required Parameters
  • particleList (str)

    Name of particle list with reconstructed particles.

Parameters
  • overwrite (int, default=0)

    -1/0/1/2: Overwrite if lower / don’t overwrite / overwrite if higher / always overwrite, in case if extra info with given name already exists

  • variables (dict(str -> str), default={})

    Dictionary of variables and extraInfo names to save in the event-extra-info field. Variables are taken from Variable::Manager, and are identical to those available to e.g. ParticleSelector.

VariablesToExtraInfo

For each particle in the input list the selected variables are saved in an extra-info field with the given name. Can be used when wanting to save variables before modifying them, e.g. when performing vertex fits.

Package

analysis

Library

libVariablesToExtraInfo.so

Required Parameters
  • particleList (str)

    Name of particle list with reconstructed particles.

Parameters
  • decayString (str, default=’’)

    DecayString specifying the daughter Particle to be included in the ParticleList

  • overwrite (int, default=0)

    -1/0/1/2: Overwrite if lower / don’t overwrite / overwrite if higher / always overwrite, in case if extra info with given name already exists

  • variables (dict(str -> str), default={})

    Dictionary of variables and extraInfo names to save in the extra-info field. Variables are taken from Variable::Manager, and are identical to those available to e.g. ParticleSelector.

VariablesToHistogram

Calculate variables specified by the user for a given ParticleList and save them into one or two dimensional histograms.

Package

analysis

Library

libVariablesToHistogram.so

Parameters
  • directory (str, default=’’)

    Directory for all histograms inside the file to allow for histograms from multiple particlelists in the same file without conflicts

  • fileName (str, default=’VariablesToHistogram.root’)

    Name of ROOT file for output.

  • particleList (str, default=’’)

    Name of particle list with reconstructed particles. If no list is provided the variables are saved once per event (only possible for event-type variables)

  • variables (list(tuple(str, int, float, float)), default=[])

    List of variables to save. Variables are taken from Variable::Manager, and are identical to those available to e.g. ParticleSelector.

  • variables_2d (list(tuple(str, int, float, float, str, int, float, float)), default=[])

    List of variable pairs to save. Variables are taken from Variable::Manager, and are identical to those available to e.g. ParticleSelector.

VariablesToNtuple

Calculate variables specified by the user for a given ParticleList and save them into a TNtuple. The TNtuple is candidate-based, meaning that the variables of each candidate are saved separate rows.

Package

analysis

Library

libVariablesToNtuple.so

Parameters
  • fileName (str, default=’VariablesToNtuple.root’)

    Name of ROOT file for output.

  • particleList (str, default=’’)

    Name of particle list with reconstructed particles. If no list is provided the variables are saved once per event (only possible for event-type variables)

  • sampling (tuple(str, dict(int -> unsigned int)), default=(‘’, {}))

    Tuple of variable name and a map of integer values and inverse sampling rate. E.g. (signal, {1: 0, 0:10}) selects all signal candidates and every 10th background candidate.

  • treeName (str, default=’ntuple’)

    Name of the NTuple in the saved file.

  • variables (list(str), default=[])

    List of variables (or collections) to save. Variables are taken from Variable::Manager, and are identical to those available to e.g. ParticleSelector.