Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
TUnfoldDensity.h
Go to the documentation of this file.
1// Author: Stefan Schmitt
2// DESY, 11/08/11
3
4// Version 17.5, bug fix in TUnfold also corrects GetEmatrixSysUncorr()
5//
6// History:
7// Version 17.4, in parallel to changes in TUnfoldBinning
8// Version 17.3, in parallel to changes in TUnfoldBinning
9// Version 17.2, in parallel to changes in TUnfoldBinning
10// Version 17.1, add scan type RhoSquare
11// Version 17.0, support for density regularisation and complex binning schemes
12
13#ifndef ROOT_TUnfoldDensity
14#define ROOT_TUnfoldDensity
15
16//////////////////////////////////////////////////////////////////////////
17// //
18// //
19// TUnfoldDensity, an extension of the class TUnfoldSys to correct for //
20// migration effects. TUnfoldDensity provides methods to deal with //
21// multidimensional complex binning schemes and variable bin widths //
22// //
23// Citation: S.Schmitt, JINST 7 (2012) T10003 [arXiv:1205.6201] //
24// //
25//////////////////////////////////////////////////////////////////////////
26
27/*
28 This file is part of TUnfold.
29
30 TUnfold is free software: you can redistribute it and/or modify
31 it under the terms of the GNU General Public License as published by
32 the Free Software Foundation, either version 3 of the License, or
33 (at your option) any later version.
34
35 TUnfold is distributed in the hope that it will be useful,
36 but WITHOUT ANY WARRANTY; without even the implied warranty of
37 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
38 GNU General Public License for more details.
39
40 You should have received a copy of the GNU General Public License
41 along with TUnfold. If not, see <http://www.gnu.org/licenses/>.
42*/
43
44#include "TUnfoldSys.h"
45#include "TUnfoldBinning.h"
46
47
48class TUnfoldDensity : public TUnfoldSys {
49 protected:
50 /// binning scheme for the output (truth level)
52 /// binning scheme for the input (detector level)
54 /// pointer to output binning scheme if owned by this class
56 /// pointer to input binning scheme if owned by this class
58 /// binning scheme for the regularisation conditions
60
61 public:
62 /// choice of regularisation scale factors to cinstruct the matrix L
64 /// no scale factors, matrix L is similar to unity matrix
66 /// scale factors from multidimensional bin width
68 /// scale factors from user function in TUnfoldBinning
70 /// scale factors from multidimensional bin width and user function
72 };
73 protected:
74
75 TString GetOutputBinName(Int_t iBinX) const override; // name a bin
76
77 Double_t GetDensityFactor(EDensityMode densityMode,Int_t iBin) const; // density correction factor for this bin
79 (const TUnfoldBinning *binning,ERegMode regmode,
80 EDensityMode densityMode,const char *distribution,
81 const char *axisSteering); // regularize the given binning recursively
83 (const TUnfoldBinning *binning,ERegMode regmode,
84 EDensityMode densityMode,const char *axisSteering); // regularize the distribution of one binning node
85
86 public:
87 TUnfoldDensity(void); // constructor for derived classes, do nothing
88
89 TUnfoldDensity(const TH2 *hist_A, EHistMap histmap,
93 const TUnfoldBinning *outputBins=nullptr,
94 const TUnfoldBinning *inputBins=nullptr,
95 const char *regularisationDistribution=nullptr,
96 const char *regularisationAxisSteering="*[UOB]"); // constructor for using the histogram classes. Default regularisation is on the curvature of the bin-width normalized density, excluding underflow and overflow bins
97
98 ~ TUnfoldDensity(void) override; // delete data members
99
100 void RegularizeDistribution(ERegMode regmode,EDensityMode densityMode,
101 const char *distribution,
102 const char *axisSteering); // regularize distribution(s) of the output binning scheme
103
104 /// scan mode for correlation scan
106 /// average global correlation coefficient (from TUnfold::GetRhoI())
108 /// maximum global correlation coefficient (from TUnfold::GetRhoI())
110 /// average global correlation coefficient (from TUnfoldSys::GetRhoItotal())
112 /// maximum global correlation coefficient (from TUnfoldSys::GetRhoItotal())
114 /// average global correlation coefficient squared (from TUnfold::GetRhoI())
116 /// average global correlation coefficient squared (from TUnfoldSys::GetRhoItotal())
118 };
119
120 virtual Int_t ScanTau(Int_t nPoint,Double_t tauMin,Double_t tauMax,
121 TSpline **scanResult,Int_t mode=kEScanTauRhoAvg,
122 const char *distribution=nullptr,const char *projectionMode=nullptr,TGraph **lCurvePlot=nullptr,TSpline **logTauXPlot=nullptr,TSpline **logTauYPlot=nullptr); // scan some variable (e.g. global correlation) and find a minimum using successive calls to DoUnfold(Double_t) at various tau
123 virtual Double_t GetScanVariable(Int_t mode,const char *distribution,const char *projectionMode); // calculate variable for ScanTau()
124
125 TH1 *GetOutput(const char *histogramName,
126 const char *histogramTitle=nullptr,const char *distributionName=nullptr,
127 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE) const; // get unfolding result
128 TH1 *GetBias(const char *histogramName,
129 const char *histogramTitle=nullptr,const char *distributionName=nullptr,
130 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE) const; // get bias
131 TH1 *GetFoldedOutput(const char *histogramName,
132 const char *histogramTitle=nullptr,
133 const char *distributionName=nullptr,
134 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE,
135 Bool_t addBgr=kFALSE) const; // get unfolding result folded back
136 TH1 *GetBackground(const char *histogramName,const char *bgrSource=nullptr,
137 const char *histogramTitle=nullptr,
138 const char *distributionName=nullptr,
139 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE,Int_t includeError=3) const; // get background source
140 TH1 *GetInput(const char *histogramName,const char *histogramTitle=nullptr,
141 const char *distributionName=nullptr,
142 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE) const; // get unfolding input
143 TH1 *GetDeltaSysSource(const char *source,
144 const char *histogramName,
145 const char *histogramTitle=nullptr,
146 const char *distributionName=nullptr,
147 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE); // get systematic shifts from one systematic source
148 TH1 *GetDeltaSysBackgroundScale(const char *bgrSource,
149 const char *histogramName,
150 const char *histogramTitle=nullptr,
151 const char *distributionName=nullptr,
152 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE); // get correlated uncertainty induced by the scale uncertainty of a background source
153 TH1 *GetDeltaSysTau(const char *histogramName,
154 const char *histogramTitle=nullptr,
155 const char *distributionName=nullptr,
156 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE); // get correlated uncertainty from varying tau
157 TH2 *GetEmatrixSysUncorr(const char *histogramName,
158 const char *histogramTitle=nullptr,
159 const char *distributionName=nullptr,
160 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE); // get error matrix contribution from uncorrelated errors on the matrix A
161 TH2 *GetEmatrixSysBackgroundUncorr(const char *bgrSource,
162 const char *histogramName,
163 const char *histogramTitle=nullptr,
164 const char *distributionName=nullptr,
165 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE); // get error matrix from uncorrelated error of one background source
166 TH2 *GetEmatrixInput(const char *histogramName,
167 const char *histogramTitle=nullptr,
168 const char *distributionName=nullptr,
169 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE); // get error contribution from input vector
170 TH2 *GetEmatrixTotal(const char *histogramName,
171 const char *histogramTitle=nullptr,
172 const char *distributionName=nullptr,
173 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE); // get total error including systematic,statistical,background,tau errors
174 TH1 *GetRhoIstatbgr(const char *histogramName,const char *histogramTitle=nullptr,
175 const char *distributionName=nullptr,
176 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE,
177 TH2 **ematInv=nullptr); // get global correlation coefficients, stat+bgr errors only (from TUnfold)
178 TH1 *GetRhoItotal(const char *histogramName,const char *histogramTitle=nullptr,
179 const char *distributionName=nullptr,
180 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE,
181 TH2 **ematInv=nullptr); // get global correlation coefficients, including systematic errors (from TUnfoldSys)
182 TH2 *GetRhoIJtotal(const char *histogramName,
183 const char *histogramTitle=nullptr,
184 const char *distributionName=nullptr,
185 const char *projectionMode=nullptr,Bool_t useAxisBinning=kTRUE); // get correlation coefficients
186 TH2 *GetL(const char *histogramName,
187 const char *histogramTitle=nullptr,
188 Bool_t useAxisBinning=kTRUE); // get regularisation matrix
189 TH1 *GetLxMinusBias(const char *histogramName,const char *histogramTitle=nullptr); // get vector L(x-bias) of regularisation conditions
190
191 TH2 *GetProbabilityMatrix(const char *histogramName,
192 const char *histogramTitle=nullptr,Bool_t useAxisBinning=kTRUE) const; // get matrix of probabilities
193
194 const TUnfoldBinning *GetInputBinning(const char *distributionName=nullptr) const; // find binning scheme for input bins
195 const TUnfoldBinning *GetOutputBinning(const char *distributionName=nullptr) const; // find binning scheme for output bins
196 /// return binning scheme for regularisation conditions (matrix L)
198
199 ClassDefOverride(TUnfoldDensity, TUnfold_CLASS_VERSION) //Unfolding with density regularisation
200};
201
202#endif
bool Bool_t
Definition RtypesCore.h:63
int Int_t
Definition RtypesCore.h:45
constexpr Bool_t kFALSE
Definition RtypesCore.h:101
double Double_t
Definition RtypesCore.h:59
constexpr Bool_t kTRUE
Definition RtypesCore.h:100
#define ClassDefOverride(name, id)
Definition Rtypes.h:341
Option_t Option_t TPoint TPoint const char mode
#define TUnfold_CLASS_VERSION
Definition TUnfold.h:100
A TGraph is an object made of two arrays X and Y with npoints each.
Definition TGraph.h:41
TH1 is the base class of all histogram classes in ROOT.
Definition TH1.h:58
Service class for 2-D histogram classes.
Definition TH2.h:30
Base class for spline implementation containing the Draw/Paint methods.
Definition TSpline.h:31
Basic string class.
Definition TString.h:139
Binning schemes for use with the unfolding algorithm TUnfoldDensity.
An algorithm to unfold distributions from detector to truth level.
void RegularizeOneDistribution(const TUnfoldBinning *binning, ERegMode regmode, EDensityMode densityMode, const char *axisSteering)
Regularize the distribution of the given node.
EScanTauMode
scan mode for correlation scan
@ kEScanTauRhoAvg
average global correlation coefficient (from TUnfold::GetRhoI())
@ kEScanTauRhoMax
maximum global correlation coefficient (from TUnfold::GetRhoI())
@ kEScanTauRhoSquareAvgSys
average global correlation coefficient squared (from TUnfoldSys::GetRhoItotal())
@ kEScanTauRhoMaxSys
maximum global correlation coefficient (from TUnfoldSys::GetRhoItotal())
@ kEScanTauRhoSquareAvg
average global correlation coefficient squared (from TUnfold::GetRhoI())
@ kEScanTauRhoAvgSys
average global correlation coefficient (from TUnfoldSys::GetRhoItotal())
TH1 * GetRhoItotal(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE, TH2 **ematInv=nullptr)
Retrieve global correlation coefficients including all uncertainty sources.
TH2 * GetEmatrixSysUncorr(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
Retrieve covariance contribution from uncorrelated (statistical) uncertainties of the response matrix...
Double_t GetDensityFactor(EDensityMode densityMode, Int_t iBin) const
Density correction factor for a given bin.
TH2 * GetRhoIJtotal(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
Retrieve correlation coefficients, including all uncertainties.
TString GetOutputBinName(Int_t iBinX) const override
Get bin name of an output bin.
const TUnfoldBinning * fConstOutputBins
binning scheme for the output (truth level)
const TUnfoldBinning * GetOutputBinning(const char *distributionName=nullptr) const
Locate a binning node for the unfolded (truth level) quantities.
TUnfoldBinning * GetLBinning(void) const
return binning scheme for regularisation conditions (matrix L)
TH2 * GetEmatrixInput(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
Get covariance contribution from the input uncertainties (data statistical uncertainties).
TUnfoldBinning * fRegularisationConditions
binning scheme for the regularisation conditions
TH2 * GetL(const char *histogramName, const char *histogramTitle=nullptr, Bool_t useAxisBinning=kTRUE)
Access matrix of regularisation conditions in a new histogram.
TUnfoldBinning * fOwnedOutputBins
pointer to output binning scheme if owned by this class
TH2 * GetEmatrixTotal(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
Get covariance matrix including all contributions.
TUnfoldBinning * fOwnedInputBins
pointer to input binning scheme if owned by this class
TH1 * GetDeltaSysBackgroundScale(const char *bgrSource, const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
Retrieve systematic 1-sigma shift corresponding to a background scale uncertainty.
void RegularizeDistribution(ERegMode regmode, EDensityMode densityMode, const char *distribution, const char *axisSteering)
Set up regularisation conditions.
TH2 * GetProbabilityMatrix(const char *histogramName, const char *histogramTitle=nullptr, Bool_t useAxisBinning=kTRUE) const
Get matrix of probabilities in a new histogram.
TH1 * GetOutput(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE) const
retrieve unfolding result as a new histogram
TH1 * GetFoldedOutput(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE, Bool_t addBgr=kFALSE) const
Retrieve unfolding result folded back as a new histogram.
const TUnfoldBinning * GetInputBinning(const char *distributionName=nullptr) const
Locate a binning node for the input (measured) quantities.
TH1 * GetInput(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE) const
Retrieve input distribution in a new histogram.
TH1 * GetRhoIstatbgr(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE, TH2 **ematInv=nullptr)
Retrieve global correlation coefficients including input (statistical) and background uncertainties.
TH1 * GetDeltaSysSource(const char *source, const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
Retrieve a correlated systematic 1-sigma shift.
TH1 * GetDeltaSysTau(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
Retrieve 1-sigma shift corresponding to the previously specified uncertainty on tau.
TH2 * GetEmatrixSysBackgroundUncorr(const char *bgrSource, const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
Retrieve covariance contribution from uncorrelated background uncertainties.
const TUnfoldBinning * fConstInputBins
binning scheme for the input (detector level)
TH1 * GetLxMinusBias(const char *histogramName, const char *histogramTitle=nullptr)
Get regularisation conditions multiplied by result vector minus bias L(x-biasScale*biasVector).
void RegularizeDistributionRecursive(const TUnfoldBinning *binning, ERegMode regmode, EDensityMode densityMode, const char *distribution, const char *axisSteering)
Recursively add regularisation conditions for this node and its children.
TUnfoldDensity(void)
Only for use by root streamer or derived classes.
TH1 * GetBias(const char *histogramName, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE) const
Retrieve bias vector as a new histogram.
virtual Int_t ScanTau(Int_t nPoint, Double_t tauMin, Double_t tauMax, TSpline **scanResult, Int_t mode=kEScanTauRhoAvg, const char *distribution=nullptr, const char *projectionMode=nullptr, TGraph **lCurvePlot=nullptr, TSpline **logTauXPlot=nullptr, TSpline **logTauYPlot=nullptr)
Scan a function wrt tau and determine the minimum.
virtual Double_t GetScanVariable(Int_t mode, const char *distribution, const char *projectionMode)
Calculate the function for ScanTau().
EDensityMode
choice of regularisation scale factors to cinstruct the matrix L
@ kDensityModeUser
scale factors from user function in TUnfoldBinning
@ kDensityModeNone
no scale factors, matrix L is similar to unity matrix
@ kDensityModeBinWidthAndUser
scale factors from multidimensional bin width and user function
@ kDensityModeBinWidth
scale factors from multidimensional bin width
TH1 * GetBackground(const char *histogramName, const char *bgrSource=nullptr, const char *histogramTitle=nullptr, const char *distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE, Int_t includeError=3) const
Retrieve a background source in a new histogram.
An algorithm to unfold distributions from detector to truth level, with background subtraction and pr...
Definition TUnfoldSys.h:55
EConstraint
type of extra constraint
Definition TUnfold.h:109
@ kEConstraintArea
enforce preservation of the area
Definition TUnfold.h:115
ERegMode
choice of regularisation scheme
Definition TUnfold.h:119
@ kRegModeCurvature
regularize the 2nd derivative of the output distribution
Definition TUnfold.h:131
EHistMap
arrangement of axes for the response matrix (TH2 histogram)
Definition TUnfold.h:139