Merges bin uncertainties and creates bin-by-bin statistical uncertainties. More...

#include "CombineHarvester/CombineTools/interface/BinByBin.h"

Public Member Functions
	BinByBinFactory ()

void	MergeBinErrors (CombineHarvester &cb)
	Merges histogram bin errors between processes. More...

void	AddBinByBin (CombineHarvester &src, CombineHarvester &dest)
	Create bin-by-bin shape uncertainties for every process in src, and add these to dest More...

void	MergeAndAdd (CombineHarvester &src, CombineHarvester &dest)
	A convenience function which calls MergeBinErrors and AddBinByBin in turn. More...

BinByBinFactory &	SetVerbosity (unsigned verbosity)
	By default this class only produces output on the screen when an error occurs, set to a value greater than zero for more verbose output. More...

BinByBinFactory &	SetAddThreshold (double val)
	Set the fractional bin error threshold for bin-by-bin creation and for participation in the merging algorithm. More...

BinByBinFactory &	SetMergeThreshold (double val)
	The threshold for the merging algorithm. More...

BinByBinFactory &	SetPattern (std::string const &pattern)
	The pattern-string for the systematic naming convention. More...

BinByBinFactory &	SetFixNorm (bool fix)
	Whether or not the bin-by-bin systematics are allowed to vary the process normalisation. More...

BinByBinFactory &	SetPoissonErrors (bool poisson_errors)
	Construct approximate Poisson uncertainties instead of default Gaussian. More...

BinByBinFactory &	SetMergeZeroBins (bool merge)
	Set whether bins with zero content can participate in the merging procedure. More...

BinByBinFactory &	SetMergeSaturatedBins (bool merge)
	Set whether bins with error >= content participate in the merging procedure. More...

unsigned	GetVerbosity ()
	Getter functions for class attributes. More...

double	GetAddThreshold ()

double	GetMergeThreshold ()

std::string	GetPattern ()

bool	GetFixNorm ()

bool	GetPoissonErrors ()

bool	GetMergeZeroBins ()

bool	GetMergeSaturatedBins ()

Detailed Description

Merges bin uncertainties and creates bin-by-bin statistical uncertainties.

Typical usage:

auto bbb = ch::BinByBinFactory()
    .SetAddThreshold(0.1)
    .SetMergeThreshold(0.5)
    .SetFixNorm(true);
bbb.MergeBinErrors(cb.cp().backgrounds());
bbb.AddBinByBin(cb.cp().backgrounds(), cb);

See below for details on each class method.

Definition at line 21 of file BinByBin.h.

Constructor & Destructor Documentation

◆ BinByBinFactory()

ch::BinByBinFactory::BinByBinFactory ( )

Definition at line 11 of file BinByBin.cc.

Member Function Documentation

◆ MergeBinErrors()

void ch::BinByBinFactory::MergeBinErrors ( CombineHarvester & cb )

Merges histogram bin errors between processes.

The method will loop through each analysis category and apply the merging algorithm to the histograms of all processes within that category:

In a given histogram bin consider contributions from the $j$ processes with bin contents $x_{i}$, bin errors $e_{i}$ and with $e_{i}/x_{i}$ larger than the bin-by-bin addition threshold (SetAddThreshold). Note that by setting this threshold to zero the contributions from all processes will be considered.
Evaluate the total squared uncertainty from these processes: $e_{TOT}^{2} = e_{1}^{2} + e_{2}^{2} + ... + e_{j}^{2} $
Rank bins from lowest to highest fraction error: $e_{i}^{2}/e_{TOT}^{2}$
Start removing bin errors from the lowest ranked bins as long as the total sum of squared error removed ( $r_{sub}$) is less than the merge threshold (SetMergeThreshold).
Once as many bin errors have been removed as possible, scale up the remaining errors by a factor $\sqrt{1/(1-r_{sub})}$, which ensure the total bin error from all processes remains the same.
Note that the BinByBinFactory default is a merging threshold of zero, in which no merging takes place. The most extreme threshold is 1, in which all errors will be merged into a single process.

Note: For a valid result all analysis event categories must have a unique bin() value.

Definition at line 22 of file BinByBin.cc.

◆ AddBinByBin()

void ch::BinByBinFactory::AddBinByBin	(	CombineHarvester &	src,
		CombineHarvester &	dest
	)

Create bin-by-bin shape uncertainties for every process in src, and add these to dest

The behaviour of this function is controlled by three parameters:

The first is the uncertainty threshold which determines whether a systematic will be created for a given histogram bin (SetAddThreshold). For a bin with content $x$ and bin error $e$, this threshold is thefractional error $e/x$.
The second parameters (SetFixNorm) is a flag that when set to true will re-normalize the up and down shape templates to have the same integral as the nominal. This means the nuisance parameter for this bin is only able to change the shape of the distribution: if a bin is shifted up, all other bins are shifted down slightly to preserve the normalisation. This feature is useful when the statistical uncertainty in the process yield is considered as an independent nuisance parameter.
The third parameters is a pattern-string which prescribes how the bin-by-bin uncertainties should be named. By default this is CMS_$ANALYSIS_$CHANNEL_$BIN_$ERA_$PROCESS_bin_$#, but can be changed with SetPattern. Note that the special term $# should always be included as this is replaced with the bin index.

Definition at line 105 of file BinByBin.cc.

◆ MergeAndAdd()

void ch::BinByBinFactory::MergeAndAdd	(	CombineHarvester &	src,
		CombineHarvester &	dest
	)

A convenience function which calls MergeBinErrors and AddBinByBin in turn.

Definition at line 202 of file BinByBin.cc.

◆ SetVerbosity()

BinByBinFactory& ch::BinByBinFactory::SetVerbosity ( unsigned verbosity )

inline

By default this class only produces output on the screen when an error occurs, set to a value greater than zero for more verbose output.

Definition at line 90 of file BinByBin.h.

◆ SetAddThreshold()

BinByBinFactory& ch::BinByBinFactory::SetAddThreshold ( double val )

inline

Set the fractional bin error threshold for bin-by-bin creation and for participation in the merging algorithm.

Definition at line 99 of file BinByBin.h.

◆ SetMergeThreshold()

BinByBinFactory& ch::BinByBinFactory::SetMergeThreshold ( double val )

inline

The threshold for the merging algorithm.

Definition at line 107 of file BinByBin.h.

◆ SetPattern()

BinByBinFactory& ch::BinByBinFactory::SetPattern ( std::string const & pattern )

inline

The pattern-string for the systematic naming convention.

Definition at line 115 of file BinByBin.h.

◆ SetFixNorm()

BinByBinFactory& ch::BinByBinFactory::SetFixNorm ( bool fix )

inline

Whether or not the bin-by-bin systematics are allowed to vary the process normalisation.

Definition at line 124 of file BinByBin.h.

◆ SetPoissonErrors()

BinByBinFactory& ch::BinByBinFactory::SetPoissonErrors ( bool poisson_errors )

inline

Construct approximate Poisson uncertainties instead of default Gaussian.

Definition at line 132 of file BinByBin.h.

◆ SetMergeZeroBins()

BinByBinFactory& ch::BinByBinFactory::SetMergeZeroBins ( bool merge )

inline

Set whether bins with zero content can participate in the merging procedure.

Definition at line 140 of file BinByBin.h.

◆ SetMergeSaturatedBins()

BinByBinFactory& ch::BinByBinFactory::SetMergeSaturatedBins ( bool merge )

inline

Set whether bins with error >= content participate in the merging procedure.

Definition at line 148 of file BinByBin.h.

◆ GetVerbosity()

unsigned ch::BinByBinFactory::GetVerbosity ( )

inline

Getter functions for class attributes.

Definition at line 156 of file BinByBin.h.

◆ GetAddThreshold()

double ch::BinByBinFactory::GetAddThreshold ( )

inline

Definition at line 157 of file BinByBin.h.

◆ GetMergeThreshold()

double ch::BinByBinFactory::GetMergeThreshold ( )

inline

Definition at line 158 of file BinByBin.h.

◆ GetPattern()

std::string ch::BinByBinFactory::GetPattern ( )

inline

Definition at line 159 of file BinByBin.h.

◆ GetFixNorm()

bool ch::BinByBinFactory::GetFixNorm ( )

inline

Definition at line 160 of file BinByBin.h.

◆ GetPoissonErrors()

bool ch::BinByBinFactory::GetPoissonErrors ( )

inline

Definition at line 161 of file BinByBin.h.

◆ GetMergeZeroBins()

bool ch::BinByBinFactory::GetMergeZeroBins ( )

inline

Definition at line 162 of file BinByBin.h.

◆ GetMergeSaturatedBins()

bool ch::BinByBinFactory::GetMergeSaturatedBins ( )

inline

Definition at line 163 of file BinByBin.h.

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

CombineTools/interface/BinByBin.h
CombineTools/src/BinByBin.cc

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BinByBinFactory()

Member Function Documentation

◆ MergeBinErrors()

◆ AddBinByBin()

◆ MergeAndAdd()

◆ SetVerbosity()

◆ SetAddThreshold()

◆ SetMergeThreshold()

◆ SetPattern()

◆ SetFixNorm()

◆ SetPoissonErrors()

◆ SetMergeZeroBins()

◆ SetMergeSaturatedBins()

◆ GetVerbosity()

◆ GetAddThreshold()

◆ GetMergeThreshold()

◆ GetPattern()

◆ GetFixNorm()

◆ GetPoissonErrors()

◆ GetMergeZeroBins()

◆ GetMergeSaturatedBins()