{
"cells": [
{
"cell_type": "markdown",
"id": "cc97557b",
"metadata": {},
"source": [
"# rs_numbercountingutils\n",
"'Number Counting Utils' RooStats tutorial\n",
"\n",
"This tutorial shows an example of the RooStats standalone\n",
"utilities that calculate the p-value or Z value (eg. significance in\n",
"1-sided Gaussian standard deviations) for a number counting experiment.\n",
"This is a hypothesis test between background only and signal-plus-background.\n",
"The background estimate has uncertainty derived from an auxiliary or sideband\n",
"measurement.\n",
"\n",
"Documentation for these utilities can be found here:\n",
"https://root.cern.ch/doc/master/namespaceNumberCountingUtils.html\n",
"\n",
"\n",
"This problem is often called a proto-type problem for high energy physics.\n",
"In some references it is referred to as the on/off problem.\n",
"\n",
"The problem is treated in a fully frequentist fashion by\n",
"interpreting the relative background uncertainty as\n",
"being due to an auxiliary or sideband observation\n",
"that is also Poisson distributed with only background.\n",
"Finally, one considers the test as a ratio of Poisson means\n",
"where an interval is well known based on the conditioning on the total\n",
"number of events and the binomial distribution.\n",
"For more on this, see\n",
" - http://arxiv.org/abs/0905.3831\n",
" - http://arxiv.org/abs/physics/physics/0702156\n",
" - http://arxiv.org/abs/physics/0511028\n",
"\n",
"\n",
"\n",
"\n",
"\n",
"**Author:** Artem Busorgin, Kyle Cranmer (C++ version) \n",
"This notebook tutorial was automatically generated with ROOTBOOK-izer from the macro found in the ROOT repository on Tuesday, May 19, 2026 at 08:36 PM."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "01d3f993",
"metadata": {
"collapsed": false,
"execution": {
"iopub.execute_input": "2026-05-19T20:36:12.065382Z",
"iopub.status.busy": "2026-05-19T20:36:12.065245Z",
"iopub.status.idle": "2026-05-19T20:36:13.052211Z",
"shell.execute_reply": "2026-05-19T20:36:13.045946Z"
}
},
"outputs": [],
"source": [
"import ROOT"
]
},
{
"cell_type": "markdown",
"id": "a47e4968",
"metadata": {},
"source": [
"From the root prompt, you can see the full list of functions by using tab-completion\n",
"~~~{.bash}\n",
"root [0] RooStats::NumberCountingUtils:: \n",
"BinomialExpZ\n",
"BinomialWithTauExpZ\n",
"BinomialObsZ\n",
"BinomialWithTauObsZ\n",
"BinomialExpP\n",
"BinomialWithTauExpP\n",
"BinomialObsP\n",
"BinomialWithTauObsP\n",
"~~~"
]
},
{
"cell_type": "markdown",
"id": "24185b82",
"metadata": {},
"source": [
"For each of the utilities you can inspect the arguments by tab completion\n",
"~~~{.bash}\n",
"root [1] NumberCountingUtils::BinomialExpZ( \n",
"Double_t BinomialExpZ(Double_t sExp, Double_t bExp, Double_t fractionalBUncertainty)\n",
"~~~"
]
},
{
"cell_type": "markdown",
"id": "9c125e1b",
"metadata": {},
"source": [
"-------------------------------------------------\n",
"Here we see common usages where the experimenter\n",
"has a relative background uncertainty, without\n",
"explicit reference to the auxiliary or sideband\n",
"measurement"
]
},
{
"cell_type": "markdown",
"id": "88dfd1f8",
"metadata": {},
"source": [
"-------------------------------------------------------------\n",
"Expected p-values and significance with background uncertainty"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "db96a400",
"metadata": {
"collapsed": false,
"execution": {
"iopub.execute_input": "2026-05-19T20:36:13.062275Z",
"iopub.status.busy": "2026-05-19T20:36:13.062140Z",
"iopub.status.idle": "2026-05-19T20:36:13.196538Z",
"shell.execute_reply": "2026-05-19T20:36:13.195923Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"expected p-value = 0.0009416504675382001 Z value (Gaussian sigma) = 3.108043895747122\n"
]
}
],
"source": [
"sExpected = 50\n",
"bExpected = 100\n",
"relativeBkgUncert = 0.1\n",
"\n",
"pExp = ROOT.RooStats.NumberCountingUtils.BinomialExpP(sExpected, bExpected, relativeBkgUncert)\n",
"zExp = ROOT.RooStats.NumberCountingUtils.BinomialExpZ(sExpected, bExpected, relativeBkgUncert)\n",
"print(\"expected p-value = {} Z value (Gaussian sigma) = {}\".format(pExp, zExp))"
]
},
{
"cell_type": "markdown",
"id": "d37b3de1",
"metadata": {},
"source": [
"-------------------------------------------------\n",
"Expected p-values and significance with background uncertainty"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "536b0992",
"metadata": {
"collapsed": false,
"execution": {
"iopub.execute_input": "2026-05-19T20:36:13.197906Z",
"iopub.status.busy": "2026-05-19T20:36:13.197785Z",
"iopub.status.idle": "2026-05-19T20:36:13.307516Z",
"shell.execute_reply": "2026-05-19T20:36:13.306914Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"observed p-value = 0.0009416504675382001 Z value (Gaussian sigma) = 3.108043895747122\n"
]
}
],
"source": [
"observed = 150\n",
"pObs = ROOT.RooStats.NumberCountingUtils.BinomialObsP(observed, bExpected, relativeBkgUncert)\n",
"zObs = ROOT.RooStats.NumberCountingUtils.BinomialObsZ(observed, bExpected, relativeBkgUncert)\n",
"print(\"observed p-value = {} Z value (Gaussian sigma) = {}\".format(pObs, zObs))"
]
},
{
"cell_type": "markdown",
"id": "123c8533",
"metadata": {},
"source": [
"---------------------------------------------------------\n",
"Here we see usages where the experimenter has knowledge\n",
"about the properties of the auxiliary or sideband\n",
"measurement. In particular, the ratio tau of background\n",
"in the auxiliary measurement to the main measurement.\n",
"Large values of tau mean small background uncertainty\n",
"because the sideband is very constraining."
]
},
{
"cell_type": "markdown",
"id": "a12abc51",
"metadata": {},
"source": [
"Usage:\n",
"~~~{.bash}\n",
"root [0] RooStats::NumberCountingUtils::BinomialWithTauExpP(\n",
"Double_t BinomialWithTauExpP(Double_t sExp, Double_t bExp, Double_t tau)\n",
"~~~"
]
},
{
"cell_type": "markdown",
"id": "8b5fadef",
"metadata": {},
"source": [
"--------------------------------------------------------------\n",
"Expected p-values and significance with background uncertainty"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "599bf670",
"metadata": {
"collapsed": false,
"execution": {
"iopub.execute_input": "2026-05-19T20:36:13.309156Z",
"iopub.status.busy": "2026-05-19T20:36:13.309034Z",
"iopub.status.idle": "2026-05-19T20:36:13.428277Z",
"shell.execute_reply": "2026-05-19T20:36:13.427940Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"observed p-value = 0.0009416504675382253 Z value (Gaussian sigma) = 3.108043895747114\n"
]
}
],
"source": [
"tau = 1\n",
"\n",
"pExpWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauExpP(sExpected, bExpected, tau)\n",
"zExpWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauExpZ(sExpected, bExpected, tau)\n",
"print(\"observed p-value = {} Z value (Gaussian sigma) = {}\".format(pExpWithTau, zExpWithTau))"
]
},
{
"cell_type": "markdown",
"id": "03fbe2ba",
"metadata": {},
"source": [
"---------------------------------------------------------------\n",
"Expected p-values and significance with background uncertainty"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "c775732f",
"metadata": {
"collapsed": false,
"execution": {
"iopub.execute_input": "2026-05-19T20:36:13.438914Z",
"iopub.status.busy": "2026-05-19T20:36:13.438779Z",
"iopub.status.idle": "2026-05-19T20:36:13.547978Z",
"shell.execute_reply": "2026-05-19T20:36:13.547633Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"observed p-value = 0.0009416504675382253 Z value (Gaussian sigma) = 3.108043895747114\n"
]
}
],
"source": [
"pObsWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauObsP(observed, bExpected, tau)\n",
"zObsWithTau = ROOT.RooStats.NumberCountingUtils.BinomialWithTauObsZ(observed, bExpected, tau)\n",
"print(\"observed p-value = {} Z value (Gaussian sigma) = {}\".format(pObsWithTau, zObsWithTau))"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.12.12"
}
},
"nbformat": 4,
"nbformat_minor": 5
}