Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
RooStats::HypoTestInverter Class Reference

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.

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 (used only for I/O)
 
 HypoTestInverter (AsymptoticCalculator &hc, RooRealVar *scannedVariable, double size=0.05)
 constructor from asymptotic calculator
 
 HypoTestInverter (FrequentistCalculator &hc, RooRealVar *scannedVariable, double size=0.05)
 constructor from frequentist calculator
 
 HypoTestInverter (HybridCalculator &hc, RooRealVar *scannedVariable=nullptr, double size=0.05)
 constructor from hybrid calculator
 
 HypoTestInverter (HypoTestCalculatorGeneric &hc, RooRealVar *scannedVariable=nullptr, double size=0.05)
 constructor from generic hypotest calculator
 
 HypoTestInverter (RooAbsData &data, ModelConfig &sb, ModelConfig &b, RooRealVar *scannedVariable=nullptr, ECalculatorType type=kFrequentist, double size=0.05)
 constructor from two ModelConfigs (first sb (the null model) then b (the alt model) creating a calculator inside
 
 ~HypoTestInverter () override
 destructor
 
void Clear ()
 delete contained result and graph
 
double ConfidenceLevel () const override
 Get the Confidence level for the test.
 
HypoTestCalculatorGenericGetHypoTestCalculator () const
 retrieved a reference to the internally used HypoTestCalculator it might be invalid when the class is deleted
 
HypoTestInverterResultGetInterval () const override
 Run a fixed scan or the automatic scan depending on the configuration.
 
SamplingDistributionGetLowerLimitDistribution (bool rebuild=false, int nToys=100)
 get the upper/lower limit distribution
 
TestStatisticGetTestStatistic () const
 get the test statistic
 
SamplingDistributionGetUpperLimitDistribution (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
 
TClassIsA () const override
 
SamplingDistributionRebuildDistributions (bool isUpper=true, int nToys=100, TList *clsDist=nullptr, TList *clsbDist=nullptr, TList *clbDist=nullptr, const char *outputfile="HypoTestInverterRebuiltDist.root")
 function to rebuild the distributions
 
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=nullptr) 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.
 
void SetConfidenceLevel (double cl) override
 set the confidence level for the interval (eg. 0.95 for a 95% Confidence Interval)
 
void SetData (RooAbsData &) override
 Set the DataSet ( add to 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)
 set maximum number of toys
 
void SetModel (const ModelConfig &) override
 Set the Model.
 
void SetNumErr (double err)
 set numerical error in test statistic evaluation (default is zero)
 
void SetTestSize (double size) override
 set the size of the test (rate of Type I error) ( Eg. 0.05 for a 95% Confidence Interval)
 
bool SetTestStatistic (TestStatistic &stat)
 set the test statistic
 
void SetVerbose (int level=1)
 set verbose level (0,1,2)
 
double Size () const override
 Get the size of the test (eg. rate of Type I error)
 
void Streamer (TBuffer &) override
 
void StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)
 
void UseCLs (bool on=true)
 
- Public Member Functions inherited from RooStats::IntervalCalculator
virtual ~IntervalCalculator ()
 
void StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)
 

Static Public Member Functions

static TClassClass ()
 
static const char * Class_Name ()
 
static constexpr Version_t Class_Version ()
 
static const char * DeclFileName ()
 
- Static Public Member Functions inherited from RooStats::IntervalCalculator
static TClassClass ()
 
static const char * Class_Name ()
 
static constexpr Version_t Class_Version ()
 
static const char * DeclFileName ()
 

Protected Member Functions

 HypoTestInverter (const HypoTestInverter &rhs)
 copy c-tor
 
void CreateResults () const
 create a new HypoTestInverterResult to hold all computed results
 
HypoTestResultEval (HypoTestCalculatorGeneric &hc, bool adaptive, double clsTarget) const
 run the hybrid at a single point
 
HypoTestInverteroperator= (const HypoTestInverter &rhs)
 assignment
 

Static Protected Member Functions

static void CheckInputModels (const HypoTestCalculatorGeneric &hc, const RooRealVar &scanVar)
 check the model given the given hypotestcalculator
 
