7.6. Event based analysis#

Note

The analysis software framework is designed to work with particles. In the default candidate-wise paradigm the analyst takes lists of particles, builds up candidates, loads analysis modules, and saves information (i.e. using the VariablesToNtuple tool) for each candidate. If you are new, it is probably best to start with this approach.

In some situations, it is useful to make cuts on, and write out event-wise information.

Warning

Please note that this use model and the documentation are under development.

Please ask questions at Belle II questions and report bugs using GitLab. Be sure to tag your questions and bug reports as “analysis” and “event based” to help us find them.

7.6.1. VariablesToEventBasedTree#

The VariablesToNtuple tool writes out one entry in a TTree for every candidate. If you want one entry for every event, you should use the VariableToEventBasedTree module. Note that this still operates on a particle list so you will still need to build up a list of candidates in the normal way.

Here is an example of writing event-wise information for all pions in the event:

import basf2
from stdCharged import stdPi

mypath = basf2.Path()
stdPi('all', path=mypath)
mypath.add_module('VariablesToEventBasedTree',
                  particleList='pi+:all',
                  variables=['isSignal', 'mcErrors', 'p', 'E'],
                  event_variables=['nTracks', 'expNum', 'runNum', 'evtNum'])
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. Can be overridden using the -o argument of basf2.

  • fileNameSuffix (str, default=’’)

    The suffix of the output ROOT file to be appended before .root.

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

7.6.2. Event based selection#

Instead of making cuts on properties of particle lists, it is possible to reject all events that fail an event based variable cut. Here is a simple example:

from modularAnalysis import applyEventCuts, buildEventShape
from stdCharged import stdPi

stdPi('all', path=mypath)
buildEventShape(path=mypath)
applyEventCuts('foxWolframR2 < 0.3', path=mypath)

This builds the list of all pions but only processes events where the event-level R2 passes the cut.

See also

B2A307 shows a full example.

modularAnalysis.applyEventCuts(cut, path, metavariables=None)[source]

Removes events that do not pass the cut (given selection criteria).

Example

continuum events (in mc only) with more than 5 tracks

