SLAC PEP-II
BABAR
SLAC<->RAL
Babar logo
Workbook HEPIC Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Unwrap page!
Wkbk. Search
Wkbk. Sitemap
Introduction
Non SLAC
HOWTO's
Introduction
Logging In
QuickTour
Detector
Info Resources
Software Infrastructure
CM2 Introduction
Unix
OO
SRT
Objectivity
Event Store
Framework
Beta
Modifying Code
Writing and Editing
Compiling
Debugging
Analysis
Framework II
Analysis
Find Data
Batch Processing
PAW
PAW II
ROOT I
ROOT II
ROOT III
Advanced Infrastructure
New Releases
Workdir
Main Packages
Event Displays
Gen/Sim/Reco
Contributing Software
SRT and CVS
Coding
Advanced Topics
Make CM2 Ntuples
New Packages
New Packages 2
Persistent Classes
Java
Site Installation
Check this page for HTML 4.01 Transitional compliance with the
W3C Validator
(More checks...)

Workbook for BaBar Offline Users - Beta: the Analysis Package

Beta is an analysis toolkit for use with BaBar data. It forms the basic interface to the complete reconstruction of BaBar data. The primary goal of Beta is to provide a simple, common basis for writing detailed physics analysis programs. It provides for particle identification, vertexing, tagging, and so forth. This chapter will cover the mechanics of using Beta to perform user analysis. More advanced uses of Beta for analysis tasks are in the Analysis section of Advanced Analysis in the Workbook.

Basic Structure

The most important Beta package for most users is BetaMiniUser. BetaMiniUser is a package that has been created to facilitate a user's interaction with the larger-scale Beta package. The BetaMiniUser package, which makes the BetaMiniApp executable, is where an individual can develop their own analysis. The information in this section will be focused on using Beta through the BetaMiniUser package. This package contains various self-contained examples of simple analysis jobs. To see a list of Beta packages, just look for files beginning with the word "Beta":
    > ls $BFDIST/releases/analysis-30/Beta[TAB]
Beta                    BetaMicroAdapter        BetaMiniUser
BetaBogus               BetaMicroBase           BetaPid
BetaBuildPidEnv         BetaMicroTruth          BetaPidCalib
BetaCoreTools           BetaMini                BetaReco
BetaEvent               BetaMiniData            BetaRecoAdapter
BetaExamples            BetaMiniEnvSequences    BetaSequences
BetaIfrPidCalib         BetaMiniModules         BetaTools
BetaLumi                BetaMiniQA              BetaUser
BetaMC                  BetaMiniRooEnvSequences
BetaMicro               BetaMiniSequences

As you can see, Beta is a system of many packages, including:

Beta
Base classes, candidate classes, etc.
BetaExamples
Example analysis modules. A good resource for modules to experiment with, and code to look at for new ideas and techniques.
BetaMC, BetaReco, BetaRecoAdapter
Interface packages for running on reconstructed data
BetaSequences
Sequences and .tcl files used by Beta to run in various modes
BetaTools
Analysis-level tools that you might want to use in your program. For example, this package include general two-body and three-body decay finders.
BetaMiniUser
The sample package on which you can build your analysis. "Mini" refers to the Mini database.
BetaUser
An old version of BetaMiniUser, used to access the old (obsolete) "Micro" database.

In general, you will want to work with packages beginning with "BetaMini", because these are the ones designed for the new Mini database. Packages beginning with "BetaMicro" access the Micro database, and will not work with current analysis code releases.

The BetaMini packages include (see also BAD 508):

BetaMiniUser
For many analyses, this will be the only package that the user had to modify. It contains the example analysis modules, AppUserBuilds and sample scripts that the user can copy and modify in order to access and analyze the Mini data through the Beta interface.
BetaMiniSequences
This core package contains the sequences, tcl scripts and TCL parameter definitions needed to create the BtaCandidate lists from the Mini database.
BetaMini
This package creates the basic lists of charged and neutral BtaCandidates from the information stored on the Mini database. It contains lots of mini-specific packages like LoadMiniBtaCandidates, BtaMiniTrkQual, BtaMiniCalQual, BtaMiniIfrQual, and BtaMiniPidInfo.
BetaMiniModules and BetaMiniQA
These packages contain classes to display and validate the information stored on the Mini database. BetaMiniQA receives contributions from the component subsystems; BetaMiniModules is maintained by the core mini developers.
BetaMiniData
This core package provides classes which uniquely identify each BtaCandidate on the mini and maps between the identifiers and BtaCandidates. Again, though, while there are many BetaMini packages, you will probably work only with BetaMiniUser and possibly one or two others.

Workdir Directory

Like most BaBar executables, BetaMiniApp is run only from the workdir directory, due to needed data files for reconstruction. You will need the workdir package checked out in your test release directory to perform analysis with the BetaMiniUser package.

The workdir package is used to run a variety of applications in addition to Beta jobs. Consequently is contains some files that are either not directly used or not used at all by Beta packages. The most important files in the workdir package are symbolic links to the areas where library and executable files are stored.

