Babar logo
Workbook HEPIC Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Unwrap page!
Wkbk. Search
Wkbk. Sitemap
Logging In
Info Resources
Software Infrastructure
CM2 Introduction
Event Store
Modifying Code
Writing and Editing
Framework II
Find Data
Batch Processing
Advanced Infrastructure
New Releases
Main Packages
Event Displays
Contributing Software
Advanced Topics
Make CM2 Ntuples
New Packages
New Packages 2
Persistent Classes
Site Installation
Check this page for HTML 4.01 Transitional compliance with the
W3C Validator
(More checks...)

Workbook for BaBar Offline Users - Analysis

This section presents more advanced topics on the Beta analysis packages covering the details on how to manipulate candidates with operators, Monte Carlo truth associators, and introduces several concepts useful for running physics analyses at BaBar. Users who are new to using Beta candidates should first read the Workbook Beta section.

Available Information in the Event

Quick link: Available lists and event parameters

Data and Monte Carlo events are stored in various levels of database, from raw (all the basic information about detector hits) to reco (some basic reconstruction done, but still lots of information) to mini (new, fairly detailed), to micro (where the basic analysis is usually done), to nano (very brief information for fast-filtering).

A typical analysis job starts with a first pass through the nano-level data for very quick filtering, followed by accessing information from the micro database for full data analysis. Detector, particle identification and triggering studies can now be carried out on the mini database, which is slightly slower than the micro, but contains much more detailed information from the detector subsystems.

The different levels of the BaBar event store are described more completely in the Workbook section Event Store, which also contains a listing of much of the information available in these databases.

Extra tags for analysis releases

As you saw in the Quicktour, often extra information is required for specific analysis releases, and extra tags of specific packages are released. These extra tags are documented here:

Extra tags page

Candidate Lists

In an event the reconstructed BtaCandidate objects are grouped into Pid lists (often with one candidate occupying more than one list). Each list has a different identity hypothesis and different selection criteria. Some of the most-used lists include the ChargedTracks list of charged tracks, and the CalorNeutral list of neutral candidates. You can see a complete list of lists and their selection criteria here:

Candidate Lists and Maps page.

In the event loop, you can now obtain the list of desired particles using the List Name as a secondary key as was done in
In your .hh file define the key with which you'll recall the list:

     AbsParmIfdStrKey   _btaChargedList; 
at the constructor level in your .cc file assign the List Name to the key you just defined

     PExample::PExample( const char* const theName, 
                       const char* const theDescription )
       : AppModule( theName, theDescription )
       , _btaChargedList("trackCandidates", this, "ChargedTracks")
and finally extract the list from the event store at the event() level:

AppResult PExample::event( AbsEvent* anEvent )

  // get list of input track candidates
  HepAList<BtaCandidate>* trkList  =
    Ifd<HepAList< BtaCandidate > >::get(anEvent, _btaChargedList.value());

Particle Identification (PID)

Particle Identifcation (PID) is concerned with the identification of detected particles - ones that live long enough to leave an actual signal in the detector. The detected particles are electrons, muons, pions, kaons, protons, and photons. Other particles decay too quickly to be detected, and must be reconstructed by combining the detected particles to form composite candidates, and testing these candidates. You will learn about particle composition later in this section.

Particle ID is the responsibility of the Particle ID Group. The PID group develops, tests and maintains particle selectors, standard sets of selection criteria used in all BaBar analyses to identify the detected particles.

The efficiency of a selector is the fraction of signal events accepted by the selector. The purity is the fraction of all events selected that are signal events. In general, you want high efficiency and high purity. However, there is usually a tradeoff between efficiency and purity: if you tighten your selection criteria, you will cut out more background events, but you will lose more signal events as well.

To provide each user with the level of selection required for his or her analysis, each particle typically has several levels of selector, from VeryLoose (most efficient, least pure) to VeryTight (most pure, least efficient).