applyEventCuts("[nTracks > 5] and [isContinuumEvent], path=mypath)

Warning

Only event-based variables are allowed in this function and only square brackets [ and ] for conditional statements.

Parameters
  • cut (str) – Events that do not pass these selection criteria are skipped

  • path (basf2.Path) – modules are added to this path

  • metavariables (list(str)) – List of meta variables to be considered in decomposition of cut

Event based variables#

Here is a list of event based variables on which you can make a cut using the above.

B0Mode

[Eventbased] It will return the decays mode of B0 particles

Group

MCParticle tag variables

Bbar0Mode

[Eventbased] It will return the decays mode of anti-B0 particles

Group

MCParticle tag variables

BminusMode

[Eventbased] It will return the decays mode of B- particles

Group

MCParticle tag variables

BplusMode

[Eventbased] It will return the decays mode of B+ particles

Group

MCParticle tag variables

Bs0Mode

[Eventbased] It will return the decays mode of B_s0 particles

Group

MCParticle tag variables

Bsbar0Mode

[Eventbased] It will return the decays mode of anti-B_s0 particles

Group

MCParticle tag variables

D0Mode

[Eventbased] It will return the decays mode of D0 particles

Group

MCParticle tag variables

Dbar0Mode

[Eventbased] It will return the decays mode of anti-D0 particles

Group

MCParticle tag variables

DminusMode

[Eventbased] It will return the decays mode of D- particles

Group

MCParticle tag variables

DplusMode

[Eventbased] It will return the decays mode of D+ particles

Group

MCParticle tag variables

DsminusMode

[Eventbased] It will return the decays mode of D_s- particles

Group

MCParticle tag variables

DsplusMode

[Eventbased] It will return the decays mode of D_s+ particles

Group

MCParticle tag variables

DstminusMode

[Eventbased] It will return the decays mode of D*- particles

Group

MCParticle tag variables

DstplusMode

[Eventbased] It will return the decays mode of D*+ particles

Group

MCParticle tag variables

Ecms

[Eventbased] Returns center-of-mass energy.

Unit

GeV

Group

Event

EcmsMC

[Eventbased] Truth value of sqrt(s)

Unit

GeV

Group

Event

HighLevelTrigger

[Eventbased] True if event passes the HLT trigger, false if not

Group

Software Trigger

IPCov(i, j)

[Eventbased] Returns (i,j)-th element of the covariance matrix of the measured interaction point.

Unit

\(\text{cm}^2\)

Group

Event

IPY

[Eventbased] Returns y coordinate of the measured interaction point.

Unit

cm

Group

Event

IPZ

[Eventbased] Returns z coordinate of the measured interaction point.

Unit

cm

Group

Event

L1TimeQuality

[Eventbased] Returns expected Level1 timing resolution. This flag will be used for SVD 3-point sampling in future. 0:None; 1:Coarse (sigma > x ns); 2:FINE (sigma < x ns); x has been set to about 5ns before LS1 but can be changed in future

Group

L1 Trigger

L1TimeType

[Eventbased] Returns kind of detector which determines the Level1 trigger timing. 0:ECL, 1:TOP, 2:SELF(timing of PSNM bit), 3:CDC, 5:delayed bhabha, 7: random, 13:poisson.

Group

L1 Trigger

L1Trigger

[Eventbased] Returns 1 if at least one PSNM L1 trigger bit is true.

Group

L1 Trigger

PxHER

[Eventbased] Returns truth value of the x component of the incoming electron momentum in the laboratory frame.

Unit

GeV/c

Group

Event

PxLER

[Eventbased] Returns truth value of the x component of the incoming positron momentum in the laboratory frame.

Unit

GeV/c

Group

Event

PyHER

[Eventbased] Returns truth value of the y component of the incoming electron momentum in the laboratory frame.

Unit

GeV/c

Group

Event

PyLER

[Eventbased] Returns truth value of the y component of the incoming positron momentum in the laboratory frame.

Unit

GeV/c

Group

Event

PzHER

[Eventbased] Returns truth value of the z component of the incoming electron momentum in the laboratory frame.

Unit

GeV/c

Group

Event

PzLER

[Eventbased] Returns truth value of the z component of the incoming positron momentum in the laboratory frame.

Unit

GeV/c

Group

Event

SoftwareTriggerPrescaling(triggerIdentifier)

[Eventbased] return the prescaling for the specific software trigger identifier. Please note, this prescaling is taken from the currently setup database. It only corresponds to the correct HLT prescale if you are using the online database!If the trigger identifier is not found, returns NaN.

Group

Software Trigger

SoftwareTriggerResultNonPrescaled(triggerIdentifier)

[Eventbased] [Expert] returns the SoftwareTriggerCutResult, if this trigger would not be prescaled.Please note, this is not the final HLT decision! It is defined as reject (-1), accept (1), or noResult (0). Note that the meanings of these change depending if using trigger or the skim stage, hence expert.If the trigger identifier is not found, returns NaN.

Group

Software Trigger

TauminusMode

[Eventbased] It will return the decays mode of tau- particles

Group

MCParticle tag variables

TauplusMode

[Eventbased] It will return the decays mode of tau+ particles

Group

MCParticle tag variables

averageValueInList(particleListName, variable)

[Eventbased] Returns the arithmetic mean of the given variable of the particles in the given particle list.

Group

MetaFunctions

beamE

[Eventbased] Returns total beam energy in the laboratory frame.

Unit

GeV

Group

Event

beamPx

[Eventbased] Returns x component of total beam momentum in the laboratory frame.

Unit

GeV/c

Group

Event

beamPy

[Eventbased] Returns y component of total beam momentum in the laboratory frame.

Unit

GeV/c

Group

Event

beamPz

[Eventbased] Returns z component of total beam momentum in the laboratory frame.

Unit

GeV/c

Group

Event

countInList(particleList, cut='')

[Eventbased] Returns number of particle which pass given in cut in the specified particle list. Useful for creating statistics about the number of particles in a list. E.g. countInList(e+, isSignal == 1) returns the number of correctly reconstructed electrons in the event. The variable is event-based and does not need a valid particle pointer as input.

Group

MetaFunctions

currentROEIsInList(particleList)

[Eventbased] Returns 1 the associated particle of the current ROE is contained in the given list or its charge-conjugated.Useful to restrict the for_each loop over ROEs to ROEs of a certain ParticleList.

Group

Rest Of Event

eventCached(variable)

[Eventbased] Returns value of event-based variable and caches this value in the EventExtraInfo. The result of second call to this variable in the same event will be provided from the cache. It is recommended to use this variable in order to declare custom aliases as event-based. This is necessary if using the eventwise mode of variablesToNtuple).