For a discussion of the workdir package and its role in running Beta applications, see The workdir Package chapter of the workbook; specifically the Beta section.

BetaMiniUser

The BetaMiniUser package contains several tcl files that accommodate a variety of BetaMiniApp applications. Of those many files the following were used in the QuickTour analysis.

AppUserBuild.cc, AppUserBuildRoo.cc, AppUserBuildBase.cc
implementation for AppUserBuild class
btaMini.tcl
tcl file for setting up analysis path to the Mini database
MyMiniAnalysis.tcl
tcl file for a general user analysis sequence
NTrkExample (.cc and .hh)
code to plot a trks/event histogram

Beta

The Beta package itself contains the candidate classes and base classes. For standard analysis editing the BetaMiniUser package should be sufficient, while the Beta package should be consulted for further definitions of event quantities and functions.

Variables

The Beta software packages exist in modular form. That is, the Beta software has been split into building blocks of code that can be assembled to form customized BetaXXXApp applications (BetaApp, BetaMiniApp, BetaMiniQAApp...). For example, a block of Beta code for reading from the production database can be put together with simulation and reconstruction blocks to form an executable. The advantage of this modular scheme is that when you use only the code you need for your application, you save compilation and linking time.

(Warning: A perfect modular system would have no dependencies between modules. But sometimes Beta's modular structure is less than perfect, so there may be intermodular dependencies.)

A set of variables are used to control what modules gets linked into a Beta[Something]App application. Each variable has a default value determined by the software release. For release analysis-30 the default settings are as follows (again taken from BAD508):

Table: BetaMiniUser TCL configuration parameters.
TCL parameter Allowed values Default Comments
levelOfDetail micro, cache, extend, refit, rebuild cache See Table 1. The list of allowed levelOfDetail values are stored in the variable BetaMiniLevels.
ConfigPatch Run1, Run2, MC Run2 Specifies the data taking period of the input. Run2 now encompasses all data taking periods. MC specifies Monte Carlo simulated data.
MCTruth true, false false if ConfigPatch is not equal to MC, else true true means construct the MCTruth BtaCandidates and maps to reco candidates
inputList     Space-delimited list of input collections. The format of the input data, Bdb or Kan, is specified by the variable BetaMiniReadPersistence.
BetaMiniReadPersistence Kan, Bdb Kan The persistence format of the input data
BetaMiniTuple hbook, root hbook Determines the type of output histogram file to create. This parameter will enable RooTupleEnv (HbkTupleEnv) module and disable HbkTupleEnv (RooTupleEnv) module if this parameter is set to root ( hbook).
histFileName   BetaMini.
${BetaMiniTuple}
Name of ntuple file.
BetaMiniSystems Eid Tag Trk Emc Ifr Pid G3 G4 Reco Svt Dch Drc L1Glt L1Fct L3T BtaMini The list of systems to be read, constructed by BetaMiniSequences/BetaMiniDefineSystems.tcl. A subset of systems may be explicitly specified but must account for system interdependencies.
BetaMiniReadComponents Esd, Cnd, Aod, Tru, Tag, Sim Dependent on levelOfDetail The components which can be configured in a BetaMiniUser job.
BetaMiniReclusterComponents   Esd Sim Defines which components are written into which root file. All components except those specified in BetaMiniReclusterComponents are written into the first (header) file.

Setting these variables appropriately can greatly reduce compile time. However, this also means that the settings of these variables can limit what tcl scripts, and therefore what type of data, you can use at run time.

In the Quicktour analysis you used your snippet.tcl file to set some of these variables:

set ConfigPatch MC
set levelOfDetail cache
set BetaMiniTuple root
set histFileName myHistogram.root
You can see that you did not really have to set the levelofDetail, since "cache" (the one you want) is the default. But it doesn't hurt.

Program Flow

The program flow of analysis job is best explained with a concrete example. The following information will explicitly discuss using the BetaMiniUser application to perform analysis, as done in the QuickTour analysis. Most of the details pertain to any general analysis.

Any source code (specifically user-definted module class header and implemantation files, .cc and .hh files) located in the your test release will be compiled and linked by the gmake all command. Compiling and linking the code in the BetaMiniUser package produces an executable named BetaMiniApp.

In the Quicktour analysis you ran the executable by calling the executable BetaMiniApp in the workdir package.

 ana30/workdir> BetaMiniApp snippet.tcl

The last chapter of the workbook described how to interact with the framework, but not how the framework gets created or how long it lasts. The framework is implemented as a class, and an executable like BetaMiniApp is needed to create it. Every time you run an executable it instantiates (creates) a framework object. The framework is effectively the program that is run. It is the main function of an analysis executable. What the framework is given to work with and what it is asked to do differentiates analysis applications.

The main function of your executable does two things, it instantiates the framework and then creates an object of the AppUserBuild class. The AppUserBuild class is used to create the modules required by your analysis application and make them available to the framework. The framework contains a data member that is a list of modules. Initially this list is empty. The constructor for the AppUserBuild class can create module class objects and add them to the framework's list. Once a module is in this list it can be accessed and used by the framework in analysis applications. Here is an annotated copy of the AppUserBuildBase.cc file that you used in the Quicktour analysis (comments are in blue).

After the executable performs these two initial actions it sources the "tickle" runfile with which it was run. In the Quicktour analysis the tcl file was snippet.tcl. This tcl file sources a number of secondary tcl files that create sequences in the framework and define what modules make up those sequences. Also, the script creates a path in the framework and appends the sequences in the appropriate order. These sequences are created by ready-made scripts to shield the user from their details.

The snippet.tcl file passes the job to MyMiniAnalysis.tcl, which in turn passes it to btaMini.tcl, the main tcl file. After the btaMini.tcl script has been run the executable returns the framework prompt, '>'. While the executable is running, a framework prompt is given whenever user input is allowed or required. Then you get to act like a tcl file. All legal commands that you issue at the '>' prompt are translated into calls to framework member functions. The framework interfaces between you and the analysis application that you have defined within the context of the framework.

At this point you can get started with analysis. You can issue the command to begin event analysis (ev begin), control the name of output files, change parameters, change input, and so forth. This is how you use the framework to manipulate your application.

When you exit the framework you terminate the BetaMiniApp executable and are returned to your usual unix shell prompt.

Summary

When you compile and link (gmake all) the C++ code (.cc and .hh files), you create a BetaMiniApp executable, which is basically a program. When you run the job, the BetaMiniApp executable creates a framework and an AppUserBuild object, which loads the framework with modules. Then the tcl files (or you, acting like a tcl file) tell the framework what to do. In particular, the tcl files (or you) set configuration variables and tell the framework where to get data and how much to analyze.


Input and Output Control

Input and output is controlled by tcl scripts. For each supported input data type an associated tcl file is included in the BetaMiniUser package. Each script will create an analysis path with an appropriate input module and initial analysis sequence. The standard set is btaMiniPhysics.tcl, but you can get more (btaMiniPhysProdSequence.tcl) or less (btaMini.tcl) if you want.

There are several ways to give input to the framework. The best way is to use BbkDatasetTcl to make a tcl file full of "lappend inputList collection_name" commands, and then add a "source INPUTFILE.tcl" command in your controlling tcl file (in this case, snippet.tcl or MyMiniAnalysis.tcl). This tells the framework where to get the given collections.

The second way is to run the job interactively and act like the tcl file yourself. This means that when you get your framework prompt, you have to "mod talk" to an input module, usually KanEventInput:

    > mod talk KanEventInput
KanEventInput> input add collection_name_1
KanEventINput> input add collection_name_2
...
KanEventInput> input add collection_name_N
KanEventInput> exit
    >
This adds the N collections to the framework's list of data to run on. Once you do you "ev beg -nev NEvents" command, the framework will run on the first NEvents in this list of collections.

Output

The output is written to a .root file (or an .hbook file if you set BtaMiniTuple to "hbook"). You set the file name in your snippet.tcl:
  • myHistogram.root
Otherwise you would have gotten the default name in MyMiniAnalysis.tcl, namely MyMiniAnalysis.root. This file is created in the workdir directory since this is where the BetaMiniApp executable is run from.

Finding Available Data

See the workbook section Finding Data for information about on finding data to run analysis jobs on.

Beta Candidates

A Beta Candidate is a representation of what is known or assumed about an (alleged, thus candidate) particle. Candidates can represent various levels of processing, various data types: a reconstructed object, a combination of candidates, a transformation of a candidate for a few examples. Candidates are represented by the BtaCandidate class. Lists, specifically HepALists, of BtaCandidates are stored in an event (type AbsEvent). Possible lists in an event may be of charged tracks or of muon candidates.

Some basic information about a candidate may be accessed directly via the accessor member functions of the BtaCandidate class. A list (not exhaustive) follows.

  • double charge() const
  • double energy() const
  • double mass() const
  • double p() const
  • Hep3Vector p3() const
  • Hep4Vector p4() const
These values are for the candidate at the origin/decay vertex.

More member functions of the BtaCandidate class are contained in the Workbook Event Store information on Kinematic Variables and EventParameters, and the full list of member functions of the BtaCandidate class is contained in the source code, which can be viewed here.

Most/all information is either directly in or accessible from the BtaCandidate class. The core of any analysis module will consist of accessing data from BtaCandidate lists in events and manipulation of BtaCandidates. This will involve writing or at least modifying existing C++ code and is thus postponed to Analysis which follows the Editing Code section of the workbook. For a complete listing of member functions consult the BtaCandidate header file.


Interactive Beta

Interactive Beta enables the user to re-use Beta code interactively while running an analysis session in ROOT. See the Workbook sections ROOT I, ROOT II and ROOT III for more information about ROOT.
General Related Documents:

Back to Workbook Front Page

Author: Tracey Marsh
Contributors:
Joseph Perl
Charlie Young Jenny Williams
Last updated:
Jenny Williams

Last modification: 7 June 2005
Last significant update: 7 June 2005