Short Contents

Table of Contents


Next: , Up: (dir)

The RooRarFit Document

A general ML fitting package based on ROOT/RooFit.

To download rarFit and find more information, please go to SF.net.

You can also get a pdf version of this doc, and a tutorial (pdf, ppt). MyFirstRooRarFit written by Karsten Könekeis also very helpful to beginners.

Current stable RooRarFit version: V00-01-95

Please check online doc for the latest stable version

Supported Root versions: 5.26 and later.

Supported BaBar releases: 24.5.6/analysis-52 and up.

This version of RooRarFit has been compiled, linked and run on RH5/SL5 with Root 5.26-00 and BaBar release code 24.5.6/analysis-52. The code should also work with RH4/SL4 and some earlier versions of Root but this has not been tested.


Next: , Previous: Top, Up: Top

Preface


Next: , Up: Why

What is RooRarFit?

RooRarFit is a general Maximum Likelihood (ML) fitting package based on ROOT / RooFit. It is an application package making use of ROOT/RooFit so physicists can be virtually free from direct ROOT/RooFit coding.


Next: , Previous: What is RooRarFit, Up: Why

Why not use RooFit directly?

A ill-designed tool sometimes can really limit analysis capacity, so for best flexibility and availability, we could be better off using ROOT/RooFit directly. However this fitter requires no direct C++ coding, which is highly preferable for the purpose of productivity.

By using plain text configuration files, it is virtually free of coding for final users, so people do not need much programming experience to use it. Debugging an analysis is quite frustrating and if people have to compile code for individual analyses, he has to make sure the code for every mode is correct and has to debug it if something is wrong.


Previous: Why not use RooFit directly, Up: Why

General Idea of RooRarFit

The idea of the fitter is that it acts as a wrapper of RooFit so that the fitter is driven by a readable text configuration files. It should be easy to implement, easy to improve, and easy to expand. If the goal as a wrapper is clear, all of the features are easy to realize.

The configuration file has three main parts, each having one or more sections.

  1. Dataset Definition
    This defines the dataset and reads in all the datasets.

  2. PDF Configuration

    All the PDFs are defined here. It can have any number of components in the ML function with any number of variables. Each PDF has its own configuration section. Fitter classes are wrappers of those in RooFit, and PDFs like Gaussian, TwoGauss, BifurGauss, Polynomial, etc..., are implemented, as well as combination operations like Add, Prod, etc. So it is very easy to build new PDF, through a configuration file only!

  3. Fitter Action Section

    After every PDF is created, this part of the configuration file is used to direct the fitter to finish its job. Possible actions include fitting the PDFs (pdfFit), fitting the model (mlFit), performing Monte Carlo Toy studies (toyStudy), projection plotting (ProjAct), scanning the log-likelihood distribution (ScanAct), making sPlots (SPlotAct) and combing statitsical and systematic errors (CombineAct). For each fitting job, one can decide which action, or what action combinations, to perform.


Next: , Previous: Why, Up: Top

1 RooRarFit Implementation

The source codes of the new mlFitter can be classified into three groups:

  1. Auxiliary Classes, Files, Main Program and Scripts

  2. Dataset Classes

  3. PDF Classes


Next: , Previous: Implementation, Up: Top

2 RooRarFit Configuration


Next: , Up: Configuration File

2.1 Dataset Configuration

The dataset configs have two parts: one is to define the structure of dataset entry, the other one is to read in and store the datasets.


Next: , Up: Dataset Configuration

2.1.1 Dataset Definition Section

The container of dataset column definitions, an object of class rarDatasetDef, is instantiated by datasets object, rarDatasets, and its configuration section is specified in dataset input section with configuration dsdSec See Dataset Input. If dsdSec is not specified, the default dataset definition section is [Dataset Definition].

Because all these variables declared in this section are globally accessible, they should have unique and meaningful names. (With the naming schema for dataset definition section, the configuration name is its final, unique variable name if the optional full name is not given.)

A sample configuration section for dataset definition is shown below:

     
     [Dataset Definition]
     // Fields defined for datasets
     Fields = onOffRes cosT de mes hiEvtID loEvtID
     
     // Definition for each field
     onOffRes= RooCategory "on/off Ups(4S) resonance" 3 Unknown 0 OnRes 1 OffRes 2
     cosT    = RooRealVar "cosT" 0 1. B(100)
     de      = RooRealVar "#Delta E" -0.01 0.08 B(45) "GeV"
     mes     = RooRealVar "M_{es}" 5.20 5.29 B(45) "GeV"
     kltype  = RooCategory "kltype" 3 emc 0 ifr 1 both 2
     hiEvtID = RooStringVar "TS upperID"
     loEvtID = RooStringVar "TS lowerID"
     

Since many configuration files (for the same analysis or similar analyses) may share the same dataset definition section, it is advisable to put the contents of this section into a separate configuration file and include that file into this section. For example,

     [Dataset Definition]
     // The actual configuration items (shown in the previous example) are in dsd.config
     include dsd.config

This setting also makes the main configuration file more concise.

All these RooAbsArg variables are created using rarConfig::createAbsVar.


Previous: Dataset Definition, Up: Dataset Configuration

2.1.2 Dataset Input Section

The container of all datasets, an object of class rarDatasets, is instantiated by main function of the program, and its configuration section, [Dataset Input], can be changed by command line option, -D "<data input section name>".

A sample configuration section for dataset input is shown below:

     [Dataset Input]
     // Specify dataset definition section
     dsdSec = Dataset Definition
     
     // Specify datasets to be defined
     Datasets = sigMC bkgMC onData gsbData desbData simData
     
     // Definition for each dataset
     sigMC    = ascii "sig MC Data" "omega/dat/omegaks_SIGMC.text" Q // quiet mode
     bkgMC    = ascii "tot bkg MC Data" "omega/dat/omegaks_BKGMC.text" Q
     onData   = ascii "onpeak Data" "omega/dat/omegaks_ONPEAK.text" Q
     gsbData  = reduce "gsd Data" onData "mes<5.27"
     desbData = reduce "de sb Data" onData "(de<-.1)||(de>.1)"
     simData  = add "simulated Data" sigMC 0.0113 bkgMC 6000


Next: , Previous: Dataset Configuration, Up: Configuration File

2.2 PDF Definition Configuration

All PDFs are created from top to bottom with the rarMLFitter object as starting point, and each PDF has its own configuration section. The name of PDF is global which means you can not create a PDF with the same name twice, and the actual PDF creator, rarConfig::createPdf, will return the pointer to the already created PDF instead.

If the name of a RooRarFit PDF is myPdfName, the configuration section for that PDF is [myPdfName Config], and the name of the actual RooFit PDF is the_myPdfName.

In the following sub-sections, we will list configurations for each RooRarFit PDF. Unless explicitly stated, most of these configurations are NOT mandatory. If the configurations are to define default observables of RooRarFit PDF, those configurations are usually mandatory.


Next: , Up: PDF Definition Configuration

2.2.1 Configs Common to All RooRarFit PDFs

There are some configs in PDF config section which are common to all RooRarFit PDFs.


Next: , Previous: commonPdfConfig, Up: PDF Definition Configuration

2.2.2 rarMLFitter Configs

The final mlFitter, an object of class rarMLFitter, is instantiated by main function of the program, and its config section, [mlFitter Config], can be changed by command line option, -C "<mlFitter config section>". This is the master PDF config section, the configs of which might affect all other PDF sections.

After pdf has been created from top to bottom, action section will be invoked to finish fitting jobs. Intermediate fitting results will be saved for later uses. It is crucial for each action to get desired initial values from the right param files. So the fitter is designed to have param file name for each fitter, action, etc., generated automatically. User can specify param file creation rules and refer to the destination param file by the rules. For each action, there are configs to specify IO param files. You can also have those param file configs in the master section, which will override those in action section.

An example is shown below:

     [mlFitter Config]
     Comps = yieldModel
     fitData = onData
     
     simultaneousFit = yes
     
     // SimPdfBuilder configs
     physModels = the_yieldModel // Please remember the RooFit pdf is created with a
                                 // "the_" before the name of RooRarFit PDF object.
     splitCats = kltype tagCat
     protDataVars = kltype tagCat
     the_yieldModel  = kltype : sigma1_deSigTriGauss      \\
                       kltype,tagCat : sigma2_deSigTriGauss, P01_esNN2SigPoly \\
                       kltype : Frac_nSig_kltype[ifr], Frac_nBkg_kltype[ifr] \\
                       tagCat : Frac_nSig_tagCat[04T0], Frac_nBkg_tagCat[04T0]
     


Next: , Previous: rarMLFitterConfig, Up: PDF Definition Configuration

2.2.3 rarMLPdf Configs

rarMLPdf is an extended AddPdf, which serves as prototype pdf for final mlFitter if the final mlFitter is SimPdf, or it will be the final mlFit model if the final mlFitter is not SimPdf.

An example is shown below:

     [yieldModel Config]
     configStr=MLPdf "ml model"
     Comps=SigPdf BkgPdf ChlsPdf
     Coeffs=nSig nBkg nChls
     nBkg =nBkg  6000 L(  0 - 10000)
     nSig =nSig   156 L(-10 -   500)
     nChls=nChls 1300 L(  0 -  3000)


Next: , Previous: rarMLPdfConfig, Up: PDF Definition Configuration

2.2.4 rarMultPdf Configs

rarMultPdf is a wrapper of RooGenericPdf to build a special pdf to deal with different fit ranges for multiple sub mode in simPdf fit.

An example is shown below:

     [mESigS Config]
     configStr = MultPdf
     Comps = mESig mEStep
     
     [mESig Config]
     configStr = TwoGauss
     x = mEta
     meanC =  0.540 L(0.52 - 0.58)
     meanT =  0.530 L(0.52 - 0.58)
     sigmaC = 0.012 L(0.0  - 0.02)
     sigmaT = 0.030 L(0.0  - 0.1)
     fracC =  0.65   L(0.0  - 1.0)
     
     [mEStep Config]
     configStr = Generic
     x = mEta
     formula = "@1 <= @0 && @0 <= @2" x mEStepLo mEStepHi
     mEStepLo = mEStep_mEStepLo 0.485 C L( 0 - 1.0)
     mEStepHi = mEStep_mEStepHi 0.605 C L( 0 - 1.0)


Next: , Previous: rarMultPdfConfig, Up: PDF Definition Configuration

2.2.5 rarProd Configs

rarProd is a wrapper of RooProdPdf to build composite pdf as a product of PDFs.

An example is shown below:

     [SigPdf Config]
     configStr = ProdPdf "Signal Pdf"
     Comps = deSig mesSig fisherSig mOmegaSig heliSig
     fitData = sigMC

An example of multivariate PDF is shown below:

     // The 2D PDF is defined in terms of P(h) and conditional PDF P(m|h)
     // P(m,h)=P(m|h)*P(h)
     [hm2D Config]
     configStr = ProdPdf "P(m,h)"
     Comps = hPdf mPdf
     CondPdfs = mPdf
     CondObss = m
     fitData = sigMC


Next: , Previous: rarProdConfig, Up: PDF Definition Configuration

2.2.6 rarAdd Configs

rarAdd is a wrapper of RooAddPdf/RooAddModel to build composite pdf as a sum of PDFs. There are N-1 free coefficients with N components, or N coefficients if the composite pdf is extended. RooAddModel can only be non-extended pdf.

An example is shown below:

     [fisBkg Config]
     configStr = AddPdf "Add two Pdfs"
     Comps  = fisBkgC fisBkgT
     Coeffs = fracC
     fracC  = T "f_{C}" 0.9 L(0 - 1.)


Next: , Previous: rarAddConfig, Up: PDF Definition Configuration

2.2.7 rarSimPdf Configs

rarSimPdf uses RooSimPdfBuilder to build RooSimultaneous Pdf. This pdf can not be used to build ML fitter model!


Next: , Previous: rarSimPdfConfig, Up: PDF Definition Configuration

2.2.8 rarArgusBG Configs

rarArgusBG is a wrapper of RooArgusBG to build ArgusBG PDF. This distribution was first used by the Argus experiment to descibe the combinatorial background.

An example is shown below:

     [mesBkg Config]
     fitData = desbData
     configStr = ArgusBG
     x = mes
     max = 5.29 C
     c = -20 L(-80 - -.1)
     pow = 0.5 L(-3 - 3)
     postPdfFloat = c


Next: , Previous: rarArgusBGConfig, Up: PDF Definition Configuration

2.2.9 rarBallack Configs

rarBallack implements the Ballack function.

