7.1.1. Standard Particles#

Warning

Construction site!

At the moment, we are in a strange situation where some of the standard particle lists are actually not recommended for use with recent data processings.

However, some of these lists have been tested and can be used.

Tip

The following pi0 and V0 standard lists are good (i.e. recommended for use):

However, please check this Neutrals Performance confluence page for the latest updates.

Tip

The following standard lepton lists are good (i.e. recommended for use):

for a choice of the input listtype parameter among:

  • ‘FixedThresh05’

  • ‘FixedThresh09’

  • ‘FixedThresh095’

  • ‘UniformEff60’

  • ‘UniformEff70’

  • ‘UniformEff80’

  • ‘UniformEff90’

  • ‘UniformEff95’

However, please check the Lepton ID Performance confluence page for the latest updates.

The ultimate goal is that these standard particle lists will provide recommended selection criteria for final-state particles, and in some cases, for composite particles. The recommended selections will be provided by the performance group(s). Furthermore the intention is that systematics will be provided centrally for these recommended lists. For information about their status, please see 4045.

There are also some skimming, development and legacy lists available. These are specifically for use in skims, for study, or for comparison with Belle and old simulations. If you don’t know that you specifically need these legacy/skim lists, then avoid them.

Default final-state particle list builder functions#

stdPi0s.stdPi0s(listtype='eff60_May2020', path=None, beamBackgroundMVAWeight='', fakePhotonMVAWeight='', biasCorrectionTable='')[source]#

Function to prepare one of several standardized types of pi0 lists:

  • ‘all’ using gamma:all

  • ‘eff10_May2020’ gamma:pi0eff10_May2020, mass range selection, 10% pi0 efficiency list, optimized in May 2020

  • ‘eff20_May2020’ gamma:pi0eff20_May2020, mass range selection, 20% pi0 efficiency list, optimized in May 2020

  • ‘eff30_May2020’ gamma:pi0eff30_May2020, mass range selection, 30% pi0 efficiency list, optimized in May 2020

  • ‘eff40_May2020’ gamma:pi0eff40_May2020, mass range selection, 40% pi0 efficiency list, optimized in May 2020

  • ‘eff50_May2020’ gamma:pi0eff50_May2020, mass range selection, 50% pi0 efficiency list, optimized in May 2020

  • ‘eff60_May2020’ gamma:pi0eff60_May2020, mass range selection, 60% pi0 efficiency list, optimized in May 2020

You can also append “Fit” to the listtype which will run a mass fit and require that the fit did not fail. For example: “pi0:eff50_May2020Fit” is the 50% efficiency list plus a not-failing mass fit.

Parameters

  • listtype (str) – name of standard list

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

  • beamBackgroundMVAWeight (str) –

    type of weight file for beam background MVA; if empty, beam background MVA will not be used

    Tip

    Please refer to the Neutrals Performance Confluence page for information on the beam background MVA.

  • fakePhotonMVAWeight (str) –

    type of weight file for fake photon MVA; if empty, fake photon MVA will not be used

    Tip

    Please refer to the Neutrals Performance Confluence page for information on the fake photon MVA.

  • biasCorrectionTable (str) –

    correction table for the photon energy bias correction (should only be applied to data)

    Tip

    Please refer to the Neutrals Performance Confluence page for information on the names of available correction tables.

stdV0s.stdKshorts(prioritiseV0=True, fitter='TreeFit', path=None, updateAllDaughters=False, writeOut=False)[source]#

Load a combined list of the Kshorts list from V0 objects merged with a list of particles combined using the analysis ParticleCombiner module.

The ParticleList is named K_S0:merged. A vertex fit is performed and only candidates with an invariant mass in the range \(0.450 < M < 0.550~GeV\), and for which the vertex fit did not fail, are kept.

The vertex fitter can be selected among TreeFit, KFit, and Rave.

