class TUnfoldDensity: public TUnfoldSys

TUnfoldDensity : public TUnfoldSys : public TUnfold

TUnfold is used to decompose a measurement y into several sources x
given the measurement uncertainties and a matrix of migrations A

More details are described with the documentation of TUnfold.

For most applications, it is best to use TUnfoldDensity
instead of using TUnfoldSys or TUnfold

If you use this software, please consider the following citation
S.Schmitt, JINST 7 (2012) T10003 [arXiv:1205.6201]

More documentation and updates are available on
http://www.desy.de/~sschmitt

As compared to TUnfold, TUndolfDensity adds the following functionality
* background subtraction (see documentation of TUnfoldSys)
* error propagation (see documentation of TUnfoldSys)
* regularisation schemes respecting the bin widths
* support for complex, multidimensional input distributions

Complex binning schemes are imposed on the measurements y and
on the result vector x with the help of the class TUnfoldBinning
The components of x or y are part of multi-dimensional distributions.
The bin widths along the relevant directions in these distributions
are used to calculate bin densities (number of events divided by bin width)
or to calculate derivatives taking into account the proper distance of

Complex binning schemes

in literature on unfolding, the "standard" test case is a
one-dimensional distribution without underflow or overflow bins.
The migration matrix is almost diagonal.

This "standard" case is rarely realized for real problems.

Often one has to deal with multi-dimensional input distributions.
In addition, there are underflow and overflow bins
or other background bins, possibly determined with the help of auxillary
measurements

In TUnfoldDensity, such complex binning schemes are handled with the help
of the class TUnfoldBinning. For each vector there is a tree
structure. The tree nodes hold multi-dimensiopnal distributions

For example, the "measurement" tree could have two leaves, one for
the primary distribution and one for auxillary measurements

Similarly, the "truth" tree could have two leaves, one for the
signal and one for the background.

each of the leaves may then have a multi-dimensional distribution.

The class TUnfoldBinning takes care to map all bins of the
"measurement" to the one-dimensional vector y.
Similarly, the "truth" bins are mapped to the vector x.

Choice of the regularisation

In TUnfoldDensity, two methods are implemented to determine tau**2
(1)  ScanLcurve()  locate the tau where the L-curve plot has a "kink"
this function is implemented in the TUnfold class
(2)  ScanTau() finds the solution such that some variable
(e.g. global correlation coefficient) is minimized
this function is implemented in the TUnfoldDensity class,
such that the variable could be made depend on the binning scheme

The algorithm (1) does not work if the input data are too similar to the
MC prediction, that is unfolding with tau=0 gives a least-square sum
of zero. Typical no-go cases of the L-curve scan are:
(a) the number of measurements is too small (e.g. ny=nx)
(b) the input data have no statistical fluctuations
[identical MC events are used to fill the matrix of migrations
and the vector y]

The algorithm (2) only works if the variable does have a real minimum
as a function of tau.
If global correlations are minimized, the situation is as follows:
The matrix of migration typically introduces negative correlations.
The area constraint introduces some positive correlation.
Regularisation on the "size" introduces no correlation.
Regularisation on 1st or 2nd derivatives adds positive correlations.
For this reason, "size" regularisation does not work well with
the tau-scan: the higher tau, the smaller rho, but there is no minimum.
In contrast, the tau-scan is expected to work well with 1st or 2nd
derivative regularisation, because at some point the negative
correlations from migrations are approximately cancelled by the
positive correlations from the regularisation conditions.

whichever algorithm is used, the output has to be checked:
(1) The L-curve should have approximate L-shape
and the final choice of tau should not be at the very edge of the
scanned region
(2) The scan result should have a well-defined minimum and the
final choice of tau should sit right in the minimum

Function Members (Methods)

