 |
ROOT 6.12/07 Reference Guide |
| |
ROOT 6.12/07 Reference Guide |
An algorithm to unfold distributions from detector to truth level.
TUnfold is used to decompose a measurement y into several sources x, given the measurement uncertainties and a matrix of migrations A. The method can be applied to a large number of problems, where the measured distribution y is a linear superposition of several Monte Carlo shapes. Beyond such a simple template fit, TUnfold has an adjustable regularisation term and also supports an optional constraint on the total number of events.
For most applications, it is better to use the derived class TUnfoldDensity instead of TUnfold. TUnfoldDensity adds various features to TUnfold, such as: background subtraction, propagation of systematic uncertainties, complex multidimensional arrangements of the bins. For innocent users, the most notable improvement of TUnfoldDensity over TUnfold are the getter functions. For TUnfold, histograms have to be booked by the user and the getter functions fill the histogram bins. TUnfoldDensity simply returns a new, already filled histogram.
If you use this software, please consider the following citation
S.Schmitt, JINST 7 (2012) T10003 [arXiv:1205.6201]
Detailed documentation and updates are available on http://www.desy.de/~sschmitt
Brief recipe to use TUnfold:
Basic formulae:
\[ \chi^{2}_{A}=(Ax-y)^{T}V_{yy}^{-1}(Ax-y) \\ \chi^{2}_{L}=(x-f*x_{0})^{T}L^{T}L(x-f*x_{0}) \\ \chi^{2}_{unf}=\chi^{2}_{A}+\tau^{2}\chi^{2}_{L}+\lambda\Sigma_{i}(Ax-y)_{i} \]
Without area constraint, \( \lambda \) is set to zero, and \( \chi^{2}_{unf} \) is minimized to determine \( x \). With area constraint, both \( x \) and \( \lambda \) are determined.
This file is part of TUnfold.
TUnfold is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
TUnfold is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with TUnfold. If not, see http://www.gnu.org/licenses/.
Version 17.6, updated doxygen-style comments, add one argument for scanLCurve
Public Types | |
| enum | EConstraint { kEConstraintNone =0, kEConstraintArea =1 } |
| type of extra constraint More... | |
| enum | EHistMap { kHistMapOutputHoriz = 0, kHistMapOutputVert = 1 } |
| arrangement of axes for the response matrix (TH2 histogram) More... | |
| enum | ERegMode { kRegModeNone = 0, kRegModeSize = 1, kRegModeDerivative = 2, kRegModeCurvature = 3, kRegModeMixed = 4 } |
| choice of regularisation scheme More... | |
 Public Types inherited from TObject | |
