ROOT   Reference Guide
rs_numbercountingutils.C
Go to the documentation of this file.
1 /// \file
2 /// \ingroup tutorial_roostats
3 /// \notebook -nodraw
4 /// 'Number Counting Utils' RooStats tutorial
5 ///
6 /// This tutorial shows an example of the RooStats standalone
7 /// utilities that calculate the p-value or Z value (eg. significance in
8 /// 1-sided Gaussian standard deviations) for a number counting experiment.
9 /// This is a hypothesis test between background only and signal-plus-background.
10 /// The background estimate has uncertainty derived from an auxiliary or sideband
11 /// measurement.
12 ///
13 /// Documentation for these utilities can be found here:
14 /// http://root.cern.ch/root/html/RooStats__NumberCountingUtils.html
15 ///
16 ///
17 /// This problem is often called a proto-type problem for high energy physics.
18 /// In some references it is referred to as the on/off problem.
19 ///
20 /// The problem is treated in a fully frequentist fashion by
21 /// interpreting the relative background uncertainty as
22 /// being due to an auxiliary or sideband observation
23 /// that is also Poisson distributed with only background.
24 /// Finally, one considers the test as a ratio of Poisson means
25 /// where an interval is well known based on the conditioning on the total
26 /// number of events and the binomial distribution.
27 /// For more on this, see
28 /// - http://arxiv.org/abs/0905.3831
29 /// - http://arxiv.org/abs/physics/physics/0702156
30 /// - http://arxiv.org/abs/physics/0511028
31 ///
32 ///
33 /// \macro_image
34 /// \macro_output
35 /// \macro_code
36 ///
37 /// \author Kyle Cranmer
38
39 #include "RooStats/RooStatsUtils.h"
40 #include <iostream>
41
42 using namespace RooFit;
43 using namespace RooStats; // the utilities are in the RooStats namespace
44 using namespace std;
45
46 void rs_numbercountingutils()
47 {
48
49  // From the root prompt, you can see the full list of functions by using tab-completion
50  // ~~~{.bash}
51  // root [0] RooStats::NumberCountingUtils:: <tab>
52  // BinomialExpZ
53  // BinomialWithTauExpZ
54  // BinomialObsZ
55  // BinomialWithTauObsZ
56  // BinomialExpP
57  // BinomialWithTauExpP
58  // BinomialObsP
59  // BinomialWithTauObsP
60  // ~~~
61
62  // For each of the utilities you can inspect the arguments by tab completion
63  // ~~~{.bash}
64  // root [1] NumberCountingUtils::BinomialExpZ( <tab>
65  // Double_t BinomialExpZ(Double_t sExp, Double_t bExp, Double_t fractionalBUncertainty)
66  // ~~~
67
68  // -------------------------------------------------
69  // Here we see common usages where the experimenter
70  // has a relative background uncertainty, without
71  // explicit reference to the auxiliary or sideband
72  // measurement
73
74  // -------------------------------------------------------------
75  // Expected p-values and significance with background uncertainty
76  double sExpected = 50;
77  double bExpected = 100;
78  double relativeBkgUncert = 0.1;
79
80  double pExp = NumberCountingUtils::BinomialExpP(sExpected, bExpected, relativeBkgUncert);
81  double zExp = NumberCountingUtils::BinomialExpZ(sExpected, bExpected, relativeBkgUncert);
82  cout << "expected p-value =" << pExp << " Z value (Gaussian sigma) = " << zExp << endl;
83
84  // -------------------------------------------------
85  // Expected p-values and significance with background uncertainty
86  double observed = 150;
87  double pObs = NumberCountingUtils::BinomialObsP(observed, bExpected, relativeBkgUncert);
88  double zObs = NumberCountingUtils::BinomialObsZ(observed, bExpected, relativeBkgUncert);
89  cout << "observed p-value =" << pObs << " Z value (Gaussian sigma) = " << zObs << endl;
90
91  // ---------------------------------------------------------
92  // Here we see usages where the experimenter has knowledge
93  // about the properties of the auxiliary or sideband
94  // measurement. In particular, the ratio tau of background
95  // in the auxiliary measurement to the main measurement.
96  // Large values of tau mean small background uncertainty
97  // because the sideband is very constraining.
98
99  // Usage:
100  // ~~~{.bash}
101  // root [0] RooStats::NumberCountingUtils::BinomialWithTauExpP(
102  // Double_t BinomialWithTauExpP(Double_t sExp, Double_t bExp, Double_t tau)
103  // ~~~
104
105  // --------------------------------------------------------------
106  // Expected p-values and significance with background uncertainty
107  double tau = 1;
108
109  double pExpWithTau = NumberCountingUtils::BinomialWithTauExpP(sExpected, bExpected, tau);
110  double zExpWithTau = NumberCountingUtils::BinomialWithTauExpZ(sExpected, bExpected, tau);
111  cout << "expected p-value =" << pExpWithTau << " Z value (Gaussian sigma) = " << zExpWithTau << endl;
112
113  // ---------------------------------------------------------------
114  // Expected p-values and significance with background uncertainty
115  double pObsWithTau = NumberCountingUtils::BinomialWithTauObsP(observed, bExpected, tau);
116  double zObsWithTau = NumberCountingUtils::BinomialWithTauObsZ(observed, bExpected, tau);
117  cout << "observed p-value =" << pObsWithTau << " Z value (Gaussian sigma) = " << zObsWithTau << endl;
118 }
RooStats::NumberCountingUtils::BinomialWithTauExpP
Double_t BinomialWithTauExpP(Double_t sExp, Double_t bExp, Double_t tau)
Definition: NumberCountingUtils.cxx:70
RooStats::NumberCountingUtils::BinomialExpZ
Double_t BinomialExpZ(Double_t sExp, Double_t bExp, Double_t fractionalBUncertainty)
Definition: NumberCountingUtils.cxx:122
RooStats::NumberCountingUtils::BinomialObsP
Double_t BinomialObsP(Double_t nObs, Double_t, Double_t fractionalBUncertainty)
Definition: NumberCountingUtils.cxx:86
RooStats::NumberCountingUtils::BinomialObsZ
Double_t BinomialObsZ(Double_t nObs, Double_t bExp, Double_t fractionalBUncertainty)
Definition: NumberCountingUtils.cxx:133
RooStats::NumberCountingUtils::BinomialWithTauObsZ
Double_t BinomialWithTauObsZ(Double_t nObs, Double_t bExp, Double_t tau)
Definition: NumberCountingUtils.cxx:138
RooStats::NumberCountingUtils::BinomialWithTauExpZ
Double_t BinomialWithTauExpZ(Double_t sExp, Double_t bExp, Double_t tau)
Definition: NumberCountingUtils.cxx:127
RooFit
The namespace RooFit contains mostly switches that change the behaviour of functions of PDFs (or othe...
Definition: RooCFunction1Binding.h:29
RooStats::NumberCountingUtils::BinomialWithTauObsP
Double_t BinomialWithTauObsP(Double_t nObs, Double_t bExp, Double_t tau)
Definition: NumberCountingUtils.cxx:107
RooStatsUtils.h
RooStats
Namespace for the RooStats classes.
Definition: Asimov.h:19
RooStats::NumberCountingUtils::BinomialExpP
Double_t BinomialExpP(Double_t sExp, Double_t bExp, Double_t fractionalBUncertainty)
Definition: NumberCountingUtils.cxx:25