public:
protected:
 void TUnfold::AddMSparse(TMatrixDSparse* dest, Double_t f, const TMatrixDSparse* src) const Bool_t TUnfold::AddRegularisationCondition(Int_t nEle, const Int_t* indices, const Double_t* rowData) Bool_t TUnfold::AddRegularisationCondition(Int_t i0, Double_t f0, Int_t i1 = -1, Double_t f1 = 0., Int_t i2 = -1, Double_t f2 = 0.) void TUnfold::ClearHistogram(TH1* h, Double_t x = 0.) const virtual void TUnfoldSys::ClearResults() TMatrixDSparse* TUnfold::CreateSparseMatrix(Int_t nrow, Int_t ncol, Int_t nele, Int_t* row, Int_t* col, Double_t* data) const static void TUnfold::DeleteMatrix(TMatrixD** m) static void TUnfold::DeleteMatrix(TMatrixDSparse** m) void TUnfoldSys::DoBackgroundSubtraction() virtual void TObject::DoError(int level, const char* location, const char* fmt, va_list va) const virtual Double_t TUnfold::DoUnfold() void TUnfold::ErrorMatrixToHist(TH2* ematrix, const TMatrixDSparse* emat, const Int_t* binMap, Bool_t doClear) const const TMatrixDSparse* TUnfold::GetAx() const Int_t TUnfold::GetBinFromRow(int ix) const Double_t GetDensityFactor(TUnfoldDensity::EDensityMode densityMode, Int_t iBin) const const TMatrixDSparse* TUnfold::GetDXDAM(int i) const const TMatrixDSparse* TUnfold::GetDXDAZ(int i) const const TMatrixDSparse* TUnfold::GetDXDtauSquared() const const TMatrixDSparse* TUnfold::GetDXDY() const const TMatrixDSparse* TUnfold::GetE() const const TMatrixDSparse* TUnfold::GetEinv() const void TUnfoldSys::GetEmatrixFromVyy(const TMatrixDSparse* vyy, TH2* ematrix, const Int_t* binMap, Bool_t clearEmat) Int_t TUnfold::GetNx() const Int_t TUnfold::GetNy() const virtual TString GetOutputBinName(Int_t iBinX) const Double_t TUnfold::GetRhoIFromMatrix(TH1* rhoi, const TMatrixDSparse* eOrig, const Int_t* binMap, TH2* invEmat) const Int_t TUnfold::GetRowFromBin(int ix) const TMatrixDSparse* TUnfoldSys::GetSummedErrorMatrixXX() TMatrixDSparse* TUnfoldSys::GetSummedErrorMatrixYY() const TMatrixDSparse* TUnfold::GetVxx() const const TMatrixDSparse* TUnfold::GetVxxInv() const const TMatrixDSparse* TUnfold::GetVyyInv() const const TMatrixD* TUnfold::GetX() const TMatrixDSparse* TUnfold::InvertMSparseSymmPos(const TMatrixDSparse* A, Int_t* rank) const void TObject::MakeZombie() TMatrixDSparse* TUnfold::MultiplyMSparseM(const TMatrixDSparse* a, const TMatrixD* b) const TMatrixDSparse* TUnfold::MultiplyMSparseMSparse(const TMatrixDSparse* a, const TMatrixDSparse* b) const TMatrixDSparse* TUnfold::MultiplyMSparseMSparseTranspVector(const TMatrixDSparse* m1, const TMatrixDSparse* m2, const TMatrixTBase* v) const TMatrixDSparse* TUnfold::MultiplyMSparseTranspMSparse(const TMatrixDSparse* a, const TMatrixDSparse* b) const virtual TMatrixDSparse* TUnfoldSys::PrepareCorrEmat(const TMatrixDSparse* m1, const TMatrixDSparse* m2, const TMatrixDSparse* dsys) virtual void TUnfoldSys::PrepareSysError() virtual TMatrixDSparse* TUnfoldSys::PrepareUncorrEmat(const TMatrixDSparse* m1, const TMatrixDSparse* m2) void RegularizeDistributionRecursive(const TUnfoldBinning* binning, TUnfold::ERegMode regmode, TUnfoldDensity::EDensityMode densityMode, const char* distribution, const char* axisSteering) void RegularizeOneDistribution(const TUnfoldBinning* binning, TUnfold::ERegMode regmode, TUnfoldDensity::EDensityMode densityMode, const char* axisSteering) void TUnfoldSys::ScaleColumnsByVector(TMatrixDSparse* m, const TMatrixTBase* v) const TUnfoldDensity() void TUnfoldSys::VectorMapToHist(TH1* hist_delta, const TMatrixDSparse* delta, const Int_t* binMap)

