Logo ROOT   6.18/05
Reference Guide
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 virtual TString GetOutputBinName(Int_t iBinX) const; // 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=0,
94 const TUnfoldBinning *inputBins=0,
95 const char *regularisationDistribution=0,
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 virtual ~ TUnfoldDensity(void); // 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=0,const char *projectionMode=0,TGraph **lCurvePlot=0,TSpline **logTauXPlot=0,TSpline **logTauYPlot=0); // 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=0,const char *distributionName=0,
127 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE) const; // get unfolding result
128 TH1 *GetBias(const char *histogramName,
129 const char *histogramTitle=0,const char *distributionName=0,
130 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE) const; // get bias
131 TH1 *GetFoldedOutput(const char *histogramName,
132 const char *histogramTitle=0,
133 const char *distributionName=0,
134 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE,
135 Bool_t addBgr=kFALSE) const; // get unfolding result folded back
136 TH1 *GetBackground(const char *histogramName,const char *bgrSource=0,
137 const char *histogramTitle=0,
138 const char *distributionName=0,
139 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE,Int_t includeError=3) const; // get background source
140 TH1 *GetInput(const char *histogramName,const char *histogramTitle=0,
141 const char *distributionName=0,
142 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE) const; // get unfolding input
143 TH1 *GetDeltaSysSource(const char *source,
144 const char *histogramName,
145 const char *histogramTitle=0,
146 const char *distributionName=0,
147 const char *projectionMode=0,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=0,
151 const char *distributionName=0,
152 const char *projectionMode=0,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=0,
155 const char *distributionName=0,
156 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE); // get correlated uncertainty from varying tau
157 TH2 *GetEmatrixSysUncorr(const char *histogramName,
158 const char *histogramTitle=0,
159 const char *distributionName=0,
160 const char *projectionMode=0,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=0,
164 const char *distributionName=0,
165 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE); // get error matrix from uncorrelated error of one background source
166 TH2 *GetEmatrixInput(const char *histogramName,
167 const char *histogramTitle=0,
168 const char *distributionName=0,
169 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE); // get error contribution from input vector
170 TH2 *GetEmatrixTotal(const char *histogramName,
171 const char *histogramTitle=0,
172 const char *distributionName=0,
173 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE); // get total error including systematic,statistical,background,tau errors
174 TH1 *GetRhoIstatbgr(const char *histogramName,const char *histogramTitle=0,
175 const char *distributionName=0,
176 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE,
177 TH2 **ematInv=0); // get global correlation coefficients, stat+bgr errors only (from TUnfold)
178 TH1 *GetRhoItotal(const char *histogramName,const char *histogramTitle=0,
179 const char *distributionName=0,
180 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE,
181 TH2 **ematInv=0); // get global correlation coefficients, including systematic errors (from TUnfoldSys)
182 TH2 *GetRhoIJtotal(const char *histogramName,
183 const char *histogramTitle=0,
184 const char *distributionName=0,
185 const char *projectionMode=0,Bool_t useAxisBinning=kTRUE); // get correlation coefficients
186 TH2 *GetL(const char *histogramName,
187 const char *histogramTitle=0,
188 Bool_t useAxisBinning=kTRUE); // get regularisation matrix
189 TH1 *GetLxMinusBias(const char *histogramName,const char *histogramTitle=0); // get vector L(x-bias) of regularisation conditions
190
191 TH2 *GetProbabilityMatrix(const char *histogramName,
192 const char *histogramTitle=0,Bool_t useAxisBinning=kTRUE) const; // get matrix of probabilities
193
194 const TUnfoldBinning *GetInputBinning(const char *distributionName=0) const; // find binning scheme for input bins
195 const TUnfoldBinning *GetOutputBinning(const char *distributionName=0) const; // find binning scheme for output bins
196 /// return binning scheme for regularisation conditions (matrix L)
198 ClassDef(TUnfoldDensity, TUnfold_CLASS_VERSION) //Unfolding with density regularisation
199};
200
201#endif
int Int_t
Definition: RtypesCore.h:41
const Bool_t kFALSE
Definition: RtypesCore.h:88
bool Bool_t
Definition: RtypesCore.h:59
double Double_t
Definition: RtypesCore.h:55
const Bool_t kTRUE
Definition: RtypesCore.h:87
#define ClassDef(name, id)
Definition: Rtypes.h:326
#define TUnfold_CLASS_VERSION
Definition: TUnfold.h:101
A Graph is a graphics object made of two arrays X and Y with npoints each.
Definition: TGraph.h:41
The TH1 histogram class.
Definition: TH1.h:56
Service class for 2-Dim histogram classes.
Definition: TH2.h:30
Base class for spline implementation containing the Draw/Paint methods.
Definition: TSpline.h:22
Basic string class.
Definition: TString.h:131
Binning schemes for use with the unfolding algorithm TUnfoldDensity.
An algorithm to unfold distributions from detector to truth level.
TH2 * GetRhoIJtotal(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
Retrieve correlation coefficients, including all uncertainties.
void RegularizeOneDistribution(const TUnfoldBinning *binning, ERegMode regmode, EDensityMode densityMode, const char *axisSteering)
Regularize the distribution of the given node.
TH1 * GetRhoItotal(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE, TH2 **ematInv=0)
Retrieve global correlation coefficients including all uncertainty sources.
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())
TH2 * GetL(const char *histogramName, const char *histogramTitle=0, Bool_t useAxisBinning=kTRUE)
Access matrix of regularisation conditions in a new histogram.
Double_t GetDensityFactor(EDensityMode densityMode, Int_t iBin) const
Density correction factor for a given bin.
TH2 * GetEmatrixInput(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
Get covariance contribution from the input uncertainties (data statistical uncertainties).
TH1 * GetDeltaSysTau(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
Retrieve 1-sigma shift corresponding to the previously specified uncertainty on tau.
TH2 * GetEmatrixSysUncorr(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
Retrieve covariance contribution from uncorrelated (statistical) uncertainties of the response matrix...
const TUnfoldBinning * fConstOutputBins
binning scheme for the output (truth level)
TUnfoldBinning * GetLBinning(void) const
return binning scheme for regularisation conditions (matrix L)
virtual TString GetOutputBinName(Int_t iBinX) const
Get bin name of an output bin.
TUnfoldBinning * fRegularisationConditions
binning scheme for the regularisation conditions
TH1 * GetBackground(const char *histogramName, const char *bgrSource=0, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE, Int_t includeError=3) const
Retrieve a background source in a new histogram.
TH2 * GetProbabilityMatrix(const char *histogramName, const char *histogramTitle=0, Bool_t useAxisBinning=kTRUE) const
Get matrix of probabilities in a new histogram.
TH1 * GetDeltaSysBackgroundScale(const char *bgrSource, const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
Retrieve systematic 1-sigma shift corresponding to a background scale uncertainty.
TH1 * GetFoldedOutput(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE, Bool_t addBgr=kFALSE) const
Retrieve unfolding result folded back as a new histogram.
TUnfoldBinning * fOwnedOutputBins
pointer to output binning scheme if owned by this class
TUnfoldBinning * fOwnedInputBins
pointer to input binning scheme if owned by this class
void RegularizeDistribution(ERegMode regmode, EDensityMode densityMode, const char *distribution, const char *axisSteering)
Set up regularisation conditions.
TH1 * GetBias(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE) const
Retrieve bias vector as a new histogram.
TH1 * GetLxMinusBias(const char *histogramName, const char *histogramTitle=0)
Get regularisation conditions multiplied by result vector minus bias L(x-biasScale*biasVector).
TH2 * GetEmatrixTotal(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
Get covariance matrix including all contributions.
const TUnfoldBinning * GetOutputBinning(const char *distributionName=0) const
Locate a binning node for the unfolded (truth level) quantities.
TH1 * GetDeltaSysSource(const char *source, const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
Retrieve a correlated systematic 1-sigma shift.
TH2 * GetEmatrixSysBackgroundUncorr(const char *bgrSource, const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
Retrieve covariance contribution from uncorrelated background uncertainties.
TH1 * GetOutput(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE) const
retrieve unfolding result as a new histogram
TH1 * GetInput(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE) const
Retrieve input distribution in a new histogram.
const TUnfoldBinning * fConstInputBins
binning scheme for the input (detector level)
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.
virtual Int_t ScanTau(Int_t nPoint, Double_t tauMin, Double_t tauMax, TSpline **scanResult, Int_t mode=kEScanTauRhoAvg, const char *distribution=0, const char *projectionMode=0, TGraph **lCurvePlot=0, TSpline **logTauXPlot=0, TSpline **logTauYPlot=0)
Scan a function wrt tau and determine the minimum.
TH1 * GetRhoIstatbgr(const char *histogramName, const char *histogramTitle=0, const char *distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE, TH2 **ematInv=0)
Retrieve global correlation coefficients including input (statistical) and background uncertainties.
const TUnfoldBinning * GetInputBinning(const char *distributionName=0) const
Locate a binning node for the input (measured) quantities.
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
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:110
@ kEConstraintArea
enforce preservation of the area
Definition: TUnfold.h:116
ERegMode
choice of regularisation scheme
Definition: TUnfold.h:120
@ kRegModeCurvature
regularize the 2nd derivative of the output distribution
Definition: TUnfold.h:132
EHistMap
arrangement of axes for the response matrix (TH2 histogram)
Definition: TUnfold.h:140