The following table, from the PID selector page, shows the different PID selectors. The lists of the same names are lists of particles that pass the selectors.
"Common Name" C++ - class Beta-Modules Further Documentation
Muon Selectors
Cut based Muon Selection, .hh MinimumIoniziongMuonMicroSelection
BAD #60
BAD #799
Neural Net based
Muon Selection, .hh NNVeryLooseMuonSelection
BAD #474
Electron Selectors
Cut based Electron Selector,.hh NoCalElectronMicroSelection
BAD #90
Likelihood based Electron Selector,.hh PidLHElectrons BAD #196
Pion Selectors
Likelihood based
Pion Selector, .hh VeryLooseLHPionSelection
Description of LH Selectors
"Roy" Pion Selector, hh PidRoyPionSelectionLoose
Kaon Selectors
Kaon SMS Selector,.hh VeryLooseKaonMicroSelection
BAD #116
Likelihood based
Kaon Selector,.hh VeryLooseLHKaonMicroSelection
Description of LH Selectors
Neural Net based
Kaon Selector,.hh VeryLooseNNKaonMicroSelection
BAD #116
Proton Selectors
Likelihood based
Proton Selector, .hh VeryLooseLHProtonSelection

You will need to determine which level of selector you require by studying the efficiencies and purities of those selectors for your specific analysis.

Example: Changing the Particle Selector

The NTrkExample, PExample, and FrmwkExample modules that you have made so far all use "ChargedTracks" as their input list. ChargedTracks is one of the lists made at runtime.

Now suppose you decide you are interested only in electron candidates that have passed the PidLHElectronSelector. The corresponding PID list is PidLHElectrons.

The Quicktour analysis does not include the code needed to produce the PID lists. The trouble is that MyMiniAnalysis.tcl uses btaMini.tcl instead of btaMiniPhysics.tcl. This is very easy to fix: just change:

sourceFoundFile BetaMiniUser/btaMini.tcl
#sourceFoundFile BetaMiniUser/btaMiniPhysics.tcl
#sourceFoundFile BetaMiniUser/btaMiniPhysProdSequence.tcl
#sourceFoundFile BetaMiniUser/btaMini.tcl
sourceFoundFile BetaMiniUser/btaMiniPhysics.tcl
#sourceFoundFile BetaMiniUser/btaMiniPhysProdSequence.tcl

btaMini.tcl, btaMiniPhysics.tcl, and btaMiniPhysProdSequence.tcl are general tcl files used to access the Mini database. Many packages use these tcl files, not just BetaMiniUser.

The above change will cause the PID lists (and some other lists) to be produced. Now let's find out how to access them.

NTrkExample and PExample

For NTrkExample and PExample modules, the value of _btaChargedList is not accessible to the framework. So to use PidLHElectrons as the input list instead of ChargedTracks, you would need to replace

, _btaChargedList("trackCandidates", this, "ChargedTracks"),
, _btaChargedList("trackCandidates", this, "PidLHElectrons")
in the .cc file. Then you would need to recompile, relink and rerun your code to see the new, electrons-only histograms.


In the FrmwkExample module that you created in the Framework Continued, you appended _btaChargedList to the commands list, making it accessible to the framework. Now you do not have to recompile and relink every time you want to change the input list. Instead, you can set the value of the list by adding the following line in snippet.tcl or MyMiniAnalysis.tcl:

trackCandidates set PidLHElectrons
You can also change the value of the input list at any time during your interaction with the framework by talking to FrmwkExample:
> mod talk FrmwkExample
FrmwkExample> trackCandidates set PidLHElectrons
FrmwkExample> exit
It is often convenient to put commands like this in a tcl file. See the Framework Continued section to learn how to make a tcl file that sets parameters - including the input list of trackCandidates - for the FrmwkExample module.

PID and Monte Carlo

Since Monte Carlo (simulated data) is not yet optimally tuned to the data, the performance of the particle selectors is not the same for data and Monte Carlo. The PID Tables store the efficiency and misidentification rates of the various particle selectors, based on studies of data control samples.