Parameters

  • prioritiseV0 (bool) – should the V0 mdst objects be prioritised when merging?

  • fitter (str) – vertex fitter name, valid options are TreeFit, KFit, and Rave.

  • path (basf2.Path) – the path to load the modules

  • updateAllDaughters (bool) –

    see the updateAllDaughters parameter of vertex.treeFit or the daughtersUpdate parameter of vertex.kFit / vertex.raveFit.

    Warning

    The momenta of the daughters are updated only if updateAllDaughters is set to True (i.e. not by default). Some variables, e.g. daughterAngle, will only return meaningful results if the daughters momenta are updated.

    This happens because variables like daughterAngle assume the direction of the daughers momenta at the Ks vertex to be provided, while non-updated daughters will provide their momenta direction at the point-of-closest-approach (POCA) to the beam axis.

  • writeOut (bool) – whether RootOutput module should save the created ParticleList

stdV0s.stdLambdas(prioritiseV0=True, fitter='TreeFit', path=None, updateAllDaughters=False, writeOut=False)[source]#

Load a combined list of the Lambda list from V0 objects merged with a list of particles combined using the analysis ParticleCombiner module.

The ParticleList is named Lambda0:merged. A vertex fit is performed and only candidates with an invariant mass in the range \(1.10 < M < 1.13~GeV\), and for which the vertex fit did not fail, are kept.

The vertex fitter can be selected among TreeFit, KFit, and Rave.

Parameters

  • prioritiseV0 (bool) – should the V0 mdst objects be prioritised when merging?

  • fitter (str) – vertex fitter name, valid options are TreeFit, KFit, and Rave.

  • path (basf2.Path) – the path to load the modules

  • updateAllDaughters (bool) –

    see the updateAllDaughters parameter of vertex.treeFit or the daughtersUpdate parameter of vertex.kFit / vertex.raveFit.

    Warning

    The momenta of the daughters are updated only if updateAllDaughters is set to True (i.e. not by default). Some variables, e.g. daughterAngle, will only return meaningful results if the daughters momenta are updated.

    This happens because variables like daughterAngle assume the direction of the daughers momenta at the Lambda vertex to be provided, while non-updated daughters will provide their momenta direction at the point-of-closest-approach (POCA) to the beam axis.

  • writeOut (bool) – whether RootOutput module should save the created ParticleList

stdCharged.stdE(listtype='good', method=None, classification=None, lid_weights_gt=None, release=None, channel_eff='combination', channel_misid_pi='combination', channel_misid_K='combination', inputListName=None, outputListLabel=None, trainingModeMulticlass=1, trainingModeBinary=0, path=None)[source]#

Function to prepare one of several standardized types of electron lists. See the documentation of stdLep for details.

It also accepts any of the legacy definitions for the listtype parameter (aka working_point in stdLep) to fall back to the stdCharged behaviour:

  • ‘all’

  • ‘good’

  • ‘loosepid’

  • ‘loose’

  • ‘higheff’

  • ‘95eff’

  • ‘90eff’

  • ‘85eff’

Returns

the alias for the electron ID variable, and the list of aliases for the weights.

Return type

tuple(str, list(str))

stdCharged.stdMu(listtype='good', method=None, classification=None, lid_weights_gt=None, release=None, channel_eff='combination', channel_misid_pi='combination', channel_misid_K='combination', inputListName=None, outputListLabel=None, trainingModeMulticlass=1, trainingModeBinary=0, path=None)[source]#

Function to prepare one of several standardized types of muon lists. See the documentation of stdLep for details.

It also accepts any of the legacy definitions for the listtype parameter (aka working_point in stdLep) to fall back to the stdCharged behaviour:

  • ‘all’

  • ‘good’

  • ‘loosepid’

  • ‘loose’

  • ‘higheff’

  • ‘95eff’

  • ‘90eff’

  • ‘85eff’

Returns

the alias for the muon ID variable, and the list of aliases for the weights.

Return type

tuple(str, list(str))

