How do I use DecayTreeFitter?
Objectives
- Learn what DecayTreeFitter is and how to use it!
DecayTreeFitter (DTF) is an algorithm to determine the kinematics of a particle decay. Without using DTF a particle that decays is reconstructed in steps from the final-state stable tracks. For example, take the decay \( D^{\ast +} \to D^{0}\pi^{+} \) with \( D^{0} \to K^{-} \pi^{+} \). Ordinarily one starts with the final state \( K^{-} \pi^{+} \) tracks and combines their 4-momenta with a fit for a vertex to form a \( D^{0} \) candidate. To this, a second \( \pi^{+} \) is added to form the \( D^{\ast +} \) candidate. Whilst particle trajectories are fitted to produce vertices, the decay chain is built sequentially from the bottom up.
By contrast, DTF performs a kinematic fit of the whole decay chain in one go. Doing so allows one to impose constraints on the composite particles in the decay chain. For example we could require in the fit that the \( K^{-} \pi^{+} \) combination produce a particle that has exactly the \( D^{0} \) mass, leading to improved resolution on the reconstructed \( D^{\ast} \) invariant mass. We could also add a constraint such that the \( \pi^{+} \) from the \( D^{\ast +} \) decay points back to the PV.
Generally (though not always) the gains felt by using DecayTreeFitter, are most felt when considering particles with narrow natural widths such as \(D^*, J/\psi, \) ...
For more information on DTF see:
The tutorial here is taken from the tutorial in DaVinci and the related examples for PV constraints and with PID substitution.
DecayTreeFitter with a mass constraint
Consider the decay chain \( B_{s}^{0} \to J/\psi \phi \), with \( J/\psi \to \mu^{+}\mu^{-} \) and \( \phi \to K^{+}K^{-} \). We know the \( J/\psi \) is a narrow resonance, so we can constrain the \( \mu^{+}\mu^{-} \) mass to be \( 3.0969\,{\rm GeV} \):
from PyConf.reading import get_particles, get_pvs
from DecayTreeFitter import DecayTreeFitter
# Load data from dst onto a TES
turbo_line = "Hlt2B2CC_BsToJpsiPhi_Detached"
input_data = get_particles(f"/Event/HLT2/{turbo_line}/Particles")
# Make the DTF
DTF = DecayTreeFitter(
name="DTF", input_particles=input_data, mass_constraints=["J/psi(1S)"]
)
# Now make the kinematic functors for the particles that have been fitted with DTF
kin = FC.Kinematics()
dtf_kin = FunctorCollection(
{"DTF_" + k: DTF(v) for k, v in kin.get_thor_functors().items()}
)
dtf_kin can be added to the FunTuple variables along with all the other variables you may want in the usual manner.
We can see in the plots below the effect of DecayTreeFitter on the \(B_{s}^{0} \) mass resolution. In both plots the variables with the \( J/\psi \) mass constraint is the red histogram, without DecayTreeFitter is the blue histogram. In the first plot the mass constraint on the \( J/\psi \) is clear in the red line. In the second, the resulting width of the distribution of the \( B_{s}^{0} \) is narrower for the red histogram, due to the mass constraint.
DecayTreeFitter with a PV constraint
One could add a PV constraint to the \( B_{s}^{0} \) candidate i.e. the momentum vector must point back to a PV. This then begets the question of exactly which PV to use:
- The PV already associated with the particle;
- The PV already associated with the particle, but that has the signal tracks removed from the PV fit - i.e. it is unbiased ;
- Note that for this to work you must ensure that the PV tracks have been saved in HLT2 with
pv_tracks=True! ;
- Note that for this to work you must ensure that the PV tracks have been saved in HLT2 with
- The best PV from all possible PVs
The choice is up to the analyst with the subsequent implementation in the DaVinci options being straightforward.
# 1: the PV already associated with the particle
DTF_OWNPV = DecayTreeFitter(
name="DTF_OwnPV",
input_particles=input_data,
mass_constraints=["J/psi(1S)"],
constrain_to_ownpv=True,
)
# 2: The "unbiased" PV
# First create a new B list with unbiased PVs
from PyConf.reading import get_extended_pvs
from PyConf.Algorithms import ParticleUnbiasedPVAdder
B_Data_unbiasedpv = ParticleUnbiasedPVAdder(
InputParticles=input_data, PrimaryVertices=get_extended_pvs()
).OutputParticles
DTF_UNBIASEDPV = DecayTreeFitter(
name="DTF_UnbiasedPV",
input_particles=B_Data_unbiasedpv,
mass_constraints=["J/psi(1S)"],
constrain_to_ownpv=True,
)
# 3: The "best" PV:
# First get the list of possible PVs
pvs = get_pvs()
DTF_BESTPV = DecayTreeFitter(
"DTF_BESTPV", # name of algorithm
input_data, # input particles
input_pvs=pvs,
mass_constraints=["J/psi(1S)"],
)
# Define some functors that will be affected by the PV constraint
pv_fun = {}
pv_fun["BPVLTIME"] = F.BPVLTIME(pvs)
pv_fun["BPVIPCHI2"] = F.BPVIPCHI2(pvs)
pv_coll = FunctorCollection(pv_fun)
# Again, make the DTF versions of the functors but this time add them to the existing functor collection
pv_coll += FunctorCollection(
{"DTF_OWNPV_" + k: DTF_OWNPV(v) for k, v in pv_coll.get_thor_functors().items()},
{"DTF_BESTPV_" + k: DTF_BESTPV(v) for k, v in pv_coll.get_thor_functors().items()},
{"DTF_UNBIASEDPV_" + k: DTF_UNBIASEDPV(v) for k, v in pv_coll.get_thor_functors().items()},
)
Similarly, these functors with the PV constraint may be added to the FunTuple variables in the usual manner.
The DecayTreeFitterResults functor collection
There is a helpful functor collection already defined for your DecayTreeFitter variables, called DecayTreeFitterResults. It can be set up in the following manner:
dtf_vars = FC.DecayTreeFitterResults(
DTF = DTF_PV,
prefix = 'DTF_PV_FC',
decay_origin = True, # Add the variables describing the origin vertex of the decaying particle
with_lifetime = True, # Add the decay time, the flight distance and their uncertainties
with_kinematics = True, # Add the 4-momentum components
)