6.3.1. VariableManager

The VariableManager handles all variables in basf2 analysis. It is implemented as a singleton C++ class with a python interface.

The C++ documentation is here.

Tip

For (unfortunate) historical reasons, the python accessor to the VariableManager singleton is called variables and is in the python variables module. This leads to strange-looking python import commands.

For example:

from variables import variables

To avoid confusion, example/tutorial scripts often use a namespace alias vm. You might want to use this in your scripts.

from variables import variables as vm # shorthand for VariableManager

class VariableManager

Singleton class to hold all variables and aliases in the current scope.

addAlias(alias, expression)

Create a new alias.

Variable names are deliberately verbose and explicit (to avoid ambiguity). However, it is often not desirable to deal with long unwieldy variable names particularly in the context of Variable Manager Output.

Example:

Aliases to a verbose variable may be set with:

>>> from variables import variables as vm
>>> vm.addAlias("shortname", "aReallyLongAndSpecificVariableName(1, 2, 3)")

See also

variables.utils.create_aliases and variables.utils.create_aliases_for_selected might be helpful if you find yourself setting many aliases in your analysis script.

Warning

The VariableManager instance is configured independently of the basf2.Path. In case of adding the same alias twice, the configuration just before calling basf2.process is what wins.

Parameters

• alias (str) – New alias to create

• expression (str) – The expression the alias should evaluate to

Returns

True if the alias was successfully added

getAliasNames()

Get a list of all alias names (in reverse order added)

Tip

This returns a ROOT.vector which you will probably need to convert into a python list(str).

>>> my_aliases = list(vm.getAliasNames())

Returns

ROOT.vector list of alias names

addCollection(collection, variables)

Create a new variable collection.

Tip

This method takes a ROOT.vector<string> as input. It’s probably easier to use variables.utils.add_collection which wraps this function for you.

Parameters

• collection (str) – The new collection to create.

• variables – A ROOT.std.vector(string) instance of variables to add as the variable collection.

Returns

True if the collection was successfully added

getCollection(collection)

Get a list of all variables in the collection.

Parameters

collection (str) – The name of the existing variable collection

Returns

ROOT.vector list of variable names

printAliases()

Prints all aliases currently registered. Useful to call just before calling basf2.process on an analysis basf2.Path when debugging.

6.3.2. Variables by group

Here is a categorised list of variables known to basf2. You can also look at the alphabetical index: Basf2 Variable Index.

Kinematics

ArmenterosDaughter1Qt

Transverse momentum of the first daughter with respect to the V0 mother. The mother is required to have exactly two daughters

ArmenterosDaughter2Qt

Transverse momentum of the second daughter with respect to the V0 mother. The mother is required to have exactly two daughters

ArmenterosLongitudinalMomentumAsymmetry

Longitudinal momentum asymmetry of V0’s daughters. The mother (V0) is required to have exactly two daughters

E

energy

ECLClusterE_uncertainty

energy uncertainty as given by the underlying ECL cluster.

E_uncertainty

energy uncertainty (sqrt(sigma2))

ErrM

uncertainty of invariant mass

ImpactXY

The impact parameter of the given particle in the xy plane

InvM

invariant mass (determined from particle’s daughter 4-momentum vectors). If this particle has no daughters, defaults to M.

InvMLambda

Invariant mass (determined from particle’s daughter 4-momentum vectors), assuming the first daughter is a pion and the second daughter is a proton. If the particle has not 2 daughters, it returns just the mass value.

M

The particle’s mass.

Note that this is context-dependent variable and can take different values depending on the situation. This should be the “best” value possible with the information provided.

• If this particle is track- or cluster- based, then this is the value of the mass hypothesis.

• If this particle is an MC particle then this is the mass of that particle.

• If this particle is composite, then initially this takes the value of the invariant mass of the daughters.

• If this particle is composite and a mass or vertex fit has been performed then this may be updated by the fit.

  • You will see a difference between this mass and the InvM.

M2

The particle’s mass squared.

Mbc

beam constrained mass

PDG

PDG code

Q

released energy in decay

SigM

signed deviation of particle’s invariant mass from its nominal mass in units of the uncertainty on the invariant mass (dM/ErrM)

b2bClusterPhi

Azimuthal angle in the lab system that is back-to-back to the particle’s associated ECLCluster in the CMS. Returns NAN if no cluster is found. Useful for low multiplicity studies.

b2bClusterTheta

Polar angle in the lab system that is back-to-back to the particle’s associated ECLCluster in the CMS. Returns NAN if no cluster is found. Useful for low multiplicity studies.

b2bPhi

Azimuthal angle in the lab system that is back-to-back to the particle in the CMS. Useful for low multiplicity studies.

b2bTheta

Polar angle in the lab system that is back-to-back to the particle in the CMS. Useful for low multiplicity studies.

cosAngleBetweenMomentumAndVertexVector

cosine of the angle between momentum and vertex vector (vector connecting ip and fitted vertex) of this particle

cosAngleBetweenMomentumAndVertexVectorInXYPlane

cosine of the angle between momentum and vertex vector (vector connecting ip and fitted vertex) of this particle in xy-plane

cosTheta

momentum cosine of polar angle

cosThetaBetweenParticleAndNominalB

cosine of the angle in CMS between momentum the particle and a nominal B particle. It is somewhere between -1 and 1 if only a massless particle like a neutrino is missing in the reconstruction.

cosThetaErr

error of momentum cosine of polar angle

cosToThrustOfEvent

Returns the cosine of the angle between the particle and the thrust axis of the event, as calculate by the EventShapeCalculator module. buildEventShape() must be run before calling this variable

dM

mass minus nominal mass

dQ

released energy in decay minus nominal one

deltaE

energy difference

eRecoil

energy recoiling against given Particle

m2Recoil

invariant mass squared of the system recoiling against given Particle

m2RecoilSignalSide

Squared recoil mass of the signal side which is calculated in the CMS frame under the assumption that the signal and tag side are produced back to back and the tag side energy equals the beam energy. The variable must be applied to the Upsilon and the tag side must be the first, the signal side the second daughter

mRecoil

Invariant mass of the system recoiling against given Particle

momDevChi2

momentum deviation chi^2 value calculated aschi^2 = sum_i (p_i - mc(p_i))^2/sigma(p_i)^2, where sum runs over i = px, py, pz andmc(p_i) is the mc truth value and sigma(p_i) is the estimated error of i-th component of momentum vector

momVertCovM(i, j)

returns the (i,j)-th element of the MomentumVertex Covariance Matrix (7x7). Order of elements in the covariance matrix is: px, py, pz, E, x, y, z.

p

momentum magnitude

pErr

error of momentum magnitude

pRecoil

magnitude of 3 - momentum recoiling against given Particle

pRecoilPhi

Azimutal angle of a particle’s missing momentum

pRecoilTheta

Polar angle of a particle’s missing momentum

phi

momentum azimuthal angle in radians

phiErr

error of momentum azimuthal angle in radians

pt

transverse momentum

ptErr

error of transverse momentum

px

momentum component x

pxErr

error of momentum component x

pxRecoil

component x of 3-momentum recoiling against given Particle

py

momentum component y

pyErr

error of momentum component y

pyRecoil

component y of 3-momentum recoiling against given Particle

pz

momentum component z

pzErr

error of momentum component z

pzRecoil

component z of 3-momentum recoiling against given Particle

theta

polar angle in radians

thetaErr

error of polar angle in radians

xp

scaled momentum: the momentum of the particle in the CMS as a fraction of its maximum available momentum in the collision

Helicity

acoplanarityAngle

Acoplanarity angle (see Particle::getAcoplanarity) assuming a two body decay of the particle and its daughters. See PDG Polarization Review for the definition of the acoplanarity angle.

cosAcoplanarityAngle(i, j)

Cosine of the acoplanarity angle (\(\Phi\) in the PDG Polarization Review). Given a two-body decay, the acoplanarity angle is defined as the angle between the two decay planes in the reference frame of the mother.

We calculate the acoplanarity angle as the angle between the two normal vectors of the decay planes. Each normal vector is the cross product of the momentum of one daughter (in the frame of the mother) and the momentum of one of the granddaughters (in the reference frame of the daughter).

This variable needs two integer arguments: the first one, i is the index of the first granddaughter, and the second one, j the index of the second granddaughter.

For example, in the decay \(B^0 \to \left(J/\psi \to \mu^+ \mu^-\right) \left(K^{*0} \to K^+ \pi^-\right)\), if the provided particle is \(B^0\) and the selected indices are (0, 0), the variable will return the acoplanarity using the \(\mu^+\) and the \(K^+\) granddaughters.

cosHelicityAngle(i, j)

Cosine of the helicity angle between the momentum of the provided particle and the momentum of the selected granddaughter in the reference frame of the selected daughter (\(\theta_1\) and \(\theta_2\) in the PDG 2018, p. 722).

This variable needs two integer arguments: the first one, i, is the index of the daughter and the second one, j is the index of the granddaughter.

For example, in the decay \(B^0 \to \left(J/\psi \to \mu^+ \mu^-\right) \left(K^{*0} \to K^+ \pi^-\right)\), if the provided particle is \(B^0\) and the selected indices are (0, 0), the variable will return the angle between the momentum of the \(B^0\) and the momentum of the \(\mu^+\), both momenta in the rest frame of the \(J/\psi\).

This variable is needed for angular analyses of \(B\)-meson decays into two vector particles.

cosHelicityAngleBeamMomentum(i)

Cosine of the helicity angle of the \(i\)-th daughter of the particle provided, assuming that the mother of the provided particle corresponds to the centre-of-mass system, whose parameters are automatically loaded by the function, given the accelerator’s conditions.

cosHelicityAngleDaughter(i [, j])

Cosine of the helicity angle of the i-th daughter (see Particle::getCosHelicityDaughter). The optional second argument is the index of the granddaughter that defines the angle, default is 0.

For example, in the decay: \(B^0 \to \left(J/\psi \to \mu^+ \mu^-\right) \left(K^{*0} \to K^+ \pi^-\right)\), if the provided particle is \(B^0\) and the selected index is 0, the variable will return the helicity angle of the \(\mu^+\). If the selected index is 1 the variable will return the helicity angle of the \(K^+\) (defined via the rest frame of the \(K^{*0}\)). In rare cases if one wanted the helicity angle of the second granddaughter, indices 1,1 would return the helicity angle of the \(\pi^-\)).

See PDG Polarization Review for the definition of the helicity angle.

cosHelicityAngleMomentum

If the given particle has two daughters: cosine of the angle between the line defined by the momentum difference of the two daughters in the frame of the given particle (mother) and the momentum of the given particle in the lab frame.

If the given particle has three daughters: cosine of the angle between the normal vector of the plane defined by the momenta of the three daughters in the frame of the given particle (mother) and the momentum of the given particle in the lab frame.

Otherwise, it returns 0.

cosHelicityAngleMomentumPi0Dalitz

To be used for the decay \(\pi^0 \to e^+ e^- \gamma\): cosine of the angle between the momentum of the gamma in the frame of the given particle (mother) and the momentum of the given particle in the lab frame.

Otherwise, it returns 0.

cosHelicityAnglePrimary

Cosine of the helicity angle (see``Particle::getCosHelicity``) assuming the center of mass system as mother rest frame. See PDG Polarization Review for the definition of the helicity angle.

Tracking

Here is a list of track variables:

chi2

Chi2 of the track fit. Computed based on pValue and ndf. Note that for pValue exactly equal to 0 it returns infinity(). For mdst versions < 5.1, returns quiet_NaN().

d0

Signed distance to the POCA in the r-phi plane

d0Err

Error of signed distance to the POCA in the r-phi plane

d0Pull

mc-meas/err_meas for d0

firstCDCLayer

First activated CDC layer associated to the track

firstPXDLayer

First activated PXD layer associated to the track

firstSVDLayer

First activated SVD layer associated to the track

hasExtraCDCHitsInLayer(i)

[Eventbased] Returns 1 if a non-assigned hit exists in the specified CDC layer

hasExtraCDCHitsInSuperLayer(i)

[Eventbased] Returns 1 if a non-assigned hit exists in the specified CDC SuperLayer

helixExtPhi

Returns phi of extrapolated helix parameters (parameters (in cm): radius, z fwd, z bwd)

helixExtTheta

Returns theta of extrapolated helix parameters (parameters (in cm): radius, z fwd, z bwd)

lastCDCLayer

Last CDC layer associated to the track

nCDCHits

Number of CDC hits associated to the track

nExtraCDCHits

[Eventbased] The number of CDC hits in the event not assigned to any track

nExtraCDCHitsPostCleaning

[Eventbased] The number of CDC hits in the event not assigned to any track nor very likely beam background (i.e. hits that survive a cleanup selection)

nExtraCDCSegments

[Eventbased] The number of CDC segments not assigned to any track

nPXDHits

Number of PXD hits associated to the track

nSVDHits

Number of SVD hits associated to the track

nVXDHits

Number of PXD and SVD hits associated to the track

ndf

Number of degrees of freedom of the track fit. Note that it is not NHIT-5 due to outlier hit rejection. For mdst versions < 5.1, returns quiet_NaN().

omega

Curvature of the track

omegaErr

Error of curvature of the track

omegaPull

mc-meas/err_meas for omega

pValue

chi2 probalility of the track fit

phi0

Angle of the transverse momentum in the r-phi plane

phi0Err

Error of angle of the transverse momentum in the r-phi plane

phi0Pull

mc-meas/err_meas for phi0

tanLambdaPull

mc-meas/err_meas for tanLambda

tanlambda

Slope of the track in the r-z plane

tanlambdaErr

Error of slope of the track in the r-z plane

trackFindingFailureFlag

[Eventbased] A flag set by the tracking if there is reason to assume there was a track in the event missed by the tracking, or the track finding was (partly) aborted for this event.

trackFitHypothesisPDG

PDG code of the track hypothesis actually used for the fit

trackNECLClusters

Number ecl clusters matched to the track. This is always 0 or 1 with newer versions of ECL reconstruction.

z0

z coordinate of the POCA

z0Err

Error of z coordinate of the POCA

z0Pull

mc-meas/err_meas for z0

V0 Tracking

Here is a list of track variables for V0 daughters:

v0DaughterCov(i, j)

j-th element of the 15 covariance matrix elements (at IP perigee) of the i-th daughter track. (0,0), (0,1) … (1,1), (1,2) … (2,2) …

v0DaughterD0(i)

d0 of the i-th daughter track fit

v0DaughterD0Error(i)

d0 error of the i-th daughter track fit

v0DaughterD0PullWithOriginAsPivot(i)

d0 pull of the i-th daughter track with the origin as the track pivot

v0DaughterD0PullWithTrueVertexAsPivot(i)

d0 pull of the i-th daughter track with the true V0 vertex as the track pivot

v0DaughterFirstCDCLayer(i)

First activated CDC layer associated to the i-th daughter track

v0DaughterFirstPXDLayer(i)

First activated PXD layer associated to the i-th daughter track

v0DaughterFirstSVDLayer(i)

First activated SVD layer associated to the i-th daughter track

v0DaughterLastCDCLayer(i)

Last CDC layer associated to the i-th daughter track

v0DaughterNCDCHits(i)

Number of CDC hits associated to the i-th daughter track

v0DaughterNPXDHits(i)

Number of PXD hits associated to the i-th daughter track

v0DaughterNSVDHits(i)

Number of SVD hits associated to the i-th daughter track

v0DaughterNVXDHits(i)

Number of PXD+SVD hits associated to the i-th daughter track

v0DaughterOmega(i)

omega of the i-th daughter track fit

v0DaughterOmegaError(i)

omega error of the i-th daughter track fit

v0DaughterOmegaPullWithOriginAsPivot(i)

omega pull of the i-th daughter track with the origin as the track pivot

v0DaughterOmegaPullWithTrueVertexAsPivot(i)

omega pull of the i-th daughter track with the true V0 vertex as the track pivot

v0DaughterPValue(i)

chi2 probalility of the i-th daughter track fit

v0DaughterPhi0(i)

phi0 of the i-th daughter track fit

v0DaughterPhi0Error(i)

phi0 error of the i-th daughter track fit

v0DaughterPhi0PullWithOriginAsPivot(i)

phi0 pull of the i-th daughter track with the origin as the track pivot

v0DaughterPhi0PullWithTrueVertexAsPivot(i)

phi0 pull of the i-th daughter track with the true V0 vertex as the track pivot

v0DaughterTanLambda(i)

tan(lambda) of the i-th daughter track fit

v0DaughterTanLambdaError(i)

tan(lambda) error of the i-th daughter track fit

v0DaughterTanLambdaPullWithOriginAsPivot(i)

tan(lambda) pull of the i-th daughter track with the origin as the track pivot

v0DaughterTanLambdaPullWithTrueVertexAsPivot(i)

tan(lambda) pull of the i-th daughter track with the true V0 vertex as the track pivot

v0DaughterTau(i, j)

j-th track parameter (at IP perigee) of the i-th daughter track. j: 0:d0, 1:phi0, 2:omega, 3:z0, 4:tanLambda

v0DaughterZ0(i)

z0 of the i-th daughter track fit

v0DaughterZ0Error(i)

z0 error of the i-th daughter track fit

v0DaughterZ0PullWithOriginAsPivot(i)

z0 pull of the i-th daughter track with the origin as the track pivot

v0DaughterZ0PullWithTrueVertexAsPivot(i)

z0 pull of the i-th daughter track with the true V0 vertex as the track pivot

PID

Here is a list of particle identification variables:

Warning

The standard global and binary PID variables - namely electronID, pionID… binaryPID - currently use information from all detectors except for the SVD. This is because at the moment “physical” SVD \(dE/dx\) PDFs are available only for some particle hypotheses (\(\pi,K,p\)) but not for others (\(e,\mu,d\)), which could potentially bias the PID definition.

For hadronID only, a set of convenience variables have been defined that include the SVD:

• For global PID, \(\text{<Part>ID}=\mathcal{L}_{\text{<Part>}}/(\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p)\), where \(\text{<Part>}\in[\pi,K,p]\) : pionID_SVD, kaonID_SVD, protonID_SVD.

• For binary PID, \(\pi/K,\pi/p,K/p\) : binaryPID_SVD.

Note that in the above the particle hypotheses \(e,\mu,d\) have been excluded in the PID definition.

Please note, this distinction is meant to be only temporary: as soon as SVD PDFs are available for all particle hypotheses and thoroughly validated, the standard PID variables will include the SVD information back.

Warning

In release 5, a bug has been found in the TOP electron PDFs that degrades the electron identification performance. A set of two convenience PID variables where the TOP likelihoods are completely excluded - electronID_noTOP and binaryPID_noTOP - has been thus defined. These are expected to perform significantly better than the standard ones. Note that these are just temporary, and will be removed as soon as fixed TOP electron PDFs are available.

Warning

The definitions of the default PID variables have changed between release-01 and release-02.

Prior to release-02-00-00 (i.e. in release-01-XX-YY) each ID was calculated against the pion likelihood alone, or the kaon in the case of the pion itself. Namely the pair probability (also known as the binary probability) was returned:

• for all particles: \(\text{<Part>ID}=\mathcal{L}_{\text{<Part>}}/\mathcal{L}_\pi\), where \(\text{<Part>}\in[e,\mu,K,p,d]\).

• for pions: \(\text{PionID}=\mathcal{L}_\pi/\mathcal{L}_K\).

In other words, pionID was sensitive only to the pion-kaon mis-id, and not to the pion-proton or pion-muon mis-identification.

binaryPID(pdgCode1, pdgCode2)

Returns the binary probability for the first provided mass hypothesis with respect to the second mass hypothesis using all detector components, excluding the SVD

binaryPID_SVD(pdgCode1, pdgCode2)

Returns the binary probability for the first provided mass hypothesis with respect to the second mass hypothesis using all detector components, including the SVD. Accepted mass hypotheses are: 211 (\(\pi\)), 321 (\(K\)), 2212 (\(p\))

binaryPID_noTOP(pdgCode1, pdgCode2)

(SPECIAL (TEMP) variable) Returns the binary probability for the first provided mass hypothesis with respect to the second mass hypothesis using all detector components, excluding the SVD and the TOP. Note that either hypothesis in the pair must be of an electron.

deuteronID

