Beta: A package for analysis access to reconstructed data

This page is under continuous construction.
On this page:
Introduction
Status: [Existing features] [Missing features]
Using Beta: [Using candidates] [Getting started] [Hints and tips]
Reference Information
Other pages of interest: [Project list for Beta] [Older Beta information] [ Analysis tools Hypernews page] [Physics and analysis page] [Workbook Quick Tour] [Beta design notes] [Guide to the BetaUser package]

Recent Changes

• 29 Aug, 1999 -- Added link to Tag, Micro info page (BobJ)
• 21 Jul, 1999 -- Changed Tutorial to use Workbook Quick Tour - CCY
• 13 Aug, 1998 -- General cleanup - BobJ
• 14 Oct, 1997 -- Changed Tutorial pointer - BobJ
• 31 July, 1997 -- Made instructions more explicit, added warning - BobJ
• 19 July, 1997 -- Fix lots of typos - BobJ
• 6 July, 1997 -- Update status with Beast - BobJ
• 29 Apr, 1997 -- Tutorial pointers - BobJ

Introduction

Its primary goal is to provide a simple, common basis for writing detailed physics analysis programs.

• It must be very easy to use, with easy to understand metaphors for common tasks, and without requiring the user to master the archania of the C++ programming language.
• It must be complete, in the sense that it permits the analyst to examine anything available within the reconstruction processing and output.
• It must be common, which means that it must be usable on all supported machines, with all our sources of data, at all levels of detail.
• So long as the required information is available, an analysis routine should run on Aslund, bbsim and real data output, and regardless of how sparsified and compressed.

To do this, Beta defines several basic concepts:

Candidate

A candidate is the Beta representation of what is known or assumed about some particle that may have existed in the event in question. Charged tracks can be candidate pions, neutral clusters can be candidate photons. The output of vertexing two candidates is another candidate, representing the "particle" that might have decayed to those two tracks. There are many types of candidates, from different sources and with different implementations. But all of them provide the same, complete interface, so they can be used interchangeably.

Operator

An operator can combine one or more candidates to form new ones. Vertexing, mass constrained fitting, and simple 4vector addition are all operators. The analyst selects the operator needed at particular stages in the analysis, trading off accuracy and completeness for speed and flexibility.

In addition, we are trying to define some higher level concepts. If we can make these useful, yet common, it will help us share analysis algorithms across the collaboration, and between reconstruction and analysis:

Selectors

A basic operation of analysis is applying "cuts" to select hypotheses that are acceptable. For example, a kaon candidate might have to pass cuts on the signatures seen in the DIRC and dE/dx. To the extent that these are reusable in other analyses, they become "selectors". We expect to have a whole spectrum, ranging from general PID selectors based on various algorithms, to selectors for various forms of composite particles (D and B mesons, for example), down to ones that are very specific to a particular analysis.

Associators

Its often useful to "associate" one Candidate with another during analysis. Reco candidates are associated with their appropriate Monte Carlo truth candidates, charged track candidates are associated with neutral cluster candidates, etc. The BtaAssociator classes provide a family of ways to do this with a consistent interface.

• The Beta tutorial is now in the Quick Tour section of the User Workbook
• Documentation of the Tag and Micro information
• Recent posts in the Analysis Tools Hypernews group
• The Beta design notes

Status

Although not complete, these lists are current as of release 6.10.5

Existing features

• Particle Data Table access
• Vertexing of composite Candidates
• PID access class(es) and pointers
• Position and other spatial information from Candidate
• Filled MC mother/daughter truth information for all modes
• Add4 and multiple vertexing operators for combining candidates by just adding their four-vectors, or by spatial vertexing
• vector3 and vector4 from BtaCandidate for vector algebra
• p(Point) support in BtaCandidate, plus an implementing subclass
• Genealogy and combinatorics support, overlaps()
• Errors on positions and momenta
• Support for PID selectors

Missing features

Using Beta

Getting started

Flags used when building a Beta executable

Contents

BetaUser

The sample package, on which you can build simple analyses

Beta

Candidate classes, base classes, etc.

BetaExamples

Analysis-level examples of techniues you might want to use in your program

BetaTools

Analysis-level tools

BetaAslund

The interface for running with Aslund input

BetaReco

The interface modules for running on reconstructed data

BetaRecoAdapter

Code connecting Beta to reconstruction objects

BetaSequences

Sequences and .tcl files used by Beta to run in various modes

BetaMC