Data Members

public:
 static TObject::(anonymous) TObject::kBitMask static TObject::EStatusBits TObject::kCanDelete static TObject::EStatusBits TObject::kCannotPick static TUnfoldDensity::EDensityMode kDensityModeBinWidth static TUnfoldDensity::EDensityMode kDensityModeBinWidthAndUser static TUnfoldDensity::EDensityMode kDensityModeUser static TUnfoldDensity::EDensityMode kDensityModeeNone static TUnfold::EConstraint TUnfold::kEConstraintArea static TUnfold::EConstraint TUnfold::kEConstraintNone static TUnfoldDensity::EScanTauMode kEScanTauRhoAvg static TUnfoldDensity::EScanTauMode kEScanTauRhoAvgSys static TUnfoldDensity::EScanTauMode kEScanTauRhoMax static TUnfoldDensity::EScanTauMode kEScanTauRhoMaxSys static TUnfoldDensity::EScanTauMode kEScanTauRhoSquareAvg static TUnfoldDensity::EScanTauMode kEScanTauRhoSquareAvgSys static TObject::EStatusBits TObject::kHasUUID static TUnfold::EHistMap TUnfold::kHistMapOutputHoriz static TUnfold::EHistMap TUnfold::kHistMapOutputVert static TObject::EStatusBits TObject::kInvalidObject static TObject::(anonymous) TObject::kIsOnHeap static TObject::EStatusBits TObject::kIsReferenced static TObject::EStatusBits TObject::kMustCleanup static TObject::EStatusBits TObject::kNoContextMenu static TObject::(anonymous) TObject::kNotDeleted static TObject::EStatusBits TObject::kObjInCanvas static TObject::(anonymous) TObject::kOverwrite static TUnfold::ERegMode TUnfold::kRegModeCurvature static TUnfold::ERegMode TUnfold::kRegModeDerivative static TUnfold::ERegMode TUnfold::kRegModeMixed static TUnfold::ERegMode TUnfold::kRegModeNone static TUnfold::ERegMode TUnfold::kRegModeSize static TObject::(anonymous) TObject::kSingleKey static TUnfoldSys::ESysErrMode TUnfoldSys::kSysErrModeMatrix static TUnfoldSys::ESysErrMode TUnfoldSys::kSysErrModeRelative static TUnfoldSys::ESysErrMode TUnfoldSys::kSysErrModeShift static TObject::(anonymous) TObject::kWriteDelete static TObject::(anonymous) TObject::kZombie
protected:
 TMatrixDSparse* TUnfold::fA Input: matrix TMatrixD* TUnfoldSys::fAoutside Input: underflow/overflow bins TMap* TUnfoldSys::fBgrErrScaleIn Input: background sources correlated error TMap* TUnfoldSys::fBgrErrUncorrInSq Input: uncorr error squared from bgr sources TMap* TUnfoldSys::fBgrIn Input: size of background sources Double_t TUnfold::fBiasScale Input: scale factor for the bias const TUnfoldBinning* fConstInputBins binning scheme for the input const TUnfoldBinning* fConstOutputBins binning scheme for the output TUnfold::EConstraint TUnfold::fConstraint Input: type of constraint to use TMatrixD* TUnfoldSys::fDAinColRelSq Input: normalized column err.sq. (inp.matr.) TMatrixDSparse* TUnfoldSys::fDAinRelSq Input: normalized errors from input matrix TMap* TUnfoldSys::fDeltaCorrAx Result: syst.shift from fSysIn on fAx TMap* TUnfoldSys::fDeltaCorrX Result: syst.shift from fSysIn on fX TMatrixDSparse* TUnfoldSys::fDeltaSysTau Result: systematic shift from tau Double_t TUnfoldSys::fDtau Input: error on tau TMatrixDSparse* TUnfoldSys::fEmatUncorrAx Result: syst.error from fDA2 on fAx TMatrixDSparse* TUnfoldSys::fEmatUncorrX Result: syst.error from fDA2 on fX TArrayI TUnfold::fHistToX Input: histogram bins -> matrix indices TMatrixDSparse* TUnfold::fL Input: regularisation conditions TUnfoldBinning* fOwnedInputBins input binning scheme if owner TUnfoldBinning* fOwnedOutputBins output binning scheme if owner TUnfold::ERegMode TUnfold::fRegMode Input: type of regularisation TUnfoldBinning* fRegularisationConditions binning scheme for the regularisation conditions TArrayD TUnfold::fSumOverY Input: sum of all columns TMap* TUnfoldSys::fSysIn Input: correlated errors Double_t TUnfold::fTauSquared Input: regularisation parameter TMatrixDSparse* TUnfold::fVyy Input: covariance matrix for y TMatrixDSparse* TUnfoldSys::fVyyData Input: error on fY prior to bgr subtraction TMatrixD* TUnfold::fX0 Input: x0 TArrayI TUnfold::fXToHist Input: matrix indices -> histogram bins TMatrixD* TUnfold::fY Input: y TMatrixD* TUnfoldSys::fYData Input: fY prior to bgr subtraction