x is the default observable of the pdf. mean is the mean. width is the width. tail is the tail. alpha is the expoential. n is the power.

All the variables can be defined as RooRealVar or RooFormulaVar. See createVar for more info on how to create those variables.

An example is shown below:

     [mSig Config]
     configStr = Ballack
     x     = de
     mean  = 0 L (-1 - 1)
     sigma = 0.003 L(0 - .01)
     alpha = -2 L(-5 - 0)
     n     = 1 L(0 - 10)


Next: , Previous: rarBallackConfig, Up: PDF Definition Configuration

2.2.10 rarBinned Configs

rarBinned implements a binned function.

x is the default observable of the pdf. nbins is the number of bins of the binned function. limits is a list on nbins+1 setting the bounds of those bins. H00... are the nbins+1 free parameters of the binned function. All the variables can be defined as RooRealVar or RooFormulaVar. See createVar for more info on how to create those variables.

An example is shown below:

     [mSig Config]
     configStr = Binned
     x = de
     nbins  = 3
     limits = 0.0 2.0 4.0 5.0
     H00    = 5 L (0.0 - 1.0)


Next: , Previous: rarBinnedConfig, Up: PDF Definition Configuration

2.2.11 rarCruijff Configs

rarCruijff implements a Cruijff function.This distribution is similar to that of a Gaussian with different widths above and below the mean together with a low and high exponential tail.

x is the default observable of the pdf. mean is the mean. sigmaL is the left/low width. sigmaR is the right/high width. alphaL is the left/low exponential tail. alphaR is the right/high exponential tail. All the variables can be defined as RooRealVar or RooFormulaVar. See createVar for more info on how to create those variables.

An example is shown below:

     [cruijffSig Config]
     configStr = Cruijff
     x     = de
     mean     = 0 L (-1 - 1)
     sigmaL = 0.003 L(0 - .01)
     sigmaR = 0.004 L(0 - .01)
     alphaL = 0.01 L(0 - 1)
     alphaR = 0.02 L(0 - 1)


Next: , Previous: rarCruijffConfig, Up: PDF Definition Configuration

2.2.12 rarDecay Configs

rarDecay is a wrapper of RooBCPGenDecay/RooBDecay/RooDecay to build BCPGenDecay / BDecay / Decay Model. These are single or double sided decay functions that can be convolved with a resolution model such as GaussModel. Decay is an exponential decay; BDecay models the decay of the B meson; BMixDecay includes mixing the decay; BCPGenDecay includes CP violation in the decay.

x is the default observable of the pdf. No derived dependent is allowed in rarDecay so please make sure x is observable defined in datasets. tau is the average B0 lifetime. model is the resolution model. decayType can be SingleSided, DoubleSided (default), Flipped.

For BCPGenDecay and BDecay, dm is the mixing frequency; dgamma is the difference in B0/B0bar width; tag is the flavor tag category; w is the mistag rate; dw is the mistag rate difference between B0/B0bar; mu is the difference in tagging efficiency between B0/B0bar; S is CP sine parameter, and C CP cosine parameter, the CP asymmetry parameters The default blindStatus is blind, to unblind, blindStatus must be set to unblind. blindString must be set to a unique string for blinding. blindValues specifies blinding values and scales for C and S, (default .2 .2 .2 .2).

All the `AbsReal' parameters can be defined as RooRealVar or RooFormulaVar, the `AbsCat' parameter can be defined as any RooAbsCategory. See createVar for more info on how to create those variables.

An example is shown below:

     [dtSig Config]
     configStr = BCPGenDecay "CPV signal"
     projWData_dt = yes
     //pdfFit = no
     //pdfPlot = no
     x = dt
     model = sigResModel
     tag = tagFlav                        // tagging category
     tau = dtSigTau  1.530 C L(0.5 - 2.5) // B0 lifetime
     dm  = dtSigDm   0.507 C L(0.2 - 1.0) // B0 mixing frequency
     w   = dtSigAmtr 0.2  C L(0.0 - 0.5)  // mistag rate
     dw  = dtSigDmtr 0.02 C L(-2. - 2.0)  // B0/B0bar mistag rate difference
     mu  = dtSigMu   0.0  C L(-2. - 2.0)  // B0/B0bar tagging efficiency difference
     C = 0.0 L(-3 - 3)                    // direct CP parameter
     S = 0.7 L(-3 - 3)                    // indirect CP parameter
     blindStatus = unblind
     blindString = Physicists do it vivace
     blindValues = .2 .2 .2 .2
     postPdfFloat = C S
     
     [sigResModel Config]
     configStr = TriGaussModel "CPV signal resolution model"
     x = dt
     meanC  = dtSigBiasC "BiasC"  -0.16 C L(-5 - +5)
     sigmaC = dtSigScfaC "ScaleC"  0.732813 C L(.5 - 5)
     meanT  = dtSigBiasT "BiasT"  -1.1140 C  L(-5 - 0)
     sigmaT = dtSigScfaT "ScaleT"  3.00  C L(.5 - 10)
     meanO  = dtSigBiasO "BiasO"   0. C
     sigmaO = dtSigScfaO "ScaleO"  8. C
     fracC  = dtSigFracC "fC"      0.8888 C L(.5 - 1)
     fracO  = dtSigFracO "f0"      0.0033 C L(0. - 0.2)
     msSF = dterr
     protDataVars = dterr
     xtraGenerators = dterrGen


Next: , Previous: rarDecayConfig, Up: PDF Definition Configuration

2.2.13 rarBifurGauss Configs

rarBifurGauss is a wrapper of RooBifurGauss to build Bifurcated Gaussian PDF.

An example is shown below:

     [fisherSig Config]
     configStr = BifurGauss
     x    = fisher
     peak = -.5 L(-2 - 2)
     sigL =  .4 L(0 - 1)
     sigR =  .6 L(0 - 1)
     
     [fisherSig Config]
     configStr = BGGauss
     x = fisher
     mean  = -.5 L(-2 - 2)
     rms   =  .1 L(-0.5 - 0.5)
     asym  =  .6 L(0 - 1)


Next: , Previous: rarBifurGaussConfig, Up: PDF Definition Configuration

2.2.14 rarCBShape Configs

rarCBShape is a wrapper of RooCBShape to build Crystal Ball lineshape PDF. It is a Gaussian with an exponential tail.