| enum | { kIsOnHeap = 0x01000000, kNotDeleted = 0x02000000, kZombie = 0x04000000, kInconsistent = 0x08000000, kBitMask = 0x00ffffff } |
| enum | { kSingleKey = BIT(0), kOverwrite = BIT(1), kWriteDelete = BIT(2) } |
| enum | EDeprecatedStatusBits { kObjInCanvas = BIT(3) } |
| enum | EStatusBits { kCanDelete = BIT(0), kMustCleanup = BIT(3), kIsReferenced = BIT(4), kHasUUID = BIT(5), kCannotPick = BIT(6), kNoContextMenu = BIT(8), kInvalidObject = BIT(13) } |
Public Member Functions | |
| TUnfold (const TH2 *hist_A, EHistMap histmap, ERegMode regmode=kRegModeSize, EConstraint constraint=kEConstraintArea) | |
| Set up response matrix and regularisation scheme. More... | |
| TUnfold (void) | |
| Only for use by root streamer or derived classes. More... | |
| virtual | ~TUnfold (void) |
| virtual Double_t | DoUnfold (Double_t tau) |
| Perform the unfolding for a given regularisation parameter tau. More... | |
| Double_t | DoUnfold (Double_t tau, const TH1 *hist_y, Double_t scaleBias=0.0) |
| Perform the unfolding for a given input and regularisation. More... | |
| void | GetBias (TH1 *bias, const Int_t *binMap=0) const |
| Get bias vector including bias scale. More... | |
| Double_t | GetChi2A (void) const |
| get χ2A contribution determined in recent unfolding More... | |
| Double_t | GetChi2L (void) const |
| Get \( chi^{2}_{L} \) contribution determined in recent unfolding. More... | |
| void | GetEmatrix (TH2 *ematrix, const Int_t *binMap=0) const |
| Get output covariance matrix, possibly cumulated over several bins. More... | |
| Double_t | GetEpsMatrix (void) const |
| get numerical accuracy for Eigenvalue analysis when inverting matrices with rank problems More... | |
| void | GetFoldedOutput (TH1 *folded, const Int_t *binMap=0) const |
| Get unfolding result on detector level. More... | |
| void | GetInput (TH1 *inputData, const Int_t *binMap=0) const |
| Input vector of measurements. More... | |
| void | GetInputInverseEmatrix (TH2 *ematrix) |
| Get inverse of the measurement's covariance matrix. More... | |
| void | GetL (TH2 *l) const |
| Get matrix of regularisation conditions. More... | |
| virtual Double_t | GetLcurveX (void) const |
| Get value on x-axis of L-curve determined in recent unfolding. More... | |
| virtual Double_t | GetLcurveY (void) const |
| Get value on y-axis of L-curve determined in recent unfolding. More... | |
| void | GetLsquared (TH2 *lsquared) const |
| Get matrix of regularisation conditions squared. More... | |
| Int_t | GetNdf (void) const |
| get number of degrees of freedom determined in recent unfolding More... | |
| void | GetNormalisationVector (TH1 *s, const Int_t *binMap=0) const |
| Histogram of truth bins, determined from summing over the response matrix. More... | |
| Int_t | GetNpar (void) const |
| Get number of truth parameters determined in recent unfolding. More... | |
| Int_t | GetNr (void) const |
| Get number of regularisation conditions. More... | |
| void | GetOutput (TH1 *output, const Int_t *binMap=0) const |
| Get output distribution, possibly cumulated over several bins. More... | |
| void | GetProbabilityMatrix (TH2 *A, EHistMap histmap) const |
| Get matrix of probabilities. More... | |
| Double_t | GetRhoAvg (void) const |
| get average global correlation determined in recent unfolding More... | |
| Double_t | GetRhoI (TH1 *rhoi, const Int_t *binMap=0, TH2 *invEmat=0) const |
| Get global correlation coefficients, possibly cumulated over several bins. More... | |
| void | GetRhoIJ (TH2 *rhoij, const Int_t *binMap=0) const |
| Get correlation coefficients, possibly cumulated over several bins. More... | |
| Double_t | GetRhoMax (void) const |
| get maximum global correlation determined in recent unfolding More... | |
| Double_t | GetTau (void) const |
| Return regularisation parameter. More... | |
| Int_t | RegularizeBins (int start, int step, int nbin, ERegMode regmode) |
| Add regularisation conditions for a group of bins. More... | |
| Int_t | RegularizeBins2D (int start_bin, int step1, int nbin1, int step2, int nbin2, ERegMode regmode) |
| Add regularisation conditions for 2d unfolding. More... | |
| Int_t | RegularizeCurvature (int left_bin, int center_bin, int right_bin, Double_t scale_left=1.0, Double_t scale_right=1.0) |
| Add a regularisation condition on the curvature of three truth bin. More... | |
| Int_t | RegularizeDerivative (int left_bin, int right_bin, Double_t scale=1.0) |
| Add a regularisation condition on the difference of two truth bin. More... | |
| Int_t | RegularizeSize (int bin, Double_t scale=1.0) |
| Add a regularisation condition on the magnitude of a truth bin. More... | |
| virtual Int_t | ScanLcurve (Int_t nPoint, Double_t tauMin, Double_t tauMax, TGraph **lCurve, TSpline **logTauX=0, TSpline **logTauY=0, TSpline **logTauCurvature=0) |
| Scan the L curve, determine tau and unfold at the final value of tau. More... | |
| void | SetBias (const TH1 *bias) |
| Set bias vector. More... | |
| void | SetConstraint (EConstraint constraint) |
| Set type of area constraint. More... | |
| void | SetEpsMatrix (Double_t eps) |
| set numerical accuracy for Eigenvalue analysis when inverting matrices with rank problems More... | |
| 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 data for subsequent calls to DoUnfold(tau). More... | |
| Public Member Functions inherited from TObject | |
| TObject () | |
| TObject constructor. More... | |
| TObject (const TObject &object) | |
| TObject copy ctor. More... | |
| virtual | ~TObject () |
| TObject destructor. More... | |
| void | AbstractMethod (const char *method) const |
| Use this method to implement an "abstract" method that you don't want to leave purely abstract. More... | |
| virtual void | AppendPad (Option_t *option="") |
| Append graphics object to current pad. More... | |
| virtual void | Browse (TBrowser *b) |
| Browse object. May be overridden for another default action. More... | |
| ULong_t | CheckedHash () |
| Checked and record whether for this class has a consistent Hash/RecursiveRemove setup (*) and then return the regular Hash value for this object. More... | |
| virtual const char * | ClassName () const |
| Returns name of class to which the object belongs. More... | |
| virtual void | Clear (Option_t *="") |
| virtual TObject * | Clone (const char *newname="") const |
| Make a clone of an object using the Streamer facility. More... | |
| virtual Int_t | Compare (const TObject *obj) const |
| Compare abstract method. More... | |
| virtual void | Copy (TObject &object) const |
| Copy this to obj. More... | |
| virtual void | Delete (Option_t *option="") |
| Delete this object. More... | |
| virtual Int_t | DistancetoPrimitive (Int_t px, Int_t py) |
| Computes distance from point (px,py) to the object. More... | |
| virtual void | Draw (Option_t *option="") |
| Default Draw method for all objects. More... | |
| virtual void | DrawClass () const |
| Draw class inheritance tree of the class to which this object belongs. More... | |
| virtual TObject * | DrawClone (Option_t *option="") const |
Draw a clone of this object in the current selected pad for instance with: gROOT->SetSelectedPad(gPad). More... | |
| virtual void | Dump () const |
| Dump contents of object on stdout. More... | |
| virtual void | Error (const char *method, const char *msgfmt,...) const |
| Issue error message. More... | |
| virtual void | Execute (const char *method, const char *params, Int_t *error=0) |
| Execute method on this object with the given parameter string, e.g. More... | |
| virtual void | Execute (TMethod *method, TObjArray *params, Int_t *error=0) |
| Execute method on this object with parameters stored in the TObjArray. More... | |
| virtual void | ExecuteEvent (Int_t event, Int_t px, Int_t py) |
| Execute action corresponding to an event at (px,py). More... | |
| virtual void | Fatal (const char *method, const char *msgfmt,...) const |
| Issue fatal error message. More... | |
| virtual TObject * | FindObject (const char *name) const |
| Must be redefined in derived classes. More... | |
| virtual TObject * | FindObject (const TObject *obj) const |
| Must be redefined in derived classes. More... | |
| virtual Option_t * | GetDrawOption () const |
| Get option used by the graphics system to draw this object. More... | |
| virtual const char * | GetIconName () const |
| Returns mime type name of object. More... | |
| virtual const char * | GetName () const |
| Returns name of object. More... | |
| virtual char * | GetObjectInfo (Int_t px, Int_t py) const |
| Returns string containing info about the object at position (px,py). More... | |
| virtual Option_t * | GetOption () const |
| virtual const char * | GetTitle () const |
| Returns title of object. More... | |
| virtual UInt_t | GetUniqueID () const |
| Return the unique object id. More... | |
| virtual Bool_t | HandleTimer (TTimer *timer) |
| Execute action in response of a timer timing out. More... | |
| virtual ULong_t | Hash () const |
| Return hash value for this object. More... | |
| Bool_t | HasInconsistentHash () const |
| Return true is the type of this object is known to have an inconsistent setup for Hash and RecursiveRemove (i.e. More... | |
| virtual void | Info (const char *method, const char *msgfmt,...) const |
| Issue info message. More... | |
| virtual Bool_t | InheritsFrom (const char *classname) const |
| Returns kTRUE if object inherits from class "classname". More... | |
| virtual Bool_t | InheritsFrom (const TClass *cl) const |
| Returns kTRUE if object inherits from TClass cl. More... | |
| virtual void | Inspect () const |
| Dump contents of this object in a graphics canvas. More... | |
| void | InvertBit (UInt_t f) |
| virtual Bool_t | IsEqual (const TObject *obj) const |
| Default equal comparison (objects are equal if they have the same address in memory). More... | |
| virtual Bool_t | IsFolder () const |
| Returns kTRUE in case object contains browsable objects (like containers or lists of other objects). More... | |
| R__ALWAYS_INLINE Bool_t | IsOnHeap () const |
| virtual Bool_t | IsSortable () const |
| R__ALWAYS_INLINE Bool_t | IsZombie () const |
| virtual void | ls (Option_t *option="") const |
| The ls function lists the contents of a class on stdout. More... | |
| void | MayNotUse (const char *method) const |
| Use this method to signal that a method (defined in a base class) may not be called in a derived class (in principle against good design since a child class should not provide less functionality than its parent, however, sometimes it is necessary). More... | |
| virtual Bool_t | Notify () |
| This method must be overridden to handle object notification. More... | |
| void | Obsolete (const char *method, const char *asOfVers, const char *removedFromVers) const |
| Use this method to declare a method obsolete. More... | |
| void | operator delete (void *ptr) |
| Operator delete. More... | |
| void | operator delete[] (void *ptr) |
| Operator delete []. More... | |
| void * | operator new (size_t sz) |
| void * | operator new (size_t sz, void *vp) |
| void * | operator new[] (size_t sz) |
| void * | operator new[] (size_t sz, void *vp) |
| TObject & | operator= (const TObject &rhs) |
| TObject assignment operator. More... | |
| virtual void | Paint (Option_t *option="") |
| This method must be overridden if a class wants to paint itself. More... | |
| virtual void | Pop () |
| Pop on object drawn in a pad to the top of the display list. More... | |
| virtual void | Print (Option_t *option="") const |
| This method must be overridden when a class wants to print itself. More... | |
| virtual Int_t | Read (const char *name) |
| Read contents of object with specified name from the current directory. More... | |
| virtual void | RecursiveRemove (TObject *obj) |
| Recursively remove this object from a list. More... | |
| void | ResetBit (UInt_t f) |
| virtual void | SaveAs (const char *filename="", Option_t *option="") const |
| Save this object in the file specified by filename. More... | |
| virtual void | SavePrimitive (std::ostream &out, Option_t *option="") |
| Save a primitive as a C++ statement(s) on output stream "out". More... | |
| void | SetBit (UInt_t f, Bool_t set) |
| Set or unset the user status bits as specified in f. More... | |
| void | SetBit (UInt_t f) |
| virtual void | SetDrawOption (Option_t *option="") |
| Set drawing option for object. More... | |
| virtual void | SetUniqueID (UInt_t uid) |
| Set the unique object id. More... | |
| virtual void | SysError (const char *method, const char *msgfmt,...) const |
| Issue system error message. More... | |
| R__ALWAYS_INLINE Bool_t | TestBit (UInt_t f) const |
| Int_t | TestBits (UInt_t f) const |
| virtual void | UseCurrentStyle () |
| Set current style settings in this object This function is called when either TCanvas::UseCurrentStyle or TROOT::ForceStyle have been invoked. More... | |
| virtual void | Warning (const char *method, const char *msgfmt,...) const |
| Issue warning message. More... | |
| virtual Int_t | Write (const char *name=0, Int_t option=0, Int_t bufsize=0) |
| Write this object to the current directory. More... | |
| virtual Int_t | Write (const char *name=0, Int_t option=0, Int_t bufsize=0) const |
| Write this object to the current directory. More... | |
Static Public Member Functions | |
| static const char * | GetTUnfoldVersion (void) |
| Return a string describing the TUnfold version. More... | |
| Static Public Member Functions inherited from TObject | |
| static Long_t | GetDtorOnly () |
| Return destructor only flag. More... | |
| static Bool_t | GetObjectStat () |
| Get status of object stat flag. More... | |
| static void | SetDtorOnly (void *obj) |
| Set destructor only flag. More... | |
| static void | SetObjectStat (Bool_t stat) |
| Turn on/off tracking of objects in the TObjectTable. More... | |
Protected Member Functions | |
| void | AddMSparse (TMatrixDSparse *dest, Double_t f, const TMatrixDSparse *src) const |
| Add a sparse matrix, scaled by a factor, to another scaled matrix. More... | |
| Bool_t | AddRegularisationCondition (Int_t i0, Double_t f0, Int_t i1=-1, Double_t f1=0., Int_t i2=-1, Double_t f2=0.) |
| Add a row of regularisation conditions to the matrix L. More... | |
| Bool_t | AddRegularisationCondition (Int_t nEle, const Int_t *indices, const Double_t *rowData) |
| Add a row of regularisation conditions to the matrix L. More... | |
| void | ClearHistogram (TH1 *h, Double_t x=0.) const |
| Initialize bin contents and bin errors for a given histogram. More... | |
| virtual void | ClearResults (void) |
| Reset all results. More... | |
| TMatrixDSparse * | CreateSparseMatrix (Int_t nrow, Int_t ncol, Int_t nele, Int_t *row, Int_t *col, Double_t *data) const |
| Create a sparse matrix, given the nonzero elements. More... | |
| virtual Double_t | DoUnfold (void) |
| Core unfolding algorithm. More... | |
| void | ErrorMatrixToHist (TH2 *ematrix, const TMatrixDSparse *emat, const Int_t *binMap, Bool_t doClear) const |
| Add up an error matrix, also respecting the bin mapping. More... | |
| const TMatrixDSparse * | GetAx (void) const |
| vector of folded-back result More... | |
| Int_t | GetBinFromRow (int ix) const |
| converts matrix row to truth histogram bin number More... | |
| const TMatrixDSparse * | GetDXDAM (int i) const |
| matrix contributions of the derivative dx/dA More... | |
| const TMatrixDSparse * | GetDXDAZ (int i) const |
| vector contributions of the derivative dx/dA More... | |
| const TMatrixDSparse * | GetDXDtauSquared (void) const |
| vector of derivative dx/dtauSquared, using internal bin counting More... | |
| const TMatrixDSparse * | GetDXDY (void) const |
| matrix of derivatives dx/dy More... | |
| const TMatrixDSparse * | GetE (void) const |
| matrix E, using internal bin counting More... | |
| const TMatrixDSparse * | GetEinv (void) const |
| matrix E-1, using internal bin counting More... | |
| Int_t | GetNx (void) const |
| returns internal number of output (truth) matrix rows More... | |
| Int_t | GetNy (void) const |
| returns the number of measurement bins More... | |
| virtual TString | GetOutputBinName (Int_t iBinX) const |
| Get bin name of an output bin. More... | |
| Double_t | GetRhoIFromMatrix (TH1 *rhoi, const TMatrixDSparse *eOrig, const Int_t *binMap, TH2 *invEmat) const |
| Get global correlation coefficients with arbitrary min map. More... | |
| Int_t | GetRowFromBin (int ix) const |
| converts truth histogram bin number to matrix row More... | |
| const TMatrixDSparse * | GetVxx (void) const |
| covariance matrix of the result More... | |
| const TMatrixDSparse * | GetVxxInv (void) const |
| inverse of covariance matrix of the result More... | |
| const TMatrixDSparse * | GetVyyInv (void) const |
| inverse of covariance matrix of the data y More... | |
| const TMatrixD * | GetX (void) const |
| vector of the unfolding result More... | |
| TMatrixDSparse * | InvertMSparseSymmPos (const TMatrixDSparse *A, Int_t *rank) const |
| Get the inverse or pseudo-inverse of a positive, sparse matrix. More... | |
| TMatrixDSparse * | MultiplyMSparseM (const TMatrixDSparse *a, const TMatrixD *b) const |
| Multiply sparse matrix and a non-sparse matrix. More... | |
| TMatrixDSparse * | MultiplyMSparseMSparse (const TMatrixDSparse *a, const TMatrixDSparse *b) const |
| Multiply two sparse matrices. More... | |
| TMatrixDSparse * | MultiplyMSparseMSparseTranspVector (const TMatrixDSparse *m1, const TMatrixDSparse *m2, const TMatrixTBase< Double_t > *v) const |
| Calculate a sparse matrix product \( M1*V*M2^{T} \) where the diagonal matrix V is given by a vector. More... | |
| TMatrixDSparse * | MultiplyMSparseTranspMSparse (const TMatrixDSparse *a, const TMatrixDSparse *b) const |
| Multiply a transposed Sparse matrix with another sparse matrix,. More... | |
| Protected Member Functions inherited from TObject | |
| virtual void | DoError (int level, const char *location, const char *fmt, va_list va) const |
| Interface to ErrorHandler (protected). More... | |
| void | MakeZombie () |
Static Protected Member Functions | |
| static void | DeleteMatrix (TMatrixD **m) |
| delete matrix and invalidate pointer More... | |
| static void | DeleteMatrix (TMatrixDSparse **m) |
| delete sparse matrix and invalidate pointer More... | |
Protected Attributes | |
| TMatrixDSparse * | fA |
| response matrix A More... | |
| Double_t | fBiasScale |
| scale factor for the bias More... | |
| EConstraint | fConstraint |
| type of constraint to use for the unfolding More... | |
| TArrayI | fHistToX |
| mapping of histogram bins to matrix indices More... | |
| TMatrixDSparse * | fL |
| regularisation conditions L More... | |
| ERegMode | fRegMode |
| type of regularisation More... | |
| TArrayD | fSumOverY |
| truth vector calculated from the non-normalized response matrix More... | |
| Double_t | fTauSquared |
| regularisation parameter tau squared More... | |
| TMatrixDSparse * | fVyy |
| covariance matrix Vyy corresponding to y More... | |
| TMatrixD * | fX0 |
| bias vector x0 More... | |
| TArrayI | fXToHist |
| mapping of matrix indices to histogram bins More... | |
| TMatrixD * | fY |
| input (measured) data y More... | |
Private Member Functions | |
| void | InitTUnfold (void) |
| Initialize data members, for use in constructors. More... | |
Private Attributes | |
| TMatrixDSparse * | fAx |
| result x folded back A*x More... | |
| Double_t | fChi2A |
| chi**2 contribution from (y-Ax)Vyy-1(y-Ax) More... | |
| TMatrixDSparse * | fDXDAM [2] |
| matrix contribution to the of derivative dx_k/dA_ij More... | |
| TMatrixDSparse * | fDXDAZ [2] |
| vector contribution to the of derivative dx_k/dA_ij More... | |
| TMatrixDSparse * | fDXDtauSquared |
| derivative of the result wrt tau squared More... | |
| TMatrixDSparse * | fDXDY |
| derivative of the result wrt dx/dy More... | |
| TMatrixDSparse * | fE |
| matrix E More... | |
| TMatrixDSparse * | fEinv |
| matrix E^(-1) More... | |
| Double_t | fEpsMatrix |
| machine accuracy used to determine matrix rank after eigenvalue analysis More... | |
| Int_t | fIgnoredBins |
| number of input bins which are dropped because they have error=0 More... | |
| Double_t | fLXsquared |
| chi**2 contribution from (x-s*x0)TLTL(x-s*x0) More... | |
| Int_t | fNdf |
| number of degrees of freedom More... | |
| Double_t | fRhoAvg |
| average global correlation coefficient More... | |
| Double_t | fRhoMax |
| maximum global correlation coefficient More... | |
| TMatrixDSparse * | fVxx |
| covariance matrix Vxx More... | |
| TMatrixDSparse * | fVxxInv |
| inverse of covariance matrix Vxx-1 More... | |
| TMatrixDSparse * | fVyyInv |
| inverse of the input covariance matrix Vyy-1 More... | |
| TMatrixD * | fX |
| unfolding result x More... | |
#include <TUnfold.h>
| enum TUnfold::EConstraint |
| enum TUnfold::EHistMap |
| enum TUnfold::ERegMode |
choice of regularisation scheme
| TUnfold::TUnfold | ( | const TH2 * | hist_A, |
| EHistMap | histmap, | ||
| ERegMode | regmode = kRegModeSize, |
||
| EConstraint | constraint = kEConstraintArea |
||
| ) |
Set up response matrix and regularisation scheme.
| [in] | hist_A | matrix of MC events that describes the migrations |
| [in] | histmap | mapping of the histogram axes |
| [in] | regmode | (default=kRegModeSize) global regularisation mode |
| [in] | constraint | (default=kEConstraintArea) type of constraint |
Treatment of overflow bins in the matrix hist_A
If unsure, do the following:
Definition at line 1715 of file TUnfold.cxx.
| TUnfold::TUnfold | ( | void | ) |
Only for use by root streamer or derived classes.
Definition at line 248 of file TUnfold.cxx.
|
virtual |
Definition at line 132 of file TUnfold.cxx.
|
protected |
Add a sparse matrix, scaled by a factor, to another scaled matrix.
| [in,out] | dest | destination matrix |
| [in] | f | scaling factor |
| [in] | src | matrix to be added to dest |
a replacement for
which suffered from a bug in old root versions.
Definition at line 930 of file TUnfold.cxx.
|
protected |
Add a row of regularisation conditions to the matrix L.
| [in] | i0 | truth histogram bin number |
| [in] | f0 | entry in the matrix L, column i0 |
| [in] | i1 | truth histogram bin number |
| [in] | f1 | entry in the matrix L, column i1 |
| [in] | i2 | truth histogram bin number |
| [in] | f2 | entry in the matrix L, column i2 |
the arguments are used to form one row (k) of the matrix L, where \( L_{k,i0}=f0 \) and \( L_{k,i1}=f1 \) and \( L_{k,i2}=f2 \) negative indexes i0,i1,i2 are ignored.
Definition at line 1936 of file TUnfold.cxx.
|
protected |
Add a row of regularisation conditions to the matrix L.
| [in] | nEle | number of valid entries in indices and rowData |
| [in] | indices | column numbers of L to fill |
| [in] | rowData | data to fill into the new row of L |
returns true if a row was added, false otherwise
A new row k is added to the matrix L, its dimension is expanded. The new elements \( L_{ki} \) are filled from the array rowData[] where the indices i which are taken from the array indices[].
Definition at line 1974 of file TUnfold.cxx.
Initialize bin contents and bin errors for a given histogram.
| [out] | h | histogram |
| [in] | x | new histogram content |
all histgram errors are set to zero, all contents are set to x
Definition at line 3643 of file TUnfold.cxx.
|
protected |
Create a sparse matrix, given the nonzero elements.
| [in] | nrow | number of rows |
| [in] | ncol | number of columns |
| [in] | nel | number of non-zero elements |
| [in] | row | row indexes of non-zero elements |
| [in] | col | column indexes of non-zero elements |
| [in] | data | non-zero elements data |
return pointer to a new sparse matrix
shortcut to new TMatrixDSparse() followed by SetMatrixArray().
Definition at line 592 of file TUnfold.cxx.
delete matrix and invalidate pointer
Delete matrix and invalidate pointer.
| [in,out] | m | pointer to a matrix-pointer |
If the matrix pointer os non-zero, the matrix id deleted. The matrix pointer is set to zero.
Definition at line 195 of file TUnfold.cxx.
|
staticprotected |
delete sparse matrix and invalidate pointer
Delete sparse matrix and invalidate pointer.
| [in,out] | m | pointer to a matrix-pointer |
if the matrix pointer os non-zero, the matrix id deleted. The matrix pointer is set to zero.
Definition at line 209 of file TUnfold.cxx.
Core unfolding algorithm.
Main unfolding algorithm. Declared virtual, because other algorithms could be implemented
Purpose: unfold y -> x
Definition at line 290 of file TUnfold.cxx.
Perform the unfolding for a given regularisation parameter tau.
| [in] | tau | regularisation parameter |
This method sets tau and then calls the core unfolding algorithm required data members:
Definition at line 2517 of file TUnfold.cxx.
Perform the unfolding for a given input and regularisation.
| [in] | tau_reg | regularisation parameter |
| [in] | input | input distribution with uncertainties |
| [in] | scaleBias | (default=0.0) scale factor applied to the bias |
This is a shortcut for { SetInput(input,scaleBias); DoUnfold(tau); }
Data members required:
Overflow bins of the input distribution are ignored!
Definition at line 2265 of file TUnfold.cxx.
|
protected |
Add up an error matrix, also respecting the bin mapping.
| [in,out] | ematrix | error matrix histogram |
| [in] | emat | error matrix stored with internal mapping (member fXToHist) |
| [in] | binMap | mapping of histogram bins |
| [in] | doClear | if true, ematrix is cleared prior to adding elements of emat to it. |
the array binMap is explained with the method GetOutput(). The matrix emat must have dimension NxN where N=fXToHist.size() The flag doClear may be used to add covariance matrices from several uncertainty sources.
Definition at line 3343 of file TUnfold.cxx.
|
inlineprotected |
Get bias vector including bias scale.
| [out] | out | histogram to store the scaled bias vector. The bin contents are overwritten |
| [in] | binMap | (default=0) array for mapping truth bins to histogram bins |
This method returns the bias vector times scaling factor, f*x_{0}
The use of binMap is explained with the documentation of the GetOutput() method
Definition at line 2922 of file TUnfold.cxx.
|
inlineprotected |
Get \( chi^{2}_{L} \) contribution determined in recent unfolding.
Definition at line 3194 of file TUnfold.cxx.
|
inlineprotected |
|
inlineprotected |
|
inlineprotected |
|
inlineprotected |
|
inlineprotected |
|
inlineprotected |
Get output covariance matrix, possibly cumulated over several bins.
| [out] | ematrix | histogram to store the covariance. The bin contents are overwritten. |
| [in] | binMap | (default=0) array for mapping truth bins to histogram bins |
The use of binMap is explained with the documentation of the GetOutput() method
Definition at line 3410 of file TUnfold.cxx.
Get unfolding result on detector level.
| [out] | out | histogram to store the correlation coefficients. The bin contents and errors are overwritten. |
| [in] | binMap | (default=0) array for mapping truth bins to histogram bins |
This method returns the unfolding output folded by the response matrix, i.e. the vector Ax.
The use of binMap is explained with the documentation of the GetOutput() method
Definition at line 2948 of file TUnfold.cxx.
Input vector of measurements.
| [out] | out | histogram to store the measurements. Bin content and bin errors are overwrite. |
| [in] | binMap | (default=0) array for mapping truth bins to histogram bins |
Bins which had an uncertainty of zero in the call to SetInput() may acquire bin contents or bin errors different from the original settings in SetInput().
The use of binMap is explained with the documentation of the GetOutput() method
Definition at line 3031 of file TUnfold.cxx.
Get inverse of the measurement's covariance matrix.
| [out] | out | histogram to store the inverted covariance |
Definition at line 3060 of file TUnfold.cxx.
Get matrix of regularisation conditions.
| [out] | out | histogram to store the regularisation conditions. the bin contents are overwritten |
The histogram should have dimension nr (x-axis) times nx (y-axis). nr corresponds to the number of regularisation conditions, it can be obtained using the method GetNr(). nx corresponds to the number of histogram bins in the response matrix along the truth axis.
Definition at line 3153 of file TUnfold.cxx.
Get value on x-axis of L-curve determined in recent unfolding.
\( x=log_{10}(GetChi2A()) \)
Definition at line 3216 of file TUnfold.cxx.
Get value on y-axis of L-curve determined in recent unfolding.
\( y=log_{10}(GetChi2L()) \)
Definition at line 3226 of file TUnfold.cxx.
Get matrix of regularisation conditions squared.
| [out] | out | histogram to store the squared matrix of regularisation conditions. the bin contents are overwritten |
This returns the square matrix L^{T}L as a histogram
The histogram should have dimension nx times nx, where nx corresponds to the number of histogram bins in the response matrix along the truth axis.
Definition at line 3113 of file TUnfold.cxx.
Histogram of truth bins, determined from summing over the response matrix.
| [out] | out | histogram to store the truth bins. The bin contents are overwritten |
| [in] | binMap | (default=0) array for mapping truth bins to histogram bins |
This vector is also used to initialize the bias x_{0}. However, the bias vector may be changed using the SetBias() method.
The use of binMap is explained with the documentation of the GetOutput() method.
Definition at line 2898 of file TUnfold.cxx.
Get number of truth parameters determined in recent unfolding.
empty bins of the response matrix or bins which can not be unfolded due to rank deficits are not counted
Definition at line 3206 of file TUnfold.cxx.
Get number of regularisation conditions.
This returns the number of regularisation conditions, useful for booking a histogram for a subsequent call of GetL().
Definition at line 3138 of file TUnfold.cxx.
Get output distribution, possibly cumulated over several bins.
| [out] | output | existing output histogram. content and errors will be updated. |
| [in] | binMap | (default=0) array for mapping truth bins to histogram bins |
If nonzero, the array binMap must have dimension n+2, where n corresponds to the number of bins on the truth axis of the response matrix (the histogram specified with the TUnfold constructor). The indexes of binMap correspond to the truth bins (including underflow and overflow) of the response matrix. The element binMap[i] specifies the histogram number in output where the corresponding truth bin will be stored. It is possible to specify the same output bin number for multiple indexes, in which case these bins are added. Set binMap[i]=-1 to ignore an unfolded truth bin. The uncertainties are calculated from the corresponding parts of the covariance matrix, properly taking care of added truth bins.
If the pointer binMap is zero, the bins are mapped one-to-one. Truth bin zero (underflow) is stored in the output underflow, truth bin 1 is stored in bin number 1, etc.
Definition at line 3263 of file TUnfold.cxx.
Get bin name of an output bin.
| [in] | iBinX | bin number |
Return value: name of the bin
For TUnfold and TUnfoldSys, this function simply returns the bin number as a string. This function really only makes sense in the context of TUnfoldDensity, where binning schemes are implemented using the class TUnfoldBinning, and non-trivial bin names are returned.
Reimplemented in TUnfoldDensity.
Definition at line 1684 of file TUnfold.cxx.
Get matrix of probabilities.
| [out] | A | two-dimensional histogram to store the probabilities (normalized response matrix). The bin contents are overwritten |
| [in] | histmap | specify axis along which the truth bins are oriented |
Definition at line 2996 of file TUnfold.cxx.
Get global correlation coefficients, possibly cumulated over several bins.
| [out] | rhoi | histogram to store the global correlation coefficients. The bin contents are overwritten. |
| [in] | binMap | (default=0) array for mapping truth bins to histogram bins |
| [out] | invEmat | (default=0) histogram to store the inverted covariance matrix |
for a given bin, the global correlation coefficient is defined as \( \rho_{i} = \sqrt{1-\frac{1}{(V_{ii}*V^{-1}_{ii})}} \)
such that the calculation of global correlation coefficients possibly involves the inversion of a covariance matrix.
return value: maximum global correlation coefficient
The use of binMap is explained with the documentation of the GetOutput() method
Definition at line 3466 of file TUnfold.cxx.
|
protected |
Get global correlation coefficients with arbitrary min map.
Definition at line 3528 of file TUnfold.cxx.
Get correlation coefficients, possibly cumulated over several bins.
| [out] | rhoij | histogram to store the correlation coefficients. The bin contents are overwritten. |
| [in] | binMap | (default=0) array for mapping truth bins to histogram bins |
The use of binMap is explained with the documentation of the GetOutput() method
Definition at line 3425 of file TUnfold.cxx.
|
inlineprotected |
Return regularisation parameter.
Definition at line 3185 of file TUnfold.cxx.
|
static |
Return a string describing the TUnfold version.
The version is reported in the form Vmajor.minor Changes of the minor version number typically correspond to bug-fixes. Changes of the major version may result in adding or removing data attributes, such that the streamer methods are not compatible between different major versions.
Definition at line 3680 of file TUnfold.cxx.
|
inlineprotected |
|
inlineprotected |
|
inlineprotected |
Initialize data members, for use in constructors.
Definition at line 149 of file TUnfold.cxx.
|
protected |
Get the inverse or pseudo-inverse of a positive, sparse matrix.
| [in] | A | the sparse matrix to be inverted, has to be positive |
| [in,out] | rankPtr | if zero, suppress calculation of pseudo-inverse otherwise the rank of the matrix is returned in *rankPtr |
return value: 0 or a new sparse matrix
the matrix inversion is optimized in performance for the case where a large submatrix of A is diagonal
Definition at line 1008 of file TUnfold.cxx.
|
protected |
Multiply sparse matrix and a non-sparse matrix.
| [in] | a | sparse matrix |
| [in] | b | matrix |
returns a new sparse matrix a*b. A replacement for: new TMatrixDSparse(a,TMatrixDSparse::kMult,b) the root implementation had problems in older versions of root.
Definition at line 773 of file TUnfold.cxx.
|
protected |
Multiply two sparse matrices.
| [in] | a | sparse matrix |
| [in] | b | sparse matrix |
returns a new sparse matrix a*b.
A replacement for: new TMatrixDSparse(a,TMatrixDSparse::kMult,b) the root implementation had problems in older versions of root.
Definition at line 617 of file TUnfold.cxx.
|
protected |
Calculate a sparse matrix product \( M1*V*M2^{T} \) where the diagonal matrix V is given by a vector.
| [in] | m1 | pointer to sparse matrix with dimension I*K |
| [in] | m2 | pointer to sparse matrix with dimension J*K |
| [in] | v | pointer to vector (matrix) with dimension K*1 |
returns a sparse matrix R with elements \( r_{ij}=\Sigma_{k}M1_{ik}V_{k}M2_{jk} \)
Definition at line 833 of file TUnfold.cxx.
|
protected |
Multiply a transposed Sparse matrix with another sparse matrix,.
| [in] | a | sparse matrix (to be transposed) |
| [in] | b | sparse matrix |
returns a new sparse matrix a^{T}*b
this is a replacement for the root constructors new TMatrixDSparse(TMatrixDSparse(TMatrixDSparse::kTransposed,*a), TMatrixDSparse::kMult,*b)
Definition at line 693 of file TUnfold.cxx.
Add regularisation conditions for a group of bins.
| [in] | start | first bin number |
| [in] | step | step size |
| [in] | nbin | number of bins |
| [in] | regmode | regularisation mode (one of: kRegModeSize, kRegModeDerivative, kRegModeCurvature) |
add regularisation conditions for a group of equidistant bins. There are nbin bins, starting with bin start and with a distance of step between bins.
Return value: number of regularisation conditions which could not be added.
Conditions which are not added typically correspond to bin numbers where the truth can not be unfolded (either response matrix is empty or the data do not constrain).
Definition at line 2161 of file TUnfold.cxx.
| Int_t TUnfold::RegularizeBins2D | ( | int | start_bin, |
| int | step1, | ||
| int | nbin1, | ||
| int | step2, | ||
| int | nbin2, | ||
| ERegMode | regmode | ||
| ) |
Add regularisation conditions for 2d unfolding.
| [in] | start_bin | first bin number |
| [in] | step1 | step size, 1st dimension |
| [in] | nbin1 | number of bins, 1st dimension |
| [in] | step2 | step size, 2nd dimension |
| [in] | nbin2 | number of bins, 2nd dimension |
| [in] | regmode | regularisation mode (one of: kRegModeSize, kRegModeDerivative, kRegModeCurvature) |
add regularisation conditions for a grid of bins. The start bin is start_bin. Along the first (second) dimension, there are nbin1 (nbin2) bins and adjacent bins are spaced by step1 (step2) units.
Return value: number of regularisation conditions which could not be added. Conditions which are not added typically correspond to bin numbers where the truth can not be unfolded (either response matrix is empty or the data do not constrain).
Definition at line 2222 of file TUnfold.cxx.
| Int_t TUnfold::RegularizeCurvature | ( | int | left_bin, |
| int | center_bin, | ||
| int | right_bin, | ||
| Double_t | scale_left = 1.0, |
||
| Double_t | scale_right = 1.0 |
||
| ) |
Add a regularisation condition on the curvature of three truth bin.
| [in] | left_bin | bin number |
| [in] | center_bin | bin number |
| [in] | right_bin | bin number |
| [in] | scale_left | (default=1) scale factor |
| [in] | scale_right | (default=1) scale factor |
this adds one row to L, where the element left_bin takes the value -scale_left, the element right_bin takes the value -scale_right and the element center_bin takes the value scale_left+scale_right
return value: 0 if ok, 1 if the condition has not been added. Conditions which are not added typically correspond to bin numbers where the truth can not be unfolded (either response matrix is empty or the data do not constrain).
The RegularizeXXX() methods can be used to set up a custom matrix of regularisation conditions. In this case, start with an empty matrix L (argument regmode=kRegModeNone in the constructor)
Definition at line 2117 of file TUnfold.cxx.
Add a regularisation condition on the difference of two truth bin.
| [in] | left_bin | bin number |
| [in] | right_bin | bin number |
| [in] | scale | (default=1) scale factor |
this adds one row to L, where the element left_bin takes the value -scale and the element right_bin takes the value +scale
return value: 0 if ok, 1 if the condition has not been added. Conditions which are not added typically correspond to bin numbers where the truth can not be unfolded (either response matrix is empty or the data do not constrain).
The RegularizeXXX() methods can be used to set up a custom matrix of regularisation conditions. In this case, start with an empty matrix L (argument regmode=kRegModeNone in the constructor)
Definition at line 2078 of file TUnfold.cxx.
Add a regularisation condition on the magnitude of a truth bin.
| [in] | bin | bin number |
| [in] | scale | (default=1) scale factor |
this adds one row to L, where the element bin takes the value scale
return value: 0 if ok, 1 if the condition has not been added. Conditions which are not added typically correspond to bin numbers where the truth can not be unfolded (either response matrix is empty or the data do not constrain).
The RegularizeXXX() methods can be used to set up a custom matrix of regularisation conditions. In this case, start with an empty matrix L (argument regmode=kRegModeNone in the constructor)
Definition at line 2044 of file TUnfold.cxx.
|
virtual |
Scan the L curve, determine tau and unfold at the final value of tau.
| [in] | nPoint | number of points used for the scan |
| [in] | tauMin | smallest tau value to study |
| [in] | tauMax | largest tau value to study. If tauMin=tauMax=0, a scan interval is determined automatically. |
| [out] | lCurve | if nonzero, a new TGraph is returned, containing the L-curve |
| [out] | logTauX | if nonzero, a new TSpline is returned, to parameterize the L-curve's x-coordinates as a function of log10(tau) |
| [out] | logTauY | if nonzero, a new TSpline is returned, to parameterize the L-curve's y-coordinates as a function of log10(tau) |
| [out] | logTauCurvature | if nonzero, a new TSpline is returned of the L-curve curvature as a function of log10(tau) |
return value: the coordinate number in the logTauX,logTauY graphs corresponding to the "final" choice of tau
Recommendation: always check logTauCurvature, it should be a peaked function (similar to a Gaussian), the maximum corresponding to the final choice of tau. Also, check the lCurve it should be approximately L-shaped. If in doubt, adjust tauMin and tauMax until the results are satisfactory.
Definition at line 2548 of file TUnfold.cxx.
Set bias vector.
| [in] | bias | histogram with new bias vector |
the initial bias vector is determined from the response matrix but may be changed by using this method
Definition at line 1912 of file TUnfold.cxx.
| void TUnfold::SetConstraint | ( | EConstraint | constraint | ) |
Set type of area constraint.
results of a previous unfolding are reset
Definition at line 3173 of file TUnfold.cxx.
set numerical accuracy for Eigenvalue analysis when inverting matrices with rank problems
Definition at line 3666 of file TUnfold.cxx.
|
virtual |
Define input data for subsequent calls to DoUnfold(tau).
| [in] | input | input distribution with uncertainties |
| [in] | scaleBias | (default=0) scale factor applied to the bias |
| [in] | oneOverZeroError | (default=0) for bins with zero error, this number defines 1/error. |
| [in] | hist_vyy | (default=0) if non-zero, this defines the data covariance matrix |
| [in] | hist_vyy_inv | (default=0) if non-zero and hist_vyy is set, defines the inverse of the data covariance matrix. This feature can be useful for repeated unfoldings in cases where the inversion of the input covariance matrix is lengthy |
Return value: nError1+10000*nError2
Data members modified:
Reimplemented in TUnfoldSys.
Definition at line 2300 of file TUnfold.cxx.
|
protected |
|
private |
|
protected |
|
private |
|
protected |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
protected |
|
private |
|
protected |
|
private |
|
protected |
|
private |
|
private |
|
protected |
|
protected |
|
private |
|
private |
|
protected |
|
private |
|
protected |
ROOT 6.12/07 - Reference Guide Generated on Sat Sep 29 2018 23:44:26 (GVA Time) using Doxygen 1.8.13.