deuteron identification probability defined as \(\mathcal{L}_d/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors, excluding the SVD

electronID

electron identification probability defined as \(\mathcal{L}_e/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors, excluding the SVD

electronID_noTOP

(SPECIAL (TEMP) variable) electron identification probability defined as \(\mathcal{L}_e/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors excluding the SVD and the TOP

kaonID

kaon identification probability defined as \(\mathcal{L}_K/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors, excluding the SVD

kaonID_SVD

kaon identification probability defined as \(\mathcal{L}_K/(\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p)\), using info from all available detectors, including the SVD

muonID

muon identification probability defined as \(\mathcal{L}_\mu/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors, excluding the SVD

particleID

the particle identification probability under the particle’s own hypothesis, using info from all available detectors, excluding the SVD

pionID

pion identification probability defined as \(\mathcal{L}_\pi/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors, excluding the SVD

pionID_SVD

pion identification probability defined as \(\mathcal{L}_\pi/(\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+)\), using info from all available detectors, including the SVD

protonID

proton identification probability defined as \(\mathcal{L}_p/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors, excluding the SVD

protonID_SVD

proton identification probability defined as \(\mathcal{L}_p/(\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p)\), using info from all available detectors, including the SVD

Basic particle information

charge

charge of particle

chiProb

A context-dependent \(\chi^2\) probability for ‘the fit’ related to this particle.

• If this particle is track-based, then this is the pvalue of the track fit (identical to pValue).

• If this particle is cluster-based then this variable is currently unused.

• If this particle is composite and a vertex fit has been performed, then this is the \(\chi^2\) probability of the vertex fit result.

Tip

If multiple vertex fits are performed then the last one sets the chiProb overwriting all previous.

See also

pValue for tracks

flavor

flavor type of decay(0 = unflavored, 1 = flavored)

isFromECL

Returns 1.0 if this particle was created from an ECLCluster, 0 otherwise.

isFromKLM

Returns 1.0 if this particle was created from a KLMCluster, 0 otherwise.

isFromTrack

Returns 1.0 if this particle was created from a track, 0 otherwise.

isFromV0

Returns 1.0 if this particle was created from a V0, 0 otherwise.

isUnspecified

returns 1 if the particle is marked as an unspecified object (like B0 -> @Xsd e+ e-), 0 if not

mdstIndex

Store array index (0 - based) of the MDST object from which the Particle was created. It’s 0 for composite particles.

Tip

It is not a unique identifier of particle. For example, a pion and a gamma can have the same mdstIndex: pions are created from tracks whereas gammas are created from ECL clusters; tracks and ECL clusters are stored in different arrays. A photon may be created from ECL cluster with index 0 and a pion may be created from track with index 0 will both have mdstIndex equal to 0, but they will be different particles.

Tip

Two particles of the same type can also have the same mdstIndex. This would mean that they are created from the same object. For example, if pion and kaon have the same mdstIndex it means that they are created from the same track.

Tip

If you are looking for unique identifier of the particle, please use uniqueParticleIdentifier.

nDaughters

number of daughter particles

particleSource

Returns mdst source used to create the particle. The meaning of the values are

• 0: undefined

• 1: created from track

• 2: created from ECL cluster

• 3: created from KLM cluster

• 4: created from V0

• 5: MC particle

• 6: composite particle

uniqueParticleIdentifier

Returns unique identifier of final state particle. Particles created from the same object (e.g. from the same track) have different uniqueParticleIdentifier value.

PID for expert

These expert-level variables are metavariable that allow the used to access the LogLikelihood values, the binary likelihood ratios and the global likelihood ratios for any arbitrary detector combination of mass hypothesis. The accepted detector codes are SVD, TOP, CDC, ARICH, ECL, KLM and ALL.

If a likelihood is not available from the selected detector list, NaN is returned.

Warning

These variables are not to be used in physics analyses, but only by experts doing performance studies.

pidChargedBDTScore(pdgCodeHyp, detector)

returns the charged Pid BDT score for a certain mass hypothesis with respect to all other charged stable particle hypotheses. The second argument specifies which BDT training to use: based on ‘ALL’ PID detectors (NB: ‘SVD’ is currently excluded), or ‘ECL’ only. The choice depends on the ChargedPidMVAMulticlassModule’s configuration.

pidDeltaLogLikelihoodValueExpert(pdgCode1, pdgCode2, detectorList)

returns LogL(hyp1) - LogL(hyp2) (aka DLL) for two mass hypoteses and a set of detectors.

pidIsMostLikely

Returns 1 if the PID likelihood for the particle given its PID is the largest one

pidLogLikelihoodValueExpert(pdgCode, detectorList)

returns the log likelihood value of for a specific mass hypothesis and set of detectors.

pidMissingProbabilityExpert(detectorList)

returns 1 if the PID probabiliy is missing for the provided detector list, otherwise 0.

pidMostLikelyPDG

Returns PDG code of the largest PID likelihood, or NaN if PID information is not available.

pidPairChargedBDTScore(pdgCodeHyp, pdgCodeTest, detector)

returns the charged Pid BDT score for a certain mass hypothesis with respect to an alternative hypothesis. The second argument specifies which BDT training to use: based on ‘ALL’ PID detectors (NB: ‘SVD’ is currently excluded), or ‘ECL’ only. The choice depends on the ChargedPidMVAModule’s configuration.

pidPairProbabilityExpert(pdgCodeHyp, pdgCodeTest, detectorList)

Pair (or binary) probability for the pdgCodeHyp mass hypothesis respect to the pdgCodeTest one, using an arbitrary set of detectors. \(\mathcal{L}_{hyp}/(\mathcal{L}_{test}+\mathcal{L}_{hyp}\)

pidProbabilityExpert(pdgCodeHyp, detectorList)

probability for the pdgCodeHyp mass hypothesis respect to all the other ones, using an arbitrary set of detectors \(\mathcal{L}_{hyp}/(\Sigma_{\text{all~hyp}}\mathcal{L}_{i}\).

ECL Cluster

Here is a list of variables related to ECL cluster. All ECLCluster-based variables return NaN if no ECLCluster is found.

Note

All floating type variables in the mdst dataobject ECLCluster use ROOT Double32_t types with specific range declaration to save disk storage. This has two important consequences for a user:

• All ECL cluster variables have a limited precision. This precision is always better than the intrinsic ECL data acquisition precision. However, if these variables are histogrammed, binning effects are likely.

• All ECL cluster variables are clipped at the lower and upper boundaries: Values below (above) these boundaries will be set to the lower (upper) bound.

Lower and upper limits, and precision of these variables are mentioned inside the note box below them. One should note this in the context of binning effects.

clusterAbsZernikeMoment40

Returns absolute value of Zernike moment 40 (\(|Z_{40}|\)). (shower shape variable).

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.7\)

Precision: \(10\) bit

clusterAbsZernikeMoment51

Returns absolute value of Zernike moment 51 (\(|Z_{51}|\)). (shower shape variable).

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.2\)

Precision: \(10\) bit

clusterCellID

Returns cellId of the crystal with highest energy in the ECLCluster.

clusterClusterID

Returns ECL cluster ID of this ECL cluster within the connected region (CR) to which it belongs to.

clusterConnectedRegionID

Returns ECL cluster’s connected region ID.

clusterDeltaLTemp

Returns DeltaL for the shower shape.

A cluster comprises the energy depositions of several crystals. All these crystals have slightly different orientations in space. A shower direction can be constructed by calculating the weighted average of these orientations using the corresponding energy depositions as weights. The intersection (more precisely the point of closest approach) of the vector with this direction originating from the cluster center and an extrapolated track can be used as reference for the calculation of the shower depth. It is defined as the distance between this intersection and the cluster center.

Warning

This distance is calculated on the reconstructed level and is temporarily included to the ECL cluster MDST data format for studying purposes. If it is found that it is not crucial for physics analysis then this variable will be removed in future releases. Therefore, keep in mind that this variable might be removed in the future!

Note

Please read this first.

Lower limit: \(-250.0\)

Upper limit: \(250.0\)

Precision: \(10\) bit

clusterE

Returns ECL cluster’s energy corrected for leakage and background.

The raw photon energy is given by the weighted sum of all ECL crystal energies within the ECL cluster. The weights per crystals are \(\leq 1\) after cluster energy splitting in the case of overlapping clusters. The number of crystals that are included in the sum depends on a initial energy estimation and local beam background levels at the highest energy crystal position. It is optimized to minimize the core width (resolution) of true photons. Photon energy distributions always show a low energy tail due to unavoidable longitudinal and transverse leakage that can be further modified by the clustering algorithm and beam backgrounds.The peak position of the photon energy distributions are corrected to match the true photon energy in MC:

• Leakage correction: Using large MC samples of mono-energetic single photons, a correction factor \(f\) as function of reconstructed detector position, reconstructed photon energy and beam backgrounds is determined via \(f = \frac{\text{peak_reconstructed}}{\text{energy_true}}\).

• Cluster energy calibration (data only): To reach the target precision of \(< 1.8\%\) energy resolution for high energetic photons, the remaining difference between MC and data must be calibrated using kinematically fit muon pairs. This calibration is only applied to data and not to MC and will take time to develop.

It is important to note that after perfect leakage correction and cluster energy calibration, the \(\pi^{0}\) mass peak will be shifted slightly to smaller values than the PDG average due to the low energy tails of photons. The \(\pi^{0}\) mass peak must not be corrected to the PDG value by adjusting the reconstructed photon energies. Selection criteria based on the mass for \(\pi^{0}\) candidates must be based on the biased value. Most analysis will used mass constrained \(\pi^{0}\) s anyhow.

Warning

We only store clusters with \(E > 20\,\) MeV.

Note

Please read this first.

Lower limit: \(-5\) (\(e^{-5} = 0.00674\,\) GeV)

Upper limit: \(3.0\) (\(e^3 = 20.08553\,\) GeV)

Precision: \(18\) bit

This value can be changed to a different reference frame with useCMSFrame.

clusterE1E9

Returns ratio of energies of the central crystal, E1, and 3x3 crystals, E9, around the central crystal. Since \(E1 \leq E9\), this ratio is \(\leq 1\) and tends towards larger values for photons and smaller values for hadrons.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.0\)

Precision: \(10\) bit

clusterE9E21

Returns ratio of energies in inner 3x3 crystals, E9, and 5x5 crystals around the central crystal without corners. Since \(E9 \leq E21\), this ratio is \(\leq 1\) and tends towards larger values for photons and smaller values for hadrons.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.0\)

Precision: \(10\) bit

clusterE9E25

Deprecated - kept for backwards compatibility - returns clusterE9E21.

clusterEoP

Returns ratio of uncorrelated energy E over momentum p, a convenience alias for (clusterE / p).

clusterErrorE

Returns ECL cluster’s uncertainty on energy (from background level and energy dependent tabulation).

clusterErrorPhi

Returns ECL cluster’s uncertainty on \(\phi\) (from background level and energy dependent tabulation).

clusterErrorTheta

Returns ECL cluster’s uncertainty on \(\theta\) (from background level and energy dependent tabulation).

clusterErrorTiming

Returns ECL cluster’s timing uncertainty that contains \(99\%\) of true photons (dt99).

The photon timing uncertainty is currently determined using MC. The resulting parametrization depends on the true energy deposition in the highest energetic crystal and the local beam background level in that crystal. The resulting timing distribution is non-Gaussian and for each photon the value dt99 is stored, where \(|\text{timing}| / \text{dt99} < 1\) is designed to give a \(99\%\) timing efficiency for true photons from the IP. The resulting efficiency is approximately flat in energy and independent of beam background levels.

Very large values of dt99 are an indication of failed waveform fits in the ECL. We remove such clusters in most physics photon lists.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1000.0\)

Precision: \(12\) bit

Warning

In real data there will be a sizeable number of high energetic Bhabha events (from previous or later bunch collisions) that can easily be rejected by timing cuts. However, these events create large ECL clusters that can overlap with other ECL clusters and it is not clear that a simple rejection is the correction strategy.

clusterHasFailedErrorTiming

Status bit for if the ECL cluster’s timing uncertainty calculation failed. Photon timing is given by the fitted time of the recorded waveform of the highest energetic crystal in a cluster; however, that fit can fail and so this variable tells the user if that has happened.

clusterHasFailedTiming

Status bit for if the ECL cluster’s timing fit failed. Photon timing is given by the fitted time of the recorded waveform of the highest energetic crystal in a cluster; however, that fit can fail and so this variable tells the user if that has happened.

clusterHasNPhotons

Returns 1.0 if cluster has the ‘N photons’ hypothesis (historically called ‘N1’), 0.0 if not, and NaN if no cluster is associated to the particle.

clusterHasNeutralHadron

Returns 1.0 if the cluster has the ‘neutral hadrons’ hypothesis (historically called ‘N2’), 0.0 if not, and NaN if no cluster is associated to the particle.

clusterHasPulseShapeDiscrimination

Status bit to indicate if cluster has digits with waveforms that passed energy and \(\chi^2\) thresholds for computing PSD variables.

clusterHighestE

Returns energy of the highest energetic crystal in the ECL cluster after reweighting.

Warning

This variable must be used carefully since it can bias shower selection towards photons that hit crystals in the center and hence have a large energy deposition in the highest energy crystal.

Note

Please read this first.

Lower limit: \(-5\) (\(e^{-5} = 0.00674\,\) GeV)

Upper limit: \(3.0\) (\(e^3 = 20.08553\,\) GeV)

Precision: \(18\) bit

clusterLAT

Returns lateral energy distribution (shower variable). It is defined as following:

\[S = \frac{\sum_{i=2}^{n} w_{i} E_{i} r^2_{i}}{(w_{0} E_{0} + w_{1} E_{1}) r^2_{0} + \sum_{i=2}^{n} w_{i} E_{i} r^2_{i}}\]

where \(E_{i} = (E_{0}, E_{1}, ...)\) are the single crystal energies sorted by energy (\(E_{0}\) is the highest energy and \(E_{1}\) the second highest), \(w_{i}\) is the crystal weight, \(r_{i}\) is the distance of the \(i\)-th digit to the shower center projected to a plane perpendicular to the shower axis, and \(r_{0} \approx 5\,cm\) is the distance between two crystals.

clusterLAT peaks around 0.3 for radially symmetrical electromagnetic showers and is larger for hadronic events, and electrons with a close-by radiative or Bremsstrahlung photon.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.0\)

Precision: \(10\) bit

clusterMdstIndex

StoreArray index(0 - based) of the MDST ECLCluster (useful for track-based particles matched to a cluster).

clusterNHits

Returns sum of weights \(w_{i}\) (\(w_{i} \leq 1\)) of all crystals in an ECL cluster. For non-overlapping clusters this is equal to the number of crystals in the cluster. In case of energy splitting among nearby clusters, this can be a non-integer value.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(200.0\)

Precision: \(10\) bit

If fractional weights are not of interest, this value should be cast to the nearest integer.

clusterNumberOfHadronDigits

Returns ECL cluster’s number of hadron digits in cluster (pulse shape discrimination variable). Weighted sum of digits in cluster with significant scintillation emission (\(> 3\,\) MeV) in the hadronic scintillation component. Computed only using cluster digits with energy \(> 50\,\) MeV and good offline waveform fit \(\chi^2\).

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(255.0\)

Precision: \(18\) bit

clusterPhi

Returns ECL cluster’s azimuthal angle \(\phi\) (this is not generally equal to a photon azimuthal angle).

The direction of a cluster is given by the connecting line of \(\,(0,0,0)\,\) and cluster centroid position in the ECL.

The cluster centroid position is calculated using up to 21 crystals (5x5 excluding corners) after cluster energy splitting in the case of overlapping clusters.

The centroid position is the logarithmically weighted average of all crystals evaluated at the crystal centers. Cluster centroids are generally biased towards the centers of the highest energetic crystal. This effect is larger for low energetic photons.

Beam backgrounds slightly decrease the position resolution, mainly for low energetic photons.

Note

Radius of a cluster is almost constant in the barrel and should not be used directly in any selection.

Unlike for charged tracks, the uncertainty (covariance) of the photon directions is not determined based on individual cluster properties but taken from on MC-based parametrizations of the resolution as function of true photon energy, true photon direction and beam background level.

Warning

Users must use the actual particle direction (done automatically in the modularAnalysis using the average IP position (can be changed if needed)) and not the ECL Cluster direction (position in the ECL measured from \((0,0,0)\)) for particle kinematics.

Note

Please read this first.

Lower limit: \(-\pi\)

Upper limit: \(\pi\)

Precision: \(16\) bit

clusterPulseShapeDiscriminationMVA

Returns MVA classifier that uses pulse shape discrimination to identify electromagnetic vs hadronic showers.

• 1 for electromagnetic showers

• 0 for hadronic showers

clusterR

Returns ECL cluster’s centroid distance from \((0,0,0)\).

clusterReg

Returns an integer code for the ECL region of a cluster.

• 1: forward, 2: barrel, 3: backward,

• 11: between FWD and barrel, 13: between BWD and barrel,

• 0: otherwise

clusterSecondMoment

Returns second moment \(S\). It is defined as:

\[S = \frac{\sum_{i=0}^{n} w_{i} E_{i} r^2_{i}}{\sum_{i=0}^{n} w_{i} E_{i}}\]

where \(E_{i} = (E_0, E_1, ...)\) are the single crystal energies sorted by energy, \(w_{i}\) is the crystal weight, and \(r_{i}\) is the distance of the \(i\)-th digit to the shower center projected to a plane perpendicular to the shower axis.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(40.0\)

Precision: \(10\) bit

clusterTheta

Returns ECL cluster’s polar angle \(\theta\) (this is not generally equal to a photon polar angle).

The direction of a cluster is given by the connecting line of \(\,(0,0,0)\,\) and cluster centroid position in the ECL.

The cluster centroid position is calculated using up to 21 crystals (5x5 excluding corners) after cluster energy splitting in the case of overlapping clusters.

The centroid position is the logarithmically weighted average of all crystals evaluated at the crystal centers. Cluster centroids are generally biased towards the centers of the highest energetic crystal. This effect is larger for low energetic photons.

Beam backgrounds slightly decrease the position resolution, mainly for low energetic photons.

Note

Radius of a cluster is almost constant in the barrel and should not be used directly in any selection.

Unlike for charged tracks, the uncertainty (covariance) of the photon directions is not determined based on individual cluster properties but taken from on MC-based parametrizations of the resolution as function of true photon energy, true photon direction and beam background level.

Warning

Users must use the actual particle direction (done automatically in the modularAnalysis using the average IP position (can be changed if needed)) and not the ECL Cluster direction (position in the ECL measured from \((0,0,0)\)) for particle kinematics.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(\pi\)

Precision: \(16\) bit

clusterTiming

Returns the time of the ECL cluster. It is calculated as the Photon timing minus the Event t0. Photon timing is given by the fitted time of the recorded waveform of the highest energy crystal in the cluster. After all calibrations and corrections (including Time-Of-Flight), photons from the interaction point (IP) should have a Photon timing that corresponds to the Event t0, \(t_{0}\). The Event t0 is the time of the event and may be measured by a different sub-detector (see Event t0 documentation). For an ECL cluster produced at the interation point in time with the event, the cluster time should be consistent with zero within the uncertainties. Special values are returned if the fit for the Photon timing fails (see documentation for clusterHasFailedTiming). (For MC, the calibrations and corrections are not fully simulated).

Note

Please read this first.

Lower limit: \(-1000.0\)

Upper limit: \(1000.0\)

Precision: \(12\) bit

clusterTrackMatch

Returns 1.0 if at least one reconstructed charged track is matched to the ECL cluster.

Every reconstructed charged track is extrapolated into the ECL. Every ECL crystal that is crossed by the track extrapolation is marked. Each ECL cluster that contains any marked crystal is matched to the track. Multiple tracks can be matched to one cluster and multiple clusters can be matched to one track. It is conceptually correct to have two tracks matched to the same cluster.

clusterZernikeMVA

Returns output of a MVA using eleven Zernike moments of the cluster. Zernike moments are calculated per shower in a plane perpendicular to the shower direction via

\[|Z_{nm}| = \frac{n+1}{\pi} \frac{1}{\sum_{i} w_{i} E_{i}} \left|\sum_{i} R_{nm}(\rho_{i}) e^{-im\alpha_{i}} w_{i} E_{i} \right|\]

where n, m are the integers, \(i\) runs over the crystals in the shower, \(E_{i}\) is the energy of the i-th crystal in the shower, \(R_{nm}\) is a polynomial of degree \(n\), \(\rho_{i}\) is the radial distance of the \(i\)-th crystal in the perpendicular plane, and \(\alpha_{i}\) is the polar angle of the \(i\)-th crystal in the perpendicular plane. As a crystal can be related to more than one shower, \(w_{i}\) is the fraction of the energy of the \(i\)-th crystal associated with the shower.

More details about the implementation can be found in BELLE2-NOTE-TE-2017-001 .

More details about Zernike polynomials can be found in Wikipedia .

For cluster with hypothesisId==N1: raw MVA output.

For cluster with hypothesisId==N2: 1 - prod{clusterZernikeMVA}, where the product is on all N1 showers belonging to the same connected region (shower shape variable).

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.0\)

Precision: \(10\) bit

eclClusterOnlyInvariantMass

[Expert] The invariant mass calculated from all ECLCluster daughters (i.e. photons) and cluster-matched tracks using the cluster 4-momenta.

Used for ECL-based dark sector physics and debugging track-cluster matching.

eclExtPhi

Returns extrapolated \(\phi\).

eclExtPhiId

Returns extrapolated \(\phi\) ID.

eclExtTheta

Returns extrapolated \(\theta\).

maxWeightedDistanceFromAverageECLTime

Returns maximum weighted distance between time of the cluster of a photon and the ECL average time, amongst the clusters (neutrals) and matched clusters (charged) of daughters (of all generations) of the provided particle.

minC2TDist

Returns distance between ECL cluster and nearest track hitting the ECL.

A cluster comprises the energy depositions of several crystals. All these crystals have slightly different orientations in space. A shower direction can be constructed by calculating the weighted average of these orientations using the corresponding energy depositions as weights. The intersection (more precisely the point of closest approach) of the vector with this direction originating from the cluster center and an extrapolated track can be used as reference for the calculation of the track depth. It is defined as the distance between this intersection and the track hit position on the front face of the ECL.

Note

This distance is calculated on the reconstructed level.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(250.0\)

Precision: \(10\) bit

nECLClusterTrackMatches

Returns number of charged tracks matched to this cluster.

Note

Sometimes (perfectly correctly) two tracks are extrapolated into the same cluster.

• For charged particles, this should return at least 1 (but sometimes 2 or more).

• For neutrals, this should always return 0.

• Returns NaN if there is no cluster.

nECLOutOfTimeCrystals

[Eventbased] Returns the number of crystals (ECLCalDigits) that are out of time.

nECLOutOfTimeCrystalsBWDEndcap

[Eventbased] Returns the number of crystals (ECLCalDigits) that are out of time in the backward endcap.

nECLOutOfTimeCrystalsBarrel

[Eventbased] Returns the number of crystals (ECLCalDigits) that are out of time in the barrel.

nECLOutOfTimeCrystalsFWDEndcap

[Eventbased] Returns the number of crystals (ECLCalDigits) that are out of time in the forward endcap.

nRejectedECLShowers

[Eventbased] Returns the number of showers in the ECL that do not become clusters.

nRejectedECLShowersBWDEndcap

[Eventbased] Returns the number of showers in the ECL that do not become clusters, from the backward endcap.

nRejectedECLShowersBarrel

[Eventbased] Returns the number of showers in the ECL that do not become clusters, from the barrel.

nRejectedECLShowersFWDEndcap

[Eventbased] Returns the number of showers in the ECL that do not become clusters, from the forward endcap.

weightedAverageECLTime

Returns ECL weighted average time of all clusters (neutrals) and matched clusters (charged) of daughters (of any generation) of the provided particle.

There are also some special variables related to the MC matching of ECL clusters (specifically).

clusterBestMCMatchWeight

returns the weight of the ECLCluster -> MCParticle relation for the relation with the largest weight.

clusterBestMCPDG

returns the PDG code of the MCParticle for the ECLCluster -> MCParticle relation with the largest weight.

clusterMCMatchWeight

Returns the weight of the ECLCluster -> MCParticle relation for the MCParticle matched to the particle. Returns NaN if: no cluster is related to the particle, the particle is not MC matched, or if there are no mcmatches for the cluster. Returns -1 if the cluster was matched to particles, but not the match of the particle provided.

isMC

[Eventbased] Returns 1 if run on MC and 0 for data.

Acceptance

Here is a list of variables for acceptance cuts:

inARICHAcceptance

Particle is within ARICH geometrical acceptance.

inCDCAcceptance

Particle is within CDC geometrical acceptance.

inECLAcceptance

Particle is within ECL geometrical acceptance.

inKLMAcceptance

Particle is within KLM geometrical acceptance.

inTOPAcceptance

Particle is within TOP geometrical acceptance.

ptInBECLAcceptance

Particle is within Barrel ECL transverse momentum acceptance.

ptInBKLMAcceptance

Particle is within Barrel KLM transverse momentum acceptance.

ptInTOPAcceptance

Particle is within TOP transverse momentum acceptance.

thetaInARICHAcceptance

Particle is within ARICH angular acceptance.

thetaInBECLAcceptance

Particle is within Barrel ECL angular acceptance.

thetaInBKLMAcceptance

Particle is within Barrel KLM angular acceptance.

thetaInCDCAcceptance

Particle is within CDC angular acceptance.

thetaInECLAcceptance

Particle is within ECL angular acceptance. 1: Forward; 2: Barrel; 3: Backwards.

thetaInEECLAcceptance

Particle is within Endcap ECL angular acceptance.

thetaInEKLMAcceptance

Particle is within Endcap KLM angular acceptance.

thetaInKLMAcceptance

Particle is within KLM angular acceptance. 1: Forward endcap; 2: Forward overalp; 3: Barrel; 4: Backward overlap; 5: Backward endcap.

thetaInKLMOverlapAcceptance

Particle is within the angular region where KLM barrel and endcaps overlap.

thetaInTOPAcceptance

Particle is within TOP angular acceptance.

Trigger

Here is a list of trigger variables:

L1FTDL(name)

[Eventbased] Returns the FTDL (Final Trigger Decision Logic, before prescale) status of the trigger bit with the given name.

L1FTDLBit(i)

[Eventbased] Returns the FTDL (Final Trigger Decision Logic, before prescale) status of i-th trigger bit.

L1Input(name)

[Eventbased] Returns the input bit status of the trigger bit with the given name.

L1InputBit(i)

[Eventbased] Returns the input bit status of the i-th input trigger bit.

L1PSNM(name)

[Eventbased] Returns the PSNM (Prescale And Mask, after prescale) status of the trigger bit with the given name.

L1PSNMBit(i)

[Eventbased] Returns the PSNM (Prescale And Mask, after prescale) status of i-th trigger bit.

L1PSNMBitPrescale(i)

[Eventbased] Returns the PSNM (prescale and mask) prescale of i-th trigger bit.

L1Prescale(name)

[Eventbased] Returns the PSNM (prescale and mask) prescale of the trigger bit with the given name.

L1TimType

[Eventbased] Returns ETimingType time type.

L1Trigger

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

HighLevelTrigger

[Eventbased] 1.0 if event passes the HLT trigger, 0.0 if not

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!

SoftwareTriggerResult(triggerIdentifier)

[Eventbased] [Expert] returns the SoftwareTriggerCutResult, 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.

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.

Event

Here is a list of event variables:

Ecms

[Eventbased] CMS energy

EventType

[Eventbased] EventType (0 MC, 1 Data)

IPCov(i, j)

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

IPX

[Eventbased] x coordinate of the measured interaction point.

Note

For old data and uncalibrated MC files this will return 0.0.

Note

You might hear tracking and calibration people refer to this as the BeamSpot.

IPY

[Eventbased] y coordinate of the measured interaction point

IPZ

[Eventbased] z coordinate of the measured interaction point

beamE

[Eventbased] Beam energy (lab)

beamPx

[Eventbased] Beam momentum Px (lab)

beamPy

[Eventbased] Beam momentum Py (lab)

beamPz

[Eventbased] Beam momentum Pz (lab)

belleECLEnergy

[Eventbased] legacy total energy in ECL in the event as used in Belle 1 analyses. For Belle II consider totalEnergyOfParticlesInList(gamma:all) instead

date

[Eventbased] Returns the date when the event was recorded, a number of the form YYYYMMDD (in UTC).

See also eventYear, provided for convenience. For more precise eventTime, see eventTimeSeconds and eventTimeSecondsFractionRemainder.

eventTimeSeconds

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

eventTimeSecondsFractionRemainder

[Eventbased] Remainder of the event time in fractions of a second. Use eventTimeSeconds + eventTimeSecondsFractionRemainder to get the total event time in seconds.

evtNum

[Eventbased] event number

expNum

[Eventbased] experiment number

isChargedBEvent

[Eventbased] true if event contains a charged B-meson

isContinuumEvent

[Eventbased] true if event doesn’t contain an Y(4S)

isNotContinuumEvent

[Eventbased] 1.0 if event does contain an Y(4S) and therefore is not a continuum Event

isUnmixedBEvent

[Eventbased] true if event contains opposite flavor neutral B-mesons, false in case of same flavor B-mesons and NaN if an event has no generated neutral B

nChargeZeroTrackFits

[Eventbased] number of track fits with a zero charge.Sometimes this can happen if background or non IP originating tracks (for example) are fit from the IP. These tracks are removed from particle lists but a large number charge zero fits them may indicate problems with whole event constraints or abnominally high beam backgrounds and/or noisy events.

nKLMClusters

[Eventbased] number of KLM in the event

nMCParticles

[Eventbased] number of MCParticles in the event

nTracks

[Eventbased] number of tracks in the event

productionIdentifier

[Eventbased] production identifier

runNum

[Eventbased] run number

year

[Eventbased] Returns the year when the event was recorded (in UTC). For more precise eventTime, see eventTimeSeconds and eventTimeSecondsFractionRemainder.

Parameter Functions

Here is a list of variables that require a parameter:

NumberOfMCParticlesInEvent(pdgcode)

Returns number of MC Particles (including anti-particles) with the given pdgcode in the event.

Used in the FEI to determine to calculate reconstruction efficiencies.

The variable is event-based and does not need a valid particle pointer as input.

V0Deltad0

Return the difference between d0 impact parameters of V0’s daughters with the V0 vertex point as a pivot for the track.

V0Deltaz0

Return the difference between z0 impact parameters of V0’s daughters with the V0 vertex point as a pivot for the track.

V0d0(id)

Return the d0 impact parameter of a V0’s daughter with daughterID index with the V0 vertex point as a pivot for the track.

V0z0(id)

Return the z0 impact parameter of a V0’s daughter with daughterID index with the V0 vertex point as a pivot for the track.

azimuthalAngleInDecayPlane(i, j)

Azimuthal angle of i-th daughter in decay plane towards projection of particle momentum into decay plane.

First we define the following symbols:

• P: four-momentum vector of decaying particle in whose decay plane the azimuthal angle is measured

• M: “mother” of p, however not necessarily the direct mother but any higher state, here the CMS itself is chosen

• D1: daughter for which the azimuthal angle is supposed to be calculated

• D2: another daughter needed to span the decay plane

• L: normal to the decay plane (four-component vector)

L can be defined via the following relation:

\[L^{\sigma} = \delta^{\sigma\nu} \epsilon_{\mu\nu\alpha\beta} P^{\mu}D1^{\alpha}D2^{\beta}\]

The azimuthal angle is given by

\[\phi \equiv \cos^{-1} \left(\frac{-\vec{M_{\parallel}} \cdot \vec{D1}}{|\vec{M_{\parallel}}| \cdot |\vec{D1}|}\right)\]

For a frame independent formulation the three component vectors need to be written via invariant four-momentum vectors.

\[\begin{split}-\vec{M_{\parallel}} \cdot \vec{D1} &= \biggl[M - \frac{(M \cdot L)L}{L^2}\biggr] \cdot D1 - \frac{(M \cdot P)(D1 \cdot P)}{m^2_P}\\ |\vec{M_{\parallel}}| &= |\vec{M}| \sqrt{1 - \cos^2 \psi}\\ |\vec{M}| &= \sqrt{\frac{(M \cdot P)^2}{m^2_P} - m^2_M}\\ \cos \psi &= \frac{\vec{M} \cdot \vec{L}}{|\vec{M}| \cdot |\vec{L}|} = \frac{-M \cdot L}{|\vec{M}| \cdot \sqrt{-L^2}}\\ |\vec{D1}| &= \sqrt{\frac{(D1 \cdot P)^2}{m^2_P} - m^2_{D1}}\end{split}\]

constant(float i)

Returns i.

Useful for debugging purposes and in conjunction with the formula meta-variable.

daughterInvariantMass(i, j, ...)

Returns invariant mass of the given daughter particles. E.g.:

• daughterInvariantMass(0, 1) returns the invariant mass of the first and second daughter.

• daughterInvariantMass(0, 1, 2) returns the invariant mass of the first, second and third daughter.

Useful to identify intermediate resonances in a decay, which weren’t reconstructed explicitly.

Returns NaN if particle is nullptr or if the given daughter-index is out of bound (>= amount of daughters).

daughterMCInvariantMass(i, j, ...)

Returns true invariant mass of the given daughter particles, same behaviour as daughterInvariantMass variable.

decayAngle(i)

Angle in the mother’s rest frame between the reverted CMS momentum vector and the direction of the i-th daughter

hasAncestor(PDG, abs)

Returns a positive integer if an ancestor with the given PDG code is found, 0 otherwise.

The integer is the level where the ancestor was found, 1: first mother, 2: grandmother, etc.

Second argument is optional, 1 means that the sign of the PDG code is taken into account, default is 0.

If there is no MC relations found, -1 is returned. In case of nullptr particle, NaN is returned.

isAncestorOf(i, j, ...)

Returns a positive integer if daughter at position particle->daughter(i)->daughter(j)… is an ancestor of the related MC particle, 0 otherwise.

Positive integer represents the number of steps needed to get from final MC daughter to ancestor. If any particle or MCparticle is a nullptr, NaN is returned. If MC relations of any particle doesn’t exist, -1.0 is returned.

massDifference(i)

Difference in invariant masses of this particle and its i-th daughter

massDifferenceError(i)

Estimated uncertainty on difference in invariant masses of this particle and its i-th daughter

massDifferenceSignificance(i)

Signed significance of the deviation from the nominal mass difference of this particle and its i-th daughter [(massDiff - NOMINAL_MASS_DIFF)/ErrMassDiff]

pointingAngle(i)

Angle between i-th daughter’s momentum vector and vector connecting production and decay vertex of i-th daughter. This makes only sense if the i-th daughter has itself daughter particles and therefore a properly defined vertex.

randomChoice(i, j, ...)

Returns random element of given numbers.

Useful for testing purposes.

Meta Functions

Here is a list of variables that returns extra info of a given particle:

abs(variable)

Returns absolute value of the given variable. E.g. abs(mcPDG) returns the absolute value of the mcPDG, which is often useful for cuts.

acos(variable)

Returns arccosine value of the given variable.

angleToClosestInList(particleListName)

Returns the angle between this particle and the closest particle (smallest opening angle) in the list provided.

angleToMostB2BInList(particleListName)

Returns the angle between this particle and the most back-to-back particle (closest opening angle to 180) in the list provided.

averageValueInList(particleListName, variable)

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

closestInList(particleListName, variable)

Returns variable for the closest particle (smallest opening angle) in the list provided.

conditionalVariableSelector(cut, variableIfTrue, variableIfFalse)

Returns one of the two supplied variables, depending on whether the particle passes the supplied cut. The first variable is returned if the particle passes the cut, and the second variable is returned otherwise.

cos(variable)

Returns cosine value of the given variable.

countDaughters(cut)

Returns number of direct daughters which satisfy the cut. Used by the skimming package (for what exactly?) Returns NaN if particle is a nullptr.

countInList(particleList, cut='')

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.

daughter(i, variable)

Returns value of variable for the i-th daughter. E.g.

• daughter(0, p) returns the total momentum of the first daughter.

• daughter(0, daughter(1, p) returns the total momentum of the second daughter of the first daughter.

Returns NaN if particle is nullptr or if the given daughter-index is out of bound (>= amount of daughters).

daughterAngle(daughterIndex_1, daughterIndex_2[, daughterIndex_3])

Returns the angle in between any pair of particles belonging to the same decay tree.

The particles are identified via generalized daughter indexes, which are simply colon-separated lists of daughter indexes, ordered starting from the root particle. For example, 0:1:3 identifies the fourth daughter (3) of the second daughter (1) of the first daughter (0) of the mother particle. 1 simply identifies the second daughter of the root particle.

Both two and three generalized indexes can be given to daughterAngle. If two indices are given, the variable returns the angle between the momenta of the two given particles. If three indices are given, the variable returns the angle between the momentum of the third particle and a vector which is the sum of the first two daughter momenta.

Tip

daughterAngle(0, 3) will return the angle between the first and fourth daughter. daughterAngle(0, 1, 3) will return the angle between the fourth daughter and the sum of the first and second daughter. daughterAngle(0:0, 3:0) will return the angle between the first daughter of the first daughter, and the first daughter of the fourth daughter.

daughterClusterAngleInBetween(i, j)

Returns function which returns the angle between clusters associated to the two daughters.If two indices given: returns the angle between the momenta of the clusters associated to the two given daughters.If three indices given: returns the angle between the momentum of the third particle’s cluster and a vector which is the sum of the first two daughter’s cluster momenta.Returns nan if any of the daughters specified don’t have an associated cluster.The arguments in the argument vector must be integers corresponding to the ith and jth (and kth) daughters.

daughterCombination(variable, daughterIndex_1, daughterIndex_2 ... daughterIndex_n)

Returns a variable function only of the 4-momentum calculated on an arbitrary set of (grand)daughters.

Warning

variable can only be a function of the daughters’ 4-momenta.

Daughters from different generations of the decay tree can be combined using generalized daughter indexes, which are simply colon-separated the list of daughter indexes, starting from the root particle: for example, 0:1:3 identifies the fourth daughter (3) of the second daughter (1) of the first daughter (0) of the mother particle.

Tip

daughterCombination(M, 0, 3, 4) will return the invariant mass of the system made of the first, fourth and fifth daughter of particle. daughterCombination(M, 0:0, 3:0) will return the invariant mass of the system made of the first daughter of the first daughter and the first daughter of the fourth daughter.

daughterDiffOf(i, j, variable)

Returns the difference of a variable between the two given daughters. E.g. useRestFrame(daughterDiffOf(0, 1, p)) returns the momentum difference between first and second daughter in the rest frame of the given particle. (That means that it returns \(p_j - p_i\)) Nota Bene: for the particular case ‘variable=phi’ you should use the daughterDiffOfPhi function.

daughterDiffOfClusterPhi(i, j)

Returns the difference in \(\phi\) between the ECLClusters of two given daughters. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\). The function returns NaN if at least one of the daughters is not matched to or not based on an ECLCluster. For a generic variable difference, see daughterDiffOf.

daughterDiffOfClusterPhiCMS(i, j)

Returns the difference in \(\phi\) between the ECLClusters of two given daughters in the CMS frame. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\). The function returns NaN if at least one of the daughters is not matched to or not based on an ECLCluster. For a generic variable difference, see daughterDiffOf.

daughterDiffOfPhi(i, j)

Returns the difference in \(\phi\) between the two given daughters. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\). For a generic variable difference, see daughterDiffOf.