An example is shown below:

     [deSig Config]
     configStr = CBShape
     x         = de
     mean      = 0 L(-.01 - .02)
     sigma     = 0.003 L(0 - .01)
     alpha     = -2 L(-5 - 0)
     n         = 1 L(0 - 10)


Next: , Previous: rarCBShapeConfig, Up: PDF Definition Configuration

2.2.15 rarExp Configs

rarExp is a wrapper of RooExponential to build Exponential PDF.

An example is shown below:

     [esNN3Exp Config]
     // the actual final pdf is exp(c*x*x)
     configStr=Exp
     x=RooFormulaVar "@0*@0" esNN3
     c=36 L(0 - 100)


Next: , Previous: rarExp Configuration, Up: PDF Definition Configuration

2.2.16 rarFlatte Configs

rarFlatte is a wrapper of RooFlatte to build a Flatte parameterisation PDF. This is typically used in the decays of the a0(980) or f0(980) where the invariant mass distribution of light scalar mesons near the K Kbar threshold. References: S.M.Flatte Phys. Rev. B63, 224 (1976); B.S.Zou and D.V.Bugg Phys Rev. D48, R3948 (1993); M.Ablikim wt al (BES collaboration), Phys. Rev. D70, 092002, (2004)

An example is shown below:

     [massSig Config]
     configStr = Flatte "f0(980) K*"
     x = mass                    // GeV
     mean  = 0.975 L(0.9 - 1.0)  // GeV
     g0  = 0.1108 L(0.02 - 1.0)  // GeV
     g1  = 0.4229 L(0.02 - 1.0) // GeV
     m0a = 0.13957 C // pi+ mass
     m0b = 0.13957 C // pi- mass
     m1a = 0.49368 C // K+ mass
     m1a = 0.49368 C // K- mass


Next: , Previous: rarFlatte Configuration, Up: PDF Definition Configuration

2.2.17 rarGaussian Configs

rarGaussian is a wrapper of RooGaussian/RooBreitWigner/RooLandau to build Gaussian / Breit-Wigner / Landau PDF.

An example is shown below:

     [deSig Config]
     configStr = BreitWigner
     x = de
     mean = 0 L(-.01 - 0.08)
     sigma = 0.003 L(0 - .1)
     
     [deSig Config]
     configStr = Gaussian
     x = de
     mean = 0 L(-.01 - 0.08)
     sigma = 0.003 L(0 - .1)
     
     [dtErrSig Config]
     configStr = Landau
     x = dtErr
     mean = .75 L(0 - 2.5)
     sigma = .17 L(0 - .5)


Next: , Previous: rarGaussian Configuration, Up: PDF Definition Configuration

2.2.18 rarGaussModel Configs

rarGaussModel is a wrapper of RooGaussModel to build Gaussian Resolution Model.

An example is shown below:

     [dtSigModel Config]
     configStr=GaussModel
     x=dt
     mean=-0.1715 L(-5 - +5)
     sigma=1.0893 L(.5 - 5)
     msSF=dtErr


Next: , Previous: rarGaussModel Configuration, Up: PDF Definition Configuration

2.2.19 rarGeneric Configs

rarGeneric is a wrapper of RooGenericPdf to build Generic PDF using string expression and list of variables.

An example is shown below:

     [esNN2Sig Config]
     configStr = Generic
     formula = "1.+exp(@1*@0)" esNN2 c
     c = -3.294 L(-10 - -1)


Next: , Previous: rarGeneric Configuration, Up: PDF Definition Configuration

2.2.20 rarGounarisSakurai Configs

rarGounarisSakurai is a wrapper of RooGounarisSakurai to build a Gounaris-Sakurai pi-pi scattering PDF.

An example is shown below:

     [massSig Config]
     configStr = GounarisSakurai "#rho K*"
     x = mass                    // GeV
     mean  = 0.790  L(0.7 - 0.9) // GeV
     width = 0.15   L(0.0 - 1.0) // GeV


Next: , Previous: rarGounarisSakurai Configuration, Up: PDF Definition Configuration

2.2.21 rarHistPdf Configs

rarHistPdf is a wrapper of RooHistPdf to build PDF using multidimensional histogram.

An example is shown below:

     [Sig Config]
     configStr = HistPdf
     obs = mes de
     fitData = sigMC


Next: , Previous: rarHistPdf Configuration, Up: PDF Definition Configuration

2.2.22 rarKeys Configs

rarKeys is a wrapper of RooKeysPdf/Roo2DKeysPdf to build 1/2D Keys PDF.

An example is shown below:

     [emcNNSigSimBoth Config]
     configStr = Keys
     x         = emcNN2
     keysOption = MirrorBoth


Next: , Previous: rarKeys Configuration, Up: PDF Definition Configuration

2.2.23 rarLass Configs

rarLass is a wrapper to build the LASS parameterisation of the high mass K*(1430). The default values are taken from Nucl Phys B296, 493 (1988).

An example is shown below:

     [massSig Config]
     configStr=Lass
     x           = mass
     mean        = 1.4      L (1.3 - 1.5)
     turnOffVal  = 1.53   C L (0.2 - 2.0)
     width       = 0.2579 C L (0.2 - 0.5)
     effRange    = 0.1119 C L (0.1 - 4.0)
     scatlen     = 0.05   C L (0.0 - 4.0)


Next: , Previous: rarLass Configuration, Up: PDF Definition Configuration

2.2.24 rarPoly Configs

rarPoly is a wrapper of RooPolynomial/RooChebychev to build Polynomial/Chebychev PDF.

An example is shown below:

     [emcNNSigSimEmc Config]
     configStr = Polynomial "4th order poly"
     x = emcNN2
     nOrder = 4
     P01 = 1 +/- 10 L(-100 - 100)
     P02 = 1 +/- 10 L(-1000 - 1000)
     P03 = 0 +/- 10 L(-1000 - 1000)
     P04 = 0 +/- 10 L(-1000 - 1000)
     
     [mOmegaPolyBkg Config]
     configStr = Chebychev "3rd order Cheby"
     x = mOmega
     nOrder = 3
     P01 = 0.2400 +/- 0.28626 L(-1000 - 1000)
     P02 = 0.1 +/- 0.005 L(-100 - 100)
     P03 = 0.1 +/- 0.005 L(-100 - 100)


Next: , Previous: rarPoly Configuration, Up: PDF Definition Configuration

2.2.25 rarRelBreitWigner Configs

