A class for performing a hypothesis test inversion by scanning the hypothesis test results of a HypoTestCalculator for various values of the parameter of interest.

By looking at the confidence level curve of the result, an upper limit can be derived by computing the intersection of the confidence level curve with the desired confidence level. The class implements the RooStats::IntervalCalculator interface, and returns a RooStats::HypoTestInverterResult. The result is a SimpleInterval, which via the method UpperLimit() returns to the user the upper limit value.

Scanning options

The HypoTestInverter implements various options for performing the scan.

HypoTestInverter::RunFixedScan will scan the parameter of interest using a fixed grid.
HypoTestInverter::SetAutoScan will perform an automatic scan to find optimally the curve. It will stop when the desired precision is obtained.
HypoTestInverter::RunOnePoint computes the confidence level at a given point.

CLs presciption

The class can scan the CLs+b values or alternatively CLs. For the latter, call HypoTestInverter::UseCLs().

Definition at line 36 of file HypoTestInverter.h.

Public Types
enum	ECalculatorType { kUndefined = 0 , kHybrid = 1 , kFrequentist = 2 , kAsymptotic = 3 }

Public Member Functions
	HypoTestInverter ()
	default constructor (doesn't do anything)

	HypoTestInverter (AsymptoticCalculator &hc, RooRealVar *scannedVariable, double size=0.05)
	Constructor from a reference to a AsymptoticCalculator The calculator must be created before by using the S+B model for the null and the B model for the alt If no variable to scan are given they are assumed to be the first variable from the parameter of interests of the null model.

	HypoTestInverter (FrequentistCalculator &hc, RooRealVar *scannedVariable, double size=0.05)
	Constructor from a reference to a FrequentistCalculator The calculator must be created before by using the S+B model for the null and the B model for the alt If no variable to scan are given they are assumed to be the first variable from the parameter of interests of the null model.

	HypoTestInverter (HybridCalculator &hc, RooRealVar *scannedVariable=0, double size=0.05)
	Constructor from a reference to a HybridCalculator The calculator must be created before by using the S+B model for the null and the B model for the alt If no variable to scan are given they are assumed to be the first variable from the parameter of interests of the null model.

	HypoTestInverter (HypoTestCalculatorGeneric &hc, RooRealVar *scannedVariable=0, double size=0.05)
	Constructor from a HypoTestCalculatorGeneric The HypoTest calculator must be a FrequentistCalculator or HybridCalculator type Other type of calculators are not supported.

	HypoTestInverter (RooAbsData &data, ModelConfig &sb, ModelConfig &b, RooRealVar *scannedVariable=0, ECalculatorType type=kFrequentist, double size=0.05)
	Constructor from a model for B model and a model for S+B.

virtual	~HypoTestInverter ()
	destructor (delete the HypoTestInverterResult)

void	Clear ()
	delete contained result and graph

virtual Double_t	ConfidenceLevel () const
	Get the Confidence level for the test.

HypoTestCalculatorGeneric *	GetHypoTestCalculator () const

virtual HypoTestInverterResult *	GetInterval () const
	Run a fixed scan or the automatic scan depending on the configuration.

SamplingDistribution *	GetLowerLimitDistribution (bool rebuild=false, int nToys=100)
	get the distribution of lower limit if rebuild = false (default) it will re-use the results of the scan done for obtained the observed limit and no extra toys will be generated if rebuild a new set of B toys will be done and the procedure will be repeated for each toy

TestStatistic *	GetTestStatistic () const
	return the test statistic which is or will be used by the class

SamplingDistribution *	GetUpperLimitDistribution (bool rebuild=false, int nToys=100)
	get the distribution of lower limit if rebuild = false (default) it will re-use the results of the scan done for obtained the observed limit and no extra toys will be generated if rebuild a new set of B toys will be done and the procedure will be repeated for each toy The nuisance parameter value used for rebuild is the current one in the model so it is user responsibility to set to the desired value (nomi

SamplingDistribution *	RebuildDistributions (bool isUpper=true, int nToys=100, TList clsDist=0, TList clsbDist=0, TList clbDist=0, const char outputfile="HypoTestInverterRebuiltDist.root")
	rebuild the sampling distributions by generating some toys and find for each of them a new upper limit Return the upper limit distribution and optionally also the pValue distributions for Cls, Clsb and Clbxs as a TList for each scanned point The method uses the present parameter value.

bool	RunFixedScan (int nBins, double xMin, double xMax, bool scanLog=false) const
	Run a fixed scan.

bool	RunLimit (double &limit, double &limitErr, double absTol=0, double relTol=0, const double *hint=0) const
	Run an automatic scan until the desired accuracy is reached.

bool	RunOnePoint (double thisX, bool adaptive=false, double clTarget=-1) const
	run only one point at the given POI value

void	SetAutoScan ()
	Use automatic scanning, i.e. adaptive.

virtual void	SetConfidenceLevel (Double_t cl)
	set the confidence level for the interval (e.g. 0.95 for a 95% Confidence Interval)

virtual void	SetData (RooAbsData &)
	Set the DataSet ( add to the the workspace if not already there ?)

void	SetFixedScan (int nBins, double xMin=1, double xMax=-1, bool scanLog=false)
	Set up to perform a fixed scan.

void	SetMaximumToys (int ntoys)

virtual void	SetModel (const ModelConfig &)
	Set the Model.

void	SetNumErr (double err)

virtual void	SetTestSize (Double_t size)
	set the size of the test (rate of Type I error) ( e.g. 0.05 for a 95% Confidence Interval)

bool	SetTestStatistic (TestStatistic &stat)
	set the test statistic to use

void	SetVerbose (int level=1)

virtual Double_t	Size () const
	Get the size of the test (eg. rate of Type I error)

void	UseCLs (bool on=true)

Public Member Functions inherited from RooStats::IntervalCalculator
virtual	~IntervalCalculator ()

Static Public Member Functions
static void	SetCloseProof (Bool_t flag)
	set flag to close proof for every new run

Protected Member Functions
	HypoTestInverter (const HypoTestInverter &rhs)
	copy-constructor NOTE: this class does not copy the contained result and the HypoTestCalculator, but only the pointers It requires the original HTI to be alive

void	CreateResults () const
	create a new HypoTestInverterResult to hold all computed results

HypoTestResult *	Eval (HypoTestCalculatorGeneric &hc, bool adaptive, double clsTarget) const
	Run the Hypothesis test at a previous configured point (internal function called by RunOnePoint)

HypoTestInverter &	operator= (const HypoTestInverter &rhs)
	assignment operator NOTE: this class does not copy the contained result and the HypoTestCalculator, but only the pointers It requires the original HTI to be alive

Static Protected Member Functions
static void	CheckInputModels (const HypoTestCalculatorGeneric &hc, const RooRealVar &scanVar)
	check the model given the given hypotestcalculator

static RooRealVar *	GetVariableToScan (const HypoTestCalculatorGeneric &hc)
	get the variable to scan try first with null model if not go to alternate model

Private Attributes
ECalculatorType	fCalcType

HypoTestCalculatorGeneric *	fCalculator0

std::unique_ptr< HypoTestCalculatorGeneric >	fHC

std::unique_ptr< TGraphErrors >	fLimitPlot

int	fMaxToys

int	fNBins

double	fNumErr

HypoTestInverterResult *	fResults

bool	fScanLog

RooRealVar *	fScannedVariable
	pointer to the generic hypotest calculator used

double	fSize

int	fTotalToysRun
	plot of limits

bool	fUseCLs

int	fVerbose

double	fXmax

double	fXmin

Static Private Attributes
static double	fgAbsAccuracy = 0.05

static std::string	fgAlgo = "logSecant"

static double	fgCLAccuracy = 0.005

static bool	fgCloseProof = false

static unsigned int	fgNToys = 500

static double	fgRelAccuracy = 0.05

#include <RooStats/HypoTestInverter.h>

Inheritance diagram for RooStats::HypoTestInverter:

[legend]

Member Enumeration Documentation

◆ ECalculatorType

enum RooStats::HypoTestInverter::ECalculatorType

Enumerator
kUndefined
kHybrid
kFrequentist
kAsymptotic

Definition at line 40 of file HypoTestInverter.h.

Constructor & Destructor Documentation

◆ HypoTestInverter() [1/7]

HypoTestInverter::HypoTestInverter ( )

default constructor (doesn't do anything)

Definition at line 167 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [2/7]

HypoTestInverter::HypoTestInverter	(	HypoTestCalculatorGeneric &	hc,
		RooRealVar *	scannedVariable = `0`,
		double	size = `0.05`
	)

Constructor from a HypoTestCalculatorGeneric The HypoTest calculator must be a FrequentistCalculator or HybridCalculator type Other type of calculators are not supported.

The calculator must be created before by using the S+B model for the null and the B model for the alt If no variable to scan are given they are assumed to be the first variable from the parameter of interests of the null model

Definition at line 192 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [3/7]

HypoTestInverter::HypoTestInverter	(	HybridCalculator &	hc,
		RooRealVar *	scannedVariable = `0`,
		double	size = `0.05`
	)

Constructor from a reference to a HybridCalculator The calculator must be created before by using the S+B model for the null and the B model for the alt If no variable to scan are given they are assumed to be the first variable from the parameter of interests of the null model.

Definition at line 245 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [4/7]

HypoTestInverter::HypoTestInverter	(	FrequentistCalculator &	hc,
		RooRealVar *	scannedVariable,
		double	size = `0.05`
	)

Constructor from a reference to a FrequentistCalculator The calculator must be created before by using the S+B model for the null and the B model for the alt If no variable to scan are given they are assumed to be the first variable from the parameter of interests of the null model.

Definition at line 278 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [5/7]

HypoTestInverter::HypoTestInverter	(	AsymptoticCalculator &	hc,
		RooRealVar *	scannedVariable,
		double	size = `0.05`
	)

Constructor from a reference to a AsymptoticCalculator The calculator must be created before by using the S+B model for the null and the B model for the alt If no variable to scan are given they are assumed to be the first variable from the parameter of interests of the null model.

Definition at line 310 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [6/7]

HypoTestInverter::HypoTestInverter	(	RooAbsData &	data,
		ModelConfig &	sbModel,
		ModelConfig &	bModel,
		RooRealVar *	scannedVariable = `0`,
		ECalculatorType	type = `kFrequentist`,
		double	size = `0.05`
	)

Constructor from a model for B model and a model for S+B.

An HypoTestCalculator (Hybrid of Frequentis) will be created using the S+B model as the null and the B model as the alternate If no variable to scan are given they are assumed to be the first variable from the parameter of interests of the null model

Definition at line 343 of file HypoTestInverter.cxx.

◆ ~HypoTestInverter()

HypoTestInverter::~HypoTestInverter ( )

virtual

destructor (delete the HypoTestInverterResult)

Definition at line 416 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [7/7]

HypoTestInverter::HypoTestInverter ( const HypoTestInverter & rhs )

protected

copy-constructor NOTE: this class does not copy the contained result and the HypoTestCalculator, but only the pointers It requires the original HTI to be alive

Definition at line 379 of file HypoTestInverter.cxx.

Member Function Documentation

◆ CheckInputModels()

void HypoTestInverter::CheckInputModels	(	const HypoTestCalculatorGeneric &	hc,
		const RooRealVar &	scanVar
	)

staticprotected

check the model given the given hypotestcalculator

Definition at line 127 of file HypoTestInverter.cxx.

◆ Clear()

void HypoTestInverter::Clear ( )

delete contained result and graph

Definition at line 449 of file HypoTestInverter.cxx.

◆ ConfidenceLevel()

virtual Double_t RooStats::HypoTestInverter::ConfidenceLevel ( ) const

inlinevirtual

Get the Confidence level for the test.

Implements RooStats::IntervalCalculator.

Definition at line 117 of file HypoTestInverter.h.

◆ CreateResults()

void HypoTestInverter::CreateResults ( ) const

protected

create a new HypoTestInverterResult to hold all computed results

Definition at line 458 of file HypoTestInverter.cxx.

◆ Eval()

HypoTestResult * HypoTestInverter::Eval	(	HypoTestCalculatorGeneric &	hc,
		bool	adaptive,
		double	clsTarget
	)		const

protected

Run the Hypothesis test at a previous configured point (internal function called by RunOnePoint)

Definition at line 521 of file HypoTestInverter.cxx.

◆ GetHypoTestCalculator()

HypoTestCalculatorGeneric * RooStats::HypoTestInverter::GetHypoTestCalculator ( ) const

inline

Definition at line 124 of file HypoTestInverter.h.

◆ GetInterval()

HypoTestInverterResult * HypoTestInverter::GetInterval ( ) const

virtual

Run a fixed scan or the automatic scan depending on the configuration.

Return if needed a copy of the result object which will be managed by the user.

Implements RooStats::IntervalCalculator.

Definition at line 490 of file HypoTestInverter.cxx.

◆ GetLowerLimitDistribution()

SamplingDistribution * HypoTestInverter::GetLowerLimitDistribution	(	bool	rebuild = `false`,
		int	nToys = `100`
	)

get the distribution of lower limit if rebuild = false (default) it will re-use the results of the scan done for obtained the observed limit and no extra toys will be generated if rebuild a new set of B toys will be done and the procedure will be repeated for each toy

Definition at line 1024 of file HypoTestInverter.cxx.

◆ GetTestStatistic()

TestStatistic * HypoTestInverter::GetTestStatistic ( ) const

return the test statistic which is or will be used by the class

Definition at line 425 of file HypoTestInverter.cxx.

◆ GetUpperLimitDistribution()

SamplingDistribution * HypoTestInverter::GetUpperLimitDistribution	(	bool	rebuild = `false`,
		int	nToys = `100`
	)

get the distribution of lower limit if rebuild = false (default) it will re-use the results of the scan done for obtained the observed limit and no extra toys will be generated if rebuild a new set of B toys will be done and the procedure will be repeated for each toy The nuisance parameter value used for rebuild is the current one in the model so it is user responsibility to set to the desired value (nomi

Definition at line 1051 of file HypoTestInverter.cxx.

◆ GetVariableToScan()

RooRealVar * HypoTestInverter::GetVariableToScan ( const HypoTestCalculatorGeneric & hc )

staticprotected

get the variable to scan try first with null model if not go to alternate model

Definition at line 106 of file HypoTestInverter.cxx.

◆ operator=()

HypoTestInverter & HypoTestInverter::operator= ( const HypoTestInverter & rhs )

protected

assignment operator NOTE: this class does not copy the contained result and the HypoTestCalculator, but only the pointers It requires the original HTI to be alive

Definition at line 394 of file HypoTestInverter.cxx.

◆ RebuildDistributions()

SamplingDistribution * HypoTestInverter::RebuildDistributions	(	bool	isUpper = `true`,
		int	nToys = `100`,
		TList *	clsDist = `0`,
		TList *	clsbDist = `0`,
		TList *	clbDist = `0`,
		const char *	outputfile = `"HypoTestInverterRebuiltDist.root"`
	)

rebuild the sampling distributions by generating some toys and find for each of them a new upper limit Return the upper limit distribution and optionally also the pValue distributions for Cls, Clsb and Clbxs as a TList for each scanned point The method uses the present parameter value.

It is user responsibility to give the current parameters to rebuild the distributions It returns a upper or lower limit distribution depending on the isUpper flag, however it computes also the lower limit distribution and it is saved in the output file as an histogram

Definition at line 1083 of file HypoTestInverter.cxx.

◆ RunFixedScan()

bool HypoTestInverter::RunFixedScan	(	int	nBins,
		double	xMin,
		double	xMax,
		bool	scanLog = `false`
	)		const

Run a fixed scan.

Run a Fixed scan in npoints between min and max.

Parameters

[in]	nBins	Number of points to scan.
[in]	xMin	Lower limit of range to be scanned.
[in]	xMax	Upper limit of range to be scanned.
[in]	scanLog	Run in logarithmic steps along x.

Definition at line 604 of file HypoTestInverter.cxx.

◆ RunLimit()

bool HypoTestInverter::RunLimit	(	double &	limit,
		double &	limitErr,
		double	absAccuracy = `0`,
		double	relAccuracy = `0`,
		const double *	hint = `0`
	)		const

Run an automatic scan until the desired accuracy is reached.

Start by default from the full interval (min,max) of the POI and then via bisection find the line crossing the target line. Optionally, a hint can be provided and the scan will be done closer to that value. If by bisection the desired accuracy will not be reached, a fit to the points is performed.

Parameters

[out]	limit	The limit.
[out]	limitErr	The error of the limit.
[in]	absAccuracy	Desired absolute accuracy.
[in]	relAccuracy	Desired relative accuracy.
[in]	hint	Hint to start from or nullptr for no hint.

Definition at line 770 of file HypoTestInverter.cxx.

◆ RunOnePoint()

bool HypoTestInverter::RunOnePoint	(	double	thisX,
		bool	adaptive = `false`,
		double	clTarget = `-1`
	)		const

run only one point at the given POI value

Definition at line 670 of file HypoTestInverter.cxx.

◆ SetAutoScan()

void RooStats::HypoTestInverter::SetAutoScan ( )

inline

Use automatic scanning, i.e. adaptive.

Definition at line 89 of file HypoTestInverter.h.

◆ SetCloseProof()

void HypoTestInverter::SetCloseProof ( Bool_t flag )

static

set flag to close proof for every new run

Definition at line 98 of file HypoTestInverter.cxx.

◆ SetConfidenceLevel()

virtual void RooStats::HypoTestInverter::SetConfidenceLevel ( Double_t cl )

inlinevirtual

set the confidence level for the interval (e.g. 0.95 for a 95% Confidence Interval)

Implements RooStats::IntervalCalculator.

Definition at line 113 of file HypoTestInverter.h.

◆ SetData()

void HypoTestInverter::SetData ( RooAbsData & )

virtual

Set the DataSet ( add to the the workspace if not already there ?)

Implements RooStats::IntervalCalculator.

Definition at line 1070 of file HypoTestInverter.cxx.

◆ SetFixedScan()

void RooStats::HypoTestInverter::SetFixedScan	(	int	nBins,
		double	xMin = `1`,
		double	xMax = `-1`,
		bool	scanLog = `false`
	)

inline

Set up to perform a fixed scan.

Parameters

[in]	nBins	Number of points to scan.
[in]	xMin	Lower limit of range to be scanned.
[in]	xMax	Upper limit of range to be scanned.
[in]	scanLog	Run in logarithmic steps along x.

virtual Double_t RooStats::HypoTestInverter::Size ( ) const

inlinevirtual

Get the size of the test (eg. rate of Type I error)

Implements RooStats::IntervalCalculator.

Definition at line 115 of file HypoTestInverter.h.

◆ UseCLs()

void RooStats::HypoTestInverter::UseCLs ( bool on = true )

bool RooStats::HypoTestInverter::fScanLog

private

Definition at line 194 of file HypoTestInverter.h.

◆ fScannedVariable

RooRealVar* RooStats::HypoTestInverter::fScannedVariable

private

pointer to the generic hypotest calculator used

Definition at line 190 of file HypoTestInverter.h.

◆ fSize

double RooStats::HypoTestInverter::fSize

private

Definition at line 195 of file HypoTestInverter.h.

◆ fTotalToysRun

int RooStats::HypoTestInverter::fTotalToysRun

mutableprivate

plot of limits

Definition at line 185 of file HypoTestInverter.h.

◆ fUseCLs

bool RooStats::HypoTestInverter::fUseCLs

private

Definition at line 193 of file HypoTestInverter.h.

◆ fVerbose

int RooStats::HypoTestInverter::fVerbose

private

Definition at line 196 of file HypoTestInverter.h.

◆ fXmax

double RooStats::HypoTestInverter::fXmax

private

Definition at line 200 of file HypoTestInverter.h.

◆ fXmin

double RooStats::HypoTestInverter::fXmin

private

Definition at line 199 of file HypoTestInverter.h.

Libraries for RooStats::HypoTestInverter:

[legend]

The documentation for this class was generated from the following files:

roofit/roostats/inc/RooStats/HypoTestInverter.h
roofit/roostats/src/HypoTestInverter.cxx

Scanning options

CLs presciption

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Attributes

Static Private Attributes

Member Enumeration Documentation

◆ ECalculatorType

Constructor & Destructor Documentation

◆ HypoTestInverter() [1/7]

◆ HypoTestInverter() [2/7]

◆ HypoTestInverter() [3/7]

◆ HypoTestInverter() [4/7]

◆ HypoTestInverter() [5/7]

◆ HypoTestInverter() [6/7]

◆ ~HypoTestInverter()

◆ HypoTestInverter() [7/7]

Member Function Documentation

◆ CheckInputModels()

◆ Clear()

◆ ConfidenceLevel()

◆ CreateResults()

◆ Eval()

◆ GetHypoTestCalculator()

◆ GetInterval()

◆ GetLowerLimitDistribution()

◆ GetTestStatistic()

◆ GetUpperLimitDistribution()

◆ GetVariableToScan()

◆ operator=()

◆ RebuildDistributions()

◆ RunFixedScan()

◆ RunLimit()

◆ RunOnePoint()

◆ SetAutoScan()

◆ SetCloseProof()

◆ SetConfidenceLevel()

◆ SetData()

◆ SetFixedScan()

◆ SetMaximumToys()

◆ SetModel()

◆ SetNumErr()

◆ SetTestSize()

◆ SetTestStatistic()

◆ SetVerbose()

◆ Size()

◆ UseCLs()

Member Data Documentation

◆ fCalcType

◆ fCalculator0

◆ fgAbsAccuracy

◆ fgAlgo

◆ fgCLAccuracy

◆ fgCloseProof

◆ fgNToys

◆ fgRelAccuracy

◆ fHC

◆ fLimitPlot

◆ fMaxToys

◆ fNBins

◆ fNumErr

◆ fResults

◆ fScanLog

◆ fScannedVariable

◆ fSize

◆ fTotalToysRun

◆ fUseCLs

◆ fVerbose

◆ fXmax

◆ fXmin