stdCharged.stdLep(pdgId, working_point, method, classification, lid_weights_gt, release=None, channel_eff='combination', channel_misid_pi='combination', channel_misid_K='combination', inputListName=None, outputListLabel=None, trainingModeMulticlass=1, trainingModeBinary=0, path=None)[source]#

Function to prepare one of several standardized types of lepton (\(e,\mu\)) lists, with the following working points:

  • ‘FixedThresh05’, PID cut of > 0.5 for each particle in the list.

  • ‘FixedThresh09’, PID cut of > 0.9 for each particle in the list.

  • ‘FixedThresh095’, PID cut of > 0.95 for each particle in the list.

  • ‘FixedThresh099’, PID cut of > 0.99 for each particle in the list.

  • ‘UniformEff60’ 60% lepton efficiency list, uniform in a given multi-dimensional parametrisation.

  • ‘UniformEff70’ 70% lepton efficiency list, uniform in a given multi-dimensional parametrisation.

  • ‘UniformEff80’ 80% lepton efficiency list, uniform in a given multi-dimensional parametrisation.

  • ‘UniformEff90’ 90% lepton efficiency list, uniform in a given multi-dimensional parametrisation.

  • ‘UniformEff95’ 95% lepton efficiency list, uniform in a given multi-dimensional parametrisation.

  • ‘UniformPiFR5EM1’ 50% pion to lepton fake rate, uniform in a given multi-dimensional parametrisation.

  • ‘UniformPiFR1EM1’ 10% pion to lepton fake rate, uniform in a given multi-dimensional parametrisation.

  • ‘UniformPiFR5EM2’ 5% pion to lepton fake rate, uniform in a given multi-dimensional parametrisation.

  • ‘UniformPiFR1EM2’ 1% pion to lepton fake rate, uniform in a given multi-dimensional parametrisation.

  • ‘UniformPiFR5EM3’ 0.5% pion to lepton fake rate, uniform in a given multi-dimensional parametrisation.

  • ‘UniformPiFR1EM3’ 0.1% pion to lepton fake rate, uniform in a given multi-dimensional parametrisation.

The function creates a ParticleList, selecting particles according to the chosen working_point, and decorates each candidate in the list with the nominal Data/MC \(\ell\) ID efficiency and \(\pi,K\) fake rate correction factors and their stat, syst uncertainty, reading the info from the Conditions Database (CDB) according to the chosen input global tag (GT).

Note

Particles will not be selected if they are outside the Data/MC efficiency corrections’ phase space coverage for the given working point. In fact, the threshold value for the PID cut in such cases is set to NaN.

Warning

At the moment, the only supported binary lepton identification is against the pion hypothesis. This implies that, if binary classification is chosen, only \(\pi\) fake rate corrections will be added to the resulting particle list.

Parameters

  • pdgId (int) – the lepton pdg code.

  • working_point (str) – name of the chosen working point that defines the content of the list. Choose among the above values.

  • method (str) – the PID method: ‘likelihood’ or ‘bdt’.

  • classification (str) – the type of classifier: ‘binary’ (one-vs-pion) or ‘global’ (one-vs-all).

  • lid_weights_gt (str) –

    the name identifier of the global tag with the recommended Data/MC correction weights.

    Tip

    Please refer to the Lepton ID Confluence page for info about the recommended global tags.

  • release (Optional[int]) –

    the major release number of the data and MC campaigns considered. If specified, it ensures the correct \(\ell\) ID variables are used.

    Tip

    Please refer to the Lepton ID Confluence page for info about lepton identification variables and campaigns.

  • channel_eff (Optional[str]) –

    the channel used to derive the \(\ell\) ID efficiency corrections. By default, ‘combination’ is set, meaning they are obtained by combining results of several hadronic and low multiplicity channels, wherever they overlap.

    Tip

    Please refer to the Lepton ID Confluence page for other possible choices (if any).

  • channel_misid_pi (Optional[str]) – the channel used to derive the \(\pi\) fake rate corrections.

  • channel_misid_K (Optional[str]) – the channel used to derive the \(K\) fake rate corrections.

  • inputListName (Optional[str]) –

    the name of a pre-existing ParticleList object (defined as a full decayString, e.g. ‘e-:my_input_electrons’) of which the standard lepton list will be a subset. For instance, users might want to apply a Bremsstrahlung correction to electrons first, which modifies their 4-momentum, and only later define the subset passing the PID selection, including the appropriate PID weights and uncertainties (which are \(p\)-dependent). By default, the standard lepton list is created from all Track objects in the event.

    Warning

    Do not apply any PID selection on the input list, otherwise results could be biased.

  • outputListLabel (Optional[str]) – the name of the output lepton list label, i.e., the string that follows the particle identifier (‘e-:’, ‘mu-:’). By default, it is assigned as: '{method}_{classification}_{working_point}'.

  • trainingModeMulticlass (Optional[Belle2.ChargedPidMVAWeights.ChargedPidMVATrainingMode]) – enum identifier of the multi-class (global PID) training mode. See modularAnalysis.applyChargedPidMVA docs for available options.

  • trainingModeBinary (Optional[Belle2.ChargedPidMVAWeights.ChargedPidMVATrainingMode]) – enum identifier of the classification (binary PID) training mode. See modularAnalysis.applyChargedPidMVA docs for available options.

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

Returns

the alias for the lepton ID variable, and the list of aliases for the weights.

Return type

tuple(str, list(str))

Other functions available#

Warning

These other functions are not recommended for normal use without some study of the selection, or if you are working on skimming. If you use and improve these lists, please report in a performance meeting and make a pull request.

stdCharged.stdCharged(particletype, listtype, path, writeOut=True)[source]#
Function to prepare one of several standardized types of charged particle lists:

  • ‘all’ with no cuts on track

  • ‘good’ high purity lists for data studies

  • ‘loosepid’ loose selections for skimming, PID cut only

  • ‘loose’ loose selections for skimming

  • ‘higheff’ high efficiency list with loose global ID cut for data studies

  • ‘mostlikely’ list with the highest PID likelihood

Also the following lists, which may or may not be available depending on the release

  • ‘99eff’ with 99% selection efficiency (calculated for 1<p<4 GeV) and good track (MC only)

  • ‘95eff’ with 95% selection efficiency (calculated for 1<p<4 GeV) and good track (MC only)

  • ‘90eff’ with 90% selection efficiency (calculated for 1<p<4 GeV) and good track (MC only)

  • ‘85eff’ with 85% selection efficiency (calculated for 1<p<4 GeV) and good track (MC only)

Parameters

  • particletype – type of charged particle to make a list of

  • listtype – name of standard list

  • path – modules are added to this path

  • writeOut – whether RootOutput module should save the created ParticleList

stdCharged.stdMostLikely(pidPriors=None, suffix='', custom_cuts='', path=None, writeOut=True)[source]#

Function to prepare most likely particle lists according to PID likelihood, refer to stdCharged for details

Parameters

  • pidPriors – list of 6 float numbers used to reweight PID likelihoods, for e, mu, pi, K, p and d

  • suffix – string added to the end of particle list names

  • custom_cuts – custom selection cut string, if empty, standard track quality cuts will be applied

  • path – modules are added to this path

  • writeOut – whether RootOutput module should save the created ParticleList

stdPhotons.loadStdGoodBellePhoton(path)[source]#

Load the Belle goodBelle list. Creates a ParticleList named ‘gamma:goodBelle’ with ‘0.5 < goodBelleGamma < 1.5’

Warning

Should only be used for Belle analyses using B2BII.

Parameters

path (basf2.Path) – the path to load the modules

stdPhotons.loadStdSkimPhoton(path)[source]#

Function to prepare the skim photon lists.

Warning

Should only be used by skims.

Parameters

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

stdPi0s.loadStdSkimHighEffPi0(path)[source]#