rarRelBreitWigner is a wrapper of RooRelBreitWigner to build a relativistic Breit Wigner with Blatt-Weisskopf form factors. References: PDG..

An example is shown below:

     [massSig Config]
     // in default unts of GeV
     configStr = RelBreitWigner "f0(980) K*"
     x = mass                     // GeV
     mean  = 0.975 L(0.9 - 1.0)   // GeV
     width = 0.044 L(0.02 - 1.0)  // GeV
     mass_a = 0.1396 C // pi mass
     mass_b = 0.1396 C // pi mass
     spin = 1
     
     [massSig Config]
     // in default units of MeV
     configStr = RelBreitWigner "f0(980) K*"
     x = mass                     // MeV
     mean   = 975 L(900 - 1000)   // MeV
     width  = 4.4 L(2 - 1000)  // MeV
     mass_a = 139.6 C // pi mass MeV
     mass_b = 139.6 C // pi mass MeV
     radius = 3100 C // meson radius in MeV
     spin  = 1
     


Next: , Previous: rarRelBreitWigner Configuration, Up: PDF Definition Configuration

2.2.26 rarStep Configs

rarStep is a wrapper of RooParametricStepFunction to build Parametric Step Function PDF.

An example is shown below:

     [esNN2Sig Config]
     configStr=Step
     x=esNN2
     nBins=16
     limits=0 .1 .2 .3 .4 .5 .6 .65 .7 .75 .8 .85 .9 .93 .95 .975 1.
     H00=.05 L(0 - 1)
     H01=.05 L(0 - 1)
     H02=.05 L(0 - 1)
     H03=.05 L(0 - 1)
     H04=.05 L(0 - 1)
     H05=.05 L(0 - 1)
     H06=.05 L(0 - 1)
     H07=.05 L(0 - 1)
     H08=.05 L(0 - 1)
     H09=.05 L(0 - 1)
     H10=.05 L(0 - 1)
     H11=.05 L(0 - 1)
     H12=.05 L(0 - 1)
     H13=.05 L(0 - 1)
     H14=.05 L(0 - 1)


Next: , Previous: rarStep Configuration, Up: PDF Definition Configuration

2.2.27 rarTriGauss Configs

rarTriGauss is a wrapper to build Triple Gaussian / Triple Gaussian Model / Gexp Shape. It is for convenience of those commonly used composite pdfs related to triple-Gaussian.

For TripleGaussian:

For TripleGaussian Model:

An example is shown below:

For GexpShape:

An example is shown below:


Next: , Previous: rarTriGauss Configuration, Up: PDF Definition Configuration

2.2.28 rarTwoGauss Configs

rarTwoGauss is a wrapper to build Double Gaussian PDF.

An example is shown below:

     [deSig Config]
     configStr = TwoGauss "Two Gaussians"
     x  =de
     meanC  = 0    L(-.1 - .1)
     meanT  = 0    L(-.1 - .1)
     sigmaC = 0.02 L(0 - .15)
     sigmaT = 0.1  L(0 - .3)
     fracC  = 0.8  L(0 - 1)


Next: , Previous: rarTwoGauss Configuration, Up: PDF Definition Configuration

2.2.29 rarUniform Configs

rarUniform is a wrapper of RooUniform to build a flat PDF in N dimensions

An example is shown below:

     [Sig Config]
     configStr = Uniform
     obs       = mes de
     fitData   = sigMC


Next: , Previous: rarUniform Configuration, Up: PDF Definition Configuration

2.2.30 rarVoigtian Configs

rarVoigtian implements a Voigtian function. This distribution is a Breit Wigner convoluted with a Gaussian.

x is the default observable of the pdf. mean is the mean of the Breit-Wigner. sigma is the width of the Breit-Wigner. width is the width of the Gaussian convolution function. All the variables can be defined as RooRealVar or RooFormulaVar. See createVar for more info on how to create those variables.

An example is shown below:

     [voigtianSig Config]
     configStr = Voigtian
     x     = de
     mean  = 0 L (-1 - 1)
     sigma = 0.003 L(0 - 1)
     width = 0.004 L(0 - 1)


Previous: rarVoigtian Configuration, Up: PDF Definition Configuration

2.2.31 rarUsrPdf

rarUsrPdf is a wrapper to build user-defined PDF. So for it to work for user-defined PDF, one needs to modify the source code, basically file rarUsrPdf.cc in working release dir. Please follow instructions at the very beginning of the source file:

     // Please change this cc file to make use of your PDF.
     // In many cases, you just need to change codes inside marks:
     //====================================================================>
     //                                                                    v
     //                                                                    v
     //  and
     //                                                                    ^
     //                                                                    ^
     //====================================================================>

There are two main parts need to be changed:

  1. Include header file of user-defined PDF
              //==================================================================>
              // Please include your RooFit Pdf header here                       v
              // #include "mydir/myPdf.hh"                                        v
              
              //                                                                  ^
              //                                                                  ^
              //==================================================================>
         
  2. Create RooAbsReal's and RooAbsPdf in function rarUsrPdf::init()
                //==================================================================>
                // change the lines in between the marks as you want                v
                //                                                                  v
                // first get its obs
                _x=createAbsReal("x", "observable"); assert(_x);
                // Config pdf params
                // instead of a b c etc, you can give them more meaningful names and titles
                // for example
                // _a=createAbsReal("mean", "#mu", 0, -10, 10);
                // _b=createAbsReal("sigma", "#sigma", 0, -10, 10);
                // if you give them different names, please use those names
                // in the PDF config sections,
                // for example, a is now mean, b sigma, etc.
                // [myPdf Config]
                // configStr = UsrPdf
                // x = AbsReal Def
                // mean = AbsReal Def
                // sigma = AbsReal Def
              
                // Default param creation
                _a=createAbsReal("a", "a", 0, -10, 10);
                _b=createAbsReal("b", "b", 0, -10, 10);
                _c=createAbsReal("c", "c", 0, -10, 10);
                _d=createAbsReal("d", "d", 0, -10, 10);
                _e=createAbsReal("e", "e", 0, -10, 10);
                _params.Print("v");
              
                // YOU MUST CREATE YOUR PDF AND SET IT TO _thePdf
                // create pdf
                //_thePdf=new myPdf(Form("the_%s", GetName()),_pdfType+" "+GetTitle(),
                // *_x, *_a, *_b, *_c, *_d, *_e);
                //                                                                  ^
                // change the lines in between the marks as you want                ^
                //==================================================================>
         