daughterDiffOfPhiCMS(i, j)

Returns the difference in \(\phi\) between the two given daughters in the CMS frame. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\). For a generic variable difference, see daughterDiffOf.

daughterHighest(variable)

Returns the highest value of the given variable among all daughters. E.g. useCMSFrame(daughterHighest(p)) returns the highest momentum in CMS frame.

daughterInvM(i, j)

Returns the invariant Mass adding the Lorentz vectors of the given daughters. E.g. daughterInvM(0, 1, 2) returns the invariant Mass \(m = \sqrt{(p_0 + p_1 + p_2)^2}\) of first, second and third daughter.

daughterLowest(variable)

Returns the lowest value of the given variable among all daughters. E.g. useCMSFrame(daughterLowest(p)) returns the lowest momentum in CMS frame.

daughterMotherDiffOf(i, variable)

Returns the difference of a variable between the given daughter and the mother particle itself. E.g. useRestFrame(daughterMotherDiffOf(0, p)) returns the momentum difference between the given particle and its first daughter in the rest frame of the mother.

daughterMotherNormDiffOf(i, variable)

Returns the normalized difference of a variable between the given daughter and the mother particle itself. E.g. daughterMotherNormDiffOf(1, p) returns the normalized momentum difference between the given particle and its second daughter in the lab frame.

daughterNormDiffOf(i, j, variable)

Returns the normalized difference of a variable between the two given daughters. E.g. daughterNormDiffOf(0, 1, p) returns the normalized momentum difference between first and second daughter in the lab frame.

daughterProductOf(variable)

Returns product of a variable over all daughters. E.g. daughterProductOf(extraInfo(SignalProbability)) returns the product of the SignalProbabilitys of all daughters.

daughterSumOf(variable)

Returns sum of a variable over all daughters. E.g. daughterSumOf(nDaughters) returns the number of grand-daughters.

eclClusterSpecialTrackMatched(cut)