Group

MetaFunctions

eventExtraInfo(name)

[Eventbased] Returns extra info stored under the given name in the event extra info. The extraInfo has to be set first by another module like MVAExpert in event mode. If nothing is set under this name, NaN is returned.

Group

MetaFunctions

eventRandom

[Eventbased] Returns a random number between 0 and 1 for this event. Can be used, e.g. for applying an event prescale.

Group

Miscellaneous

eventTimeSeconds

[Eventbased] Time of the event (truncated down) since 1970/1/1 (Unix epoch).

Unit

s

Group

Event

evtNum

[Eventbased] Returns the event number.

Group

Event

expNum

[Eventbased] Returns the experiment number.

Group

Event

genIPY

[Eventbased] Returns y coordinate of the interaction point used for the underlying MC generation. Returns NaN for data.

Unit

cm

Group

Event

genIPZ

[Eventbased] Returns z coordinate of the interaction point used for the underlying MC generation. Returns NaN for data.

Unit

cm

Group

Event

generatorEventWeight

[Eventbased] Returns the event weight produced by the event generator

Group

MC matching and MC truth

hasRecentInjection

[Eventbased] Returns 1 if an injection happened recently, 0 otherwise.

Group

Event

injectionInHER

[Eventbased] Returns 1 if injection was in HER, 0 otherwise.

Group

Event

invMassInLists(pList1, pList2, ...)

[Eventbased] Returns the invariant mass of the combination of particles in the given particle lists. The unit of the invariant mass is GeV/\(\text{c}^2\)

Group

MetaFunctions

isChargedBEvent

[Eventbased] Returns 1.0 if event contains a charged B-meson on generator level.

Group

Event

isContinuumEvent

[Eventbased] Returns 1.0 if event doesn’t contain a \(\Upsilon(4S)\) particle on generator level, 0.0 otherwise.

Group

Event

isMC

[Eventbased] Returns 1 if current basf2 process is running over simulated (Monte-Carlo) dataset and 0 in case of real experimental data.

Group

Event

isMajorityInRestOfEventFromB0(maskName)

[Eventbased][Expert] Checks if the majority of the tracks in the current RestOfEvent are from a B0.

Group

Flavor Tagger Expert Variables

isMajorityInRestOfEventFromB0bar(maskName)

[Eventbased][Expert] Check if the majority of the tracks in the current RestOfEvent are from a anti-B0.

Group

Flavor Tagger Expert Variables

isNotContinuumEvent

[Eventbased] Returns 1.0 if event does contain an \(\Upsilon(4S)\) particle on generator level and therefore is not a continuum event, 0.0 otherwise.

Group

Event

isPoissonTriggerInInjectionVeto

[Eventbased] Returns 1 if the poisson random trigger is within the injection veto window.

Group

L1 Trigger

isUnmixedBEvent

[Eventbased] Returns 1.0 if the event contains opposite flavor neutral B-mesons on generator level, 0.0 in case of same flavor B-mesons and NaN if the event has no generated neutral B.

Group

Event

maxOpeningAngleInList(particleListName)

[Eventbased] Returns maximum opening angle in the given particle List. The unit of the angle is rad

Group

MetaFunctions

maxPtInList(particleListName)

[Eventbased] Returns maximum transverse momentum Pt in the given particle List. The unit of the transverse momentum is GeV/c

Group

MetaFunctions

mcPxHER

[Eventbased] Returns x component of the electron beam momentum in the laboratory frame.

Unit

GeV/c

Group

Event

mcPxLER

[Eventbased] Returns x component of the positron beam momentum in the laboratory frame.

Unit

GeV/c

Group

Event

mcPyHER

[Eventbased] Returns y component of the electron beam momentum in the laboratory frame.

Unit

GeV/c

Group

Event

mcPyLER

[Eventbased] Returns y component of the positron beam momentum in the laboratory frame.

Unit

GeV/c

Group

Event

mcPzHER

[Eventbased] Returns z component of the electron beam momentum in the laboratory frame.

Unit

GeV/c

Group

Event

mcPzLER

[Eventbased] Returns z component of the positron beam momentum in the laboratory frame.

Unit

GeV/c

Group

Event

medianValueInList(particleListName, variable)

[Eventbased] Returns the median value of the given variable of the particles in the given particle list.