static RooRealVarGetVariableToScan (const HypoTestCalculatorGeneric &hc)
 helper functions
 

Private Attributes

ECalculatorType fCalcType
 
HypoTestCalculatorGenericfCalculator0
 pointer to the calculator passed in the constructor
 
std::unique_ptr< HypoTestCalculatorGenericfHC
 ! pointer to the generic hypotest calculator used
 
std::unique_ptr< TGraphErrorsfLimitPlot
 ! plot of limits
 
int fMaxToys
 maximum number of toys to run
 
int fNBins
 
double fNumErr
 
HypoTestInverterResultfResults
 pointer to the result
 
bool fScanLog
 
RooRealVarfScannedVariable
 pointer to the constrained variable
 
double fSize
 
int fTotalToysRun
 
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 unsigned int fgNToys = 500
 
static double fgRelAccuracy = 0.05
 

#include <RooStats/HypoTestInverter.h>

Inheritance diagram for RooStats::HypoTestInverter:
[legend]

Member Enumeration Documentation

◆ ECalculatorType

Enumerator
kUndefined 
kHybrid 
kFrequentist 
kAsymptotic 

Definition at line 40 of file HypoTestInverter.h.

Constructor & Destructor Documentation

◆ HypoTestInverter() [1/7]

HypoTestInverter::HypoTestInverter ( )

default constructor (used only for I/O)

default constructor (doesn't do anything)

Definition at line 156 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [2/7]

HypoTestInverter::HypoTestInverter ( HypoTestCalculatorGeneric hc,
RooRealVar scannedVariable = nullptr,
double  size = 0.05 
)

constructor from generic hypotest calculator

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 181 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [3/7]

HypoTestInverter::HypoTestInverter ( HybridCalculator hc,
RooRealVar scannedVariable = nullptr,
double  size = 0.05 
)

constructor from hybrid calculator

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 235 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [4/7]

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

constructor from frequentist calculator

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 268 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [5/7]

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

constructor from asymptotic calculator

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 301 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [6/7]

HypoTestInverter::HypoTestInverter ( RooAbsData data,
ModelConfig sbModel,
ModelConfig bModel,
RooRealVar scannedVariable = nullptr,
ECalculatorType  type = kFrequentist,
double  size = 0.05 
)

constructor from two ModelConfigs (first sb (the null model) then b (the alt model) creating a calculator inside

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 334 of file HypoTestInverter.cxx.

◆ ~HypoTestInverter()

HypoTestInverter::~HypoTestInverter ( )
override

destructor

destructor (delete the HypoTestInverterResult)

Definition at line 407 of file HypoTestInverter.cxx.

◆ HypoTestInverter() [7/7]

HypoTestInverter::HypoTestInverter ( const HypoTestInverter rhs)
protected

copy c-tor

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 370 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 116 of file HypoTestInverter.cxx.

◆ Class()

static TClass * RooStats::HypoTestInverter::Class ( )
static
Returns
TClass describing this class

◆ Class_Name()

static const char * RooStats::HypoTestInverter::Class_Name ( )
static
Returns
Name of this class

◆ Class_Version()

static constexpr Version_t RooStats::HypoTestInverter::Class_Version ( )
inlinestaticconstexpr
Returns
Version of this class

Definition at line 200 of file HypoTestInverter.h.

◆ Clear()

void HypoTestInverter::Clear ( )

delete contained result and graph

Definition at line 440 of file HypoTestInverter.cxx.

◆ ConfidenceLevel()

double RooStats::HypoTestInverter::ConfidenceLevel ( ) const
inlineoverridevirtual

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 449 of file HypoTestInverter.cxx.

◆ DeclFileName()

static const char * RooStats::HypoTestInverter::DeclFileName ( )
inlinestatic
Returns
Name of the file containing the class declaration

Definition at line 200 of file HypoTestInverter.h.

◆ Eval()

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

run the hybrid at a single point

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

Definition at line 511 of file HypoTestInverter.cxx.

◆ GetHypoTestCalculator()

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

retrieved a reference to the internally used HypoTestCalculator it might be invalid when the class is deleted

Definition at line 124 of file HypoTestInverter.h.

◆ GetInterval()

HypoTestInverterResult * HypoTestInverter::GetInterval ( ) const
overridevirtual

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 481 of file HypoTestInverter.cxx.

◆ GetLowerLimitDistribution()

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

get the upper/lower limit distribution

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 1028 of file HypoTestInverter.cxx.

◆ GetTestStatistic()

TestStatistic * HypoTestInverter::GetTestStatistic ( ) const

get the test statistic

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

Definition at line 416 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 1055 of file HypoTestInverter.cxx.

◆ GetVariableToScan()

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

helper functions

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

Definition at line 95 of file HypoTestInverter.cxx.

◆ IsA()

TClass * RooStats::HypoTestInverter::IsA ( ) const
inlineoverridevirtual
Returns
TClass describing current object

Reimplemented from RooStats::IntervalCalculator.

Definition at line 200 of file HypoTestInverter.h.

◆ operator=()

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

assignment

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 385 of file HypoTestInverter.cxx.

◆ RebuildDistributions()

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

function to rebuild the distributions

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 1087 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]nBinsNumber of points to scan.
[in]xMinLower limit of range to be scanned.
[in]xMaxUpper limit of range to be scanned.
[in]scanLogRun in logarithmic steps along x.

Definition at line 596 of file HypoTestInverter.cxx.

◆ RunLimit()

bool HypoTestInverter::RunLimit ( double limit,
double limitErr,
double  absAccuracy = 0,
double  relAccuracy = 0,
const double hint = nullptr 
) 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]limitThe limit.
[out]limitErrThe error of the limit.
[in]absAccuracyDesired absolute accuracy.
[in]relAccuracyDesired relative accuracy.
[in]hintHint to start from or nullptr for no hint.

