Logo ROOT   6.08/07
Reference Guide
TEfficiency.h
Go to the documentation of this file.
1 #ifndef ROOT_TEfficiency
2 #define ROOT_TEfficiency
3 
4 //standard header
5 #include <vector>
6 #include <utility>
7 
8 //ROOT header
9 #ifndef ROOT_TNamed
10 #include "TNamed.h"
11 #endif
12 
13 #ifndef ROOT_TAttLine
14 #include "TAttLine.h"
15 #endif
16 
17 #ifndef ROOT_TAttFill
18 #include "TAttFill.h"
19 #endif
20 
21 #ifndef ROOT_TAttMarker
22 #include "TAttMarker.h"
23 #endif
24 
25 class TCollection;
26 class TF1;
27 class TGraphAsymmErrors;
28 class TH1;
29 class TH2;
30 class TList;
31 
32 class TEfficiency: public TNamed, public TAttLine, public TAttFill, public TAttMarker
33 {
34 public:
35  //enumaration type for different statistic options for calculating confidence intervals
36  //kF* ... frequentist methods; kB* ... bayesian methods
37  enum EStatOption {
38  kFCP = 0, //Clopper-Pearson interval (recommended by PDG)
39  kFNormal, //normal approximation
40  kFWilson, //Wilson interval
41  kFAC, //Agresti-Coull interval
42  kFFC, //Feldman-Cousins interval
43  kBJeffrey, //Jeffrey interval (Prior ~ Beta(0.5,0.5)
44  kBUniform, //Prior ~ Uniform = Beta(1,1)
45  kBBayesian, //user specified Prior ~ Beta(fBeta_alpha,fBeta_beta)
46  kMidP //Mid-P Lancaster interval
47  };
48 
49 protected:
50 
51  Double_t fBeta_alpha; //global parameter for prior beta distribution (default = 1)
52  Double_t fBeta_beta; //global parameter for prior beta distribution (default = 1)
53  std::vector<std::pair<Double_t, Double_t> > fBeta_bin_params; // parameter for prior beta distribution different bin by bin
54  // (default vector is empty)
55  Double_t (*fBoundary)(Double_t,Double_t,Double_t,Bool_t); //!pointer to a method calculating the boundaries of confidence intervals
56  Double_t fConfLevel; //confidence level (default = 0.683, 1 sigma)
57  TDirectory* fDirectory; //!pointer to directory holding this TEfficiency object
58  TList* fFunctions; //->pointer to list of functions
59  TGraphAsymmErrors* fPaintGraph; //!temporary graph for painting
60  TH2* fPaintHisto; //!temporary histogram for painting
61  TH1* fPassedHistogram; //histogram for events which passed certain criteria
62  EStatOption fStatisticOption; //defines how the confidence intervals are determined
63  TH1* fTotalHistogram; //histogram for total number of events
64  Double_t fWeight; //weight for all events (default = 1)
65 
66  enum{
67  kIsBayesian = BIT(14), //bayesian statistics are used
68  kPosteriorMode = BIT(15), //use posterior mean for best estimate (Bayesian statistics)
69  kShortestInterval = BIT(16), // use shortest interval
70  kUseBinPrior = BIT(17), // use a different prior for each bin
71  kUseWeights = BIT(18) // use weights
72  };
73 
74  void Build(const char* name,const char* title);
75  void FillGraph(TGraphAsymmErrors * graph, Option_t * opt) const;
76  void FillHistogram(TH2 * h2) const;
77 
78 public:
79  TEfficiency();
80  TEfficiency(const TH1& passed,const TH1& total);
81  TEfficiency(const char* name,const char* title,Int_t nbins,
82  const Double_t* xbins);
83  TEfficiency(const char* name,const char* title,Int_t nbins,Double_t xlow,
84  Double_t xup);
85  TEfficiency(const char* name,const char* title,Int_t nbinsx,
86  Double_t xlow,Double_t xup,Int_t nbinsy,Double_t ylow,
87  Double_t yup);
88  TEfficiency(const char* name,const char* title,Int_t nbinsx,
89  const Double_t* xbins,Int_t nbinsy,const Double_t* ybins);
90  TEfficiency(const char* name,const char* title,Int_t nbinsx,
91  Double_t xlow,Double_t xup,Int_t nbinsy,Double_t ylow,
92  Double_t yup,Int_t nbinsz,Double_t zlow,Double_t zup);
93  TEfficiency(const char* name,const char* title,Int_t nbinsx,
94  const Double_t* xbins,Int_t nbinsy,const Double_t* ybins,
95  Int_t nbinsz,const Double_t* zbins);
96  TEfficiency(const TEfficiency& heff);
97  ~TEfficiency();
98 
99  void Add(const TEfficiency& rEff) {*this += rEff;}
100  void Browse(TBrowser*){Draw();}
101  TGraphAsymmErrors* CreateGraph(Option_t * opt = "") const;
102  TH2* CreateHistogram(Option_t * opt = "") const;
103  virtual Int_t DistancetoPrimitive(Int_t px, Int_t py);
104  void Draw(Option_t* opt = "");
105  virtual void ExecuteEvent(Int_t event, Int_t px, Int_t py);
106  void Fill(Bool_t bPassed,Double_t x,Double_t y=0,Double_t z=0);
107  void FillWeighted(Bool_t bPassed,Double_t weight,Double_t x,Double_t y=0,Double_t z=0);
108  Int_t FindFixBin(Double_t x,Double_t y=0,Double_t z=0) const;
109  Int_t Fit(TF1* f1,Option_t* opt="");
110  // use trick of -1 to return global parameters
111  Double_t GetBetaAlpha(Int_t bin = -1) const {return (fBeta_bin_params.size() > (UInt_t)bin) ? fBeta_bin_params[bin].first : fBeta_alpha;}
112  Double_t GetBetaBeta(Int_t bin = -1) const {return (fBeta_bin_params.size() > (UInt_t)bin) ? fBeta_bin_params[bin].second : fBeta_beta;}
113  Double_t GetConfidenceLevel() const {return fConfLevel;}
114  TH1* GetCopyPassedHisto() const;
115  TH1* GetCopyTotalHisto() const;
116  Int_t GetDimension() const;
117  TDirectory* GetDirectory() const {return fDirectory;}
118  Double_t GetEfficiency(Int_t bin) const;
119  Double_t GetEfficiencyErrorLow(Int_t bin) const;
120  Double_t GetEfficiencyErrorUp(Int_t bin) const;
121  Int_t GetGlobalBin(Int_t binx,Int_t biny=0,Int_t binz=0) const;
123  TH2* GetPaintedHistogram() const { return fPaintHisto; }
125  const TH1* GetPassedHistogram() const {return fPassedHistogram;}
127  const TH1* GetTotalHistogram() const {return fTotalHistogram;}
128  Double_t GetWeight() const {return fWeight;}
129  Long64_t Merge(TCollection* list);
130  TEfficiency& operator+=(const TEfficiency& rhs);
131  TEfficiency& operator=(const TEfficiency& rhs);
132  void Paint(Option_t* opt);
133  void SavePrimitive(std::ostream& out,Option_t* opt="");
134  void SetBetaAlpha(Double_t alpha);
135  void SetBetaBeta(Double_t beta);
136  void SetBetaBinParameters(Int_t bin, Double_t alpha, Double_t beta);
137  void SetConfidenceLevel(Double_t level);
138  void SetDirectory(TDirectory* dir);
139  void SetName(const char* name);
140  Bool_t SetPassedEvents(Int_t bin,Int_t events);
141  Bool_t SetPassedHistogram(const TH1& rPassed,Option_t* opt);
146  void SetStatisticOption(EStatOption option);
147  Bool_t SetBins(Int_t nx, Double_t xmin, Double_t xmax);
148  Bool_t SetBins(Int_t nx, const Double_t *xBins);
149  Bool_t SetBins(Int_t nx, Double_t xmin, Double_t xmax, Int_t ny, Double_t ymin, Double_t ymax);
150  Bool_t SetBins(Int_t nx, const Double_t *xBins, Int_t ny, const Double_t *yBins);
151  Bool_t SetBins(Int_t nx, Double_t xmin, Double_t xmax, Int_t ny, Double_t ymin, Double_t ymax,
152  Int_t nz, Double_t zmin, Double_t zmax);
153  Bool_t SetBins(Int_t nx, const Double_t *xBins, Int_t ny, const Double_t * yBins, Int_t nz,
154  const Double_t *zBins);
155 
156  void SetTitle(const char* title);
157  Bool_t SetTotalEvents(Int_t bin,Int_t events);
158  Bool_t SetTotalHistogram(const TH1& rTotal,Option_t* opt);
159  void SetUseWeightedEvents(Bool_t on = kTRUE);
160  void SetWeight(Double_t weight);
167 
168  static Bool_t CheckBinning(const TH1& pass,const TH1& total);
169  static Bool_t CheckConsistency(const TH1& pass,const TH1& total,Option_t* opt="");
170  static Bool_t CheckEntries(const TH1& pass,const TH1& total,Option_t* opt="");
171  static Bool_t CheckWeights(const TH1& pass,const TH1& total);
172  static Double_t Combine(Double_t& up,Double_t& low,Int_t n,const Int_t* pass,const Int_t* total,
173  Double_t alpha,Double_t beta,Double_t level=0.683,
174  const Double_t* w=0,Option_t* opt="");
175  static TGraphAsymmErrors* Combine(TCollection* pList,Option_t* opt="",Int_t n=0,const Double_t* w=0);
176 
177  //calculating boundaries of confidence intervals
178  static Double_t AgrestiCoull(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
179  static Double_t ClopperPearson(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
180  static Double_t Normal(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
181  static Double_t Wilson(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
182  static Double_t FeldmanCousins(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
183  static Bool_t FeldmanCousinsInterval(Double_t total,Double_t passed,Double_t level,Double_t & lower, Double_t & upper);
184  static Double_t MidPInterval(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
185  // Bayesian functions
186  static Double_t Bayesian(Double_t total,Double_t passed,Double_t level,Double_t alpha,Double_t beta,Bool_t bUpper, Bool_t bShortest = false);
187  // helper functions for Bayesian statistics
188  static Double_t BetaCentralInterval(Double_t level,Double_t alpha,Double_t beta,Bool_t bUpper);
189  static Bool_t BetaShortestInterval(Double_t level,Double_t alpha,Double_t beta,Double_t & lower, Double_t & upper);
190  static Double_t BetaMean(Double_t alpha,Double_t beta);
191  static Double_t BetaMode(Double_t alpha,Double_t beta);
192 
193  ClassDef(TEfficiency,2) //calculating efficiencies
194 };
195 
196 const TEfficiency operator+(const TEfficiency& lhs,const TEfficiency& rhs);
197 
198 #endif
TGraphAsymmErrors * CreateGraph(Option_t *opt="") const
Create the graph used be painted (for dim=1 TEfficiency) The return object is managed by the caller...
const int nx
Definition: kalman.C:16
void SetConfidenceLevel(Double_t level)
Sets the confidence level (0 < level < 1) The default value is 1-sigma :~ 0.683.
static Double_t Bayesian(Double_t total, Double_t passed, Double_t level, Double_t alpha, Double_t beta, Bool_t bUpper, Bool_t bShortest=false)
Calculates the boundaries for a Bayesian confidence interval (shortest or central interval depending ...
Double_t fBeta_beta
Definition: TEfficiency.h:52
static Bool_t CheckEntries(const TH1 &pass, const TH1 &total, Option_t *opt="")
Checks whether bin contents are compatible with binomial statistics.
float xmin
Definition: THbookFile.cxx:93
long long Long64_t
Definition: RtypesCore.h:69
void Build(const char *name, const char *title)
Building standard data structure of a TEfficiency object.
Class to handle efficiency histograms.
Definition: TEfficiency.h:32
virtual void ExecuteEvent(Int_t event, Int_t px, Int_t py)
Execute action corresponding to one event.
const TH1 * GetPassedHistogram() const
Definition: TEfficiency.h:125
const TEfficiency operator+(const TEfficiency &lhs, const TEfficiency &rhs)
Addition operator.
Bool_t UsesCentralInterval() const
Definition: TEfficiency.h:165
static Double_t BetaCentralInterval(Double_t level, Double_t alpha, Double_t beta, Bool_t bUpper)
Calculates the boundaries for a central confidence interval for a Beta distribution.
const char Option_t
Definition: RtypesCore.h:62
float ymin
Definition: THbookFile.cxx:93
Bool_t TestBit(UInt_t f) const
Definition: TObject.h:157
static Bool_t CheckBinning(const TH1 &pass, const TH1 &total)
Checks binning for each axis.
#define BIT(n)
Definition: Rtypes.h:120
TEfficiency & operator+=(const TEfficiency &rhs)
Adds the histograms of another TEfficiency object to current histograms.
Double_t GetBetaBeta(Int_t bin=-1) const
Definition: TEfficiency.h:112
void FillGraph(TGraphAsymmErrors *graph, Option_t *opt) const
Fill the graph to be painted with information from TEfficiency Internal method called by TEfficiency:...
int Int_t
Definition: RtypesCore.h:41
bool Bool_t
Definition: RtypesCore.h:59
void SetBetaBinParameters(Int_t bin, Double_t alpha, Double_t beta)
Sets different shape parameter α and β for the prior distribution for each bin.
int nbins[3]
~TEfficiency()
default destructor
EStatOption fStatisticOption
Definition: TEfficiency.h:62
void Browse(TBrowser *)
Browse object. May be overridden for another default action.
Definition: TEfficiency.h:100
Bool_t SetPassedEvents(Int_t bin, Int_t events)
Sets the number of passed events in the given global bin.
void SetPosteriorAverage(Bool_t on=true)
Definition: TEfficiency.h:143
Double_t(* fBoundary)(Double_t, Double_t, Double_t, Bool_t)
Definition: TEfficiency.h:55
void SetBit(UInt_t f, Bool_t set)
Set or unset the user status bits as specified in f.
Definition: TObject.cxx:739
double beta(double x, double y)
Calculates the beta function.
Bool_t UsesWeights() const
Definition: TEfficiency.h:166
Double_t GetWeight() const
Definition: TEfficiency.h:128
Marker Attributes class.
Definition: TAttMarker.h:24
TH1 * GetCopyPassedHisto() const
Returns a cloned version of fPassedHistogram.
Double_t fWeight
Definition: TEfficiency.h:64
TGraph with asymmetric error bars.
EStatOption GetStatisticOption() const
Definition: TEfficiency.h:126
Double_t GetEfficiency(Int_t bin) const
Returns the efficiency in the given global bin.
static Double_t Combine(Double_t &up, Double_t &low, Int_t n, const Int_t *pass, const Int_t *total, Double_t alpha, Double_t beta, Double_t level=0.683, const Double_t *w=0, Option_t *opt="")
Calculates the combined efficiency and its uncertainties.
Fill Area Attributes class.
Definition: TAttFill.h:24
Double_t x[n]
Definition: legend1.C:17
#define ClassDef(name, id)
Definition: Rtypes.h:254
TGraphAsymmErrors * fPaintGraph
Definition: TEfficiency.h:59
static Double_t AgrestiCoull(Double_t total, Double_t passed, Double_t level, Bool_t bUpper)
Calculates the boundaries for the frequentist Agresti-Coull interval.
The TNamed class is the base class for all named ROOT classes.
Definition: TNamed.h:33
const int ny
Definition: kalman.C:17
static Bool_t CheckWeights(const TH1 &pass, const TH1 &total)
Check if both histogram are weighted.
TH1 * fPassedHistogram
temporary histogram for painting
Definition: TEfficiency.h:61
Bool_t UsesPosteriorAverage() const
Definition: TEfficiency.h:164
TH1 * fTotalHistogram
Definition: TEfficiency.h:63
TH2 * fPaintHisto
temporary graph for painting
Definition: TEfficiency.h:60
TList * GetListOfFunctions()
const TH1 * GetTotalHistogram() const
Definition: TEfficiency.h:127
TList * fFunctions
pointer to directory holding this TEfficiency object
Definition: TEfficiency.h:58
Bool_t UsesBayesianStat() const
Definition: TEfficiency.h:161
TH2 * GetPaintedHistogram() const
Definition: TEfficiency.h:123
Bool_t SetPassedHistogram(const TH1 &rPassed, Option_t *opt)
Sets the histogram containing the passed events.
void SetTitle(const char *title)
Sets the title.
static Double_t BetaMean(Double_t alpha, Double_t beta)
Compute the mean (average) of the beta distribution.
TDirectory * GetDirectory() const
Definition: TEfficiency.h:117
static Double_t MidPInterval(Double_t total, Double_t passed, Double_t level, Bool_t bUpper)
Calculates the boundaries using the mid-P binomial interval (Lancaster method) from B...
Bool_t SetBins(Int_t nx, Double_t xmin, Double_t xmax)
Set the bins for the underlined passed and total histograms If the class have been already filled the...
void SetStatisticOption(EStatOption option)
Sets the statistic option which affects the calculation of the confidence interval.
Double_t fConfLevel
pointer to a method calculating the boundaries of confidence intervals
Definition: TEfficiency.h:56
A doubly linked list.
Definition: TList.h:47
TH1 * GetCopyTotalHisto() const
Returns a cloned version of fTotalHistogram.
Bool_t SetTotalEvents(Int_t bin, Int_t events)
Sets the number of total events in the given global bin.
void SetWeight(Double_t weight)
Sets the global weight for this TEfficiency object.
Using a TBrowser one can browse all ROOT objects.
Definition: TBrowser.h:41
float ymax
Definition: THbookFile.cxx:93
static Bool_t FeldmanCousinsInterval(Double_t total, Double_t passed, Double_t level, Double_t &lower, Double_t &upper)
Calculates the interval boundaries using the frequentist methods of Feldman-Cousins.
Service class for 2-Dim histogram classes.
Definition: TH2.h:36
void SetBetaAlpha(Double_t alpha)
Sets the shape parameter α.
void SetPosteriorMode(Bool_t on=true)
Definition: TEfficiency.h:142
static Double_t Normal(Double_t total, Double_t passed, Double_t level, Bool_t bUpper)
Returns the confidence limits for the efficiency supposing that the efficiency follows a normal distr...
Collection abstract base class.
Definition: TCollection.h:48
void Add(const TEfficiency &rEff)
Definition: TEfficiency.h:99
unsigned int UInt_t
Definition: RtypesCore.h:42
virtual Int_t DistancetoPrimitive(Int_t px, Int_t py)
Compute distance from point px,py to a graph.
void FillHistogram(TH2 *h2) const
Fill the 2d histogram to be painted with information from TEfficiency 2D Internal method called by TE...
float xmax
Definition: THbookFile.cxx:93
void SavePrimitive(std::ostream &out, Option_t *opt="")
Have histograms fixed bins along each axis?
Definition: graph.py:1
Int_t FindFixBin(Double_t x, Double_t y=0, Double_t z=0) const
Returns the global bin number containing the given values.
static unsigned int total
Bool_t UsesPosteriorMode() const
Definition: TEfficiency.h:162
Bool_t UsesShortestInterval() const
Definition: TEfficiency.h:163
void SetDirectory(TDirectory *dir)
Sets the directory holding this TEfficiency object.
double Double_t
Definition: RtypesCore.h:55
void SetUseWeightedEvents(Bool_t on=kTRUE)
Bool_t SetTotalHistogram(const TH1 &rTotal, Option_t *opt)
Sets the histogram containing all events.
Describe directory structure in memory.
Definition: TDirectory.h:44
Double_t GetEfficiencyErrorUp(Int_t bin) const
Returns the upper error on the efficiency in the given global bin.
Double_t fBeta_alpha
Definition: TEfficiency.h:51
Double_t GetConfidenceLevel() const
Definition: TEfficiency.h:113
void SetShortestInterval(Bool_t on=true)
Definition: TEfficiency.h:144
Double_t y[n]
Definition: legend1.C:17
Double_t GetBetaAlpha(Int_t bin=-1) const
Definition: TEfficiency.h:111
TEfficiency & operator=(const TEfficiency &rhs)
Assignment operator.
Int_t Fit(TF1 *f1, Option_t *opt="")
Fits the efficiency using the TBinomialEfficiencyFitter class.
The TH1 histogram class.
Definition: TH1.h:80
void SetBetaBeta(Double_t beta)
Sets the shape parameter β.
TDirectory * fDirectory
Definition: TEfficiency.h:57
Long64_t Merge(TCollection *list)
Merges the TEfficiency objects in the given list to the given TEfficiency object using the operator+=...
TH2 * CreateHistogram(Option_t *opt="") const
Create the histogram used to be painted (for dim=2 TEfficiency) The return object is managed by the c...
static Double_t FeldmanCousins(Double_t total, Double_t passed, Double_t level, Bool_t bUpper)
Calculates the boundaries for the frequentist Feldman-Cousins interval.
you should not use this method at all Int_t Int_t z
Definition: TRolke.cxx:630
Double_t GetEfficiencyErrorLow(Int_t bin) const
Returns the lower error on the efficiency in the given global bin.
Int_t GetGlobalBin(Int_t binx, Int_t biny=0, Int_t binz=0) const
Returns the global bin number which can be used as argument for the following functions: ...
void SetName(const char *name)
Sets the name.
static Bool_t BetaShortestInterval(Double_t level, Double_t alpha, Double_t beta, Double_t &lower, Double_t &upper)
Calculates the boundaries for a shortest confidence interval for a Beta distribution.
void Draw(Option_t *opt="")
Draws the current TEfficiency object.
void Paint(Option_t *opt)
Paints this TEfficiency object.
static Double_t ClopperPearson(Double_t total, Double_t passed, Double_t level, Bool_t bUpper)
Calculates the boundaries for the frequentist Clopper-Pearson interval.
1-Dim function class
Definition: TF1.h:149
void FillWeighted(Bool_t bPassed, Double_t weight, Double_t x, Double_t y=0, Double_t z=0)
This function is used for filling the two histograms with a weight.
TF1 * f1
Definition: legend1.C:11
void SetCentralInterval(Bool_t on=true)
Definition: TEfficiency.h:145
std::vector< std::pair< Double_t, Double_t > > fBeta_bin_params
Definition: TEfficiency.h:53
Int_t GetDimension() const
returns the dimension of the current TEfficiency object
const Bool_t kTRUE
Definition: Rtypes.h:91
const Int_t n
Definition: legend1.C:16
Line Attributes class.
Definition: TAttLine.h:24
TEfficiency()
default constructor
char name[80]
Definition: TGX11.cxx:109
static Double_t BetaMode(Double_t alpha, Double_t beta)
Compute the mode of the beta distribution.
void Fill(Bool_t bPassed, Double_t x, Double_t y=0, Double_t z=0)
This function is used for filling the two histograms.
static Double_t Wilson(Double_t total, Double_t passed, Double_t level, Bool_t bUpper)
Calculates the boundaries for the frequentist Wilson interval.
static Bool_t CheckConsistency(const TH1 &pass, const TH1 &total, Option_t *opt="")
Checks the consistence of the given histograms.
TGraphAsymmErrors * GetPaintedGraph() const
Definition: TEfficiency.h:122