Function to prepare the high-efficiency skim pi0 lists based on eff60_May2020 list.

Warning

Should only be used by skims.

Parameters

path (basf2.Path) –

stdPi0s.loadStdSkimPi0(path)[source]#

Function to prepare the skim pi0 lists.

Warning

Should only be used by skims.

Parameters

path (basf2.Path) –

stdV0s.goodBelleKshort(path)[source]#

Load the Belle goodKshort list. Creates a ParticleList named K_S0:legacyGoodKS. A vertex fit is performed and only candidates that satisfy the goodBelleKshort criteria, with an invariant mass in the range \(0.468 < M < 0.528~GeV\), and for which the vertex fit did not fail, are kept

Parameters

path (basf2.Path) – the path to load the modules

stdV0s.scaleErrorKshorts(prioritiseV0=True, fitter='TreeFit', scaleFactors_V0=[1.125927, 1.058803, 1.205928, 1.066734, 1.047513], scaleFactorsNoPXD_V0=[1.125927, 1.058803, 1.205928, 1.066734, 1.047513], d0Resolution_V0=[0.001174, 0.000779], z0Resolution_V0=[0.00135, 0.000583], d0MomThr_V0=0.5, z0MomThr_V0=0.0, scaleFactors_RD=[1.149631, 1.085547, 1.151704, 1.096434, 1.086659], scaleFactorsNoPXD_RD=[1.149631, 1.085547, 1.151704, 1.096434, 1.086659], d0Resolution_RD=[0.00115328, 0.00134704], z0Resolution_RD=[0.00124327, 0.0013272], d0MomThr_RD=0.5, z0MomThr_RD=0.5, path=None)[source]#

Reconstruct K_S0 applying helix error correction to K_S0 daughters given by modularAnalysis.scaleError. The ParticleList is named K_S0:scaled

Considering the difference of multiple scattering through the beam pipe, different parameter sets are used for K_S0 decaying outside/inside the beam pipe (K_S0:V0/RD).

Only for TDCPV analysis.

Parameters

  • prioritiseV0 – If True K_S0 from V0 object is prioritised over RD when merged.

  • fitter – Vertex fitter option. Choose from TreeFit, KFit and Rave.

  • scaleFactors_V0 – List of five constants to be multiplied to each of helix errors (for tracks with a PXD hit)

  • scaleFactorsNoPXD_V0 – List of five constants to be multiplied to each of helix errors (for tracks without a PXD hit)

  • d0Resolution_V0 – List of two parameters, (a [cm], b [cm/(GeV/c)]), defining d0 best resolution as sqrt{ a**2 + (b / (p*beta*sinTheta**1.5))**2 }

  • z0Resolution_V0 – List of two parameters, (a [cm], b [cm/(GeV/c)]), defining z0 best resolution as sqrt{ a**2 + (b / (p*beta*sinTheta**2.5))**2 }

  • d0MomThr_V0 – d0 best resolution is kept constant below this momentum

  • z0MomThr_V0 – z0 best resolution is kept constant below this momentum

  • scaleFactors_RD – List of five constants to be multiplied to each of helix errors (for tracks with a PXD hit)

  • scaleFactorsNoPXD_RD – List of five constants to be multiplied to each of helix errors (for tracks without a PXD hit)

  • d0Resolution_RD – List of two parameters, (a [cm], b [cm/(GeV/c)]), defining d0 best resolution as sqrt{ a**2 + (b / (p*beta*sinTheta**1.5))**2 }

  • z0Resolution_RD – List of two parameters, (a [cm], b [cm/(GeV/c)]), defining z0 best resolution as sqrt{ a**2 + (b / (p*beta*sinTheta**2.5))**2 }

  • d0MomThr_RD – d0 best resolution is kept constant below this momentum

  • z0MomThr_RD – z0 best resolution is kept constant below this momentum

stdKlongs.stdKlongs(listtype='allklm', path=None)[source]#