Group

MetaFunctions

nCleanedECLClusters(cut)

[Eventbased] Returns the number of clean Clusters in the event Clean clusters are defined by the clusters which pass the given cut assuming a photon hypothesis.

Group

MetaFunctions

nCleanedTracks(cut)

[Eventbased] Returns the number of clean Tracks in the event Clean tracks are defined by the tracks which pass the given cut assuming a pion hypothesis.

Group

MetaFunctions

nInitialPrimaryMCParticles

[Eventbased] Returns number of initial primary MCParticles in the event.

Group

Event

nKLMClusters

[Eventbased] Returns number of KLM clusters in the event.

Group

Event

nMCParticles

[Eventbased] Returns number of MCParticles in the event.

Group

Event

nNeutralECLClusters(hypothesis)

[Eventbased] Returns number of neutral ECL clusters with a given hypothesis, 1:nPhotons, 2:NeutralHadron.

Group

Event

nParticlesInList(particleListName)

[Eventbased] Returns number of particles in the given particle List.

Group

MetaFunctions

nPrimaryMCParticles

[Eventbased] Returns number of primary MCParticles in the event.

Group

Event

nTrackFitResults(particleType)

[Eventbased] Returns the total number of TrackFitResults for a given particleType. The argument can be the name of particle (e.g. pi+) or PDG code (e.g. 211).

Group

MetaFunctions

nV0s

[Eventbased] Returns number of V0s in the event.

Group

Event

nValidV0s

[Eventbased] Returns number of V0s consisting of pair of tracks with opposite charges.

Group

Event

nVirtualPrimaryMCParticles

[Eventbased] Returns number of virtual primary MCParticles in the event.

Group

Event

particleRelatedToCurrentROE(var)

[Eventbased] Returns variable applied to the particle which is related to the current RestOfEvent objectOne can use this variable only in a for_each loop over the RestOfEvent StoreArray.

Group

Rest Of Event

passesEventCut(cut)

[Eventbased] Returns 1 if event passes the cut otherwise 0. Useful if you want to select events passing a cut without looping into particles, such as for skimming.

Group

MetaFunctions

runNum

[Eventbased] Returns the run number.

Group

Event

tauMinusMCMode

[Eventbased] Decay ID for the negative tau lepton in a tau pair generated event.

Group

Generated tau decay information

tauMinusMCProng

[Eventbased] Prong for the negative tau lepton in a tau pair generated event.

Group

Generated tau decay information

tauPlusMCMode

[Eventbased] Decay ID for the positive tau lepton in a tau pair generated event.

Group

Generated tau decay information

tauPlusMCProng

[Eventbased] Prong for the positive tau lepton in a tau pair generated event.

Group

Generated tau decay information

timeSinceLastInjectionClockTicks

[Eventbased] Time since the last injected bunch passed by the detector.

Unit

clock ticks

Group

Event

timeSinceLastInjectionMicroSeconds

[Eventbased] Time since the last injected bunch passed by the detector.

Unit

\(\mathrm{\mu s}\)

Group

Event

timeSincePrevTriggerClockTicks

[Eventbased] Time since the previous trigger (127MHz=RF/4 clock).

Unit

clock ticks

Group

Event

timeSincePrevTriggerMicroSeconds

[Eventbased] Time since the previous trigger.

Unit

\(\mathrm{\mu s}\)

Group

Event

totalECLEnergyOfParticlesInList(particleListName)

[Eventbased] Returns the total ECL energy of particles in the given particle List. The unit of the energy is GeV

Group

MetaFunctions

totalEnergyMC

[Eventbased] Truth value of sum of energies of all the generated particles

Unit

GeV

Group

Event

totalEnergyOfParticlesInList(particleListName)

[Eventbased] Returns the total energy of particles in the given particle List. The unit of the energy is GeV

Group

MetaFunctions

totalPxOfParticlesInList(particleListName)

[Eventbased] Returns the total momentum Px of particles in the given particle List. The unit of the momentum is GeV/c

Group

MetaFunctions

totalPyOfParticlesInList(particleListName)

[Eventbased] Returns the total momentum Py of particles in the given particle List. The unit of the momentum is GeV/c

Group

MetaFunctions

totalPzOfParticlesInList(particleListName)

[Eventbased] Returns the total momentum Pz of particles in the given particle List. The unit of the momentum is GeV/c

Group

MetaFunctions