Config Directives:

x is the default observable of the pdf. a, b, c, d, and e are the parameters defined in the rarUsrPdf::init(). All the variables can be defined as RooRealVar or RooFormulaVar. See createVar for more info on how to create those variables.

An example is shown below:

     [myPdf Config]
     configStr = UsrPdf
     x = myObs
     a = 36 L(0 - 100)
     b = 36 L(0 - 100)
     c = 36 L(0 - 100)
     d = 36 L(0 - 100)
     e = 36 L(0 - 100)


Next: , Previous: PDF Definition Configuration, Up: Configuration File

2.3 Fitter Actions Configuration

After every pdf is created, fitter action section is used to direct the fitter to finish its jobs. The default action section, [Fitter Action], can be changed by command line option, -A "<fitter action section>". The default for all pdf actions are no action. It is advisable to have several sections with one action per section, and then run the fitter with -A option to specify which action to fulfill.

Each action works like a pipe: it has input from other action or initial values, it then outputs param/root files as other actions' input or final results for user to review. Each action initializes its params by reading in intermediate param file, and each action also has configs to override those intermediate params after reading them in.

The param value overriding order is: Initial values from pdf config sections will be overridden by input param file (except for pdfFit action if prePdfReadParams and prePdfReadSecParams are default); then values from input param file are overridden by values specified in action section and param section with config xxxReadSecParams, finally, the constant attributions will be overridden/specified with configs postPdfFloat, preMLFix, and preMLFloat in pdf config and/or action sections. Before params are saved into param files, they will be set to constant.


Next: , Up: Fitter Actions Configuration

2.3.1 pdfFit Action

pdfFit action is to fit pdfs to particular datasets to get their parameters. Pdfs, datasets, etc., can be plotted after fitting.

The default param input is the initial values after all PDFs are created. Configs prePdfReadParams and prePdfReadSecParams can be used to change the initial values. The output param file is the default input for toy study and ML fit. One can override any fitted values from this action by some configs listed below. ROOT file containing plots produced by this action is for user to review the fitting. As always, log file also provides useful information.

prePdfReadParams has been dropped. The reason for this is that pdfFit is really the very first step in the fitting procedure and you really want to make sure everything you put here is what you mean. So place the initial values into the config file and make sure they are reasonable. With another file overriding the config file, I can only see more trouble and subtlety. A corollary is that never change the intermediate param files, and if you want to change the param values in those files, change them in the config file.

An example is shown below:

     [Pdf Fit Action Config]
     // pdfFit options
     pdfFit = yes
     //pdfToFit = deSig deBkg
     postPdfMakePlot = yes
     postPdfWriteParams = yes


Next: , Previous: pdfFit Action, Up: Fitter Actions Configuration

2.3.2 toyStudy Action

toyStudy action is used to validate the fitting procedure. To split a large toy job into several smaller ones, different command line option -t <toyID> must be given for different jobs to enable different random seeds, output root file names, etc.

The default param input is the intermediate param file from pdfFit action. Configs preToyReadParams and preToyReadSecParams can be used to change the initial values. (After unblind, you may want to change the input to the intermediate param file from mlFit action. See config preToyReadParams below for howto.) There is no param file output. ROOT file containing toy study results produced by this action is for user to review. As always, log file also provides useful information.

If all or part of the events of a component are embedded from datasets other than generated from PDF, the pulls of yields are calculated based on wrong true value by RooFit, in this case, please use pull calculated by RooRarFit, with suffix _embd after the pull name. For example, yield nSig's pull will be nSigpull_embd.

An example is shown below:

     [toyStudy Action Config]
     // toy options
     toyStudy = yes
     // init values for yields
     nSig = 160 L(0 - 300)
     nChmls = 1703 L(0 - 30000)
     nBkg = 5000 L(0 - 30000) // largest number will be adjusted
     preToyRandParams = dtSig_C "@0*cos(@1) R theta" dtSig_S "@0*sin(@1) R theta"
     preToyRandGenerators = Rpdf thetaPdf
     protDatasets = onData //names of protDatasets
     toyNexp = 400 // # experiments
     toyNevt = 0 fixed // default: 0      set to protData #evt
                       //          fixed  no fluctuation
     // if it is pure toy, you do not need to specify how to generate
     // for embedded toy, for example you can do
     toySrc_nSig = sigMC "@0 nSig" // from sigMC
     toySrc_nChmls = bbMC 10 pdf "@0-10 nChmls" // 10 from bbMC, the rest from pdf
     
     [Rpdf Config]
     configStr = Generic
     formula = "@0*@0" R
     R = R 0 L(0 - 1)
     [thetaPdf Config]
     configStr = Generic
     formula = "1" theta
     theta = theta 0 L(-3.14159265358979323846 - 3.14159265358979323846)


Next: , Previous: toyStudy Action, Up: Fitter Actions Configuration

2.3.3 mlFit Action

mlFit action is to fit full ml model to (on-peak) dataset to get yields, etc.

The default param input is the intermediate param file from pdfFit action. Configs preMLReadParams and preMLReadSecParams can be used to change the initial values. The intermediate param output file have the final values from the ML fit, and will be used as input for all kind of plotting. There is no ROOT file output. All the results are shown in log file.

An example is shown below:

     [ML Fit Action Config]
     // mlFit options
     mlFit=yes
     //mlFitOption=emhr
     postMLSignf = nSig
     postMLSysParams = deSig_scale .05V deSig_simga
     postMLSysVars = nSig fL


Next: , Previous: mlFit Action, Up: Fitter Actions Configuration

2.3.4 scanPlot Action

scanPlot action is to scan NLL within interested param space. The recorded values in dataset or plot for scanPlot are actually 2NLL so they are chisquares.

The default param input is the intermediate param file from mlFit action. preScanPlotReadParams and preScanPlotReadSecParams can be used to change the initial values. There is no intermediate param file output. ROOT file containing scanPlots produced by this action is for user to review. As always, log file also provides useful information.

RooRarFit provides a set of static functions to manipulate (combine/shift/add errors) the NLL curves (for 1D scanPlot). combine.cc and combine.C show the usage. (Copy combine.C to workdir and edit it to use.)

An example is shown below:

     [BrScan]
     // scanPlot options
     scanPlot = yes
     scanVars = BR 0 10
     nScanPoints = 50