The interface for running on reconstructed data

BetaP

Event store persistance for Beta candidates

Of these, only the first four are likely to contain files of direct interest to the average user.

In addition, there are a number of physics tools packages that are based on Beta. Some of these are so closely coupled that people think of them as being part of Beta itself. For an introduction to the structure of these, see the guide to the PhysProdTools package, available in that Package.

Some files of interest in the BetaUser package:

  README                - similar to this page, perhaps more up-to-date

  runtime.input         - input file for Aslund, copy to workdir to use.
                          Generates B0 -> J/psi(ll) K0s, B0~ -> nothing; default
                          is general B decays

  SampleBetaAnalysis.cc - code for a simple J/psi search

  README                - similar to this page, perhaps more up-to-date

  BetaTest.cc           - boring module for doing specific regression tests,
                          normally disabled by the script
  
  test.tcl              - script to run regression test
  

Using candidates

Accessors to contained information, stated at the primary vertex

double charge() const

HepLorentzVector p4() const

double mass() const

Hep3Vector p3() const

double energy() const

The addition operation combines Lorentz vector and charge, but does not maintain mother/daughter information, because it returns a "Lorentz vector with charge information"

HepLorentzVectorQ& operator +=( const BtaCandidate &)

HepLorentzVectorQ operator +( const BtaCandidate &) const

Accessors to values at nearest approach to a point. Note that these can be significantly slower and/or less accurate than accessing the information at the IP.

HepLorentzVector p4(const HepPoint& pt) const

Hep3Vector p3(const HepPoint& pt) const

Accessors to specific information, not present in all Candidates

const AbsRecoTrack* recoTrk() const

const BtaAbsVertex* decayVtx() const

Candidates can maintain "genealogy" information, which consists of links to "mothers" and "daughters". The daughters of a candidate C are those candidates that were used by a BtaOperator to create C. C is a mother to each of those daughters. A candidate can have more than one mother. Member functions are provided to navigate those relations.

int nMothers() const

int nDaughters() const

HepAListIterator<BtaCandidate> motherIterator() const

HepAListIterator<BtaCandidate> daughterIterator() const

bool overlaps(const BtaCandidate&) const

Two candidates are said to "overlap" if they or at least one of their daughters are the same object. This includes the various form of "in-law" relations, but not most form of "cousins". (Shared daughters overlap, but not shared mothers)

Service routines:

virtual void print(ostream& o) const

BtaCandidate& operator =( const BtaCandidate &)

Three separate lists of BtaCandidates are kept in each BaBar event by Beta itself: One for Monte Carlo truth information, one for candidates made from reconstructed charged tracks, and one for candidates made from reconstructed neutral objects. These are kept separate to simplify user analysis code; the candidate objects themselves are interchangable.

The available operators are:

BtaOpAdd4

for combining

various vertexing and kinematic fitting operations

See the vertexing groups web page

    BtaOpAdd4 op;
    
    c3 = op.combine(c1,c2);

The + operator is also defined between two candidates. Its intended to be very fast, and the object it returns therefore does not have a lot of function. In particular, it does not remember which parent tracks it was made from.

    HepLorentzVectorQ vect;
    vect = c1+c2;

Hints, tips, pitfalls

Sample code for a simple analysis is provided in the SampleBetaAnalysis files. It's intended as an example of several techniques, not a first step toward a polished analysis. It searches for K0s -> pi+ pi- as an example of a finder routine and vertexing, and then searches for J/psi -> 2 charged tracks using a double loop. (It would be more efficient, though perhaps a less interesting tutorial, to use a finder for both searches, then combine the outputs) It makes various histograms of masses before and after fits, decay lengths, momenta in lab and CM frame, etc.

The sample executable also includes the PrintModule (for printing event summary information) and DispModule (for event display). These are by default disabled by the sample script, but can easily be enabled if desired.

Because this package continues to evolve, the sample code will be receiving updates. To avoid uncontrolled changes to your code when doing CVS updates in the BetaUser directory, it would be wise to rename SampleBetaAnalysis.* to something like MyAnalysis.* before you start to use it. (This will require corresponding changes to names in the MyAnalysis.* and AppUserBuild.cc files)

An analysis module, like the SampleBetaAnalysis that's provided as an example, is a class. Variables that are needed from event to event can therefore be stored as member variables and directly accessed. The histograms in the sample are done this way, as they are created in the begin() routine, used in the event() routine, and deleted in the end() routine.