#!/usr/bin/env python
# coding: utf-8

# # rs_numbercountingutils
# 'Number Counting Utils' RooStats tutorial
# 
# This tutorial shows an example of the RooStats standalone
# utilities that calculate the p-value or Z value (eg. significance in
# 1-sided Gaussian standard deviations) for a number counting experiment.
# This is a hypothesis test between background only and signal-plus-background.
# The background estimate has uncertainty derived from an auxiliary or sideband
# measurement.
# 
# Documentation for these utilities can be found here:
# http://root.cern.ch/root/html/RooStats__NumberCountingUtils.html
# 
# 
# This problem is often called a proto-type problem for high energy physics.
# In some references it is referred to as the on/off problem.
# 
# The problem is treated in a fully frequentist fashion by
# interpreting the relative background uncertainty as
# being due to an auxiliary or sideband observation
# that is also Poisson distributed with only background.
# Finally, one considers the test as a ratio of Poisson means
# where an interval is well known based on the conditioning on the total
# number of events and the binomial distribution.
# For more on this, see
#  - http://arxiv.org/abs/0905.3831
#  - http://arxiv.org/abs/physics/physics/0702156
#  - http://arxiv.org/abs/physics/0511028
# 
# 
# 
# 
# 
# **Author:**  Artem Busorgin, Kyle Cranmer (C++ version)  
# <i><small>This notebook tutorial was automatically generated with <a href= "https://github.com/root-project/root/blob/master/documentation/doxygen/converttonotebook.py">ROOTBOOK-izer</a> from the macro found in the ROOT repository  on Wednesday, May 15, 2024 at 09:53 AM.</small></i>

# In[1]:


import ROOT


# From the root prompt, you can see the full list of functions by using tab-completion
# ~~~{.bash}
# root [0] RooStats::NumberCountingUtils::  <tab>
# BinomialExpZ
# BinomialWithTauExpZ
# BinomialObsZ
# BinomialWithTauObsZ
# BinomialExpP
# BinomialWithTauExpP
# BinomialObsP
# BinomialWithTauObsP
# ~~~

# For each of the utilities you can inspect the arguments by tab completion
# ~~~{.bash}
# root [1] NumberCountingUtils::BinomialExpZ( <tab>
# Double_t BinomialExpZ(Double_t sExp, Double_t bExp, Double_t fractionalBUncertainty)
# ~~~

# -------------------------------------------------
# Here we see common usages where the experimenter
# has a relative background uncertainty, without
# explicit reference to the auxiliary or sideband
# measurement

# -------------------------------------------------------------
# Expected p-values and significance with background uncertainty

# In[2]:


sExpected = 50
bExpected = 100
relativeBkgUncert = 0.1

pExp = ROOT.RooStats.NumberCountingUtils.BinomialExpP(sExpected, bExpected, relativeBkgUncert)
zExp = ROOT.RooStats.NumberCountingUtils.BinomialExpZ(sExpected, bExpected, relativeBkgUncert)
print("expected p-value = {}  Z value (Gaussian sigma) = {}".format(pExp, zExp))


# -------------------------------------------------
# Expected p-values and significance with background uncertainty

# In[3]:


observed = 150
pObs = ROOT.RooStats.NumberCountingUtils.BinomialObsP(observed, bExpected, relativeBkgUncert)
zObs = ROOT.RooStats.NumberCountingUtils.BinomialObsZ(observed, bExpected, relativeBkgUncert)
print("observed p-value = {}  Z value (Gaussian sigma) = {}".format(pObs, zObs))


# ---------------------------------------------------------
# Here we see usages where the experimenter has knowledge
# about the properties of the auxiliary or sideband
# measurement.  In particular, the ratio tau of background
# in the auxiliary measurement to the main measurement.
# Large values of tau mean small background uncertainty
# because the sideband is very constraining.

# Usage:
# ~~~{.bash}
# root [0] RooStats::NumberCountingUtils::BinomialWithTauExpP(
# Double_t BinomialWithTauExpP(Double_t sExp, Double_t bExp, Double_t tau)
# ~~~

# --------------------------------------------------------------
# Expected p-values and significance with background uncertainty

# In[4]:


tau = 1

pExpWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauExpP(sExpected, bExpected, tau)
zExpWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauExpZ(sExpected, bExpected, tau)
print("observed p-value = {}  Z value (Gaussian sigma) = {}".format(pExpWithTau, zExpWithTau))


# ---------------------------------------------------------------
# Expected p-values and significance with background uncertainty

# In[5]:


pObsWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauObsP(observed, bExpected, tau)
zObsWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauObsZ(observed, bExpected, tau)
print("observed p-value = {}  Z value (Gaussian sigma) = {}".format(pObsWithTau, zObsWithTau))