Returns if at least one Track that satisfies the given condition is related to the ECLCluster of the Particle.

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

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.

exp(variable)

Returns exponential evaluated for the given variable.

extraInfo(name)

Returns extra info stored under the given name. The extraInfo has to be set by a module first. E.g. extraInfo(SignalProbability) returns the SignalProbability calculated by the MVAExpert module. If nothing is set under the given name or if the particle is a nullptr, NaN is returned. In the latter case please use eventExtraInfo if you want to access an EventExtraInfo variable.

formula(v1 + v2 * [v3 - v4] / v5^v6)

Returns the result of the given formula, where v1 to vN are variables or floating point numbers. Currently the only supported operations are addition (+), subtraction (-), multiplication (*), division (/) and power (^ or **). Parenthesis can be in the form of square brackets [v1 * v2] or normal brackets (v1 * v2). It will work also with variables taking arguments. Operator precedence is taken into account. For example

(daughter(0, E) + daughter(1, E))**2 - p**2 + 0.138

Changed in version release-03-00-00: now both, [] and () can be used for grouping operations, ** can be used for exponent and float literals are possible directly in the formula.

genParticle(index, variable)

[Eventbased] Returns the variable for the ith generator particle. The arguments of the function must be the index of the particle in the MCParticle Array, and variable, the name of the function or variable for that generator particle. If index goes beyond the length of the MCParticles array, NaN will be returned.