Next: , Previous: scanPlot Action, Up: Fitter Actions Configuration

2.3.5 projPlot Action

projPlot action is to get projection plots.

The default param input is the intermediate param file from mlFit action. preProjPlotReadParams and preProjPlotReadSecParams can be used to change the initial values. There is no intermediate param file output. ROOT file containing projPlots and LLR plots produced by this action is for user to review. As always, log file also provides useful information.

An example is shown below:

     [ProjAct]
     // projectionPlot options
     projPlot = yes
     preProjPlotReadParams = yes
     projPlotFile = default
     projComps = SigPdf
     projVars = de mes
     // for de
     projLRatioCut_de = .45
     plotBins_de = 20
     projFindOptimCut_de = yes
     projOptimStep_de = .001
     projOptimRange_de = "abs(de)<0.07"
     // for mes
     projLRatioCut_mes = .55
     plotBins_mes = 16
     projFindOptimCut_mes = yes
     projOptimStep_mes = .001
     projOptimRange_mes = "mes>5.274&&mes<5.286"
     // for all other implicitly
     projLRatioCut = .85
     projFindOptimCut = no
     projOptimStep = .005


Next: , Previous: projPlot Action, Up: Fitter Actions Configuration

2.3.6 contourPlot Action

contourPlot action is to get 2NLL contour plots for two floating parameters.

The default param input is the intermediate param file from mlFit action. preContourPlotReadParams and preContourPlotReadSecParams can be used to change the initial values. There is no intermediate param file output. ROOT file containing contourPlots produced by this action is for user to review. As always, log file also provides useful information.

An example is shown below:

     [fLvsNsigContour]
     // contourPlot options
     contourPlot = yes
     preContourPlotReadParams = yes
     contourPlotFile = default
     contourVars = nSig fL
     nContours = 3


Next: , Previous: contourPlot Action, Up: Fitter Actions Configuration

2.3.7 sPlot Action

sPlot action is to get sPlots.

The default param input is the intermediate param file from mlFit action. preSPlotReadParams and preSPlotReadSecParams can be used to change the initial values. There is no intermediate param file output. ROOT file containing sPlots and sWeighted datasets produced by this action is for user to review. As always, log file also provides useful information.

An example is shown below:

     [de sPlot Action Config]
     // sPlot options
     sPlot=yes
     preSPlotReadParams=yes
     sPlotFile=default
     sPlotComps=all
     sPlotVar=de
     plotBins_de=15


Previous: sPlot Action, Up: Fitter Actions Configuration

2.3.8 combinePlot Action

The combinePlot action is used to combine the NLL curves from the scan action and convoluted them with systematic errors. The systematic errors can be categorized as additive errors, uncorrelated multiplicative errors and correlative multiplicative errors. The significance of the central value including the combined systematic and statistical errors can be calculated as well as an upper limit at a chosen confidence level.

An example is shown below:

     [CombineAct]
     combinePlot = yes
     combineNcurves = 2 // combine two curves
     combineFilenames = "results/RhozKp_Kz.mlFitter_Config.scanPlot.rhoBRScan.root" \\
                        "results/RhozKp_Kp.mlFitter_Config.scanPlot.rhoBRScan.root"
     combinePlotnames = "NLLScanPlot_measBR_Sig" \\
                        "NLLScanPlot_measBR_Sig"
     combineCentralValues = 4.73 3.52 // central value e.g. branching fraction x 10^-6
     combineAdditive     =  0.5004 0.460768 // symmetric errors for 2 curves
     combineMultiplicativeUncorrelated = 0.00946 0.007 // uncorrelated multiplicative errors
     combineMultiplicativeCorrelated = 0.211 0.1858 // correlated multiplicative errors
     //combineFitBias  = 0.0 0.0 // fit bias if not already corrected for. (default)
     combineUpperLimit = yes 90 // calculate 90% C.L. upper limit (default)
     combineXaxisTitle = "Branching Fraction (#times 10^{-6})"


Previous: Fitter Actions Configuration, Up: Configuration File

2.4 Sample Configurations

You can find sample configuration files here (Babar internal only). Please copy the sample config file and its dsd file to workdir to run. A few typical config files are explained below:


Next: , Previous: Configuration File, Up: Top

3 RooRarFit Tutorial File


Next: , Up: Tutorial File

3.1 Introduction

RooRarFit comes with example configuration files that can be used for regression testing and to test out the RooRarFit commands. The files are available in RooRarFit/doc/tutorial/. You will first need to generate the test dataset. To generate a dataset that can be used for regression testing or tutorials:

This will create 3 datasets (in ascii and root format) in ./Ntuples

The dataset is a simulated B0/B0bar (or B+/B-) decay at the B-factories including mixing and CP violation. The dataset can be used to measure yields, branching fractions, charge CP asymmetries and Time-dependent CP Violation with event-by-event errors.

The datasets contain the following variables (in this order in the ascii files):

Variable Description of the input variables
mes B mass (GeV/c^2).
deltae Difference in energy of B and sqrt(s)/2 (GeV).
mass A resonance mass (GeV/c^2).
nn A Multi-Variate distribution (e.g. Fisher).
dt Time difference between the two B decays (ps).
tag Flavour tag (B0=1,B0bar=-1) if data treated as B0/B0bar decay.
sigmode a flag that indicates if the K* decayed to K+pi- or K0s pi0. This can be used as a test of Simultaneous fits and branching fraction measurements.
charge The charge (B+=+1,B-=-1) if data treated as B+/B- decay. The signal has a charge asymmetry Acp = -0.05.
run A run number (500 or 1000 = signal, 2000 = continuum bkg, 3000 = peaking bkg).
dterr The error on the time difference, dt (ps).

Once the dataset has been generated the configuration files can be used to test various aspects of RooRarFit. The configuration file will create a test “real dataset” that will contain: 100 signal events, 4000 continuum background events and 500 peaking background events. The input values of the fitted variables and the values returned by RooRarFit are given in the following table:

Variable Input Fitted
Yield (events) 100 105 +/- 18
BF (x 10^-6) 5.22 5.47 +/- 1.0
Charge Asymmetry -0.05 -0.19 +/- 0.16
S 0.7 0.6 +/- 0.22
C 0.0 0.003 +/- 0.15

If you want more accurate fitted results, increase the number of signal events in the “real data” sample in tutorial.config e.g.

     // In tutorial.config, edit the next line to increase the number of
     // signal events sigMC from 100 (up to 10000)
     simData  = add "MC cocktail" sigMC 100 bkgMC 500 udsMC 4000