Warning

This function is a placeholder for Klong selections. Currently everything but the ‘allklm’ list is disabled pending study.

Prepares the ‘K_L0:allklm’ list with no cuts (all KLM clusters are loaded).

Parameters

  • listtype (str) – name of standard list options (currently only ‘all’ is supported/recommended)

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

stdHyperons.goodOmega(omegatype='loose', path=None)[source]#

Select the standard good \(\Omega^-\) ParticleList named Omega-:veryloose, Omega-:loose, or Omega-:tight from the reconstructed Omega-:std.

See also

BELLE2-NOTE-PH-2019-011.

Parameters

  • omegatype (str) – specify either veryloose, loose, or tight for good ParticleList selection (default veryloose)

  • path (basf2.Path) – modules are added to this path building the Omega-:veryloose, Omega-:loose, or Omega-:tight, list

stdHyperons.goodXi(xitype='loose', path=None)[source]#

Select the standard good \(\Xi^-\) ParticleList named Xi-:veryloose, Xi-:loose, or Xi-:tight from the reconstructed Xi-:std.

See also

BELLE2-NOTE-PH-2019-011.

Parameters

  • xitype (str) – specify either veryloose, loose, or tight for good ParticleList selection (default loose)

  • path (basf2.Path) – modules are added to this path building the Xi-:veryloose, Xi-:loose, or Xi-:tight, list

stdHyperons.goodXi0(xitype='loose', path=None)[source]#

Select the standard good \(\Xi^0\) ParticleList named Xi0:veryloose, Xi0:loose, or Xi0:tight from the reconstructed Xi0:std.

See also

BELLE2-NOTE-PH-2019-011.

Parameters

  • xitype (str) – specify either veryloose, loose, or tight for good ParticleList selection (default loose)

  • path (basf2.Path) – modules are added to this path building the Xi0:veryloose, Xi0:loose, or Xi0:tight, list

stdHyperons.stdOmega(fitter='TreeFit', path=None)[source]#

Reconstruct the standard \(\Omega^-\) ParticleList named Omega-:std.

See also

BELLE2-NOTE-PH-2019-011.

Parameters

  • fitter (str) – specify either KFit or TreeFit for the vertex reconstructions (default TreeFit)

  • path (basf2.Path) – modules are added to this path building the Omega-:std list

stdHyperons.stdXi(fitter='TreeFit', path=None)[source]#

Reconstruct the standard \(\Xi^-\) ParticleList named Xi-:std.

See also

BELLE2-NOTE-PH-2019-011.

Parameters

  • fitter (str) – specify either KFit or TreeFit for the vertex reconstructions (default TreeFit)

  • path (basf2.Path) – modules are added to this path building the Xi-:std list

stdHyperons.stdXi0(gammatype='eff40', beamBackgroundMVAWeight='', fakePhotonMVAWeight='', biasCorrectionTable='', path=None)[source]#

Reconstruct the standard \(\Xi^0\) ParticleList named Xi0:std.

See also

BELLE2-NOTE-PH-2019-011.

Parameters

  • gammatype (str) – specify either eff60, eff50, eff40, eff30, or eff20 to select the signal efficiency of the photons used in the pi0 reconstruction (default eff40)

  • beamBackgroundMVAWeight (str) –

    type of weight file for beam background MVA; if empty, beam background MVA will not be used

    Tip

    Please refer to the Neutrals Performance Confluence page for information on the beam background MVA.

  • fakePhotonMVAWeight (str) –

    type of weight file for fake photon MVA; if empty, fake photon MVA will not be used

    Tip

    Please refer to the Neutrals Performance Confluence page for information on the fake photon MVA.

  • biasCorrectionTable (str) –

    correction table for the photon energy bias correction (should only be applied to data)

    Tip

    Please refer to the Neutrals Performance Confluence page for information on the names of available correction tables.

  • path (basf2.Path) – modules are added to this path building the Xi0:std list