Definition at line 764 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 663 of file HypoTestInverter.cxx.

◆ SetAutoScan()

void RooStats::HypoTestInverter::SetAutoScan ( )
inline

Use automatic scanning, i.e. adaptive.

Definition at line 89 of file HypoTestInverter.h.

◆ SetConfidenceLevel()

void RooStats::HypoTestInverter::SetConfidenceLevel ( double  cl)
inlineoverridevirtual

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

Implements RooStats::IntervalCalculator.

Definition at line 113 of file HypoTestInverter.h.

◆ SetData()

void HypoTestInverter::SetData ( RooAbsData )
overridevirtual

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

Implements RooStats::IntervalCalculator.

Definition at line 1074 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]nBinsNumber of points to scan.
[in]xMinLower limit of range to be scanned.
[in]xMaxUpper limit of range to be scanned.
[in]scanLogRun in logarithmic steps along x.

Definition at line 82 of file HypoTestInverter.h.

◆ SetMaximumToys()

void RooStats::HypoTestInverter::SetMaximumToys ( int  ntoys)
inline

set maximum number of toys

Definition at line 144 of file HypoTestInverter.h.

◆ SetModel()

void RooStats::HypoTestInverter::SetModel ( const ModelConfig )
inlineoverridevirtual

Set the Model.

Implements RooStats::IntervalCalculator.

Definition at line 108 of file HypoTestInverter.h.

◆ SetNumErr()

void RooStats::HypoTestInverter::SetNumErr ( double  err)
inline

set numerical error in test statistic evaluation (default is zero)

Definition at line 147 of file HypoTestInverter.h.

◆ SetTestSize()

void RooStats::HypoTestInverter::SetTestSize ( double  size)
inlineoverridevirtual

set the size of the test (rate of Type I error) ( Eg. 0.05 for a 95% Confidence Interval)

Implements RooStats::IntervalCalculator.

Definition at line 111 of file HypoTestInverter.h.

◆ SetTestStatistic()

bool HypoTestInverter::SetTestStatistic ( TestStatistic stat)

set the test statistic

set the test statistic to use

Definition at line 428 of file HypoTestInverter.cxx.

◆ SetVerbose()

void RooStats::HypoTestInverter::SetVerbose ( int  level = 1)
inline

set verbose level (0,1,2)

Definition at line 141 of file HypoTestInverter.h.

◆ Size()

double RooStats::HypoTestInverter::Size ( ) const
inlineoverridevirtual

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

Implements RooStats::IntervalCalculator.

Definition at line 115 of file HypoTestInverter.h.

◆ Streamer()

void RooStats::HypoTestInverter::Streamer ( TBuffer )
overridevirtual

Reimplemented from RooStats::IntervalCalculator.

◆ StreamerNVirtual()

void RooStats::HypoTestInverter::StreamerNVirtual ( TBuffer ClassDef_StreamerNVirtual_b)
inline

Definition at line 200 of file HypoTestInverter.h.

◆ UseCLs()

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

Definition at line 104 of file HypoTestInverter.h.

Member Data Documentation

◆ fCalcType

ECalculatorType RooStats::HypoTestInverter::fCalcType
private

Definition at line 192 of file HypoTestInverter.h.

◆ fCalculator0

HypoTestCalculatorGeneric* RooStats::HypoTestInverter::fCalculator0
private

pointer to the calculator passed in the constructor

Definition at line 183 of file HypoTestInverter.h.

◆ fgAbsAccuracy

double HypoTestInverter::fgAbsAccuracy = 0.05
staticprivate

Definition at line 171 of file HypoTestInverter.h.

◆ fgAlgo

std::string HypoTestInverter::fgAlgo = "logSecant"
staticprivate

Definition at line 173 of file HypoTestInverter.h.

◆ fgCLAccuracy

double HypoTestInverter::fgCLAccuracy = 0.005
staticprivate

Definition at line 170 of file HypoTestInverter.h.

◆ fgNToys

unsigned int HypoTestInverter::fgNToys = 500
staticprivate

Definition at line 169 of file HypoTestInverter.h.

◆ fgRelAccuracy

double HypoTestInverter::fgRelAccuracy = 0.05
staticprivate

Definition at line 172 of file HypoTestInverter.h.

◆ fHC

std::unique_ptr<HypoTestCalculatorGeneric> RooStats::HypoTestInverter::fHC
private

! pointer to the generic hypotest calculator used

Definition at line 184 of file HypoTestInverter.h.

◆ fLimitPlot

std::unique_ptr<TGraphErrors> RooStats::HypoTestInverter::fLimitPlot
mutableprivate

! plot of limits

Definition at line 176 of file HypoTestInverter.h.

◆ fMaxToys

int RooStats::HypoTestInverter::fMaxToys
private

maximum number of toys to run

Definition at line 181 of file HypoTestInverter.h.

◆ fNBins

int RooStats::HypoTestInverter::fNBins
private

Definition at line 193 of file HypoTestInverter.h.

◆ fNumErr

double RooStats::HypoTestInverter::fNumErr
private

Definition at line 196 of file HypoTestInverter.h.

◆ fResults

HypoTestInverterResult* RooStats::HypoTestInverter::fResults
mutableprivate

pointer to the result

Definition at line 186 of file HypoTestInverter.h.

◆ fScanLog

bool RooStats::HypoTestInverter::fScanLog
private

Definition at line 189 of file HypoTestInverter.h.

◆ fScannedVariable

RooRealVar* RooStats::HypoTestInverter::fScannedVariable
private

pointer to the constrained variable

Definition at line 185 of file HypoTestInverter.h.

◆ fSize

double RooStats::HypoTestInverter::fSize
private

Definition at line 190 of file HypoTestInverter.h.

◆ fTotalToysRun

int RooStats::HypoTestInverter::fTotalToysRun
mutableprivate

Definition at line 180 of file HypoTestInverter.h.

◆ fUseCLs

bool RooStats::HypoTestInverter::fUseCLs
private

Definition at line 188 of file HypoTestInverter.h.

◆ fVerbose

int RooStats::HypoTestInverter::fVerbose
private

Definition at line 191 of file HypoTestInverter.h.

◆ fXmax

double RooStats::HypoTestInverter::fXmax
private

Definition at line 195 of file HypoTestInverter.h.

◆ fXmin

double RooStats::HypoTestInverter::fXmin
private

Definition at line 194 of file HypoTestInverter.h.

Libraries for RooStats::HypoTestInverter:

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