Logo ROOT   6.14/05
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 #include "TNamed.h"
10 
11 #include "TAttLine.h"
12 
13 #include "TAttFill.h"
14 
15 #include "TAttMarker.h"
16 
17 #include "TFitResultPtr.h"
18 
19 
20 class TCollection;
21 class TF1;
22 class TGraphAsymmErrors;
23 class TH1;
24 class TH2;
25 class TList;
26 
27 class TEfficiency: public TNamed, public TAttLine, public TAttFill, public TAttMarker
28 {
29 public:
30  //enumaration type for different statistic options for calculating confidence intervals
31  //kF* ... frequentist methods; kB* ... bayesian methods
32  enum EStatOption {
33  kFCP = 0, //Clopper-Pearson interval (recommended by PDG)
34  kFNormal, //normal approximation
35  kFWilson, //Wilson interval
36  kFAC, //Agresti-Coull interval
37  kFFC, //Feldman-Cousins interval
38  kBJeffrey, //Jeffrey interval (Prior ~ Beta(0.5,0.5)
39  kBUniform, //Prior ~ Uniform = Beta(1,1)
40  kBBayesian, //user specified Prior ~ Beta(fBeta_alpha,fBeta_beta)
41  kMidP //Mid-P Lancaster interval
42  };
43 
44 protected:
45 
46  Double_t fBeta_alpha; //global parameter for prior beta distribution (default = 1)
47  Double_t fBeta_beta; //global parameter for prior beta distribution (default = 1)
48  std::vector<std::pair<Double_t, Double_t> > fBeta_bin_params; // parameter for prior beta distribution different bin by bin
49  // (default vector is empty)
50  Double_t (*fBoundary)(Double_t,Double_t,Double_t,Bool_t); //!pointer to a method calculating the boundaries of confidence intervals
51  Double_t fConfLevel; //confidence level (default = 0.683, 1 sigma)
52  TDirectory* fDirectory; //!pointer to directory holding this TEfficiency object
53  TList* fFunctions; //->pointer to list of functions
54  TGraphAsymmErrors* fPaintGraph; //!temporary graph for painting
55  TH2* fPaintHisto; //!temporary histogram for painting
56  TH1* fPassedHistogram; //histogram for events which passed certain criteria
57  EStatOption fStatisticOption; //defines how the confidence intervals are determined
58  TH1* fTotalHistogram; //histogram for total number of events
59  Double_t fWeight; //weight for all events (default = 1)
60 
61  enum EStatusBits {
62  kIsBayesian = BIT(14), //bayesian statistics are used
63  kPosteriorMode = BIT(15), //use posterior mean for best estimate (Bayesian statistics)
64  kShortestInterval = BIT(16), // use shortest interval
65  kUseBinPrior = BIT(17), // use a different prior for each bin
66  kUseWeights = BIT(18) // use weights
67  };
68 
69  void Build(const char* name,const char* title);
70  void FillGraph(TGraphAsymmErrors * graph, Option_t * opt) const;
71  void FillHistogram(TH2 * h2) const;
72 
73 public:
74  TEfficiency();
75  TEfficiency(const TH1& passed,const TH1& total);
76  TEfficiency(const char* name,const char* title,Int_t nbins,
77  const Double_t* xbins);
78  TEfficiency(const char* name,const char* title,Int_t nbins,Double_t xlow,
79  Double_t xup);
80  TEfficiency(const char* name,const char* title,Int_t nbinsx,
81  Double_t xlow,Double_t xup,Int_t nbinsy,Double_t ylow,
82  Double_t yup);
83  TEfficiency(const char* name,const char* title,Int_t nbinsx,
84  const Double_t* xbins,Int_t nbinsy,const Double_t* ybins);
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,Int_t nbinsz,Double_t zlow,Double_t zup);
88  TEfficiency(const char* name,const char* title,Int_t nbinsx,
89  const Double_t* xbins,Int_t nbinsy,const Double_t* ybins,
90  Int_t nbinsz,const Double_t* zbins);
91  TEfficiency(const TEfficiency& heff);
92  ~TEfficiency();
93 
94  void Add(const TEfficiency& rEff) {*this += rEff;}
95  void Browse(TBrowser*){Draw();}
96  TGraphAsymmErrors* CreateGraph(Option_t * opt = "") const;
97  TH2* CreateHistogram(Option_t * opt = "") const;
98  virtual Int_t DistancetoPrimitive(Int_t px, Int_t py);
99  void Draw(Option_t* opt = "");
100  virtual void ExecuteEvent(Int_t event, Int_t px, Int_t py);
101  void Fill(Bool_t bPassed,Double_t x,Double_t y=0,Double_t z=0);
102  void FillWeighted(Bool_t bPassed,Double_t weight,Double_t x,Double_t y=0,Double_t z=0);
103  Int_t FindFixBin(Double_t x,Double_t y=0,Double_t z=0) const;
104  TFitResultPtr Fit(TF1* f1,Option_t* opt="");
105  // use trick of -1 to return global parameters
106  Double_t GetBetaAlpha(Int_t bin = -1) const {return (fBeta_bin_params.size() > (UInt_t)bin) ? fBeta_bin_params[bin].first : fBeta_alpha;}
107  Double_t GetBetaBeta(Int_t bin = -1) const {return (fBeta_bin_params.size() > (UInt_t)bin) ? fBeta_bin_params[bin].second : fBeta_beta;}
108  Double_t GetConfidenceLevel() const {return fConfLevel;}
109  TH1* GetCopyPassedHisto() const;
110  TH1* GetCopyTotalHisto() const;
111  Int_t GetDimension() const;
112  TDirectory* GetDirectory() const {return fDirectory;}
113  Double_t GetEfficiency(Int_t bin) const;
114  Double_t GetEfficiencyErrorLow(Int_t bin) const;
115  Double_t GetEfficiencyErrorUp(Int_t bin) const;
116  Int_t GetGlobalBin(Int_t binx,Int_t biny=0,Int_t binz=0) const;
118  TH2* GetPaintedHistogram() const { return fPaintHisto; }
120  const TH1* GetPassedHistogram() const {return fPassedHistogram;}
122  const TH1* GetTotalHistogram() const {return fTotalHistogram;}
123  Double_t GetWeight() const {return fWeight;}
124  Long64_t Merge(TCollection* list);
125  TEfficiency& operator+=(const TEfficiency& rhs);
126  TEfficiency& operator=(const TEfficiency& rhs);
127  void Paint(Option_t* opt);
128  void SavePrimitive(std::ostream& out,Option_t* opt="");
129  void SetBetaAlpha(Double_t alpha);
130  void SetBetaBeta(Double_t beta);
131  void SetBetaBinParameters(Int_t bin, Double_t alpha, Double_t beta);
132  void SetConfidenceLevel(Double_t level);
133  void SetDirectory(TDirectory* dir);
134  void SetName(const char* name);
135  Bool_t SetPassedEvents(Int_t bin,Int_t events);
136  Bool_t SetPassedHistogram(const TH1& rPassed,Option_t* opt);
141  void SetStatisticOption(EStatOption option);
142  Bool_t SetBins(Int_t nx, Double_t xmin, Double_t xmax);
143  Bool_t SetBins(Int_t nx, const Double_t *xBins);
144  Bool_t SetBins(Int_t nx, Double_t xmin, Double_t xmax, Int_t ny, Double_t ymin, Double_t ymax);
145  Bool_t SetBins(Int_t nx, const Double_t *xBins, Int_t ny, const Double_t *yBins);
146  Bool_t SetBins(Int_t nx, Double_t xmin, Double_t xmax, Int_t ny, Double_t ymin, Double_t ymax,
147  Int_t nz, Double_t zmin, Double_t zmax);
148  Bool_t SetBins(Int_t nx, const Double_t *xBins, Int_t ny, const Double_t * yBins, Int_t nz,
149  const Double_t *zBins);
150 
151  void SetTitle(const char* title);
152  Bool_t SetTotalEvents(Int_t bin,Int_t events);
153  Bool_t SetTotalHistogram(const TH1& rTotal,Option_t* opt);
154  void SetUseWeightedEvents(Bool_t on = kTRUE);
155  void SetWeight(Double_t weight);
162 
163  static Bool_t CheckBinning(const TH1& pass,const TH1& total);
164  static Bool_t CheckConsistency(const TH1& pass,const TH1& total,Option_t* opt="");
165  static Bool_t CheckEntries(const TH1& pass,const TH1& total,Option_t* opt="");
166  static Bool_t CheckWeights(const TH1& pass,const TH1& total);
167  static Double_t Combine(Double_t& up,Double_t& low,Int_t n,const Int_t* pass,const Int_t* total,
168  Double_t alpha,Double_t beta,Double_t level=0.683,
169  const Double_t* w=0,Option_t* opt="");
170  static TGraphAsymmErrors* Combine(TCollection* pList,Option_t* opt="",Int_t n=0,const Double_t* w=0);
171 
172  //calculating boundaries of confidence intervals
173  static Double_t AgrestiCoull(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
174  static Double_t ClopperPearson(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
175  static Double_t Normal(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
176  static Double_t Wilson(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
177  static Double_t FeldmanCousins(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
178  static Bool_t FeldmanCousinsInterval(Double_t total,Double_t passed,Double_t level,Double_t & lower, Double_t & upper);
179  static Double_t MidPInterval(Double_t total,Double_t passed,Double_t level,Bool_t bUpper);
180  // Bayesian functions
181  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);
182  // helper functions for Bayesian statistics
183  static Double_t BetaCentralInterval(Double_t level,Double_t alpha,Double_t beta,Bool_t bUpper);
184  static Bool_t BetaShortestInterval(Double_t level,Double_t alpha,Double_t beta,Double_t & lower, Double_t & upper);
185  static Double_t BetaMean(Double_t alpha,Double_t beta);
186  static Double_t BetaMode(Double_t alpha,Double_t beta);
187 
188  ClassDef(TEfficiency,2) //calculating efficiencies
189 };
190 
191 const TEfficiency operator+(const TEfficiency& lhs,const TEfficiency& rhs);
192 
193 #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...
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:47
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:27
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:120
const TEfficiency operator+(const TEfficiency &lhs, const TEfficiency &rhs)
Addition operator.
Bool_t UsesCentralInterval() const
Definition: TEfficiency.h:160
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
static Bool_t CheckBinning(const TH1 &pass, const TH1 &total)
Checks binning for each axis.
#define BIT(n)
Definition: Rtypes.h:78
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:107
R__ALWAYS_INLINE Bool_t TestBit(UInt_t f) const
Definition: TObject.h:172
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.
TFitResultPtr Fit(TF1 *f1, Option_t *opt="")
Fits the efficiency using the TBinomialEfficiencyFitter class.
~TEfficiency()
default destructor
EStatOption fStatisticOption
Definition: TEfficiency.h:57
void Browse(TBrowser *)
Browse object. May be overridden for another default action.
Definition: TEfficiency.h:95
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:138
Double_t(* fBoundary)(Double_t, Double_t, Double_t, Bool_t)
Definition: TEfficiency.h:50
void SetBit(UInt_t f, Bool_t set)
Set or unset the user status bits as specified in f.
Definition: TObject.cxx:694
double beta(double x, double y)
Calculates the beta function.
Bool_t UsesWeights() const
Definition: TEfficiency.h:161
Double_t GetWeight() const
Definition: TEfficiency.h:123
Marker Attributes class.
Definition: TAttMarker.h:19
TH1 * GetCopyPassedHisto() const
Returns a cloned version of fPassedHistogram.
Double_t fWeight
Definition: TEfficiency.h:59
TGraph with asymmetric error bars.
EStatOption GetStatisticOption() const
Definition: TEfficiency.h:121
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:19
Double_t x[n]
Definition: legend1.C:17
#define ClassDef(name, id)
Definition: Rtypes.h:320
TGraphAsymmErrors * fPaintGraph
Definition: TEfficiency.h:54
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:29
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:56
Bool_t UsesPosteriorAverage() const
Definition: TEfficiency.h:159
TH1 * fTotalHistogram
Definition: TEfficiency.h:58
TH2 * fPaintHisto
temporary graph for painting
Definition: TEfficiency.h:55
TList * GetListOfFunctions()
const TH1 * GetTotalHistogram() const
Definition: TEfficiency.h:122
TList * fFunctions
pointer to directory holding this TEfficiency object
Definition: TEfficiency.h:53
Bool_t UsesBayesianStat() const
Definition: TEfficiency.h:156
TH2 * GetPaintedHistogram() const
Definition: TEfficiency.h:118
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:112
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:51
A doubly linked list.
Definition: TList.h:44
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:37
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:30
void SetBetaAlpha(Double_t alpha)
Sets the shape parameter α.
void SetPosteriorMode(Bool_t on=true)
Definition: TEfficiency.h:137
Provides an indirection to the TFitResult class and with a semantics identical to a TFitResult pointe...
Definition: TFitResultPtr.h:31
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:63
void Add(const TEfficiency &rEff)
Definition: TEfficiency.h:94
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:157
Bool_t UsesShortestInterval() const
Definition: TEfficiency.h:158
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:34
Double_t GetEfficiencyErrorUp(Int_t bin) const
Returns the upper error on the efficiency in the given global bin.
EStatusBits
Definition: TObject.h:57
Double_t fBeta_alpha
Definition: TEfficiency.h:46
Double_t GetConfidenceLevel() const
Definition: TEfficiency.h:108
void SetShortestInterval(Bool_t on=true)
Definition: TEfficiency.h:139
Double_t y[n]
Definition: legend1.C:17
Double_t GetBetaAlpha(Int_t bin=-1) const
Definition: TEfficiency.h:106
TEfficiency & operator=(const TEfficiency &rhs)
Assignment operator.
The TH1 histogram class.
Definition: TH1.h:56
void SetBetaBeta(Double_t beta)
Sets the shape parameter β.
TDirectory * fDirectory
Definition: TEfficiency.h:52
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:211
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:140
std::vector< std::pair< Double_t, Double_t > > fBeta_bin_params
Definition: TEfficiency.h:48
Int_t GetDimension() const
returns the dimension of the current TEfficiency object
const Bool_t kTRUE
Definition: RtypesCore.h:87
const Int_t n
Definition: legend1.C:16
Line Attributes class.
Definition: TAttLine.h:18
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:117