Class Charts

Inheritance Chart:
 TObject
TUnfold
TUnfoldSys
TUnfoldDensity

Function documentation

TUnfoldDensity(const TUnfoldDensity& )
empty constructor, for derived classes
~TUnfoldDensity(void)
clean up
TString GetOutputBinName(Int_t iBinX) const
TUnfoldDensity(const TUnfoldDensity& )
Double_t GetDensityFactor(TUnfoldDensity::EDensityMode densityMode, Int_t iBin) const
TUnfoldDensity(const TH2* hist_A, TUnfold::EHistMap histmap, TUnfold::ERegMode regmode = kRegModeCurvature, TUnfold::EConstraint constraint = kEConstraintArea, TUnfoldDensity::EDensityMode densityMode = kDensityModeBinWidthAndUser, const TUnfoldBinning* outputBins = 0, const TUnfoldBinning* inputBins = 0, const char* regularisationDistribution = 0, const char* regularisationAxisSteering = "*[UOB]")
void RegularizeDistribution(TUnfold::ERegMode regmode, TUnfoldDensity::EDensityMode densityMode, const char* distribution, const char* axisSteering)
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)
TH1 * GetOutput(const char* histogramName, const char* histogramTitle = 0, const char* distributionName = 0, const char* projectionMode = 0, Bool_t useAxisBinning = kTRUE) const
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
TH1 * GetInput(const char* histogramName, const char* histogramTitle = 0, const char* distributionName = 0, const char* projectionMode = 0, Bool_t useAxisBinning = kTRUE) const
TH1 * GetDeltaSysBackgroundScale(const char* bgrSource, const char* histogramName, const char* histogramTitle = 0, const char* distributionName = 0, const char* projectionMode = 0, Bool_t useAxisBinning = kTRUE)
TH2 * GetEmatrixSysUncorr(const char* histogramName, const char* histogramTitle = 0, const char* distributionName = 0, const char* projectionMode = 0, Bool_t useAxisBinning = kTRUE)
TH2 * GetEmatrixInput(const char* histogramName, const char* histogramTitle = 0, const char* distributionName = 0, const char* projectionMode = 0, Bool_t useAxisBinning = kTRUE)
TH1 * GetRhoIstatbgr(const char* histogramName, const char* histogramTitle = 0, const char* distributionName = 0, const char* projectionMode = 0, Bool_t useAxisBinning = kTRUE, TH2** ematInv = 0)
TH2 * GetRhoIJtotal(const char* histogramName, const char* histogramTitle = 0, const char* distributionName = 0, const char* projectionMode = 0, Bool_t useAxisBinning = kTRUE)
TH1 * GetLxMinusBias(const char* histogramName, const char* histogramTitle = 0)
TH2 * GetProbabilityMatrix(const char* histogramName, const char* histogramTitle = 0, Bool_t useAxisBinning = kTRUE) const
const TUnfoldBinning * GetOutputBinning(const char* distributionName = 0) const
TUnfoldBinning * GetLBinning(void)