Logo ROOT   6.14/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 
48 class 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
63  enum EDensityMode {
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,
90  ERegMode regmode = kRegModeCurvature,
91  EConstraint constraint=kEConstraintArea,
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
An algorithm to unfold distributions from detector to truth level.
const TUnfoldBinning * fConstOutputBins
binning scheme for the output (truth level)
virtual ~ TUnfoldDensity(void)
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 * 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.
Base class for spline implementation containing the Draw/Paint methods.
Definition: TSpline.h:20
An algorithm to unfold distributions from detector to truth level, with background subtraction and pr...
Definition: TUnfoldSys.h:55
Basic string class.
Definition: TString.h:131
int Int_t
Definition: RtypesCore.h:41
bool Bool_t
Definition: RtypesCore.h:59
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...
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.
TUnfoldDensity(void)
Only for use by root streamer or derived classes.
EDensityMode
choice of regularisation scale factors to cinstruct the matrix L
TUnfoldBinning * fOwnedOutputBins
pointer to output binning scheme if owned by this class
TH2 * GetL(const char *histogramName, const char *histogramTitle=0, Bool_t useAxisBinning=kTRUE)
Access matrix of regularisation conditions in a new histogram.
void RegularizeDistribution(ERegMode regmode, EDensityMode densityMode, const char *distribution, const char *axisSteering)
Set up regularisation conditions.
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.
average global correlation coefficient squared (from TUnfold::GetRhoI())
EScanTauMode
scan mode for correlation scan
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.
#define ClassDef(name, id)
Definition: Rtypes.h:320
scale factors from multidimensional bin width
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.
EHistMap
arrangement of axes for the response matrix (TH2 histogram)
Definition: TUnfold.h:140
EConstraint
type of extra constraint
Definition: TUnfold.h:110
average global correlation coefficient (from TUnfold::GetRhoI())
void RegularizeOneDistribution(const TUnfoldBinning *binning, ERegMode regmode, EDensityMode densityMode, const char *axisSteering)
Regularize the distribution of the given node.
maximum global correlation coefficient (from TUnfold::GetRhoI())
maximum global correlation coefficient (from TUnfoldSys::GetRhoItotal())
ERegMode
choice of regularisation scheme
Definition: TUnfold.h:120
scale factors from user function in TUnfoldBinning
TUnfoldBinning * fRegularisationConditions
binning scheme for the regularisation conditions
TUnfoldBinning * GetLBinning(void) const
return binning scheme for regularisation conditions (matrix L)
scale factors from multidimensional bin width and user function
Service class for 2-Dim histogram classes.
Definition: TH2.h:30
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.
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 * GetInputBinning(const char *distributionName=0) const
Locate a binning node for the input (measured) quantities.
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.
average global correlation coefficient squared (from TUnfoldSys::GetRhoItotal())
enforce preservation of the area
Definition: TUnfold.h:116
const Bool_t kFALSE
Definition: RtypesCore.h:88
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...
Binning schemes for use with the unfolding algorithm TUnfoldDensity.
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.
average global correlation coefficient (from TUnfoldSys::GetRhoItotal())
virtual TString GetOutputBinName(Int_t iBinX) const
Get bin name of an output bin.
double Double_t
Definition: RtypesCore.h:55
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
The TH1 histogram class.
Definition: TH1.h:56
const TUnfoldBinning * fConstInputBins
binning scheme for the input (detector level)
#define TUnfold_CLASS_VERSION
Definition: TUnfold.h:101
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.
TUnfoldBinning * fOwnedInputBins
pointer to input binning scheme if owned by this class
A Graph is a graphics object made of two arrays X and Y with npoints each.
Definition: TGraph.h:41
virtual Double_t GetScanVariable(Int_t mode, const char *distribution, const char *projectionMode)
Calculate the function for ScanTau().
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 * 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.
no scale factors, matrix L is similar to unity matrix
regularize the 2nd derivative of the output distribution
Definition: TUnfold.h:132
const Bool_t kTRUE
Definition: RtypesCore.h:87
TH2 * GetProbabilityMatrix(const char *histogramName, const char *histogramTitle=0, Bool_t useAxisBinning=kTRUE) const
Get matrix of probabilities in a new histogram.
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.