CombineHarvester
ch::BinByBinFactory Class Reference

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

#include "/afs/cern.ch/user/a/agilbert/CMSSW_14_1_0_pre4/src/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...
 
BinByBinFactorySetVerbosity (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...
 
BinByBinFactorySetAddThreshold (double val)
 Set the fractional bin error threshold for bin-by-bin creation and for participation in the merging algorithm. More...
 
BinByBinFactorySetMergeThreshold (double val)
 The threshold for the merging algorithm. More...
 
BinByBinFactorySetPattern (std::string const &pattern)
 The pattern-string for the systematic naming convention. More...
 
BinByBinFactorySetFixNorm (bool fix)
 Whether or not the bin-by-bin systematics are allowed to vary the process normalisation. More...
 
BinByBinFactorySetPoissonErrors (bool poisson_errors)
 Construct approximate Poisson uncertainties instead of default Gaussian. More...
 
BinByBinFactorySetMergeZeroBins (bool merge)
 Set whether bins with zero content can participate in the merging procedure. More...
 
BinByBinFactorySetMergeSaturatedBins (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: