Logo ROOT   6.14/05
Reference Guide
TUnfoldSys.h
Go to the documentation of this file.
1 // Author: Stefan Schmitt
2 // DESY, 23/01/09
3 
4 // Version 17.5, bug fixes in TUnfold fix problem with 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, add methods to find back systematic and background sources
10 // Version 17.1, bug fix with background uncertainty
11 // Version 17.0, possibility to specify an error matrix with SetInput
12 // Version 16.2, bug-fix with the calculation of background errors
13 // Version 16.1, parallel to changes in TUnfold
14 // Version 16.0, parallel to changes in TUnfold
15 // Version 15, fix bugs with uncorr. uncertainties, add backgnd subtraction
16 // Version 14, with changes in TUnfoldSys.cxx
17 // Version 13, support for systematic errors
18 
19 #ifndef ROOT_TUnfoldSys
20 #define ROOT_TUnfoldSys
21 
22 //////////////////////////////////////////////////////////////////////////
23 // //
24 // //
25 // TUnfoldSys, an extension of the class TUnfold to correct for //
26 // migration effects. It provides methods for background subtraction //
27 // and propagation of systematic uncertainties //
28 // //
29 // Citation: S.Schmitt, JINST 7 (2012) T10003 [arXiv:1205.6201] //
30 // //
31 //////////////////////////////////////////////////////////////////////////
32 
33 /*
34  This file is part of TUnfold.
35 
36  TUnfold is free software: you can redistribute it and/or modify
37  it under the terms of the GNU General Public License as published by
38  the Free Software Foundation, either version 3 of the License, or
39  (at your option) any later version.
40 
41  TUnfold is distributed in the hope that it will be useful,
42  but WITHOUT ANY WARRANTY; without even the implied warranty of
43  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
44  GNU General Public License for more details.
45 
46  You should have received a copy of the GNU General Public License
47  along with TUnfold. If not, see <http://www.gnu.org/licenses/>.
48 */
49 
50 #include <TMap.h>
51 #include <TSortedList.h>
52 #include "TUnfold.h"
53 
54 
55 class TUnfoldSys : public TUnfold {
56  private:
57  void InitTUnfoldSys(void); // initialize all data members
58  protected:
59  /// Input: normalized errors from input matrix
61  /// Input: normalized column err.sq. (inp.matr.)
63  /// Input: underflow/overflow bins
65  /// Input: correlated errors
67  /// Input: size of background sources
69  /// Input: uncorr error squared from bgr sources
71  /// Input: background sources correlated error
73  /// Input: error on tau
75  /// Input: fY prior to bgr subtraction
77  /// Input: error on fY prior to bgr subtraction
79  /// Result: syst.error from fDA2 on fX
81  /// Result: syst.error from fDA2 on fAx
83  /// Result: syst.shift from fSysIn on fX
85  /// Result: syst.shift from fSysIn on fAx
87  /// Result: systematic shift from tau
89  protected:
90  virtual void ClearResults(void); // clear all results
91  virtual void PrepareSysError(void); // common calculations for syst.errors
92  virtual TMatrixDSparse *PrepareUncorrEmat(const TMatrixDSparse *m1,const TMatrixDSparse *m2); // calculate uncorrelated error matrix
93  virtual TMatrixDSparse *PrepareCorrEmat(const TMatrixDSparse *m1,const TMatrixDSparse *m2,const TMatrixDSparse *dsys); // calculate correlated error matrix
94  void ScaleColumnsByVector(TMatrixDSparse *m,const TMatrixTBase<Double_t> *v) const; // scale columns of m by the corresponding rows of v
95  void VectorMapToHist(TH1 *hist_delta,const TMatrixDSparse *delta,const Int_t *binMap); // map and sum vector delta, save in hist_delta
96  void GetEmatrixFromVyy(const TMatrixDSparse *vyy,TH2 *ematrix,const Int_t *binMap,Bool_t clearEmat); // propagate error matrix vyy to the result
97  void DoBackgroundSubtraction(void);
100  public:
101  /// type of matrix specified with AddSysError()
102  enum ESysErrMode {
103  /// matrix is an alternative to the default matrix, the errors are the difference to the original matrix
105  /// matrix gives the absolute shifts
107  /// matrix gives the relative shifts
109  };
110  TUnfoldSys(const TH2 *hist_A, EHistMap histmap, ERegMode regmode = kRegModeSize,
111  EConstraint constraint=kEConstraintArea); // constructor
112  TUnfoldSys(void); // for derived classes
113  virtual ~ TUnfoldSys(void); // delete data members
114  void AddSysError(const TH2 *sysError,const char *name, EHistMap histmap,
115  ESysErrMode mode); // add a systematic error source
116  void SubtractBackground(const TH1 *hist_bgr,const char *name,
117  Double_t scale=1.0,
118  Double_t scale_error=0.0); // subtract background prior to unfolding
119  virtual Int_t SetInput(const TH1 *hist_y,Double_t scaleBias=0.0,Double_t oneOverZeroError=0.0,const TH2 *hist_vyy=0,const TH2 *hist_vyy_inv=0); // define input consistently in case of background subtraction
120  void SetTauError(Double_t delta_tau); // set uncertainty on tau
121  TSortedList *GetBgrSources(void) const; // get names of background sources
122  TSortedList *GetSysSources(void) const; // get names of systematic sources
123  void GetBackground(TH1 *bgr,const char *bgrSource=0,const Int_t *binMap=0,Int_t includeError=3,Bool_t clearHist=kTRUE) const; // get background as histogram
124  void GetEmatrixSysBackgroundUncorr(TH2 *ematrix,const char *source,
125  const Int_t *binMap=0,Bool_t clearEmat=kTRUE); // get error matrix from uncorrelated error of one background source
126  void GetEmatrixSysBackgroundScale(TH2 *ematrix,const char *source,
127  const Int_t *binMap=0,Bool_t clearEmat=kTRUE); // get error matrix from the scale error of one background source
128  Bool_t GetDeltaSysBackgroundScale(TH1 *delta,const char *source,
129  const Int_t *binMap=0); // get correlated uncertainty induced by the scale uncertainty of a background source
130  void GetEmatrixSysUncorr(TH2 *ematrix,const Int_t *binMap=0,Bool_t clearEmat=kTRUE); // get error matrix contribution from uncorrelated errors on the matrix A
131  void GetEmatrixSysSource(TH2 *ematrix,const char *source,
132  const Int_t *binMap=0,Bool_t clearEmat=kTRUE); // get error matrix from one systematic source
133  Bool_t GetDeltaSysSource(TH1 *hist_delta,const char *source,
134  const Int_t *binMap=0); // get systematic shifts from one systematic source
135  void GetEmatrixSysTau(TH2 *ematrix,
136  const Int_t *binMap=0,Bool_t clearEmat=kTRUE); // get error matrix from tau variation
137  Bool_t GetDeltaSysTau(TH1 *delta,const Int_t *binMap=0); // get correlated uncertainty from varying tau
138  void GetEmatrixInput(TH2 *ematrix,const Int_t *binMap=0,Bool_t clearEmat=kTRUE); // get error contribution from input vector
139  void GetEmatrixTotal(TH2 *ematrix,const Int_t *binMap=0); // get total error including systematic,statistical,background,tau errors
140  void GetRhoItotal(TH1 *rhoi,const Int_t *binMap=0,TH2 *invEmat=0); // get global correlation coefficients including systematic,statistical,background,tau errors
141  Double_t GetChi2Sys(void); // get total chi**2 including all systematic errors
142  ClassDef(TUnfoldSys, TUnfold_CLASS_VERSION) //Unfolding with support for systematic error propagation
143 };
144 
145 #endif
void InitTUnfoldSys(void)
Initialize pointers and TMaps.
Definition: TUnfoldSys.cxx:625
TMatrixDSparse * fEmatUncorrX
Result: syst.error from fDA2 on fX.
Definition: TUnfoldSys.h:80
auto * m
Definition: textangle.C:8
virtual void ClearResults(void)
Clear all data members which depend on the unfolding results.
Definition: TUnfoldSys.cxx:667
Double_t GetChi2Sys(void)
Calculate total chi**2 including all systematic errors.
void GetEmatrixInput(TH2 *ematrix, const Int_t *binMap=0, Bool_t clearEmat=kTRUE)
Covariance matrix contribution from input measurement uncertainties.
TMap * fBgrErrScaleIn
Input: background sources correlated error.
Definition: TUnfoldSys.h:72
Bool_t GetDeltaSysSource(TH1 *hist_delta, const char *source, const Int_t *binMap=0)
Correlated one-sigma shifts correspinding to a given systematic uncertainty.
TMap * fBgrIn
Input: size of background sources.
Definition: TUnfoldSys.h:68
void VectorMapToHist(TH1 *hist_delta, const TMatrixDSparse *delta, const Int_t *binMap)
Map delta to hist_delta, possibly summing up bins.
virtual TMatrixDSparse * PrepareCorrEmat(const TMatrixDSparse *m1, const TMatrixDSparse *m2, const TMatrixDSparse *dsys)
Propagate correlated systematic shift to an output vector.
TMatrixDSparse * fDAinRelSq
Input: normalized errors from input matrix.
Definition: TUnfoldSys.h:60
virtual void PrepareSysError(void)
Matrix calculations required to propagate systematic errors.
Definition: TUnfoldSys.cxx:683
TSortedList * GetSysSources(void) const
Get a new list of all systematic uuncertainty sources.
An algorithm to unfold distributions from detector to truth level, with background subtraction and pr...
Definition: TUnfoldSys.h:55
int Int_t
Definition: RtypesCore.h:41
bool Bool_t
Definition: RtypesCore.h:59
void SetTauError(Double_t delta_tau)
Specify an uncertainty on tau.
Double_t fDtau
Input: error on tau.
Definition: TUnfoldSys.h:74
virtual Int_t SetInput(const TH1 *hist_y, Double_t scaleBias=0.0, Double_t oneOverZeroError=0.0, const TH2 *hist_vyy=0, const TH2 *hist_vyy_inv=0)
Define the input data for subsequent calls to DoUnfold(Double_t).
Definition: TUnfoldSys.cxx:465
TSortedList * GetBgrSources(void) const
Get a new list of all background sources.
void GetEmatrixSysBackgroundUncorr(TH2 *ematrix, const char *source, const Int_t *binMap=0, Bool_t clearEmat=kTRUE)
Covariance contribution from background uncorrelated uncertainty.
TMap * fSysIn
Input: correlated errors.
Definition: TUnfoldSys.h:66
#define ClassDef(name, id)
Definition: Rtypes.h:320
void ScaleColumnsByVector(TMatrixDSparse *m, const TMatrixTBase< Double_t > *v) const
Scale columns of a matrix by the corresponding rows of a vector.
void GetEmatrixSysUncorr(TH2 *ematrix, const Int_t *binMap=0, Bool_t clearEmat=kTRUE)
Covariance contribution from uncorrelated uncertainties of the response matrix.
Definition: TUnfoldSys.cxx:787
regularise the amplitude of the output distribution
Definition: TUnfold.h:126
EHistMap
arrangement of axes for the response matrix (TH2 histogram)
Definition: TUnfold.h:140
EConstraint
type of extra constraint
Definition: TUnfold.h:110
TMatrixDSparse * fDeltaSysTau
Result: systematic shift from tau.
Definition: TUnfoldSys.h:88
void GetEmatrixSysBackgroundScale(TH2 *ematrix, const char *source, const Int_t *binMap=0, Bool_t clearEmat=kTRUE)
Covariance contribution from background normalisation uncertainty.
A sorted doubly linked list.
Definition: TSortedList.h:28
matrix gives the absolute shifts
Definition: TUnfoldSys.h:106
void DoBackgroundSubtraction(void)
Perform background subtraction.
Definition: TUnfoldSys.cxx:334
TMatrixDSparse * GetSummedErrorMatrixXX(void)
Determine total error matrix on the vector x.
TMatrixDSparse * GetSummedErrorMatrixYY(void)
Determine total error matrix on the vector Ax.
ERegMode
choice of regularisation scheme
Definition: TUnfold.h:120
TMap * fBgrErrUncorrInSq
Input: uncorr error squared from bgr sources.
Definition: TUnfoldSys.h:70
void GetEmatrixSysSource(TH2 *ematrix, const char *source, const Int_t *binMap=0, Bool_t clearEmat=kTRUE)
Covariance contribution from a systematic variation of the response matrix.
virtual ~ TUnfoldSys(void)
TMap * fDeltaCorrX
Result: syst.shift from fSysIn on fX.
Definition: TUnfoldSys.h:84
TMap * fDeltaCorrAx
Result: syst.shift from fSysIn on fAx.
Definition: TUnfoldSys.h:86
Service class for 2-Dim histogram classes.
Definition: TH2.h:30
SVector< double, 2 > v
Definition: Dict.h:5
virtual TMatrixDSparse * PrepareUncorrEmat(const TMatrixDSparse *m1, const TMatrixDSparse *m2)
Propagate uncorrelated systematic errors to a covariance matrix.
Definition: TUnfoldSys.cxx:894
TMatrixTSparse.
void GetEmatrixTotal(TH2 *ematrix, const Int_t *binMap=0)
Get total error matrix, summing up all contributions.
Bool_t GetDeltaSysTau(TH1 *delta, const Int_t *binMap=0)
Correlated one-sigma shifts from shifting tau.
static constexpr double m2
void GetBackground(TH1 *bgr, const char *bgrSource=0, const Int_t *binMap=0, Int_t includeError=3, Bool_t clearHist=kTRUE) const
Get background into a histogram.
Definition: TUnfoldSys.cxx:551
Linear Algebra Package.
enforce preservation of the area
Definition: TUnfold.h:116
void SubtractBackground(const TH1 *hist_bgr, const char *name, Double_t scale=1.0, Double_t scale_error=0.0)
Specify a source of background.
Definition: TUnfoldSys.cxx:504
TMatrixDSparse * fVyyData
Input: error on fY prior to bgr subtraction.
Definition: TUnfoldSys.h:78
void GetEmatrixSysTau(TH2 *ematrix, const Int_t *binMap=0, Bool_t clearEmat=kTRUE)
Covariance matrix contribution from error on regularisation parameter.
double Double_t
Definition: RtypesCore.h:55
TMatrixD * fDAinColRelSq
Input: normalized column err.sq. (inp.matr.)
Definition: TUnfoldSys.h:62
TMap implements an associative array of (key,value) pairs using a THashTable for efficient retrieval ...
Definition: TMap.h:40
TUnfoldSys(void)
Only for use by root streamer or derived classes.
Definition: TUnfoldSys.cxx:139
The TH1 histogram class.
Definition: TH1.h:56
TMatrixDSparse * fEmatUncorrAx
Result: syst.error from fDA2 on fAx.
Definition: TUnfoldSys.h:82
#define TUnfold_CLASS_VERSION
Definition: TUnfold.h:101
void AddSysError(const TH2 *sysError, const char *name, EHistMap histmap, ESysErrMode mode)
Specify a correlated systematic uncertainty.
Definition: TUnfoldSys.cxx:249
An algorithm to unfold distributions from detector to truth level.
Definition: TUnfold.h:104
matrix gives the relative shifts
Definition: TUnfoldSys.h:108
TMatrixD * fYData
Input: fY prior to bgr subtraction.
Definition: TUnfoldSys.h:76
void GetRhoItotal(TH1 *rhoi, const Int_t *binMap=0, TH2 *invEmat=0)
Get global correlatiocn coefficients, summing up all contributions.
void GetEmatrixFromVyy(const TMatrixDSparse *vyy, TH2 *ematrix, const Int_t *binMap, Bool_t clearEmat)
Propagate an error matrix on the input vector to the unfolding result.
const Bool_t kTRUE
Definition: RtypesCore.h:87
ESysErrMode
type of matrix specified with AddSysError()
Definition: TUnfoldSys.h:102
Bool_t GetDeltaSysBackgroundScale(TH1 *delta, const char *source, const Int_t *binMap=0)
Correlated one-sigma shifts from background normalisation uncertainty.
char name[80]
Definition: TGX11.cxx:109
matrix is an alternative to the default matrix, the errors are the difference to the original matrix ...
Definition: TUnfoldSys.h:104
TMatrixD * fAoutside
Input: underflow/overflow bins.
Definition: TUnfoldSys.h:64