Each PID selector can be run in one of five modes, each with a different strategy for making Monte Carlo behave more like data:

  • plain
    The selection procedure defined by this selector is applied, nothing else is done.
  • kill The selector is applied, but then a random number generator is used to reject ("kill") random Monte Carlo events, to make the Monte Carlo efficiency as low as the data efficiency (according to the PID tables).
  • tweak
    The selector is applied, but "tweaked" so that events for which the selector efficiencies for data and Monte Carlo are very different are more likely to be rejected.
  • weight
    The ratio of data efficiency to Monte Carlo efficiency is stored, so that you can use it to weight your histograms, etc., on an event-by-event basis.
  • skim
    A track is accepted if its true identity is the one the selector is looking for, or if it passes the selection criteria defined by the selector, or if it is accepted by "PID-tweaking". Later you will probably apply a tighter selection.
The mode is a tcl parameter, set by talking to the module. For example, if you wanted to use the LooseMuonMicroSelection selector in "weight" mode, you would put one of the following lines in MyMiniAnalysis.tcl:

pidCfg_mode weight LooseMuonMicroSelection

mod talk LooseMuonMicroSelection
mode set weight
A particularly useful command is the wildcard xxx:

pidCfg_mode weight *
This tells ALL of the selectors to operate in weight mode.

A detailed explanation of PID on Monte Carlo, and "in-a-nutshell" instructions for PID-weighting and PID-tweaking for analysis-30, can all be found on the PID webpage.

Beta Operators

Accessing the lists of BetaCandidates in the event store was the first step for the analysis; we now have to learn which kind of operations can be performed. In the previous Workbook Beta Section we already saw some of the member functions of the BtaCandidate class: functions to access the charge, energy, mass, 3-momentum, and 4-momentum of any Beta Candidate. These functions belong to the BtaCandidate class. (See the doxygen documentation for a nice interface to use to study the functions of the BtaCandidate class and related classes.)

There are also many functions that can be performed on BtaCandidates. These functions are not members of the BtaCandidate class; rather, they take BtaCandidates as input. Vertexing, mass-constrained fitting, and simple 4-vector addition are examples of such operators. The analyst selects the operator needed at particular stages in the analysis, trading off accuracy and completeness for speed and flexibility. This is just the beginning of the list of all the possible operations that can be performed on BetaCandidates:

  • Cloning
  • Setting particle type
  • Combining 4-vectors
  • Vertexing
  • Applying constraints
  • Obtaining Monte Carlo Truth
  • Changing a reference frame
  • ..........
In the previous Workbook Beta section we already saw some simple operations that can be performed on a BetaCandidate; in the following of this section we will see how to combine more BetaCandidates, how to use Associators and maybe something more. We will also learn about the software packages available to test, fit and keep track of lists of composite BetaCandidates.

Combining BtaCandidates

A basic operation of analysis is creating acceptable candidates for a particular reaction from scratch. There are many tools available for combining Beta Candidates:
Simple addition
Beta Candidate (class BtaCandidate) can be simply combined to form a new Beta Candidate. This type of addition imposes no constraints.
Vertex and Kinematic Fitting
These are fitters that can be used within a BaBar Framework application to create composite candidates, incorporating geometric constraints, kinematic constraints, or both.
SimpleComposition is a package full of BaBar Framework modules that create lists of composite particles, automating the work of making combinations, performing fits, and making cuts.

Simple Addition of Beta Candidates

Two BtaCandidates can be combined by simply adding their 4-momenta:
    BtaCandidate* c1;
    BtaCandidate* c2;
    BtaOpAdd4 op;
    BtaCandidate c3= op.combine( *c1, *c2 );
This operation combines BetaCandidates c1 and c2 to give the (putative) mother, c3. BtaOpAdd4 specifies a simple kinematic addition.

This type of addition does not take into account any geometric or kinematic constraints. The two BtaCandidates could be separated by a long distance in space, or combine to form a BtaCandidate with an impossible mass (for example, a mass that does not belong to any existing particle). So you will need to test the new BtaCandidate before you can be confident that it really is the mother.

Vertexing and Kinematic Fitting

A more sophisticated way of combining BtaCandidate is the vertexing/kinematic fitting procedure in which one uses physical constraints governing a particle interaction or decay to improve the measurements describing the process. Fitters can use geometric constraints, kinematic constraints, or both; and can treat single-level or more complicated decay trees.

Vertexers and kinematic fitters are both Beta operators. The input is a list or tree of BtaCandidates. A vertexer returns the most likely common vertex position, vertex momentum, and their errors. A kinematic fitter returns the best fit to the momenta/masses/energies of the candidates. Many Beta operators do both. The output is a modified version of the tree with improved vertices and momenta.

An example of the use of a vertexer can be found in the module, which came in your BetaMiniUser package. This module forms K0 candidates by vertexing pairs of pion candidates. Looking at, you can see that the code #includes the required vertexing header files,

#include "VtxBase/BtaAbsVertexer.hh"
#include "VtxFitter/VtxFitterOper.hh"
#include "VtxBase/VtxAbsAlgorithm.hh"
initiates some vertexers,

, vtxFitAlgo("vtxFitAlgo", this, VtxAbsAlgorithm::GeoKin)
, vtxFitMode("vtxFitMode", this, VtxAbsAlgorithm::Standard)
and uses them to obtain a "fitted Vee" (that is, a fitted hypothetical K -> pi+ pi- decay).

VtxFitterOper veeVertexer(initialVee,vtxFitAlgo.value(), vtxFitMode.value());;
fittedVee = veeVertexer.getFittedTree();
To learn how to use the vertexing operators go at the Vertexing/Kinematic Fitting User's Guide. This is a well-written, detailed and up-to-date guide based on analysis-21. (Note that it is based on a different release than analysis-30, the release used in the Workbook Quicktour.)

The code in the vertexing classes has been documented using Doxygen, which provides an excellent means to navigate through the classes and functions used for vertexing in BaBar. See below for links to the Doxygen documentation for vertexing.

Related Documents:


SimpleComposition is a package that takes existing lists of BtaCandidates (such as ChargedTracks, GoodTracksLoose, piDefault, KDefault, gammaDefault) and produces lists of composite BtaCandidates. A composite BtaCandidate is really a decay tree, so geometric and kinematic fits can be performed on each composite candidate.

SimpleComposition provides an interface for fitting and refitting, applying and refining selection. Each "operation" that SimpleComposition supports is given a module, and that module is configure by the user via tcl

The SimpleComposition home page has links to many useful tutorials and examples on how to use the SimpleComposition package. Another good way to get started using SimpleComposition is to try the Workbook tutorial, How to generate a set of CM2 ntuples using SimpleComposition and BtaTupleMaker.

BetaTools and BetaCoreTools

The BetaTools and BetaCoreTools packages provide a diverse set of tools for use with analyses at the Beta level. Those tools that are considered core for any physics analysis are placed in BetaCoreTools. The BetaTools package provides tools for carrying out Monte Carlo truth analyses.

Some of the more useful BetaCoreTools include:

  • Tools for calculating event shape variables, such as thrust, sphericity, the Fox Wolfram moment.
  • Monte Carlo truth associators, which associate the reconstructed objects in the event store to the corresponding Monte Carlo truth candidate (if it exists).
  • Tools providing additional event information, such as total momentum and B variables like deltaE, mes, and eBeam.
  • Utility functions to carry out tasks such as boosting a candidate and all its decay products, and doing simple vertexing (adding 4 momenta)
Some of the more useful BetaTools include:
  • Selectors and particle candidate makers.
  • Tools for making cuts/histogramming.
  • Beta Candidate counters

Descriptions and documentation for these and other BetaTools can be found on the BetaTools and BetaCoreTools page.

Some of the more useful tools are described below.

BtaBooster, BtaHelicity and helicity angle calculations

A useful quantity in many analyses is the helicity angle. In the reaction Y -> X -> a + b, the helicity angle of particle a is the angle measured in the rest frame of the decaying parent particle, X, between the direction of the decay daughter a and the direction of the grandparent particle Y. (Source: BAD 529 (V5) p.5-6)

The following short C++ routine can be used to compute the cosine of the helicity angle.

#include <TLorentzVector.h>
#include <Vector3.h>