When you run the examples, the numerical values of the fits are stored in the ./.params directory and the ROOT files containing any plots, ntuples or histograms are stored in ./results.


Next: , Previous: Tutorial Introduction, Up: Tutorial File

3.2 Example 1 (Yields and Actions):


Next: , Previous: Tutorial Example 1, Up: Tutorial File

3.3 Example 2 (Branching Fraction):

To convert the signal yield into a branching fraction taking into account any fit bias:


Next: , Previous: Tutorial Example 2, Up: Tutorial File

3.4 Example 3 (Charged asymmetries):

To fit the PDFs for a charged asymmetry Acp measurement, first change “simultaneousFit = no” to “simultaneousFit = yes” in section “[mlFitter Config]” in tutorial.config. Then:


Previous: Tutorial Example 3, Up: Tutorial File

3.5 Example 4 (time dependent asymmetries)

To fit the PDFs for a time dependent measurement,


Next: , Previous: Tutorial File, Up: Top

4 Questions and Answers

  1. How to build this doc?

    In release dirirectory, type gmake RooRarFit.guide. Make sure you have the right versions of texinfo and doxygen.

  2. My splitting rule for a model is very long, is there any limits on it?

    RooFit does have limit on how long a splitting rule can go for a model. (The limitation will be removed in the next major RooFit release.) The current default value is 4096, you can make it 10 times larger by applying the patches.

  3. How to blind yields?

    CP parameters C and S are the variables can be set to blind easily. You can choose to blind your yields (or any variable), but it is not quite as easy.

              [yourYieldModel Config]
              yBlindCat = yBlindCat RooCategory "Yield blind state" useIdx Blind 1 Unblind 0
              Comps  = Sig Chmls Bkg
              Coeffs = nbSig nbChmls nbBkg
              nbSig  = nbSig RooUnblindOffset "blind nSig" "keep yield of mode xxx blind" 10 nSig yBlindCat
              nbChmls = nbChmls RooUnblindOffset "blind nChmls" "keep yield of mode xxx blind" 10 nChmls yBlindCat
              nbBkg   = nbBkg RooUnblindOffset "blind nBkg" "keep yield of mode xxx blind" 20 nBkg yBlindCat
              nSig   = nSig 200 L(10 - 500)
              nChmls = nChmls 1000 L(0 - 10000)
              nBkg   = nBkg 2000 L(0 - 10000)
         

    You may also want to add option "b" to configuration mlFitOption in action section to suppress RooFit messages from fit.

  4. I would like to include a component in my fit for self crossfeed (SXF) signal events. I will then fix the fraction of self crossfeed, and then in my final fit just float the total signal yield.

    Sample configs dealing with SXF Pdf in that fashion can be found in sxfSig.config. Please notice that this configuration file is NOT complete.

  5. I am trying to set up a toy job where I embed signal MC and BB MC events with continuum background events generated from the PDFs and then fit with only the signal and continuum background components (no BB component in the fit). I want to use this type of fit to determine if I need a BB component or not.

    Suppose your fitter has been setup correctly with two yield components, nSig and nBkg, your signal MC dataset is sigMC, and BB dataset is bbMC. In your action section for toy study, change or add:

              toySrc_nSig = sigMC 90 // 90 embedded signal events for nSig
              toySrc_nBkg = bbMC 27 pdf "@0-27 nBkg" // Bkg has two parts, 27 from bbMC, the rest from pdf
         

  6. Why my pulls for embedded yields look wrong?

    See toyStudy Action, (2nd paragraph).

  7. How to get number of embedded events from individual samples in toy study output root file?

    Entries for number of embedded events from individual samples in toy study root file are named as embdEvt_<toySrc_name>, for example, embedded event number for sigMC is in entry named embdEvt_sigMC.

  8. I have deSig pdf parameters split, how can I get the split parameters for simultaneous pdf in the fit?

    In [deSig Config] section, add/change

              pdfFit = simFit
         

    See commonPdfConfig.

  9. How to fit components of product pdf together?

    For example, SigPdf is product PDF, in section [SigPdf Config] add/change config

              ndFit = yes
         

  10. How to create/add my own RooAbsPdf?

    See rarUsrPdf Configuration.

  11. I have built a model. Can I fix/float on fit action basis some parameters previous floated/fixed when I built it in PDF configuration sections?

    Yes. For example, if you have nSig as yield and float it, but want to fix it for sPlot, in action section for sPlot, add/change:

              preMLFix = nSig
         

    Please go through configs postPdfFloat, preMLFix, and preMLFloat for more detailed instructions.

  12. Can I embed a fraction of event, for example, 11.3, for embedded toys? This does not make sense to me since you can only get integer events from datasets.

    Yes, you can. Here is how it works. If you allow Poisson fluctuation, it will embed number of events per experiment which is subject to Poisson fluctuation with mean at 11.3. If you do not allow Poisson fluctuation, it will generate 11 or 12 events randomly per toy experiment with mean at 11.3.

  13. Can I use toy sample for mlFit, scanPlot, sPlot, etc?

    Yes. For toyStudy, the first toy sample generated will be saved as "toySample", so in the same action section, other actions following toyStudy can use the sample, for example, to do sPlot. Just give toySample as configuration for input data, for example

              [ToySPlotAct]
              // toy options
              toyStudy = yes
              preToyReadParams = A mlFit
              preToyReadSecParams = MCParamSec
              toyNexp = 1 // # experiments
              toyNevt = 0 extended
              // init values
              nKKKst = 70  +/- 44 C L(-1000 - 1000)
              nKsKsKs = 20  +/- 44 C L(-1000 - 1000)
              nKKPiZ = 2.3 +/- 100 C L(0 - 1000)
              nSig = 100 +/- 20.00 L(-100 - 500)
              // for embedded toy study
              toySrc_nSig = sigMC "@0 nSig"
              // ml fit
              mlFit = yes
              mlFitData = toySample
              preMLReadParams = no
              preMLReadSecParams = no
              postMLWriteParams = no
              // sPlot
              sPlot = yes
              sPlotData = toySample
              sPlotSaveSWeight = yes
              sPlotVars = mes de
              preSPlotReadParams = no
              preSPlotReadSecParams = no
         


Previous: QA, Up: Top

Index