E.g. genParticle(0, p) returns the total momentum of the first MCParticle, which is the Upsilon(4S) in a generic decay. genParticle(0, mcDaughter(1, p) returns the total momentum of the second daughter of the first MC Particle, which is the momentum of the second B meson in a generic decay.

genUpsilon4S(variable)

[Eventbased] Returns the variable evaluated for the generator-level \(\Upsilon(4S)\). If no generator level \(\Upsilon(4S)\) exists for the event, NaN will be returned.

E.g. genUpsilon4S(p) returns the total momentum of the \(\Upsilon(4S)\) in a generic decay. genUpsilon4S(mcDaughter(1, p) returns the total momentum of the second daughter of the generator-level \(\Upsilon(4S)\) (i.e. the momentum of the second B meson in a generic decay.

getVariableByRank(particleList, rankedVariableName, variableName, rank)

Returns the value of variableName for the candidate in the particleList with the requested rank.

Note

The BestCandidateSelection module available via rankByHighest / rankByLowest has to be used before.

Warning

The first candidate matching the given rank is used. Thus, it is not recommended to use this variable in conjunction with allowMultiRank in the BestCandidateSelection module.

The suffix _rank is automatically added to the argument rankedVariableName, which either has to be the name of the variable used to order the candidates or the selected outputVariable name without the ending _rank. This means that your selected name for the rank variable has to end with _rank.

An example of this variable’s usage is given in the tutorial B2A602-BestCandidateSelection

grandDaughterDecayAngle(i, j)

Returns the decay angle of the granddaughter in the daughter particle’s rest frame. It is calculated with respect to the reverted momentum vector of the particle. Two arguments representing the daughter and granddaughter indices have to be provided as arguments.

grandDaughterDiffOf(i, j, variable)

Returns the difference of a variable between the first daughters of the two given daughters. E.g. useRestFrame(grandDaughterDiffOf(0, 1, p)) returns the momentum difference between the first daughters of the first and second daughter in the rest frame of the given particle. (That means that it returns \(p_j - p_i\)) Nota Bene: for the particular case ‘variable=phi’ you should use the grandDaughterDiffOfPhi function.

grandDaughterDiffOfClusterPhi(i, j)

Returns the difference in \(\phi\) between the ECLClusters of the daughters of the two given daughters. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\). The function returns NaN if at least one of the daughters is not matched to or not based on an ECLCluster.

grandDaughterDiffOfPhi(i, j)

Returns the difference in \(\phi\) between the first daughters of the two given daughters. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\).

ifNANgiveX(variable, x)

Returns x (has to be a number) if variable value is nan (determined via std::isnan(double)). Useful for technical purposes while training MVAs.

invMassInLists(pList1, pList2, ...)

Returns the invariant mass of the combination of particles in the given particle lists.

isDaughterOfList(particleListNames)

Returns 1 if the given particle is a daughter of at least one of the particles in the given particle Lists.

isDescendantOfList(particleListName[, anotherParticleListName][, generationFlag = -1])

Returns 1 if the given particle appears in the decay chain of the particles in the given ParticleLists.

Passing an integer as the last argument, allows to check if the particle belongs to the specific generation:

• isDescendantOfList(<particle_list>,1) returns 1 if particle is a daughter of the list,

• isDescendantOfList(<particle_list>,2) returns 1 if particle is a granddaughter of the list,

• isDescendantOfList(<particle_list>,3) returns 1 if particle is a great-granddaughter of the list, etc.

• Default value is -1 that is inclusive for all generations.

isGrandDaughterOfList(particleListNames)

Returns 1 if the given particle is a grand daughter of at least one of the particles in the given particle Lists.

isInList(particleListName)

Returns 1.0 if the particle is in the list provided, 0.0 if not. Note that this only checks the particle given. For daughters of composite particles, please see isDaughterOfList.

isInfinity(variable)

Returns true if variable value evaluates to infinity (determined via std::isinf(double)). Useful for debugging.

isMCDescendantOfList(particleListName[, anotherParticleListName][, generationFlag = -1])

Returns 1 if the given particle is linked to the same MC particle as any reconstructed daughter of the decay lists.

Passing an integer as the last argument, allows to check if the particle belongs to the specific generation:

• isMCDescendantOfList(<particle_list>,1) returns 1 if particle is matched to the same particle as any daughter of the list,

• isMCDescendantOfList(<particle_list>,2) returns 1 if particle is matched to the same particle as any granddaughter of the list,

• isMCDescendantOfList(<particle_list>,3) returns 1 if particle is matched to the same particle as any great-granddaughter of the list, etc.

• Default value is -1 that is inclusive for all generations.

It makes only sense for lists created with fillParticleListFromMC function with addDaughters=True argument.

isNAN(variable)

Returns true if variable value evaluates to nan (determined via std::isnan(double)). Useful for debugging.

log(variable)

Returns natural logarithm evaluated for the given variable.

log10(variable)

Returns base-10 logarithm evaluated for the given variable.

matchedMC(variable)

Returns variable output for the matched MCParticle by constructing a temporary Particle from it. This may not work too well if your variable requires accessing daughters of the particle. E.g. matchedMC(p) returns the total momentum of the related MCParticle. Returns NaN if no matched MCParticle exists.

matchedMCHasPDG(PDGCode)

Returns if the absolute value of aPDGCode of a MCParticle related to a Particle matches a given PDGCode.Returns 0/0.5/1 if PDGCode does not match/is not available/ matches

max(var1, var2)

Returns max value of two variables.

maxOpeningAngleInList(particleListName)

Returns maximum opening angle in the given particle List.

maxPtInList(particleListName)

Returns maximum transverse momentum Pt in the given particle List.

mcDaughter(i, variable)

Returns the value of the requested variable for the i-th Monte Carlo daughter of the particle. Returns NaN if the particle is nullptr, if the particle is not matched to an MC particle,or if the i-th MC daughter does not exist. E.g. mcDaughter(0, PDG) will return the PDG code of the first MC daughter of the matched MCparticle of the reconstructed particle the function is applied to./nThe meta variable can also be nested: mcDaughter(0, mcDaughter(1, PDG)).

mcMother(variable)

Returns the value of the requested variable for the Monte Carlo mother of the particle. Returns NaN if the particle is nullptr, if the particle is not matched to an MC particle,or if the MC mother does not exist. E.g. mcMother(PDG) will return the PDG code of the MC mother of the matched MCparticle of the reconstructed particle the function is applied to. The meta variable can also be nested: mcMother(mcMother(PDG)).

mcParticleIsInMCList(particleListName)

Returns 1.0 if the particle’s matched MC particle is also matched to a particle in particleListName (or if either of the lists were filled from generator level modularAnalysis.fillParticleListFromMC.)

See also

isMCDescendantOfList to check daughters.

medianValueInList(particleListName, variable)

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

min(var1, var2)

Returns min value of two variables.

modulo(variable, n)

Returns rest of division of variable by n.

mostB2BInList(particleListName, variable)

Returns variable for the most back-to-back particle (closest opening angle to 180) in the list provided.

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.

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.

nParticlesInList(particleListName)

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

numberOfNonOverlappingParticles(pList1, pList2, ...)

Returns the number of non-overlapping particles in the given particle listsUseful to check if there is additional physics going on in the detector if one reconstructed the Y4S

pValueCombination(p1, p2, ...)

Returns the combined p-value of the provided p-values according to the formula given in Nucl. Instr. and Meth. A 411 (1998) 449 . If any of the p-values is invalid, i.e. smaller than zero, -1 is returned.

particleCached(variable)

Returns value of given variable and caches this value in the ParticleExtraInfo of the provided particle. The result of second call to this variable on the same particle will be provided from the cache.

passesCut(cut)

Returns 1 if particle passes the cut otherwise 0. Useful if you want to write out if a particle would have passed a cut or not. Returns NaN if particle is a nullptr.

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.

sin(variable)

Returns sine value of the given variable.

sourceObjectIsInList(particleListName)

Returns 1.0 if the underlying mdst object (e.g. track, or cluster) was used to create a particle in particleListName, 0.0 if not.

Note

This only makes sense for particles that are not composite. Returns -1 for composite particles.

totalECLEnergyOfParticlesInList(particleListName)

Returns the total ECL energy of particles in the given particle List.

totalEnergyOfParticlesInList(particleListName)

Returns the total energy of particles in the given particle List.

totalPxOfParticlesInList(particleListName)

Returns the total momentum Px of particles in the given particle List.

totalPyOfParticlesInList(particleListName)

Returns the total momentum Py of particles in the given particle List.

totalPzOfParticlesInList(particleListName)

Returns the total momentum Pz of particles in the given particle List.

unmask(variable, flag1, flag2, ...)

unmask(variable, flag1, flag2, …) or unmask(variable, mask) sets certain bits in the variable to zero. For example, if you want to set the second, fourth and fifth bits to zero, you could call unmask(variable, 2, 8, 16) or unmask(variable, 26).

useAlternativeDaughterHypothesis(variable, daughterIndex_1:newMassHyp_1, ..., daughterIndex_n:newMassHyp_n)

Returns a variable calculated using new mass hypotheses for (some of) the particle’s daughers.

Warning

variable can only be a function of the particle 4-momentum, which is re-calculated as the sum of the daughters’ 4-momenta. This means that if you made a kinematic fit without updating the daughters’ momenta, the result of this variable will not reflect the effect of the kinematic fit. Also, the track fit is not performed again: the variable only re-calculates the 4-vectors using different mass assumptions. The alternative mass assumpion is used only internally by the variable, and is not stored in the datastore (i.e the daughters are not permanently changed).

Warning

Generalized daughter indexes are not supported (yet!): this variable can be used only on first-generation daughters.

Tip

useAlternativeDaughterHypothesis(M, 0:K+, 2:pi-) will return the invariant mass of the particle assuming that the first daughter is a kaon and the third is a pion, instead of whatever was used in reconstructing the decay. useAlternativeDaughterHypothesis(mRecoil, 1:p+) will return the recoil mass of the particle assuming that the second daughter is a proton instead of whatever was used in reconstructing the decay.

useCMSFrame(variable)

Returns the value of the variable using the CMS frame as current reference frame. E.g. useCMSFrame(E) returns the energy of a particle in the CMS frame.

useLabFrame(variable)

Returns the value of variable in the lab frame.

Tip

The lab frame is the default reference frame, usually you don’t need to use this meta-variable. E.g. useLabFrame(E) returns the energy of a particle in the Lab frame, same as just E.

Specifying the lab frame is useful in some corner-cases. For example: useRestFrame(daughter(0, formula(E - useLabFrame(E)))) which is the difference of the first daughter’s energy in the rest frame of the mother (current particle) with the same daughter’s lab-frame energy.

useRestFrame(variable)

Returns the value of the variable using the rest frame of the given particle as current reference frame. E.g. useRestFrame(daughter(0, p)) returns the total momentum of the first daughter in its mother’s rest-frame

useTagSideRecoilRestFrame(variable, daughterIndexTagB)

Returns the value of the variable in the rest frame of the recoiling particle to the tag side B meson. The variable should only be applied to an Upsilon(4S) list. E.g. useTagSideRecoilRestFrame(daughter(1, daughter(1, p)), 0) applied on a Upsilon(4S) list (Upsilon(4S)->B+:tag B-:sig) returns the momentum of the second daughter of the signal B meson in the signal B meson rest frame.

varFor(pdgCode, variable)

Returns the value of the variable for the given particle if its abs(pdgCode) agrees with the given one. E.g. varFor(11, p) returns the momentum if the particle is an electron or a positron.

varForFirstMCAncestorOfType(type, variable)

Returns requested variable of the first ancestor of the given type. Ancestor type can be set up by PDG code or by particle name (check evt.pdl for valid particle names)

varForMCGen(variable)

Returns the value of the variable for the given particle if the MC particle related to it is primary, not virtual, and not initial. If no MC particle is related to the given particle, or the MC particle is not primary, virtual, or initial, NaN will be returned. E.g. varForMCGen(PDG) returns the PDG code of the MC particle related to the given particle if it is primary, not virtual, and not initial.

veto(particleList, cut, pdgCode = 11)

Combines current particle with particles from the given particle list and returns 1 if the combination passes the provided cut. For instance one can apply this function on a signal Photon and provide a list of all photons in the rest of event and a cut around the neutral Pion mass (e.g. 0.130 < M < 0.140). If a combination of the signal Photon with a ROE photon fits this criteria, hence looks like a neutral pion, the veto-Metavariable will return 1

MC matching and MC truth

Here is a list of MC truth-related variables. For some variables, you will need to run truth matching in order to get sensible results.

from modularAnalysis import matchMCTruth
matchMCTruth("B0:myCandidates")  # for example

Variables will also work on generator-level particles:

from modularAnalysis import fillParticleListFromMC
fillParticleListFromMC("B0:generator", "") # the generator-level B particles

Eher

[Eventbased] The nominal HER energy used by the generator.

Warning

This variable does not make sense for data.

Eler

[Eventbased] The nominal LER energy used by the generator.

Warning

This variable does not make sense for data.

XAngle

[Eventbased] The nominal beam crossing angle from generator level beam kinematics.

Warning

This variable does not make sense for data.

genMotherID

Check the array index of a particles generated mother

genMotherID(i)

Check the array index of a particle n-th MC mother particle by providing an argument. 0 is first mother, 1 is grandmother etc.

genMotherP

Generated momentum of a particles MC mother particle

genMotherPDG

Check the PDG code of a particles MC mother particle

genMotherPDG(i)

Check the PDG code of a particles n-th MC mother particle by providing an argument. 0 is first mother, 1 is grandmother etc.

genNMissingDaughter(PDG)

Returns the number of missing daughters having assigned PDG codes. NaN if no MCParticle is associated to the particle.

genNStepsToDaughter(i)

Returns number of steps to i-th daughter from the particle at generator level. NaN if no MCParticle is associated to the particle or i-th daughter. NaN if i-th daughter does not exist.

genParticleID

Check the array index of a particle’s related MCParticle

generatorEventWeight

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

isCloneTrack

Return 1 if the charged final state particle comes from a cloned track, 0 if not a clone. Returns NAN if neutral, composite, or MCParticle not found (like for data or if not MCMatched)

isMisidentified

return 1 if the particle is misidentified: one or more of the final state particles have the wrong PDG code assignment (including wrong charge), 0 in all other cases.

isOrHasCloneTrack

Return 1 if the particle is a clone track or has a clone track as a daughter, 0 otherwise.

isPrimarySignal

1.0 if Particle is correctly reconstructed (SIGNAL) and primary, 0.0 otherwise

isSignal

1.0 if Particle is correctly reconstructed (SIGNAL), 0.0 otherwise. It behaves according to DecayStringGrammar.

isSignalAcceptBremsPhotons

1.0 if Particle is correctly reconstructed (SIGNAL), 0.0 otherwise. Particles with gamma daughters attached through the bremsstrahlung recovery modules are allowed.

isSignalAcceptMissing

same as isSignal, but also accept missing particle

isSignalAcceptMissingGamma

same as isSignal, but also accept missing gamma, such as B -> K* gamma, pi0 -> gamma gamma

isSignalAcceptMissingMassive

same as isSignal, but also accept missing massive particle

isSignalAcceptMissingNeutrino

same as isSignal, but also accept missing neutrino

isSignalAcceptWrongFSPs

1.0 if Particle is almost correctly reconstructed (SIGNAL), 0.0 otherwise. Misidentification of charged FSP is allowed.

isWrongCharge

return 1 if the charge of the particle is wrongly assigned, 0 in all other cases

mcDecayTime

The decay time of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcE

The energy of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcErrors

The bit pattern indicating the quality of MC match (see MCMatching::MCErrorFlags)

mcFSR

Returns 1 if Particle is related to FSR MCParticle, 0 if Particle is related to non - FSR MCParticle ,NaN if Particle is not related to MCParticle.

mcISR

Returns 1 if Particle is related to ISR MCParticle, 0 if Particle is related to non - ISR MCParticle, NaN if Particle is not related to MCParticle.

mcInitial

Returns 1 if Particle is related to initial MCParticle, 0 if Particle is related to non - initial MCParticle, NaN if Particle is not related to MCParticle.

mcLifeTime

The life time of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcMatchWeight

The weight of the Particle -> MCParticle relation (only for the first Relation = largest weight).

mcP

The total momentum of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcPDG

The PDG code of matched MCParticle, 0 if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcPT

The pt of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcPX

The px of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcPY

The py of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcPZ

The pz of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcParticleStatus

Returns status bits of related MCParticle or NaN if MCParticle relation is not set.

mcPhi

The phi of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcPhotos

Returns 1 if Particle is related to Photos MCParticle, 0 if Particle is related to non - Photos MCParticle, NaN if Particle is not related to MCParticle.

mcPrimary

Returns 1 if Particle is related to primary MCParticle, 0 if Particle is related to non - primary MCParticle, NaN if Particle is not related to MCParticle.

mcRecoilMass

The mass recoiling against the particles attached as particle’s daughters calculated using MC truth values.

mcSecPhysProc

Returns the secondary physics process flag.

mcTheta

The theta of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcVirtual

Returns 1 if Particle is related to virtual MCParticle, 0 if Particle is related to non - virtual MCParticle, NaN if Particle is not related to MCParticle.

nMCMatches

The number of relations of this Particle to MCParticle.

isReconstructible

checks charged particles were seen in the SVD and neutrals in the ECL, returns 1.0 if so, 0.0 if not, -1.0 for composite particles. Useful for generator studies, not for reconstructed particles.

seenInARICH

returns 1.0 if the MC particle was seen in the ARICH, 0.0 if not, -1.0 for composite particles. Useful for generator studies, not for reconstructed particles.

seenInCDC

returns 1.0 if the MC particle was seen in the CDC, 0.0 if not, -1.0 for composite particles. Useful for generator studies, not for reconstructed particles.

seenInECL

returns 1.0 if the MC particle was seen in the ECL, 0.0 if not, -1.0 for composite particles. Useful for generator studies, not for reconstructed particles.

seenInKLM

returns 1.0 if the MC particle was seen in the KLM, 0.0 if not, -1.0 for composite particles. Useful for generator studies, not for reconstructed particles.

seenInPXD

returns 1.0 if the MC particle was seen in the PXD, 0.0 if not, -1.0 for composite particles. Useful for generator studies, not for reconstructed particles.

seenInSVD

returns 1.0 if the MC particle was seen in the SVD, 0.0 if not, -1.0 for composite particles. Useful for generator studies, not for reconstructed particles.

seenInTOP

returns 1.0 if the MC particle was seen in the TOP, 0.0 if not, -1.0 for composite particles. Useful for generator studies, not for reconstructed particles.

Daughter info

Here is a list of variables getting info from particle’s daughters:

hasCharmedDaughter(i)

Returns information regarding the charm quark presence in the decay.

hasCharmoniumDaughter

Returns information regarding the charmonium state presence in the decay.

hasRealPhotonDaughter

Returns information regarding photon daughter origin for a particle.

KLM Cluster and \(K_{L}^0\) Identification

Here is a list of KLM Cluster and \(K_{L}^0\) identification variables:

Warning

Please note that these variables refer to KLMClusters, which are designed to reconstruct \(K_{L}^0\) and other neutral particles with the KLM subdetector. These variables must not be used to do particle identification of charged tracks (for example, they must not be used to identify muons), otherwise there is a serious risk to spoil a physics analysis.

For particle identification of charged tracks, please use the canonical PID variables.

klmClusterBelleECLFlag

Returns the Belle-style ECL flag.

klmClusterBelleTrackFlag

Returns the Belle-style Track flag.

klmClusterEnergy

Returns the energy of the associated KLMCluster.

Warning

This variable returns an approximation of the energy: it uses klmClusterMomentum as momentum and the hypothesis that the KLMCluster is originated by a \(K_{L}^0\) (\(E_{\text{KLM}} = \sqrt{M_{K^0_L}^2 + p_{\text{KLM}}^2}\), where \(E_{\text{KLM}}\) is this variable, \(M_{K^0_L}\) is the \(K^0_L\) mass and \(p_{\text{KLM}}\) is klmClusterMomentum). It should be used with caution, and may not be physically meaningful, especially for \(n\) candidates.

klmClusterInnermostLayer

Returns the number of the innermost KLM layer with a 2-dimensional hit of the associated KLMCluster.

klmClusterIsBKLM

Returns 1 if the associated KLMCluster is in barrel KLM.

klmClusterIsBackwardEKLM

Returns 1 if the associated KLMCluster is in backward endcap KLM.

klmClusterIsEKLM

Returns 1 if the associated KLMCluster is in endcap KLM.

klmClusterIsForwardEKLM

Returns 1 if the associated KLMCluster is in forward endcap KLM.

klmClusterKlId

Returns the KlId classifier output associated to the KLMCluster.

klmClusterLayers

Returns the number of KLM layers with 2-dimensional hits of the associated KLMCluster.

klmClusterMomentum

Returns the momentum magnitude of the associated KLMCluster.

Warning

This variable returns an approximation of the momentum, since it is proportional to klmClusterLayers (\(p_{\text{KLM}} = 0.215 \cdot N_{\text{layers}}\), where \(p_{\text{KLM}}\) is this variable and \(N_{\text{layers}}\) is klmClusterLayers). It should be used with caution, and may not be physically meaningful.

klmClusterPhi

Returns the azimuthal (\(\phi\)) angle of the associated KLMCluster.

klmClusterPositionX

Returns the \(x\) position of the associated KLMCluster.

klmClusterPositionY

Returns the \(y\) position of the associated KLMCluster.

klmClusterPositionZ

Returns the \(z\) position of the associated KLMCluster.

klmClusterTheta

Returns the polar (\(\theta\)) angle of the associated KLMCluster.

klmClusterTiming

Returns the timing informationf of the associated KLMCluster.

Warning

Currently the KLM has no time calibration. This leads to a huge discrepancy for the variable klmClusterTiming if one compares collisions and simulated data. Moreover, the distribution of the variable on collisions data has a very complicated structure, due to the different timing shifts of different KLM components. It is recommended to not use it in any case until the KLM is calibrated, even for simulated data.

klmClusterTrackDistance

Returns the distance between the Track and the KLMCluster associated to this Particle. This variable returns NaN if there is no Track-to-KLMCluster relationship.

maximumKLMAngleCMS

Returns the maximum angle in the CMS frame between the Particle and all KLMClusters in the event.

nKLMClusterTrackMatches

Returns the number of Tracks matched to the KLMCluster associated to this Particle. This variable can return a number greater than 0 for \(K_{L}^0\) or \(n\) candidates originating from KLMClusters and returns NaN for Particles with no KLMClusters associated.

nMatchedKLMClusters

Returns the number of KLMClusters matched to the Track associated to this Particle. This variable can return only 0 or 1 and return NaN for \(K_{L}^0\) or \(n\) candidates originating from KLMClusters with no Tracks associated.

Time Dependent CPV Analysis Variables

To use most of the variables in this section on need to run vertex.TagV method:

DeltaBoost

\(\Delta z\) in the boost direction

DeltaBoostErr

Uncertanty of \(\Delta z\) in the boost direction

DeltaT

Proper decay time difference \(\Delta t\) between signal B-meson \((B_{rec})\) and tag B-meson \((B_{tag})\) in ps.

DeltaTBelle

[Legacy] \(\Delta t\) in ps, as it was used in Belle

DeltaTErr

Proper decay time difference \(\Delta t\) uncertainty in ps

DeltaTRes

\(\Delta t\) residual in ps, to be used for resolution function studies

DeltaZ

Difference of decay vertex longitudinal components between signal B-meson \((B_{rec})\) and tag B-meson \((B_{tag})\): \(\Delta z = z(B_{rec}) - z(B_{tag})\)

DeltaZErr

Uncertainty of the difference \(z(B_{rec}) - z(B_{tag})\)

LBoost

Returns the vertex component in the boost direction

LBoostErr

Returns the error of the vertex in the boost direction

OBoost

Returns the vertex component in the direction orthogonal to the boost

OBoostErr

Returns the error of the vertex in the direction orthogonal to the boost

TagTrackAverage(var)

return the average over the tag tracks of the variable var. var must be one of the TagTrackXXX variables, for example: TagTrackAverage(TagTrackDistanceToConstraint). The tracks that are assigned a zero weight are ignored.

TagTrackAverageSquares(var)

return the average over the tag tracks of the square of the variable var. var must be one of the TagTrackXXX variables, for example: TagTrackAverageSquares(TagTrackDistanceToConstraint). The tracks that are assigned a zero weight are ignored.

TagTrackD0(i)

return the d0 parameter of the ith track used in the tag vtx fit

TagTrackDistanceToConstraint(i)

returns the measured distance between the ith tag track and the centre of the constraint.

TagTrackDistanceToConstraintErr(i)

returns the estimated error on the distance between the ith tag track and the centre of the constraint.

TagTrackDistanceToConstraintSignificance(i)

returns the significance of the distance between the centre of the constraint and the tag track indexed by track index (computed as distance / uncertainty)

TagTrackDistanceToTagV(i)

returns the measured distance between the ith tag track and the tag vtx.

TagTrackDistanceToTagVErr(i)

returns the estimated error on the distance between the ith tag track and the tag vtx. Warning: only the uncertainties on the track position parameters are taken into account.

TagTrackDistanceToTagVSignificance(i)

returns the significance of the distance between the tag vtx and the tag track indexed by trackIndex (computed as distance / uncertainty)

TagTrackMax(var)

return the maximum value of the variable var evaluated for each tag track. var must be one of the TagTrackXXX variables, for example: TagTrackMax(TagTrackDistanceToConstraint). The tracks that are assigned a zero weight are ignored.

TagTrackMin(var)

return the minimum value of the variable var evaluated for each tag track. var must be one of the TagTrackXXX variables, for example: TagTrackMin(TagTrackDistanceToConstraint). The tracks that are assigned a zero weight are ignored.

TagTrackMomentum(i)

return the magnitude of the momentum of the ith track used in the tag vtx fit.

TagTrackMomentumX(i)

return the X component of the momentum of the ith track used in the tag vtx fit.

TagTrackMomentumY(i)

return the Y component of the momentum of the ith track used in the tag vtx fit.

TagTrackMomentumZ(i)

return the Z component of the momentum of the ith track used in the tag vtx fit.

TagTrackRaveWeight(i)

returns the weight assigned by Rave to track i

TagTrackTrueDistanceToTagV(i)

return the true distance between the true B Tag decay vertex and the p’cle corresponding to the ith tag vtx track.

TagTrackTrueMomentumX(i)

return the X component of the true momentum of the MC particle corresponding to the ith tag vtx track.

TagTrackTrueMomentumY(i)

return the Y component of the true momentum of the MC particle corresponding to the ith tag vtx track.

TagTrackTrueMomentumZ(i)

return the Z component of the true momentum of the MC particle corresponding to the ith tag vtx track.

TagTrackTrueOriginX(i)

return the X component of the true origin of the MC particle corresponding to the ith tag vtx track.

TagTrackTrueOriginY(i)

return the Y component of the true origin of the MC particle corresponding to the ith tag vtx track.

TagTrackTrueOriginZ(i)

return the Z component of the true origin of the MC particle corresponding to the ith tag vtx track.

TagTrackTrueVecToTagVX(i)

return the X coordinate of the vector between the mc particle corresponding to the ith tag vtx track and the true tag B decay vertex.

TagTrackTrueVecToTagVY(i)

return the Y coordinate of the vector between the mc particle corresponding to the ith tag vtx track and the true tag B decay vertex.

TagTrackTrueVecToTagVZ(i)

return the Z coordinate of the vector between the mc particle corresponding to the ith tag vtx track and the true tag B decay vertex.

TagTrackWeightedAverage(var)

return the average over the tag tracks of the variable var, weighted by weights of the tag vertex fitter. var must be one of the TagTrackXXX variables, for example: TagTrackWeightedAverage(TagTrackDistanceToConstraint).

TagTrackWeightedAverageSquares(var)

return the average over the tag tracks of the variable var, weighted by weights of the tag vertex fitter. var must be one of the TagTrackXXX variables, for example: TagTrackWeightedAverageSquares(TagTrackDistanceToConstraint).

TagTrackZ0(i)

return the z0 parameter of the ith track used in the tag vtx fit

TagVChi2

chi2 value of the tag vertex fit

TagVChi2IP

IP component of chi2 value of the tag vertex fit

TagVDistanceToConstraint

returns the measured distance between the tag vtx and the centre of the constraint.

TagVDistanceToConstraintErr

returns the estimated error on the distance between the tag vtx and the centre of the constraint.

TagVDistanceToConstraintSignificance

returns the significance of the distance between the tag vtx and the centre of the constraint (computed as distance / uncertainty)

TagVFitTruthStatus

Returns the status of the fit performed with the truth info. Possible values are: 0: fit performed with measured parameters, 1: fit performed with true parameters, 2: unable to recover truth parameters

TagVLBoost

Returns the TagV component in the boost direction

TagVLBoostErr

Returns the error of TagV in the boost direction

TagVNDF

Number of degrees of freedom in the tag vertex fit

TagVNFitTracks

returns the number of tracks used by rave to fit the vertex (not counting the ones coming from Kshorts)

TagVNTracks

Number of tracks in the tag vertex

TagVOBoost

Returns the TagV component in the direction orthogonal to the boost

TagVOBoostErr

Returns the error of TagV in the direction orthogonal to the boost

TagVRollBackStatus

Returns the status of the fit performed with rolled back tracks. Possible values are: 0: fit performed with measured parameters, 1: fit performed with rolled back tracks, 2: unable to recover truth parameters

TagVType

Type of algo for the tag vertex. -1: failed (1,2: single track, deprecated), 3: standard, 4: standard_PXD, 5: no constraint

TagVpVal

Tag vertex p-Value

TagVx

Tag vertex X component

TagVxErr

Tag vertex X component uncertainty

TagVy

Tag vertex Y component

TagVyErr

Tag vertex Y component uncertainty

TagVz

Tag vertex Z component

TagVzErr

Tag vertex Z component uncertainty

internalTagVMCFlavor

[Expert] [Debugging] This variable is only for internal checks of the TagV module by developers. It returns the internal mc flavor information of the tag-side B provided by the TagV module.

mcDeltaBoost

True difference of decay vertex boost-direction components between signal B-meson \((B_{rec})\) and tag B-meson \((B_{tag})\): \(\Delta l = l(B_{rec}) - l(B_{tag})\)

mcDeltaT

Generated proper decay time difference (in z-difference approximation) \(\Delta t\) in ps: \((l(B_{\rm rec}) - l(B_{\rm tag}))/\beta_{\Upsilon(4S)}\gamma_{\Upsilon(4S)}\)

mcDeltaTau

Generated proper decay time difference \(\Delta t\) in ps: \(\tau(B_{\rm rec})-\tau(B_{\rm tag})\)

mcLBoost

Returns the MC vertex component in the boost direction

mcOBoost

Returns the MC vertex component in the direction orthogonal to the boost

mcTagVLBoost

Returns the MC TagV component in the boost direction

mcTagVOBoost

Returns the MC TagV component in the direction orthogonal to the boost

mcTagVx

Generated Tag vertex X component

mcTagVy

Generated Tag vertex Y component

mcTagVz

Generated Tag vertex Z component

Flavor Tagger

B0mcErrors

mcErrors MCMatching Flag on the reconstructed B0_cp.

NumberOfKShortsInRoe

Returns the number of K_S0 in the rest of event. The particleList K_S0:inRoe is required

ancestorHasWhichFlavor

checks the decay chain of the given particle upwards up to the Y(4S) resonance.Output is 0 (1) if an ancestor is found to be a B0bar (B0), if not -2.

chargeTimesKaonLiklihood

Returns the q*(highest PID_Likelihood for Kaons), else 0.

cosTPTO

cosine of angle between thrust axis of given particle and thrust axis of ROE

hasRestOfEventTracks

Returns the amount of tracks in the RestOfEvent related to the given Particle. -2 If ROE is empty.

isInElectronOrMuonCat

Returns 1.0 if the particle has been selected as target in the Muon or Electron Category, 0.0 else.

isLambda

1.0 if MCLambda0, 0.0 else.

isMajorityInRestOfEventFromB0

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

isMajorityInRestOfEventFromB0bar

[Eventbased] Check if the majority of the tracks in the current RestOfEvent are from a B0bar.

isRelatedRestOfEventB0Flavor

-1 (1) if the RestOfEvent related to the given Particle is related to a B0bar (B0). The MCError bit of Breco has to be 0, 1, 2, 16 or 1024. The output of the variable is 0 otherwise. If one Particle in the Rest of Event is found to belong the reconstructed B0, the output is -2(2) for a B0bar (B0) on the reco side.

isRelatedRestOfEventMajorityB0Flavor

0 (1) if the majority of tracks and clusters of the RestOfEvent related to the given Particle are related to a B0bar (B0).

isRestOfEventMajorityB0Flavor

0 (1) if the majority of tracks and clusters of the current RestOfEvent are related to a B0bar (B0).

lambdaFlavor

1.0 if Lambda0, -1.0 if Anti-Lambda0, 0.0 else.

lambdaZError

Returns the Matrixelement[2][2] of the PositionErrorMatrix of the Vertex fit.

mcFlavorOfOtherB

Returns the MC flavor (+-1) of the accompaning tag-side B meson if the given particle is a correctly MC-matched B candidate. It returns 0 else. In other words, this variable checks the generated flavor of the other MC Upsilon(4S) daughter.

momentumOfSecondDaughter

Returns the Momentum of second daughter if existing, else 0.

momentumOfSecondDaughterCMS

Returns the Momentum of second daughter if existing in CMS, else 0.

pMissTag

Calculates the missing Momentum for a given particle on the tag side.

ptTracksRoe

Returns the transverse momentum of all charged tracks if there exists a ROE for the given particle, else 0.

qrCombined

[Eventbased] -1 (1) if current RestOfEvent is related to a B0bar (B0). The MCError bit of Breco has to be 0, 1, 2, 16 or 1024. The output of the variable is 0 otherwise. If one Particle in the Rest of Event is found to belong the reconstructed B0, the output is -2(2) for a B0bar (B0) on the reco side.

BtagToWBosonVariables(requestedVariable)

FlavorTagging:[Eventbased] Kinematical variables (recoilMass, pMissCMS, cosThetaMissCMS or EW90) assuming a semileptonic decay with the given particle as target.

CheckingVariables(ListName, requestedVariable)

FlavorTagging:[Eventbased] Available checking variables are getListSize for particle lists.

FSCVariables(requestedVariable)

FlavorTagging:[Eventbased] Kinematical variables for FastSlowCorrelated category (pFastCMS, cosSlowFast, SlowFastHaveOpositeCharges, or cosTPTOFast).

HighestProbInCat(particleListName, extraInfoName)

Returns the highest target track probability value for the given category

IsDaughterOf(variable)

Check if the particle is a daughter of the given list.

KaonPionVariables(requestedVariable)

Kinematical variables for KaonPion category (cosKaonPion or HaveOpositeCharges)

QpOf(particleListName, outputExtraInfo, rankingExtraInfo)

FlavorTagging: [Eventbased] Returns the q*p value for a given list (argument[0]), where p is the probability of a category stored as extraInfo (argument[1]). The particle is selected after ranking according to a flavor tagging extraInfo (argument[2]).

hasHighestProbInCat(particleListName, extraInfoName)

Returns 1.0 if the given Particle is classified as target track, i.e. if it has the highest target track probability in particlelistName. The probability is accessed via extraInfoName.

hasTrueTarget(categoryName)

Returns 1 if the given category has a target. 0 Else.

hasTrueTargets(categoryName)

Returns 1 if target particles (checking only the decay chain) of the category with the given name is found in the mc Particles. The allowed categories are the official Flavor Tagger Category Names.

isRightCategory(particleName)

FlavorTagging: returns 1 if the class track by particleName category has the same flavor as the MC target track 0 else also if there is no target track

isRightTrack(particleName)

Checks if the given Particle was really from a B. 1.0 if true otherwise 0.0

isTrueCategory(categoryName)

Returns 1 if the given category tags the B0 MC flavor correctly. 0 Else.

isTrueFTCategory(categoryName)

Returns 1 if the target particle (checking the decay chain) of the category with the given name is found in the mc Particles, and if it provides the right Flavor. The allowed categories are the official Flavor Tagger Category Names.

qOutput(combinerMethod)

Returns the flavor tag q output of the flavorTagger for the given combinerMethod. The available methods are ‘FBDT’ and ‘FANN’ (category-based combiners), and ‘DNN’ (DNN tagger output).

qpCategory(categoryName)

Returns the output q (charge of target track) times p (probability that this is the right category) of the category with the given name. The allowed categories are the official Flavor Tagger Category Names.

qrOutput(combinerMethod)

Returns the output of the flavorTagger for the given combinerMethod. The available methods are ‘FBDT’ and ‘FANN’ (category-based combiners), and ‘DNN’ (DNN tagger output).

rBinBelle(combinerMethod)

Returns the corresponding r (dilution) bin according to the Belle binning for the given combinerMethod. The available methods are ‘FBDT’ and ‘FANN’ (category-based combiners), and ‘DNN’ (DNN tagger output).

variableOfTarget(particleListName, inputVariable, rankingExtraInfo)

FlavorTagging: [Eventbased] Returns the value of an input variable (argument[1]) for a particle selected from the given list (argument[0]). The particles are ranked according to a flavor tagging extraInfo (argument[2]).

weightedQpOf(particleListName, outputExtraInfo, rankingExtraInfo)

FlavorTagging: [Eventbased] Returns the weighted q*p value for a given list (argument[0]), where p is the probability of a category stored as extraInfo (argument[1]). The particles in the list are ranked according to a flavor tagging extraInfo (argument[2]). The values for the three top particles is combined into an effective (weighted) output.

Rest of Event

bssMassDifference(maskName)

Bs* - Bs mass difference

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.

etaProb(mode)

Returns eta probability, where mode is used to specify the selection criteria for soft photon. The following strings are available.

• standard: loose energy cut and no clusterNHits cut are applied to soft photon

• tight: tight energy cut and no clusterNHits cut are applied to soft photon

• cluster: loose energy cut and clusterNHits cut are applied to soft photon

• both: tight energy cut and clusterNHits cut are applied to soft photon

You can find more details in writePi0EtaVeto function in modularAnalysis.py.

hasAncestorFromSignalSide

Returns 1 if a particle has ancestor from signal side, 0 otherwise. Requires generator information and truth-matching. One can use this variable only in a for_each loop over the RestOfEvent StoreArray.

isCloneOfSignalSide

Returns 1 if a particle is a clone of signal side final state particles, 0 otherwise. Requires generator information and truth-matching. One can use this variable only in a for_each loop over the RestOfEvent StoreArray.

isInRestOfEvent

Returns 1 if a track, ecl or klmCluster associated to particle is in the current RestOfEvent object, 0 otherwise.One can use this variable only in a for_each loop over the RestOfEvent StoreArray.

nROE_Charged(maskName, PDGcode = 0)

Returns number of all charged particles in the related RestOfEvent object. First optional argument is ROE mask name. Second argument is a PDG code to count only one charged particle species, independently of charge. For example: nROE_Charged(cleanMask, 321) will output number of kaons in Rest Of Event with cleanMask. PDG code 0 is used to count all charged particles

nROE_ECLClusters(maskName)

Returns number of ECL clusters in the related RestOfEvent object that pass the selection criteria.

nROE_KLMClusters

Returns number of all remaining KLM clusters in the related RestOfEvent object.

nROE_NeutralECLClusters(maskName)

Returns number of neutral ECL clusters in the related RestOfEvent object that pass the selection criteria.

nROE_NeutralHadrons(maskName)

Returns number of all neutral hadrons in the related RestOfEvent object, accepts 1 optional argument of ROE mask name.

nROE_ParticlesInList(pListName)

Returns the number of particles in ROE from the given particle list. Use of variable aliases is advised.

nROE_Photons(maskName)

Returns number of all photons in the related RestOfEvent object, accepts 1 optional argument of ROE mask name.

nROE_RemainingTracks

Returns number of tracks in ROE - number of tracks of given particleOne can use this variable only in a for_each loop over the RestOfEvent StoreArray.

nROE_RemainingTracks(maskName)

Returns number of remaining tracks between the ROE (specified via a mask) and the given particle. For the given particle only tracks are counted which are in the RoE.One can use this variable only in a for_each loop over the RestOfEvent StoreArray.Is required for the specific FEI.

nROE_Tracks(maskName)

Returns number of tracks in the related RestOfEvent object that pass the selection criteria.

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.

passesROEMask(maskName)

Returns boolean value if track or eclCluster type particle passes a certain mask or not. Only to be used in for_each path

pi0Prob(mode)

Returns pi0 probability, where mode is used to specify the selection criteria for soft photon. The following strings are available.

• standard: loose energy cut and no clusterNHits cut are applied to soft photon

• tight: tight energy cut and no clusterNHits cut are applied to soft photon

• cluster: loose energy cut and clusterNHits cut are applied to soft photon

• both: tight energy cut and clusterNHits cut are applied to soft photon

You can find more details in writePi0EtaVeto function in modularAnalysis.py.

printROE

For debugging, prints indices of all particles in the ROE and all masks. Returns 0.

recMissM2

Returns the invariant mass squared of the missing momentum calculated assumings thereco B is at rest and calculating the neutrino (missing) momentum from \(p_\nu = p_B - p_\mathrm{had} - p_\mathrm{lep}\)

recQ2Bh

Returns the momentum transfer squared, \(q^2\), calculated in CMS as \(q^2 = (p_B - p_h)^2\), where p_h is the CMS momentum of all hadrons in the decay \(B \to H_1\dots H_n \ell \nu_\ell\). This calculation uses a weighted average of the B meson around the reco B cone

recQ2BhSimple

Returns the momentum transfer squared, \(q^2\), calculated in CMS as \(q^2 = (p_B - p_h)^2\), where p_h is the CMS momentum of all hadrons in the decay \(B \to H_1 ... H_n \ell \nu_\ell\). The B meson momentum in CMS is assumed to be 0.

roeCharge(maskName)

Returns total charge of the related RestOfEvent object.

roeDeltae(maskName)

Returns energy difference of the related RestOfEvent object with respect to \(E_\mathrm{cms}/2\).

roeE(maskName)

Returns energy of unused tracks and clusters in ROE, can be used with use***Frame() function.

roeEextra(maskName)

Returns extra energy from ECLClusters in the calorimeter that is not associated to the given Particle

roeM(maskName)

Returns invariant mass of unused tracks and clusters in ROE

roeMC_E

Returns true energy of unused tracks and clusters in ROE, can be used with use***Frame() function.

roeMC_M

Returns true invariant mass of unused tracks and clusters in ROE

roeMC_MissFlags(maskName)

Returns flags corresponding to missing particles on ROE side.

roeMC_P

Returns true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roeMC_PTheta

Returns polar angle of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roeMC_Pt

Returns transverse component of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roeMC_Px

Returns x component of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roeMC_Py

Returns y component of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roeMC_Pz

Returns z component of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roeMbc(maskName)

Returns beam constrained mass of the related RestOfEvent object with respect to \(E_\mathrm{cms}/2\).

roeNeextra(maskName)

Returns extra energy from neutral ECLClusters in the calorimeter that is not associated to the given Particle, can be used with use***Frame() function.

roeP(maskName)

Returns momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roePTheta(maskName)

Returns theta angle of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roePt(maskName)

Returns transverse component of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roePx(maskName)

Returns x component of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roePy(maskName)

Returns y component of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

roePz(maskName)

Returns z component of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

useROERecoilFrame(variable)

Returns the value of the variable using the rest frame of the ROE recoil as current reference frame. Can be used inside for_each loop or outside of it if the particle has associated Rest of Event. E.g. useROERecoilFrame(E) returns the energy of a particle in the ROE recoil frame.

weCosThetaEll(maskName)

Returns the angle between \(M\) and lepton in \(W\) rest frame in the decays of the type: \(M \to h_1 ... h_n \ell\), where W 4-momentum is given as

\[p_W = p_\ell + p_\nu.\]

The neutrino momentum is calculated from ROE taking into account the specified mask, and setting

\[E_{\nu} = |p_{miss}|.\]

weDeltae(maskName, opt)

Returns the energy difference of the B meson, corrected with the missing neutrino momentum (reconstructed side + neutrino) with respect to \(E_\mathrm{cms}/2\).

weMbc(maskName, opt)

Returns beam constrained mass of B meson, corrected with the missing neutrino momentum (reconstructed side + neutrino) with respect to \(E_\mathrm{cms}/2\).

weMissE(maskName, opt)

Returns the energy of the missing momentum, possible options opt are the following:

• 0: CMS, use energy and momentum of charged particles and photons

• 1: CMS, same as 0, fix \(E_\mathrm{miss} = p_\mathrm{miss}\)

• 2: CMS, same as 0, fix \(E_\mathrm{roe} = E_\mathrm{cms}/2\)

• 3: CMS, use only energy and momentum of signal side

• 4: CMS, same as 3, update with direction of ROE momentum

• 5: LAB, use energy and momentum of charged particles and photons from whole event

• 6: LAB, same as 5, fix \(E_\mathrm{miss} = p_\mathrm{miss}\)

• 7: CMS, correct pmiss 3-momentum vector with factor alpha so that \(d_E = 0\) (used for \(M_\mathrm{bc}\) calculation).

weMissM2(maskName, opt)

Returns the invariant mass squared of the missing momentum (see weMissE possible options)

weMissM2OverMissE(maskName)

Returns missing mass squared over missing energy

weMissP(maskName, opt)

Returns the magnitude of the missing momentum (see possible weMissE options)

weMissPTheta(maskName, opt)

Returns the polar angle of the missing momentum (see possible weMissE options)

weMissPx(maskName, opt)

Returns the x component of the missing momentum (see weMissE possible options)

weMissPy(maskName, opt)

Returns the y component of the missing momentum (see weMissE possible options)

weMissPz(maskName, opt)

Returns the z component of the missing momentum (see weMissE possible options)

weQ2lnu(maskName, option)

Returns the momentum transfer squared, \(q^2\), calculated in CMS as \(q^2 = (p_l + p_\nu)^2\), where \(B \to H_1\dots H_n \ell \nu_\ell\). Lepton is assumed to be the last reconstructed daughter. This calculation uses constraints from dE = 0 and Mbc = Mb to correct the neutrino direction. By default, option is set to 7 (see weMissE). Unless you know what you are doing, keep this default value.

weQ2lnuSimple(maskName, option)

Returns the momentum transfer squared, \(q^2\), calculated in CMS as \(q^2 = (p_l + p_\nu)^2\), where \(B \to H_1\dots H_n \ell \nu_\ell\). Lepton is assumed to be the last reconstructed daughter. By default, option is set to 1 (see weMissE). Unless you know what you are doing, keep this default value.

weXiZ(maskName)

Returns Xi_z in event (for Bhabha suppression and two-photon scattering)

Continuum Suppression

For a detailed description of the continuum suppression, see Continuum suppression

CleoConeCS(integer, string)

Returns i-th cleo cones from the continuum suppression. If only the variable is specified, the CleoCones are calculated from all final state particles. If string is set to ‘ROE’, the CleoCones are calculated only from ROE particles. Useful for ContinuumSuppression. Given particle needs a related ContinuumSuppression object (built using the ContinuumSuppressionBuilder). Returns NaN if particle has no related ContinuumSuppression object.

KSFWVariables(variable, string)

Returns variable et, mm2, or one of the 16 KSFW moments. If only the variable is specified, the KSFW moment calculated from the B primary daughters is returned. If string is set to FS1, the KSFW moment calculated from the B final state daughters is returned.

R2

Reduced Fox-Wolfram moment R2

R2EventLevel

[Eventbased] Event-Level Reduced Fox-Wolfram moment R2

cosTBTO

Cosine of angle between thrust axis of the signal B and thrust axis of ROE

cosTBz

Cosine of angle between thrust axis of the signal B and z-axis

thrustBm

Magnitude of the signal B thrust axis

thrustOm

Magnitude of the ROE thrust axis

transformedNetworkOutput(name, low, high)

Transforms the network output \(C\to C\)’ via: \(C'=\operatorname{log}((C-\mathrm{low})/(\mathrm{high}-C))\)

useBThrustFrame(variable, mode)

Returns the variable in respect to rotated coordinates, in which z lies on the specified thrust axis. If mode is set to Signal it will use the thrust axis of the reconstructed B candidate, if mode is set to ROE it will use the ROE thrust axis. If mode is set to Auto the function use the thrust axis based on isInRestOfEvent(particle). Like isinRestofEvent, you have to use path.for_each( …) to use this MetaVariable.

Event Shape

These variables are available after adding the event shape builder modules. This can be done with the function modularAnalysis.buildEventShape. For a detailed description of the event shape variables, see EventShape

aplanarity

[Eventbased] Event aplanarity, defined as the 3/2 of the third sphericity eigenvalue.

backwardHemisphereEnergy

[Eventbased] Total energy the particles flying in the direction opposite to the thrust axis.

backwardHemisphereMass

[Eventbased] Invariant mass of the particles flying in the direction opposite to the thrust axis.

backwardHemisphereMomentum

[Eventbased] Total momentum the particles flying in the direction opposite to the thrust axis.

backwardHemisphereX

[Eventbased] X component of the total momentum of the particles flying in the direciton opposite to the thrust axis

backwardHemisphereY

[Eventbased] Y component of the total momentum of the particles flying in the direction opposite to the thrust axis

backwardHemisphereZ

[Eventbased] Z component of the total momentum of the particles flying in the direction opposite to the thrust axis

cleoCone(i, axisName)

[Eventbased] i-th order cleoCone, calculated respect to the axis axisName. The order can go up to 9th., the axisName can be either ‘thrust’ or ‘collision’

cleoConeThrust0

[Eventbased] 0th Cleo cone calculated respect to the thrust axis.

cleoConeThrust1

[Eventbased] 1st Cleo cone calculated respect to the thrust axis.

cleoConeThrust2

[Eventbased] 2nd Cleo cone calculated respect to the thrust axis.

cleoConeThrust3

[Eventbased] 3rd Cleo cone calculated respect to the thrust axis.

cleoConeThrust4

[Eventbased] 4th Cleo cone calculated respect to the thrust axis.

cleoConeThrust5

[Eventbased] 5th Cleo cone calculated respect to the thrust axis.

cleoConeThrust6

[Eventbased] 6th Cleo cone calculated respect to the thrust axis.

cleoConeThrust7

[Eventbased] 7th Cleo cone calculated respect to the thrust axis.

cleoConeThrust8

[Eventbased] 8th Cleo cone calculated respect to the thrust axis.

forwardHemisphereEnergy

[Eventbased] Total energy the particles flying in the same direction of the thrust axis.

forwardHemisphereMass

[Eventbased] Invariant mass of the particles flying in the same direction of the thrust axis.

forwardHemisphereMomentum

[Eventbased] Total momentum the particles flying in the same direction of the thrust axis.

forwardHemisphereX

[Eventbased] X component of the total momentum of the particles flying in the same direction of the thrust axis

forwardHemisphereY

[Eventbased] Y component of the total momentum of the particles flying in the same direction of the thrust axis

forwardHemisphereZ

[Eventbased] Z component of the total momentum of the particles flying in the same direction of the thrust axis

foxWolframH(i)

[Eventbased] i-th order Fox Wolfram moment. The order can go up to 8th.

foxWolframR(i)

[Eventbased] ratio of the i-th to the 0-th order Fox Wolfram moments. The order can go up to 8th.

foxWolframR1

[Eventbased] ratio of the 1-st to the 0-th order Fox Wolfram moments. This is just an alias of foxWolframR(1) defined for the user’s covenience.

foxWolframR2

[Eventbased] ratio of the 2-nd to the 0-th order Fox Wolfram moments. This is just an alias of foxWolframR(2) defined for the user’s covenience.

foxWolframR3

[Eventbased] ratio of the 3-rd to the 0-th order Fox Wolfram moments. This is just an alias of foxWolframR(3) defined for the user’s covenience.

foxWolframR4

[Eventbased] ratio of the 4-th to the 0-th order Fox Wolfram moments. This is just an alias of foxWolframR(4) defined for the user’s covenience.

harmonicMoment(i, axisName)

[Eventbased] i-th order harmonic moment, calculated respect to the axis axisName. The order can go up to 8th., the axisName can be either ‘thrust’ or ‘collision’

harmonicMomentThrust0

[Eventbased] Harmonic moment of the 0th order calculated respect to the thrust axis.

harmonicMomentThrust1

[Eventbased] Harmonic moment of the 1st order calculated respect to the thrust axis.

harmonicMomentThrust2

[Eventbased] Harmonic moment of the 2nd order calculated respect to the thrust axis.

harmonicMomentThrust3

[Eventbased] Harmonic moment of the 3rd order calculated respect to the thrust axis.

harmonicMomentThrust4

[Eventbased] Harmonic moment of the 4th order calculated respect to the thrust axis.

sphericity

[Eventbased] Event sphericity, defined as the linear combination of the sphericity eigenvlaues S = (3/2)(lambda2+lambda3)

thrust

[Eventbased] Event thrust.

thrustAxisCosTheta

[Eventbased] Cosine of the polar angle component of the thrust axis.

thrustAxisX

[Eventbased] X component of the thrust axis.

thrustAxisY

[Eventbased] Y component of the thrust axis.

thrustAxisZ

[Eventbased] Z component of the thrust axis.

useThrustFrame(variable)

Evaluates a variable value in the thrust reference frame.

Event Kinematics

These variables are available after adding the event kinematics module. This can be done with the function modularAnalysis.buildEventKinematics. The variable collection event_kinematics allows to add all of them comfortably to your ntuple.

missingEnergyOfEventCMS

[Eventbased] The missing energy in CMS obtained with EventKinematics module

missingMass2OfEvent

[Eventbased] The missing mass squared obtained with EventKinematics module

missingMomentumOfEvent

[Eventbased] The magnitude of the missing momentum in lab obtained with EventKinematics module

missingMomentumOfEventCMS

[Eventbased] The magnitude of the missing momentum in CMS obtained with EventKinematics module

missingMomentumOfEventCMS_Px

[Eventbased] The x component of the missing momentum in CMS obtained with EventKinematics module

missingMomentumOfEventCMS_Py

[Eventbased] The y component of the missing momentum in CMS obtained with EventKinematics module

missingMomentumOfEventCMS_Pz

[Eventbased] The z component of the missing momentum in CMS obtained with EventKinematics module

missingMomentumOfEventCMS_theta

[Eventbased] The theta angle of the missing momentum in CMS obtained with EventKinematics module

missingMomentumOfEvent_Px

[Eventbased] The x component of the missing momentum in lab obtained with EventKinematics module

missingMomentumOfEvent_Py

[Eventbased] The y component of the missing momentum in lab obtained with EventKinematics module

missingMomentumOfEvent_Pz

[Eventbased] The z component of the missing momentum in lab obtained with EventKinematics module

missingMomentumOfEvent_theta

[Eventbased] The theta angle of the missing momentum of the event in lab obtained with EventKinematics module

totalPhotonsEnergyOfEvent

[Eventbased] The energy in lab of all the photons obtained with EventKinematics module

visibleEnergyOfEventCMS

[Eventbased] The visible energy in CMS obtained with EventKinematics module

Flight Information

Here is a list of flight time and distance variables of a (grand)daughter particle w.r.t. its (grand)mother decay vertex:

flightDistance

Returns the flight distance of particle. If a treeFit has been performed the flight distance calculated by TreeFitter is returned. Otherwise if a beam constrained rave fit has been performed the production vertex set by rave and the decay vertex are used to calculate the flight distance. If neither fit has been performed the i.p. is taken to be the production vertex.

flightDistanceErr

Returns the flight distance error of particle. If a treeFit has been performed the flight distance error calculated by TreeFitter is returned. Otherwise if a beam constrained rave fit has been performed the production vertex set by rave and the decay vertex are used to calculate the flight distance error. If neither fit has been performed the i.p. is taken to be the production vertex.

flightDistanceOfDaughter(daughterN, gdaughterN = -1)

Returns the flight distance between mother and daughter particle with daughterN index. If a treeFit has been performed the value calculated by treeFitter is returned. Otherwise the value is calculated using the decay vertices of the mother and daughter particle. If a second index granddaughterM is given the value is calculated between the mother and the Mth grandaughter (Mth daughter of Nth daughter).

flightDistanceOfDaughterErr(daughterN, gdaughterN = -1)

Returns the flight distance error between mother and daughter particle with daughterN index. If a treeFit has been performed the value calculated by treeFitter is returned. Otherwise the value is calculated using the decay vertices of the mother and daughter particle. If a second index granddaughterM is given the value is calculated between the mother and the Mth grandaughter (Mth daughter of Nth daughter).

flightTime

Returns the flight time of particle. If a treeFit has been performed the flight time calculated by TreeFitter is returned. Otherwise if a beam constrained rave fit has been performed the production vertex set by rave and the decay vertex are used to calculate the flight time. If neither fit has been performed the i.p. is taken to be the production vertex.

flightTimeErr

Returns the flight time error of particle. If a treeFit has been performed the flight time error calculated by TreeFitter is returned. Otherwise if a beam constrained rave fit has been performed the production vertex set by rave and the decay vertex are used to calculate the flight time error. If neither fit has been performed the i.p. is taken to be the production vertex.

flightTimeOfDaughter(daughterN, gdaughterN = -1)

Returns the flight time between mother and daughter particle with daughterN index. If a treeFit has been performed the value calculated by treeFitter is returned. Otherwise the value is calculated using the decay vertices of the mother and daughter particle. If a second index granddaughterM is given the value is calculated between the mother and the Mth grandaughter (Mth daughter of Nth daughter).

flightTimeOfDaughterErr(daughterN, gdaughterN = -1)

Returns the flight time error between mother and daughter particle with daughterN index. If a treeFit has been performed the value calculated by treeFitter is returned. Otherwise the value is calculated using the decay vertices of the mother and daughter particle. If a second index granddaughterM is given the value is calculated between the mother and the Mth grandaughter (Mth daughter of Nth daughter).

mcFlightDistance

Returns the MC flight distance of the particle

mcFlightDistanceOfDaughter(daughterN, gdaughterN = -1)

Returns the MC flight distance between mother and daughter particle using generated info

mcFlightTime

Returns the MC flight time of the particle

mcFlightTimeOfDaughter(daughterN, gdaughterN = -1)

Returns the MC flight time between mother and daughter particle using generated info

vertexDistance

Returns the distance between the production and decay vertex of a particle. Returns NaN if particle has no production or decay vertex.

vertexDistanceErr

Returns the uncertainty on the distance between the production and decay vertex of a particle. Returns NaN if particle has no production or decay vertex.

vertexDistanceOfDaughter(daughterN, option = '')

If any second argument is provided it returns the distance between the decay vertices of the particle and of its daughter with index daughterN. Otherwise, it is assumed that the particle has a production vertex (typically the IP) which is used to calculate the distance to the daughter’s decay vertex. Returns NaN in case anything goes wrong.

vertexDistanceOfDaughterErr(daughterN, option = '')

If any second argument is provided it returns the uncertainty on the distance between the decay vertices of the particle and of its daughter with index daughterN. Otherwise, it is assumed that the particle has a production vertex (typically the IP) with a corresponding covariance matrix to calculate the uncertainty on the distance to the daughter’s decay vertex. Returns NaN in case anything goes wrong.

vertexDistanceOfDaughterSignificance(daughterN, option = '')

If any second argument is provided it returns the distance between the decay vertices of the particle and of its daughter with index daughterN in units of the uncertainty on this value. Otherwise, it is assumed that the particle has a production vertex (typically the IP) with a corresponding covariance matrix and the significance of the separation to this vertex is calculated.

vertexDistanceSignificance

Returns the distance between the production and decay vertex of a particle in units of the uncertainty on this value, i.e. the significance of the vertex separation.

Vertex Information

Here is a list of production and decay vertex variables:

dcosTheta

vertex or POCA polar angle in respect to IP

distance

3D distance between the IP and the particle decay vertex, if available.

In case the particle has been created from a track, the distance is defined between the POCA and IP. If the particle is built from an ECL cluster, the decay vertex is set to the nominal IP. If the particle is created from a KLM cluster, the distance is calculated between the IP and the cluster itself.

dphi

vertex azimuthal angle of the vertex or POCA in degrees in respect to IP

dr

transverse distance in respect to IP for a vertex; track d0 relative to IP for a track.

dx

vertex or POCA in case of tracks x in respect to IP

dy

vertex or POCA in case of tracks y in respect to IP

dz

vertex or POCA in case of tracks z in respect to IP

mcDecayVertexFromIPDistance

Returns the distance of the decay vertex of the matched generated particle from the IP. Returns nan if the particle has no matched generated particle.

mcDecayVertexFromIPRho

Returns the transverse position of the decay vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

mcDecayVertexFromIPX

Returns the x position of the decay vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

mcDecayVertexFromIPY

Returns the y position of the decay vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

mcDecayVertexFromIPZ

Returns the z position of the decay vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

mcDecayVertexRho

Returns the transverse position of the decay vertex of the matched generated particle. Returns nan if the particle has no matched generated particle.

mcDecayVertexX

Returns the x position of the decay vertex of the matched generated particle. Returns nan if the particle has no matched generated particle.

mcDecayVertexY

Returns the y position of the decay vertex of the matched generated particle. Returns nan if the particle has no matched generated particle.

mcDecayVertexZ

Returns the z position of the decay vertex of the matched generated particle. Returns nan if the particle has no matched generated particle.

mcProductionVertexFromIPX

Returns the x position of the production vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

mcProductionVertexFromIPY

Returns the y position of the production vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

mcProductionVertexFromIPZ

Returns the z position of the production vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

mcProductionVertexX

Returns the x position of production vertex of matched generated particle. Returns nan if the particle has no matched generated particle.

mcProductionVertexY

Returns the y position of production vertex of matched generated particle. Returns nan if the particle has no matched generated particle.

mcProductionVertexZ

Returns the z position of production vertex of matched generated particle. Returns nan if the particle has no matched generated particle.

prodVertexCov(i, j)

Returns the ij covariance matrix component of particle production vertex, arguments i,j should be 0, 1 or 2. Returns NaN if particle has no production covariance matrix.

prodVertexX

Returns the x position of particle production vertex. Returns NaN if particle has no production vertex.

prodVertexXErr

Returns the x position uncertainty of particle production vertex. Returns NaN if particle has no production vertex.

prodVertexY

Returns the y position of particle production vertex.

prodVertexYErr

Returns the y position uncertainty of particle production vertex.

prodVertexZ

Returns the z position of particle production vertex.

prodVertexZErr

Returns the z position uncertainty of particle production vertex.

significanceOfDistance

significance of distance from vertex or POCA to interaction point(-1 in case of numerical problems)

x

x coordinate of vertex in case of composite particle, or point of closest approach (POCA) in case of a track

x_uncertainty

uncertainty on x (measured with respect to the origin)

y

y coordinate of vertex in case of composite particle, or point of closest approach (POCA) in case of a track

y_uncertainty

uncertainty on y (measured with respect to the origin)

z

z coordinate of vertex in case of composite particle, or point of closest approach (POCA) in case of a track

z_uncertainty

uncertainty on z (measured with respect to the origin)

For fully-inclusive particles

Here is a list of useful variables to work with fully-inclusive particles, which are produced via Rest Of Event, AllParticleCombiner or other inclusive reconstruction modules:

daughterAverageOf(variable)

Returns the mean value of a variable over all daughters.

nCompositeDaughters

Returns the number of final state composite daughters.

nDaughterCharged(pdg)

Returns the number of charged daughters with the provided PDG code or the number of all charged daughters if no argument has been provided.

nDaughterNeutralHadrons

Returns the number of K_L0 or neutrons among the final state daughters.

nDaughterPhotons

Returns the number of final state daughter photons.

Specific kinematic variables

This variables group is reserved for the variables for analyses of specific decays like, \(B \to h l \nu\), \(B \to h l^\pm l^\mp\), etc.

Belle and b2bii variables

Several legacy Belle variables are provided.

Note

These are intended for studies with b2bii and for comparison between Belle and Belle II.

BelleFirstCDCHitX

[Legacy] Returns x component of starting point of the track near the 1st SVD or CDC hit for SVD1 data (exp. 7 - 27) or the 1st CDC hit for SVD2 data (from exp. 31). (Belle only, originally stored in mdst_trk_fit.)

BelleFirstCDCHitY

[Legacy] Returns y component of starting point of the track near the 1st SVD or CDC hit for SVD1 data (exp. 7 - 27) or the 1st CDC hit for SVD2 data (from exp. 31). (Belle only, originally stored in mdst_trk_fit.)

BelleFirstCDCHitZ

[Legacy] Returns z component of starting point of the track near the 1st SVD or CDC hit for SVD1 data (exp. 7 - 27) or the 1st CDC hit for SVD2 data (from exp. 31). (Belle only, originally stored in mdst_trk_fit.)

BelleLastCDCHitX

[Legacy] Returns x component of end point of the track near the last CDC hit. (Belle only, originally stored in mdst_trk_fit.)

BelleLastCDCHitY

[Legacy] Returns y component of end point of the track near the last CDC hit. (Belle only, originally stored in mdst_trk_fit.)

BelleLastCDCHitZ

[Legacy] Returns z component of end point of the track near the last CDC hit. (Belle only, originally stored in mdst_trk_fit.)

BellePi0SigM

[Legacy] Returns the significance of the pi0 mass used in the FEI for B2BII. The significance is calculated as the difference between the reconstructed and the nominal mass divided by the mass uncertainty. Since the pi0’s covariance matrix for B2BII is empty, the latter is calculated using the photon daughters’ covariance matrices.

clusterBelleQuality

[Legacy] Returns ECL cluster’s quality indicating a good cluster in GSIM (stored in deltaL of ECL cluster object). Belle analysis typically used clusters with quality == 0 in their \(E_{\text{extra ECL}}\) (Belle only).

goodBelleGamma

[Legacy] Returns 1.0 if photon candidate passes simple region dependent energy selection for Belle data and MC (50/100/150 MeV).

goodBelleKshort

[Legacy] GoodKs Returns 1.0 if a \(K_{S}^0\to\pi\pi\) candidate passes the Belle algorithm: a momentum-binned selection including requirements on impact parameter of, and angle between the daughter pions as well as separation from the vertex and flight distance in the transverse plane.

goodBelleLambda

[Legacy] Returns 2.0, 1.0, 0.0 as an indication of goodness of \(\Lambda^0\) candidates, based on:

• The distance of the two daughter tracks at their interception at z axis,

• the minimum distance of the daughter tracks and the IP in xy plane,

• the difference of the azimuthal angle of the vertex vector and the momentum vector,

• and the flight distance of the Lambda0 candidates in xy plane.

It reproduces the goodLambda() function in Belle.

goodBelleLambda selection 1 (selected with: goodBelleLambda>0) should be used with atcPIDBelle(4,2) > 0.6, and goodBelleLambda selecton 2 (goodBelleLambda>1) can be used without a proton PID cut. The former cut is looser than the latter.”.

Warning

goodBelleLambda is not optimized or tested on Belle II data.

See also

• BN-684 Lambda selection at Belle. K F Chen et al.

• The FindLambda class can be found at /belle_legacy/findLambda/findLambda.h

PID for B2BII

Warning

These variables are to be used only when analysing converted Belle samples.

atcPIDBelle(i, j)

returns Belle’s PID atc variable: atc_pid(3,1,5,i,j).prob(). Parameters i,j are signal and backgroud hypothesis: (0 = electron, 1 = muon, 2 = pion, 3 = kaon, 4 = proton)

eIDBelle

returns Belle’s electron ID eid(3,-1,5).prob() variable.

muIDBelle

returns Belle’s PID Muon_likelihood() variable.

muIDBelleQuality

returns true if Belle’s PID Muon_likelihood() is usable (reliable).

Miscellaneous

Other variable that can be handy in development:

False

returns always 0, used for testing and debugging.

True

returns always 1, used for testing and debugging.

decayTypeRecoil

type of the particle decay(no related mcparticle = -1, hadronic = 0, direct leptonic = 1, direct semileptonic = 2,lower level leptonic = 3.

eventRandom

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

infinity

returns std::numeric_limits<double>::infinity()

mcMomTransfer2

Return the true momentum transfer to lepton pair in a B(semi -) leptonic B meson decay.

nRemainingTracksInEvent

Number of tracks in the event - Number of tracks( = charged FSPs) of particle.

printParticle

For debugging, print Particle and daughter PDG codes, plus MC match. Returns 0.

random

return a random number between 0 and 1 for each candidate. Can be used, e.g. for picking a randomcandidate in the best candidate selection.

trackMatchType

-1 particle has no ECL cluster, 0 particle has no associated track, 1 there is a matched trackcalled connected - region(CR) track match

Calibration

There are several variables also available for calibration experts who are working on cdst format files.

Warning

Many of these will not work for- and should not be used by- normal analyses.

They have a [Calibration] pretag.

eventT0

[Eventbased][Calibration] The Event t0, measured in ns, is the time of the event relative to the trigger time. The event time can be measured by several sub-detectors including the CDC, ECL, and TOP. This Event t0 variable is the final combined value of all the event time measurements. (Currently only the CDC and ECL are used in this combination.)

clusterUncorrE

[Expert] [Calibration] Returns ECL cluster’s uncorrected energy. That is, before leakage corrections. This variable should only be used for study of the ECL. Please see clusterE.

eclEnergy3BWDBarrel

[Calibration] Returns energy sum of three crystals in backward barrel.

eclEnergy3BWDEndcap

[Calibration] Returns energy sum of three crystals in backward endcap.

eclEnergy3FWDBarrel

[Calibration] Returns energy sum of three crystals in forward barrel.

eclEnergy3FWDEndcap

[Calibration] Returns energy sum of three crystals in forward endcap.

clusterNumberOfTCs(i, j, k, l)

[Calibration] Returns the number of TCs for this ECL cluster for a given TC theta ID range \((i, j)\) and hit window \((k, l)\).

clusterTCFADC(i, j, k, l)

[Calibration] Returns the total FADC sum related to this ECL cluster for a given TC theta ID range \((i, j)\) and hit window \((k, l)\).

clusterTCIsMaximum

[Calibration] Returns True if cluster is related to maximum TC.

clusterTrigger

[Calibration] Returns 1.0 if ECL cluster is matched to a trigger cluster (requires to run eclTriggerClusterMatcher (which requires TRGECLClusters in the input file)) and 0 otherwise. Returns -1 if the matching code was not run. NOT FOR PHASE2 DATA!

eclEnergySumECLCalDigitInECLCluster

[Eventbased][Calibration] Returns energy sum (in GeV) of all ECLCalDigits that are part of an ECL cluster above eclEnergySumTCECLCalDigitInECLClusterThreshold within TC thetaid 2-15.

eclEnergySumTC(i, j)

[Eventbased][Calibration] Returns energy sum (in FADC counts) of all TC cells between two theta ids i<=thetaid<=j, 1 based (1..17)

eclEnergySumTCECLCalDigit(i, j, k, l)

[Eventbased][Calibration] Returns energy sum (in GeV) of all TC cells between two theta ids i<=thetaid<=j, 1 based (1..17). k is the sum option: 0 (all), 1 (those with actual TC entries), 2 (sum of ECLCalDigit energy in this TC above threshold). l is the threshold parameter for the option k 2.

eclEnergySumTCECLCalDigitInECLCluster

[Eventbased][Calibration] Returns energy sum (in GeV) of all ECLCalDigits if TC is above threshold that are part of an ECLCluster above eclEnergySumTCECLCalDigitInECLClusterThreshold within TC thetaid 2-15.

eclEnergySumTCECLCalDigitInECLClusterThreshold

[Eventbased][Calibration] Returns threshold used to calculate eclEnergySumTCECLCalDigitInECLCluster.

eclEnergyTC(i)

[Eventbased][Calibration] Returns the energy (in FADC counts) for the \(i\)-th trigger cell (TC), 1 based (1..576).

eclEnergyTCECLCalDigit(i)

[Eventbased][Calibration] Returns the energy (in GeV) for the \(i\)-th trigger cell (TC) based on ECLCalDigits, 1 based (1..576).

eclEventTimingTC

[Eventbased][Calibration] Returns the ECL TC event time (in ns).

eclHitWindowTC(i)

[Eventbased][Calibration] Returns the hit window for the \(i\)-th trigger cell (TC), 1 based (1..576).

eclMaximumTCId

[Eventbased][Calibration] Returns the TC ID with maximum FADC value.

eclNumberOfTCs(i, j, k)

[Eventbased][Calibration] Returns the number of TCs above threshold (i=FADC counts) for this event for a given theta range (j-k)

eclTimingTC(i)

[Eventbased][Calibration] Returns the time (in ns) for the \(i\)-th trigger cell (TC), 1 based (1..576).

eclTimingTCECLCalDigit(i)

[Eventbased][Calibration] Returns the time (in ns) for the \(i\)-th trigger cell (TC) based on ECLCalDigits, 1 based (1..576)

6.3.3. Collections and Lists

To avoid very long lists of variable names in variablesToNtuple, it is possible to use collections of variables or lists of variables instead.

Lists of variables are just python lists of variables names. One can use the list in the steering file as follows:

# Defining the list
my_list = ['p','E']

# Passing it as an argument to variablesToNtuple
modularAnalysis.variablesToNtuple(variables=my_list, ...)

It is also possible to create user-defined variable collections. The name of the variable collection can be treated as a variable name.

variables.utils.add_collection(list_of_variables: Iterable[str], collection_name: str) → str

The function creates variable collection from the given list of variables It wraps the VariableManager.addCollection method which is not particularly user-friendly.

Example

Defining the collection >>> variables.utils.add_collection([‘p’,’E’], “my_collection”)

Passing it as an argument to variablesToNtuple >>> modularAnalysis.variablesToNtuple(variables=[‘my_collection’], …)

Parameters

• list_of_variables (list(str)) – list of variable names

• collection_name (str) – name of the collection

Returns

name of the variable collection

Return type

str

Predefined collections

We provide several predefined lists of variables. For each predefined list, there is a collection with the same name:

variables.collections.belle_track_hit = ['BelleFirstCDCHitX', 'BelleFirstCDCHitY', 'BelleFirstCDCHitZ', 'BelleLastCDCHitX', 'BelleLastCDCHitY', 'BelleLastCDCHitZ']

Belle Track CDC hit variables

variables.collections.cluster = ['clusterPulseShapeDiscriminationMVA', 'clusterHasPulseShapeDiscrimination', 'clusterNumberOfHadronDigits', 'clusterDeltaLTemp', 'minC2TDist', 'nECLClusterTrackMatches', 'clusterZernikeMVA', 'clusterReg', 'clusterAbsZernikeMoment40', 'clusterAbsZernikeMoment51', 'clusterBelleQuality', 'clusterClusterID', 'clusterConnectedRegionID', 'clusterE1E9', 'clusterE9E21', 'clusterE9E25', 'clusterEoP', 'clusterErrorE', 'clusterErrorPhi', 'clusterErrorTheta', 'clusterErrorTiming', 'clusterHighestE', 'clusterHasFailedErrorTiming', 'clusterHasFailedTiming', 'clusterHasNPhotons', 'clusterHasNeutralHadron', 'clusterLAT', 'clusterNHits', 'clusterPhi', 'clusterR', 'clusterSecondMoment', 'clusterTheta', 'clusterTiming', 'clusterTrackMatch', 'goodBelleGamma', 'nECLOutOfTimeCrystals', 'nECLOutOfTimeCrystalsBWDEndcap', 'nECLOutOfTimeCrystalsBarrel', 'nECLOutOfTimeCrystalsFWDEndcap', 'nRejectedECLShowers', 'nRejectedECLShowersBWDEndcap', 'nRejectedECLShowersBarrel', 'nRejectedECLShowersFWDEndcap']

Cluster-related variables

variables.collections.cluster_average = ['maxWeightedDistanceFromAverageECLTime', 'weightedAverageECLTime']

Cluster averages

variables.collections.dalitz_3body = ['daughterInvM(0, 1)', 'daughterInvM(0, 2)', 'daughterInvM(1, 2)']

Dalitz masses for three body decays

variables.collections.deltae_mbc = ['Mbc', 'deltaE']

Replacement for DeltaEMbc

variables.collections.event_kinematics = ['missingMomentumOfEvent', 'missingMomentumOfEvent_Px', 'missingMomentumOfEvent_Py', 'missingMomentumOfEvent_Pz', 'missingMomentumOfEvent_theta', 'missingMomentumOfEventCMS', 'missingMomentumOfEventCMS_Px', 'missingMomentumOfEventCMS_Py', 'missingMomentumOfEventCMS_Pz', 'missingMomentumOfEventCMS_theta', 'missingEnergyOfEventCMS', 'missingMass2OfEvent', 'visibleEnergyOfEventCMS', 'totalPhotonsEnergyOfEvent']

Variables created by event kinematics module

variables.collections.event_level_tracking = ['nExtraCDCHits', 'nExtraCDCHitsPostCleaning', 'hasExtraCDCHitsInLayer(0)', 'hasExtraCDCHitsInLayer(1)', 'hasExtraCDCHitsInLayer(2)', 'hasExtraCDCHitsInLayer(3)', 'hasExtraCDCHitsInLayer(4)', 'hasExtraCDCHitsInLayer(5)', 'hasExtraCDCHitsInLayer(6)', 'hasExtraCDCHitsInLayer(7)', 'nExtraCDCSegments', 'trackFindingFailureFlag']

Event level tracking variables

variables.collections.event_shape = ['foxWolframR1', 'foxWolframR2', 'foxWolframR3', 'foxWolframR4', 'harmonicMomentThrust0', 'harmonicMomentThrust1', 'harmonicMomentThrust2', 'harmonicMomentThrust3', 'harmonicMomentThrust4', 'cleoConeThrust0', 'cleoConeThrust1', 'cleoConeThrust2', 'cleoConeThrust3', 'cleoConeThrust4', 'cleoConeThrust5', 'cleoConeThrust6', 'cleoConeThrust7', 'cleoConeThrust8', 'sphericity', 'aplanarity', 'thrust', 'thrustAxisCosTheta']

Event shape variables

variables.collections.extra_energy = ['roeEextra()']

Extra energy variables

variables.collections.flight_info = ['flightTime', 'flightDistance', 'flightTimeErr', 'flightDistanceErr']

Flight info variables

variables.collections.inv_mass = ['M', 'ErrM', 'SigM', 'InvM']

Replacement for InvMass tool

variables.collections.kinematics = ['px', 'py', 'pz', 'pt', 'p', 'E']

Replacement to Kinematics tool

variables.collections.klm_cluster = ['klmClusterKlId', 'klmClusterTiming', 'klmClusterPositionX', 'klmClusterPositionY', 'klmClusterPositionZ', 'klmClusterInnermostLayer', 'klmClusterLayers', 'klmClusterEnergy', 'klmClusterMomentum', 'klmClusterIsBKLM', 'klmClusterIsEKLM', 'klmClusterIsForwardEKLM', 'klmClusterIsBackwardEKLM', 'klmClusterTheta', 'klmClusterPhi', 'nKLMClusterTrackMatches', 'nMatchedKLMClusters']

KLM cluster information

variables.collections.mc_event_kinematics = ['genMissingMass2OfEvent', 'genMissingEnergyOfEventCMS', 'genMissingMomentumOfEventCMS', 'genTotalPhotonsEnergyOfEvent', 'genVisibleEnergyOfEventCMS']

Variables created by MC version of event kinematics module

variables.collections.mc_flight_info = ['mcFlightTime', 'mcFlightDistance']

MC true flight info variables

variables.collections.mc_kinematics = ['mcE', 'mcP', 'mcPT', 'mcPX', 'mcPY', 'mcPZ', 'mcPhi']

Replacement for MCKinematics tool

variables.collections.mc_tag_vertex = ['mcDeltaTau', 'mcDeltaT', 'mcDeltaBoost', 'mcTagVLBoost', 'mcTagVOBoost', 'mcLBoost', 'mcOBoost', 'mcTagVx', 'mcTagVy', 'mcTagVz']

Tag-side related MC true variables

variables.collections.mc_truth = ['isSignal', 'mcErrors', 'mcPDG']

Replacement for MCTruth tool

variables.collections.mc_variables = ['genMotherID', 'genMotherP', 'genMotherPDG', 'genParticleID', 'isCloneTrack', 'mcDecayVertexX', 'mcDecayVertexY', 'mcDecayVertexZ', 'mcDecayTime', 'mcE', 'mcErrors', 'mcInitial', 'mcP', 'mcPDG', 'mcPT', 'mcPX', 'mcPY', 'mcPZ', 'mcPhi', 'mcVirtual', 'nMCMatches']

Truth-matching related variables

variables.collections.mc_vertex = ['mcDecayVertexX', 'mcDecayVertexY', 'mcDecayVertexZ', 'mcDecayVertexFromIPDistance', 'mcDecayVertexRho', 'mcProductionVertexX', 'mcProductionVertexY', 'mcProductionVertexZ']

Replacement for MCVertex tuple tool

variables.collections.momentum_uncertainty = ['E_uncertainty', 'pxErr', 'pyErr', 'pzErr']

Replacement for MomentumUnertainty tool

variables.collections.pid = ['kaonID', 'pionID', 'protonID', 'muonID', 'electronID', 'deuteronID']

PID variables

variables.collections.reco_stats = ['nTracks']

Replacement for RecoStats tool

variables.collections.recoil_kinematics = ['pRecoil', 'pRecoilPhi', 'pRecoilTheta', 'pxRecoil', 'pyRecoil', 'pzRecoil']

Recoil kinematics relaed variables

variables.collections.roe_multiplicities = ['nROE_KLMClusters']

Replacement for ROEMultiplicities tool

variables.collections.tag_vertex = ['DeltaT', 'DeltaTErr', 'DeltaZ', 'DeltaZErr', 'DeltaBoost', 'DeltaBoostErr', 'TagVLBoost', 'TagVLBoostErr', 'TagVOBoost', 'TagVOBoostErr', 'TagVpVal', 'TagVNDF', 'TagVChi2', 'TagVChi2IP', 'TagVx', 'TagVxErr', 'TagVy', 'TagVyErr', 'TagVz', 'TagVzErr']

CPV and Tag-side related variables

variables.collections.track = ['dr', 'dx', 'dy', 'dz', 'd0', 'z0', 'pValue', 'ndf']

Tracking variables, replacement for Track tool

variables.collections.track_hits = ['nCDCHits', 'nPXDHits', 'nSVDHits', 'nVXDHits']

Replacement for TrackHits tool

variables.collections.vertex = ['distance', 'significanceOfDistance', 'dx', 'dy', 'dz', 'x', 'y', 'z', 'x_uncertainty', 'y_uncertainty', 'z_uncertainty', 'dr', 'dphi', 'dcosTheta', 'prodVertexX', 'prodVertexY', 'prodVertexZ', 'prodVertexXErr', 'prodVertexYErr', 'prodVertexZErr', 'chiProb']

Replacement for Vertex tuple tool

6.3.4. Operations with variable lists

It is possible to create new variable lists using meta-variables. For example, one can define list of kinematic variables in LAB frame and create another lists of kinematic variables in CMS using useCMSFrame(variable) meta-variable:

from variables.utils import create_aliases
# Replacement to Kinematics tool
kinematics = ['px', 'py', 'pz', 'pt', 'p', 'E']

# Kinematic variables in CMS
cms_kinematics = create_aliases(kinematics, "useCMSFrame({variable})", "CMS")

Now we can use the list of aliases cms_kinematics and add them to the output in one go or modify them further. The following functions are provided to help to easily create aliases.

variables.utils.create_aliases(list_of_variables: Iterable[str], wrapper: str, prefix: str) → List[str]

The function creates aliases for variables from the variables list with given wrapper and returns list of the aliases.

If the variables in the list have arguments (like useLabFrame(p)) all non-alphanumeric characters in the variable will be replaced by underscores (for example useLabFrame_x) for the alias name.

>>> list_of_variables = ['M','p','matchedMC(useLabFrame(px))']
>>> wrapper = 'daughter(1,{variable})'
>>> prefix = 'pref'
>>> print(create_aliases(list_of_variables, wrapper, prefix))
['pref_M', 'pref_p', 'pref_matchedMC_useLabFrame_px']
>>> from variables import variables
>>> variables.printAliases()
[INFO] =====================================
[INFO] The following aliases are registered:
[INFO] pref_M                        --> daughter(1,M)
[INFO] pref_matchedMC_useLabFrame_px --> daughter(1,matchedMC(useLabFrame(px)))
[INFO] pref_p                        --> daughter(1,p)
[INFO] =====================================

Parameters

• list_of_variables (list(str)) – list of variable names

• wrapper (str) – metafunction taking variables from list_of_variables as a parameter (<metafunction>(<some configs>, {variable} ,<some other configs>)

• prefix (str) – alias prefix used for wrapped variables.

Returns

new variables list

Return type

list(str)

variables.utils.create_aliases_for_selected(list_of_variables: List[str], decay_string: str, prefix: Union[str, List[str], None] = None, *, use_names=True, always_include_indices=False, use_relative_indices=False) → List[str]

The function creates list of aliases for given variables so that they are calculated for particles selected in decay string. That is for each particle selected in the decay string an alias is created to calculate each variable in the list_of_variables.

If use_names=True (the default) then the names of the aliases are assigned as follows:

• If names are unambiguous, it’s semi-laconic DecayString style: The aliases will be prefixed with the names of all parent particle names separated by underscore. For example given the decay string B0 -> [D0 -> ^pi+ K-] pi0 the aliases for the pi+` will start with ``D0_pi_ followed by the variable name.

  >>> list_of_variables = ['M','p']
  >>> decay_string = 'B0 -> [D0 -> ^pi+ K-] pi0'
  >>> create_aliases_for_selected(list_of_variables, decay_string)
  ['D0_pi_M', 'D0_pi_p']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'D0_pi_M' --> 'daughter(0,daughter(0,M))'
  [INFO] 'D0_pi_p' --> 'daughter(0,daughter(0,p))'
  [INFO] =========================
  

• If names are ambiguous because there are multiple daughters with the same name these particles will be followed by their daughter index. For example given the decay string B0 -> [D0 -> ^pi+:1 ^pi-:2 ^pi0:3 ] ^pi0:4 will create aliases with the following prefixes for particle with the corresponding number as list name:

  1. D0_pi_0_

  2. D0_pi_1_

  3. D0_pi0_

  4. pi0_

  >>> list_of_variables = ['M','p']
  >>> decay_string = 'B0 -> [D0 -> ^pi+ ^pi- ^pi0] ^pi0'
  >>> create_aliases_for_selected(list_of_variables, decay_string)
  ['D0_pi_0_M', 'D0_pi_0_p', 'D0_pi_1_M', 'D0_pi_1_p',
  'D0_pi0_M', 'D0_pi0_p', 'pi0_M', 'pi0_p']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'D0_pi0_M' --> 'daughter(0,daughter(2,M))'
  [INFO] 'D0_pi0_p' --> 'daughter(0,daughter(2,p))'
  [INFO] 'D0_pi_0_M' --> 'daughter(0,daughter(0,M))'
  [INFO] 'D0_pi_0_p' --> 'daughter(0,daughter(0,p))'
  [INFO] 'D0_pi_1_M' --> 'daughter(0,daughter(1,M))'
  [INFO] 'D0_pi_1_p' --> 'daughter(0,daughter(1,p))'
  [INFO] 'D0_pi_M' --> 'daughter(0,daughter(0,M))'
  [INFO] 'D0_pi_p' --> 'daughter(0,daughter(0,p))'
  [INFO] 'pi0_M' --> 'daughter(1,M)'
  [INFO] 'pi0_p' --> 'daughter(1,p)'
  [INFO] =========================
  

• The user can select to always include the index even for unambiguous particles by passing always_include_indices=True

• The user can choose two different numbering schemes: If use_relative_indices=False the original decay string indices will be used if a index is added to a particle name.

  But if use_relative_indices=True the indices will just start at zero for each particle which is part of the prefixes. For example for B0-> e+ ^e-

  >>> create_aliases_for_selected(['M'], 'B0-> mu+ e- ^e+ ^e-', use_relative_indices=False)
  ['e_2_M', 'e_3_M']
  >>> create_aliases_for_selected(['M'], 'B0-> mu+ e- ^e+ ^e-', use_relative_indices=True)
  ['e_0_M', 'e_1_M']
  

If use_names=False the aliases will just start with the daughter indices of all parent particles prefixed with a d and separated by underscore. So for the previous example B0 -> [D0 -> ^pi+:1 ^pi-:2 ^pi0:3 ] ^pi0:4 this would result in aliases starting with

1. d0_d0_

2. d0_d1_

3. d0_d2_

4. d1_

In this case the always_include_indices and use_relative_indices arguments are ignored.

The naming can be modified by providing a custom prefix for each selected particle. In this case the parameter prefix needs to be either a simple string if only one particle is selected or a list of strings with one prefix for each selected particle.

>>> list_of_variables = ['M','p']
>>> decay_string = 'B0 -> [D0 -> ^pi+ ^pi- pi0] pi0'
>>> create_aliases_for_selected(list_of_variables, decay_string, prefix=['pip', 'pim'])
['pip_M', 'pip_p', 'pim_M', 'pim_p']
>>> from variables import variables
>>> variables.printAliases()
[INFO] =========================
[INFO] Following aliases exists:
[INFO] 'pim_M' --> 'daughter(0,daughter(1,M))'
[INFO] 'pim_p' --> 'daughter(0,daughter(1,p))'
[INFO] 'pip_M' --> 'daughter(0,daughter(0,M))'
[INFO] 'pip_p' --> 'daughter(0,daughter(0,p))'
[INFO] =========================

If the mother particle itself is selected the input list of variables will also be added to the returned list of created aliases. If custom prefixes are supplied then aliases will be created for the mother particle as well:

>>> create_aliases_for_selected(['M', 'p'], '^B0 -> pi+ ^pi-')
['M', 'p', 'pi_M', 'pi_p']
>>> create_aliases_for_selected(['M', 'p'], '^B0 -> pi+ ^pi-', prefix=['MyB', 'MyPi'])
['MyB_M', 'MyB_p', 'MyPi_M', 'MyPi_p']

Parameters

• list_of_variables (list(str)) – list of variable names

• decay_string (str) – Decay string with selected particles

• prefix (str, list(str)) – Custom prefix for all selected particles

• use_names (bool) – Include the names of the particles in the aliases

• always_include_indices (bool) – If use_names=True include the decay index of the particles in the alias name even if the particle could be uniquely identified without them.

• use_relative_indices (bool) – If use_names=True use a relative indicing which always starts at 0 for each particle appearing in the alias names independent of the absolute position in the decay string

Returns

new variables list

Return type

list(str)

variables.utils.create_daughter_aliases(list_of_variables: Iterable[str], indices: Union[int, Iterable[int]], prefix='', include_indices=True) → List[str]

Create Aliases for all variables for a given daughter hierarchy

Parameters

• list_of_variables (list(str)) – list of variables to create aliases for

• indices (int or list(int)) – index of the daughter, grand-daughter, grand-grand-daughter, and so forth

• prefix (str) – optional prefix to prepend to the aliases

• include_indices (bool) – if set to True (default) the aliases will contain the daughter indices as dX_dY_dZ…

Returns

new variables list

Return type

list(str)

• create aliases for the second daughter as “d1_E”, “d1_M” (daughters start at 0)

  >>> create_daughter_aliases(["E", "m"], 1)
  ['d1_E', 'd1_m']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'd1_E' --> 'daughter(1,E)'
  [INFO] 'd1_m' --> 'daughter(1,m)'
  [INFO] =========================
  

• create aliases for the first grand daughter of the second daughter, starting with “my” and without including the indices, resulting in “my_E”, “my_m”

  >>> create_daughter_aliases(["E", "m"], [1, 0], prefix="my", include_indices=False)
  ['my_E', 'my_m']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'my_E' --> 'daughter(1,daughter(0,E))'
  [INFO] 'my_m' --> 'daughter(1,daughter(0,m))'
  [INFO] =========================
  

• create aliases for the second grand grand daughter of the third grand daughter of the fifth daugther, starting with my and including the indices, resulting in “my_d4_d2_d1_E”, “my_d4_d2_d1_m”

  >>> create_daughter_aliases(["E", "m"], [4, 2, 1], prefix="my")
  ['my_d4_d2_d1_E', 'my_d4_d2_d1_m']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'my_d4_d2_d1_E' --> 'daughter(4,daughter(2,daughter(1,E))'
  [INFO] 'my_d4_d2_d1_m' --> 'daughter(4,daughter(2,daughter(1,m))'
  [INFO] =========================
  

variables.utils.create_mctruth_aliases(list_of_variables: Iterable[str], prefix='mc') → List[str]

The function wraps variables from the list with ‘matchedMC()’.

>>> list_of_variables = ['M','p']
>>> create_mctruth_aliases(list_of_variables)
['mc_M', 'mc_p']
>>> from variables import variables
>>> variables.printAliases()
[INFO] =========================
[INFO] Following aliases exists:
[INFO] 'mc_M' --> 'matchedMC(M)'
[INFO] 'mc_p' --> 'matchedMC(p)'
[INFO] =========================

Parameters

list_of_variables (list(str)) – list of variable names

Returns

list of created aliases

Return type

list(str)

variables.utils.create_isSignal_alias(aliasName, flags)

Make a VariableManager alias for a customized isSignal, which accepts specified mc match errors.

See also

see MC matching for a definition of the mc match error flags.

The following code defines a new variable isSignalAcceptMissingGammaAndMissingNeutrino, which is same as isSignal, but also accepts missing gamma and missing neutrino

>>> create_isSignal_alias("isSignalAcceptMissingGammaAndMissingNeutrino", [16, 8])

Logically, this isSignalAcceptMissingGammaAndMissingNeutrino = isSignalAcceptMissingGamma || isSignalAcceptMissingNeutrino.

In the example above, create_isSignal_alias() creates isSignalAcceptMissingGammaAndMissingNeutrino by unmasking (setting bits to zero) the c_MissGamma bit (16 or 0b00010000) and c_MissNeutrino bit (8 or 0b00001000) in mcErrors.

For more information, please check this example script.

Parameters

• aliasName (str) – the name of the alias to be set

• flags (list(int)) – a list of the bits to unmask

6.3.5. Miscellaneous helpers for using variables

variables.getAllTrgNames()

Return all PSNM trigger bit names

variables.std_vector(*args)

Creates an std::vector which can be passed to pyROOT

variables.printVars(changedVariableNames=None)

Print list of all available variables.

6.3.6. Writing your own variable

The code of VariableManager lives inside the analysis package. If you want to write your own variables you have a couple of options. You can (and should) try to make your variables general, so that they are useful for many collaborators. In this case, we recommend you make a pull request. Then your variables will be made available in a central release to many people.

In case you have something really analysis-specific that no one else will need. You can still use the VariableManager.

Below are step-by-step instructions for implementation of helicity angle for arbitrary granddaughter particle.

Step 1. Check whether your function would fit in any of the existing source files

If yes, go to the next step.

If not, create new header/source files. In case of our example, we will create AngularVariables.h and AngularVariables.cc

AngularVariables.h in analysis/VariableManager/include/:

#pragma once
// include VariableManager
#include <analysis/VariableManager/Manager.h>

// include the Belle II Particle class
#include <analysis/dataobjects/Particle.h>

// put variable in the Belle2::Variable namespace
namespace Belle2 {
  namespace Variable {

    // Your code goes here

  } // Variable namespace
} // Belle2 namespace

AngularVariables.cc in analysis/VariableManager/src/:

// Own include
#include <analysis/VariableManager/AngularVariables.h>

// put variable in the Belle2::Variable namespace
namespace Belle2 {
  namespace Variable {

    // Your code goes here
  } // Variable namespace
} // Belle2 namespace

Step 2. Add function definition in the header file

Here we define a method helicityAngle that has 3 arguments:

• pointer to a Particle

• index of the daughter Particle

• index of the granddaughter (daughter’s daughter) Particle

in the AngularVariable.h header file. The return value of every variable has to be double.

/**
  * returns cosine of the helicity angle: angle between granddaughter and this particle in the daughter's rest frame.
  * The daughter and granddaughter particles are specified with the additional parameter.
  */
double helicityAngle(const Particle* particle, const std::vector<double>& daughter_indices);

Step 3. Implement the function in the source file

• Info on getters for the Particle class

• Info on getters for the TLorentzVector class

• Pictorial definition of the helicity angle

double helicityAngle(const Particle* particle, const std::vector<double>& daughter_indices) {
  // for the calculation of the helicity angle we need particle (=particle in the argument)
  // its daughter and granddaughter. The particle is given as an argument, but the daughter
  // and granddaughter are specified as the indices in the vector (second argument)
  // daughter_indices[0] = index of the daughter
  // daughter_indices[1] = index of the granddaughter

  if (!particle)
    return std::numeric_limits<float>::quiet_NaN();
  int nDaughters = particle->getNDaughters();
  if(nDaughters < 2)
    return std::numeric_limits<float>::quiet_NaN();
  if (daughter_indices.size() != 2)
    return std::numeric_limits<float>::quiet_NaN();

  // get the daughter particle
  int daughterIndex = daughter_indices[0];
  const Particle *daughter = particle->getDaughter(daughterIndex);
  nDaughters = daughter->getNDaughters();
  if(nDaughters < 2)
    return std::numeric_limits<float>::quiet_NaN();

  // get the granddaughter
  int grandDaughterIndex = daughter_indices[1];
  const Particle *grandDaughter = daughter->getDaughter(grandDaughterIndex);

  // do the calculation
  TLorentzVector particle4Vector = particle->get4Vector();
  TLorentzVector daughter4Vector = daughter->get4Vector();
  TLorentzVector gDaughter4Vector = grandDaughter->get4Vector();
  TVector3 boost2daughter = -(daughter4Vector.BoostVector());
  particle4Vector.Boost(boost2daughter);
  gDaughter4Vector.Boost(boost2daughter);
  TVector3 particle3Vector = particle4Vector.Vect();
  TVector3 gDaughter3Vector = gDaughter4Vector.Vect();
  double numerator = gDaughter3Vector.Dot(particle3Vector);
  double denominator = (gDaughter3Vector.Mag())*(particle3Vector.Mag());
  return numerator/denominator;
}

Step 4. Register the new variable

At the end of the source file, add the following lines:

VARIABLE_GROUP("AngularVariables");
REGISTER_VARIABLE("helicityAngle(i,j)", helicityAngle,
                "cosine of the angle between particle->getDaughter(i)->getDaughter(j) and this particle in the  particle->getDaughter(i) rest frame.");

Step 5. Compile

Execute scons in your local release directory

Step 6. Done!

You can check if your variable is visible to VariableManager

>>> basf2 analysis/scripts/variables.py
AngularVariables: helicityAngle(i,j) cosine of the angle between particle->getDaughter(i)->getDaughter(j) and this particle in the particle->getDaughter(i) rest frame.

You can use your variable in the same way as you use standard variables.

How to use my variable at grid?

• Prepare the environment with the b2analysis-create tool.

>>> b2analysis-create myanalysis <current central release, e.g. release-04-00-00>
>>> cd myanalysis
>>> setupana

• Define the new variables/functions in a .cc and register them with the variable manager. This means that in the new .cc you should add:

#include <framework/core/Module.h>
#include <analysis/VariableManager/Manager.h>
#include <analysis/dataobjects/Particle.h>
namespace Belle2 {
  namespace Variable {
      double myVarFunction(const Particle* particle) { **your code** }
      VARIABLE_GROUP("CUSTOM_VARIABLES");
      REGISTER_VARIABLE("myVar", myVarFunction, "My custom variable");
  }
  // Create an empty module which does nothing at all. What it does is allowing
  // basf2 to easily find the library and load it from the steering file
  class EnableMyVariableModule: public Module {}; // And register this module to create a .map lookup file.
  REG_MODULE(EnableMyVariable);
}

Then:

• Run scons and you will get a .so and a .b2modmap files in modules/Linux_x86_64/opt.

• Load the libraries and make the variables available you need to add these lines to your steering file:

import basf2
basf2.fw.add_module_search_path(".")
basf2.register_module("EnableMyVariable") # now you can use it
from variables import variables
print(variables.getVariable("myVar").description)

These lines will add the local directory to the module search path and instantiate the module we created. This is enough to load the library and register the variables. Now you should be able to use your custom variables for your analysis and there is no need to add this module to the path, it just needs to be registered to load the library.

In the end you can run your analysis on the grid adding the .so and .map files to the input sandbox with the -f option of gbasf2:

>>> gbasf2 ./steering.py -p project -i dataset -f myanalysis.so myanalysis.b2modmap

Warning

This line implies that you already have working gbasf2 installation and gbasf2 syntax didn’t change since the moment of writing. Please refer gbasf2 documentation for more details.