Float_t coshel(TLorentzVector particle, TLorentzVector parent, 
TLorentzVector grandparent) {

TVector3 boosttoparent = -(parent.BoostVector());


TVector3 particle3 = particle.Vect();
TVector3 grandparent3 = grandparent.Vect();

Float_t numerator = particle3.Dot(grandparent3);
Float_t denominator = (particle3.Mag())*(grandparent3.Mag());
Float_t temp = numerator/denominator;

return temp;


Alternatively, the helicity is expressed in terms of Lorentz invariant quantities in BAD 522 (V6), Eq. 141, page 120. This expression avoids the need to do boosts for calculating the helicity angle.

NOTE: You should NOT use BtaBooster to compute helicity, because you cannot compare angles between a BtaBooster'ed vector and an un-BtaBooster'ed vector, as the two coordinate systems have a relative rotation. Instead, a straight Lorentz boost should be used. In the special case where X and a are already boosted to the Y reference frame, you can use the BetaCoreTools package BtaHelicity to compute the helicity. The syntax is:

#include "BetaCoreTools/BtaHelicity.hh"

  BtaHelicity h(a, b);  // a and b are BtaCandidates in X -> a + b
  double hel = h.helicity();
For example, in the BetaMiniUser package, BtaHelicity is used in to compute the helicity of d1 in the decay K-candidate -> d1 d2.


It is often useful to associate one candidate with another during analysis. Reconstruction candidates are associated with their appropriate Monte Carlo truth candidates, etc. the BtaAssociator classes provide a family of ways to do this with a consistent interface.
For example in efficiency studies it is important to be able to associate the Monte Carlo truth to the reconstructed objects. An example of how to do use associators is in our very own, where a truth map is initiated,

 , _btaTruthMap( "btaTruthMap", this, "GHit")
made framework-accessible,

  commands()->append( &_btaTruthMap );

  // get the default truth mapping
  BtaMcAssoc* truthMap =
    Ifd< BtaMcAssoc >::get(anEvent, _btaTruthMap.value());
and finally used to associate each Beta Candidate in the list *btaMicroList with its MC partner.

  // Simple example of map usage

    HepAListIterator<BtaCandidate> recoIter(*btaMicroList);
    while (BtaCandidate* reco = recoIter()){
      BtaCandidate *mcPartner = truthMap->mcFromReco(reco);
Then the difference between the momentum of the MC partner and the original candidate is written to a histogram:

        _aHisto->accumulate(mcPartner->p() - reco->p());

B Flavor Tagging

At BaBar, B-mesons are always produced in pairs: one B and one anti-B. In many studies, including the measurement of sin2beta, it is important to be able to determine the flavor (b or anti-b) of one (and thus both) of the B-mesons. Developing and maintaining a B-flavor tagging algorithm is the responsility of the B Tagging Tools Group.

A typical scenario is that one of the B-mesons (the signal B) decays in the mode of interest, while the other B-meson (the tagging B) is used to determine the flavor. The tagging B decays to a charged lepton or kaon. Then the b-quark flavor can be determined from the correlation between the b-quark charge and the charge of the "tagging" lepton or kaon.

The home page of the B Tagging Tools Group includes links to BaBar Analysis Document (BAD) 729, which describes Tag04, the latest (2004) B-tagging algorithm, and a recipe for making ntuples in CM2 with release 14.5.2.

Related Documents:

These older BADs describe earlier versions of the B-tagging algorithm:

Roofit: A ROOT toolkit

The RooFit packages provide a toolkit for modeling the expected distribution of events in a physics analysis. Models can be used to perform likelihood fits, produce plots, and generate "toy Monte Carlo" samples for various studies. The RooFit tools are integrated with ROOT.

Related Documents:

Code navigation with Doxygen

Doxygen creates documentation from source code such as C++. It can be used to generate html pages, latex, ... . The html, for example, provides a clickable graphical navigation through source code of related packages with dependency diagrams, list of functions, and usefully colour-coding of source code. It is particularly useful for studying dependencies of packages and quickly studying the structure and implementation of functions within classes. Michael Wilson has used Doxygen to document code in the packages which implement offline vertexing, and for the packages related to detector-level data, for example, the BtaCandidate class. This documentation provides an excellent means to search through the BaBar code

Back to Workbook Front Page

Massimiliano Turri
Joseph Perl, Tracey Marsh, Leon Rochester
Jenny Williams

Last update: 20 January 2006
Last significant update: 5 September 2005