ROOT   Reference Guide
Searching...
No Matches
rs_numbercountingutils.py
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## \date July 2022
38## \authors Artem Busorgin, Kyle Cranmer (C++ version)
39
40import ROOT
41
42# From the root prompt, you can see the full list of functions by using tab-completion
43# ~~~{.bash}
44# root [0] RooStats::NumberCountingUtils:: <tab>
45# BinomialExpZ
46# BinomialWithTauExpZ
47# BinomialObsZ
48# BinomialWithTauObsZ
49# BinomialExpP
50# BinomialWithTauExpP
51# BinomialObsP
52# BinomialWithTauObsP
53# ~~~
54
55# For each of the utilities you can inspect the arguments by tab completion
56# ~~~{.bash}
57# root [1] NumberCountingUtils::BinomialExpZ( <tab>
58# Double_t BinomialExpZ(Double_t sExp, Double_t bExp, Double_t fractionalBUncertainty)
59# ~~~
60
61# -------------------------------------------------
62# Here we see common usages where the experimenter
63# has a relative background uncertainty, without
64# explicit reference to the auxiliary or sideband
65# measurement
66
67# -------------------------------------------------------------
68# Expected p-values and significance with background uncertainty
69sExpected = 50
70bExpected = 100
71relativeBkgUncert = 0.1
72
73pExp = ROOT.RooStats.NumberCountingUtils.BinomialExpP(sExpected, bExpected, relativeBkgUncert)
74zExp = ROOT.RooStats.NumberCountingUtils.BinomialExpZ(sExpected, bExpected, relativeBkgUncert)
75print("expected p-value = {} Z value (Gaussian sigma) = {}".format(pExp, zExp))
76
77# -------------------------------------------------
78# Expected p-values and significance with background uncertainty
79observed = 150
80pObs = ROOT.RooStats.NumberCountingUtils.BinomialObsP(observed, bExpected, relativeBkgUncert)
81zObs = ROOT.RooStats.NumberCountingUtils.BinomialObsZ(observed, bExpected, relativeBkgUncert)
82print("observed p-value = {} Z value (Gaussian sigma) = {}".format(pObs, zObs))
83
84# ---------------------------------------------------------
85# Here we see usages where the experimenter has knowledge
86# about the properties of the auxiliary or sideband
87# measurement. In particular, the ratio tau of background
88# in the auxiliary measurement to the main measurement.
89# Large values of tau mean small background uncertainty
90# because the sideband is very constraining.
91
92# Usage:
93# ~~~{.bash}
94# root [0] RooStats::NumberCountingUtils::BinomialWithTauExpP(
95# Double_t BinomialWithTauExpP(Double_t sExp, Double_t bExp, Double_t tau)
96# ~~~
97
98# --------------------------------------------------------------
99# Expected p-values and significance with background uncertainty
100tau = 1
101
102pExpWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauExpP(sExpected, bExpected, tau)
103zExpWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauExpZ(sExpected, bExpected, tau)
104print("observed p-value = {} Z value (Gaussian sigma) = {}".format(pExpWithTau, zExpWithTau))
105
106# ---------------------------------------------------------------
107# Expected p-values and significance with background uncertainty
108pObsWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauObsP(observed, bExpected, tau)
109zObsWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauObsZ(observed, bExpected, tau)
110print("observed p-value = {} Z value (Gaussian sigma) = {}".format(pObsWithTau, zObsWithTau))
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t Int_t Int_t Window_t TString Int_t GCValues_t GetPrimarySelectionOwner GetDisplay GetScreen GetColormap GetNativeEvent const char const char dpyName wid window const char font_name cursor keysym reg const char only_if_exist regb h Point_t winding char text const char depth char const char Int_t count const char ColorStruct_t color const char Pixmap_t Pixmap_t PictureAttributes_t attr const char char ret_data h unsigned char height h Atom_t Int_t ULong_t ULong_t unsigned char prop_list Atom_t Atom_t Atom_t Time_t format