ROOT  6.07/01
Reference Guide
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
HypoTestResult.h
Go to the documentation of this file.
1 // @(#)root/roostats:$Id$
2 // Author: Kyle Cranmer, Lorenzo Moneta, Gregory Schott, Wouter Verkerke, Sven Kreiss
3 /*************************************************************************
4  * Copyright (C) 1995-2008, Rene Brun and Fons Rademakers. *
5  * All rights reserved. *
6  * *
7  * For the licensing terms see $ROOTSYS/LICENSE. *
8  * For the list of contributors see $ROOTSYS/README/CREDITS. *
9  *************************************************************************/
10 
11 
12 
13 
14 #ifndef ROOSTATS_HypoTestResult
15 #define ROOSTATS_HypoTestResult
16 
17 #ifndef ROOT_TNamed
18 #include "TNamed.h"
19 #endif
20 
21 #ifndef ROOSTATS_RooStatsUtils
22 #include "RooStats/RooStatsUtils.h"
23 #endif
24 
25 #ifndef ROOSTATS_SamplingDistribution
27 #endif
28 
29 namespace RooStats {
30 
31 
32 /**
33 
34  \ingroup Roostats
35 
36  HypoTestResult is a base class for results from hypothesis tests.
37  Any tool inheriting from HypoTestCalculator can return a HypoTestResult.
38  As such, it stores a p-value for the null-hypothesis (eg. background-only)
39  and an alternate hypothesis (eg. signal+background).
40  The p-values can also be transformed into confidence levels (CLb, CLsplusb) in a trivial way.
41  The ratio of the CLsplusb to CLb is often called CLs, and is considered useful, though it is
42  not a probability.
43  Finally, the p-value of the null can be transformed into a number of equivalent Gaussian sigma using the
44  Significance method.
45 
46  The p-value of the null for a given test statistic is rigorously defined and
47  this is the starting point for the following conventions.
48 
49 ### Conventions used in this class
50 
51 The p-value for the null and alternate are on the **same side** of the
52 observed value of the test statistic. This is the more standard
53 convention and avoids confusion when doing inverted tests.
54 
55 For exclusion, we also want the formula
56 CLs = CLs+b / CLb to hold which therefore defines our conventions
57 for CLs+b and CLb. CLs was specifically invented for exclusion
58 and therefore all quantities need be related through the assignments
59 as they are for exclusion: **CLs+b = p_{s+b}; CLb = p_b**. This
60 is derived by considering the scenarios of a powerful and not powerful
61 inverted test, where for the not so powerful test, CLs must be
62 close to one.
63 
64 For results of Hypothesis tests,
65 CLs has no similar direct interpretation as for exclusion and can
66 be larger than one.
67 
68 */
69 
70  class HypoTestResult : public TNamed {
71 
72  public:
73 
74  /// default constructor
75  explicit HypoTestResult(const char* name = 0);
76 
77  /// copy constructo
78  HypoTestResult(const HypoTestResult& other);
79 
80  /// constructor from name, null and alternate p values
81  HypoTestResult(const char* name, Double_t nullp, Double_t altp);
82 
83  /// destructor
84  virtual ~HypoTestResult();
85 
86  /// assignment operator
87  HypoTestResult & operator=(const HypoTestResult& other);
88 
89  /// add values from another HypoTestResult
90  virtual void Append(const HypoTestResult *other);
91 
92  /// Return p-value for null hypothesis
93  virtual Double_t NullPValue() const { return fNullPValue; }
94 
95  /// Return p-value for alternate hypothesis
96  virtual Double_t AlternatePValue() const { return fAlternatePValue; }
97 
98  /// Convert NullPValue into a "confidence level"
99  virtual Double_t CLb() const { return !fBackgroundIsAlt ? NullPValue() : AlternatePValue(); }
100 
101  /// Convert AlternatePValue into a "confidence level"
102  virtual Double_t CLsplusb() const { return !fBackgroundIsAlt ? AlternatePValue() : NullPValue(); }
103 
104  /// CLs is simply CLs+b/CLb (not a method, but a quantity)
105  virtual Double_t CLs() const {
106  double thisCLb = CLb();
107  if (thisCLb == 0) {
108  std::cout << "Error: Cannot compute CLs because CLb = 0. Returning CLs = -1\n";
109  return -1;
110  }
111  double thisCLsb = CLsplusb();
112  return thisCLsb / thisCLb;
113  }
114 
115  /// familiar name for the Null p-value in terms of 1-sided Gaussian significance
117 
122  RooDataSet* GetFitInfo(void) const { return fFitInfo; }
125  Bool_t HasTestStatisticData(void) const;
126 
132  void SetTestStatisticData(const Double_t tsd);
133  void SetAllTestStatisticsData(const RooArgList* tsd);
134 
135  void SetPValueIsRightTail(Bool_t pr);
137 
140 
141  /// The error on the "confidence level" of the null hypothesis
142  Double_t CLbError() const;
143 
144  /// The error on the "confidence level" of the alternative hypothesis
145  Double_t CLsplusbError() const;
146 
147  /// The error on the ratio CLs+b/CLb
148  Double_t CLsError() const;
149 
150  /// The error on the Null p-value
151  Double_t NullPValueError() const;
152 
153  /// The error on the significance, computed from NullPValueError via error propagation
154  Double_t SignificanceError() const;
155 
156 
157  void Print(const Option_t* = "") const;
158 
159  private:
160  void UpdatePValue(const SamplingDistribution* distr, Double_t &pvalue, Double_t &perror, Bool_t pIsRightTail);
161 
162 
163  protected:
164 
165  mutable Double_t fNullPValue; // p-value for the null hypothesis (small number means disfavored)
166  mutable Double_t fAlternatePValue; // p-value for the alternate hypothesis (small number means disfavored)
167  mutable Double_t fNullPValueError; // error of p-value for the null hypothesis (small number means disfavored)
168  mutable Double_t fAlternatePValueError; // error of p-value for the alternate hypothesis (small number means disfavored)
169  Double_t fTestStatisticData; // result of the test statistic evaluated on data
170  const RooArgList* fAllTestStatisticsData; // for the case of multiple test statistics, holds all the results
178 
179  ClassDef(HypoTestResult,3) // Base class to represent results of a hypothesis test
180 
181  };
182 }
183 
184 
185 #endif
void SetBackgroundAsAlt(Bool_t l=kTRUE)
void SetAltDistribution(SamplingDistribution *alt)
Double_t CLbError() const
The error on the "confidence level" of the null hypothesis.
void SetFitInfo(RooDataSet *d)
RooDataSet * GetFitInfo(void) const
const char Option_t
Definition: RtypesCore.h:62
const RooArgList * fAllTestStatisticsData
virtual Double_t CLs() const
CLs is simply CLs+b/CLb (not a method, but a quantity)
Double_t PValueToSignificance(Double_t pvalue)
Definition: RooStatsUtils.h:59
HypoTestResult is a base class for results from hypothesis tests.
HypoTestResult & operator=(const HypoTestResult &other)
assignment operator
RooDataSet * GetNullDetailedOutput(void) const
RooDataSet * fNullDetailedOutput
Double_t SignificanceError() const
The error on the significance, computed from NullPValueError via error propagation.
void UpdatePValue(const SamplingDistribution *distr, Double_t &pvalue, Double_t &perror, Bool_t pIsRightTail)
updates the pvalue if sufficient data is available
bool Bool_t
Definition: RtypesCore.h:59
SamplingDistribution * GetAltDistribution(void) const
virtual Double_t CLsplusb() const
Convert AlternatePValue into a "confidence level".
double distr(double *x, double *p)
Definition: unuranDemo.C:104
null_t< F > null()
#define ClassDef(name, id)
Definition: Rtypes.h:254
RooDataSet * GetAltDetailedOutput(void) const
The TNamed class is the base class for all named ROOT classes.
Definition: TNamed.h:33
void Print(const Option_t *="") const
int d
Definition: tornado.py:11
const RooArgList * GetAllTestStatisticsData(void) const
virtual Double_t NullPValue() const
Return p-value for null hypothesis.
void SetAllTestStatisticsData(const RooArgList *tsd)
virtual Double_t CLb() const
Convert NullPValue into a "confidence level".
virtual ~HypoTestResult()
destructor
Double_t NullPValueError() const
The error on the Null p-value.
SamplingDistribution * fAltDistr
void SetAltDetailedOutput(RooDataSet *d)
TLine * l
Definition: textangle.C:4
virtual Double_t Significance() const
familiar name for the Null p-value in terms of 1-sided Gaussian significance
Bool_t HasTestStatisticData(void) const
Bool_t GetPValueIsRightTail(void) const
RooDataSet is a container class to hold unbinned data.
Definition: RooDataSet.h:29
void SetTestStatisticData(const Double_t tsd)
This class simply holds a sampling distribution of some test statistic.
HypoTestResult(const char *name=0)
default constructor
virtual void Append(const HypoTestResult *other)
add values from another HypoTestResult
void SetPValueIsRightTail(Bool_t pr)
SamplingDistribution * fNullDistr
double Double_t
Definition: RtypesCore.h:55
SamplingDistribution * GetNullDistribution(void) const
#define name(a, b)
Definition: linkTestLib0.cpp:5
virtual Double_t AlternatePValue() const
Return p-value for alternate hypothesis.
void SetNullDetailedOutput(RooDataSet *d)
RooDataSet * fAltDetailedOutput
Double_t CLsplusbError() const
The error on the "confidence level" of the alternative hypothesis.
Double_t GetTestStatisticData(void) const
const Bool_t kTRUE
Definition: Rtypes.h:91
void SetNullDistribution(SamplingDistribution *null)
Double_t CLsError() const
The error on the ratio CLs+b/CLb.
Bool_t GetBackGroundIsAlt(void) const