Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
TUnfoldSys Class Reference

An algorithm to unfold distributions from detector to truth level, with background subtraction and propagation of systematic uncertainties.

TUnfoldSys is used to decompose a measurement y into several sources x, given the measurement uncertainties, background b 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, TUnfoldSys has an adjustable regularisation term and also supports an optional constraint on the total number of events. Background sources can be specified, with a normalisation constant and normalisation uncertainty. In addition, variants of the response matrix may be specified, these are taken to determine systematic uncertainties.

For most applications, it is better to use the derived class TUnfoldDensity instead of TUnfoldSys. TUnfoldDensity adds features to TUnfoldSys, related to possible complex multidimensional arrangements of bins. For innocent users, the most notable improvement of TUnfoldDensity over TUnfoldSys are the getter functions. For TUnfoldSys, 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 recipy to use TUnfoldSys:

  • a matrix (truth,reconstructed) is given as a two-dimensional histogram as argument to the constructor of TUnfold
  • a vector of measurements is given as one-dimensional histogram using the SetInput() method
  • repeated calls to SubtractBackground() to specify background sources
  • repeated calls to AddSysError() to specify systematic uncertainties
  • The unfolding is performed
    • either once with a fixed parameter tau, method DoUnfold(tau)
    • or multiple times in a scan to determine the best chouce of tau, method ScanLCurve()
  • Unfolding results are retrieved using various GetXXX() methods

Description of (systematic) uncertainties available in TUnfoldSys. There are covariance matrix contributions and there are systematic shifts. Systematic shifts correspond to the variation of a (buicance) parameter, for example a background normalisation or a one-sigma variation of a correlated systematic error.

Set by Access covariance matrix Access vector of shifts Description
(a) TUnfoldSys constructor GetEmatrixSysUncorr() n.a. uncorrelated errors on the input matrix histA, taken as the errors provided with the histogram. These are typically statistical errors from finite Monte Carlo samples.
(b) AddSysError() GetEmatrixSysSource() GetDeltaSysSource() correlated shifts of the input matrix histA. These shifts are taken as one-sigma effects when switchig on a given error soure. Several such error sources may be defined
(c) SetTauError() GetEmatrixSysTau() GetDeltaSysTau() A systematic error on the regularisation parameter tau
(d) SubtractBackground() GetEmatrixSysBackgroundUncorr() n.a. uncorrelated errors on background sources, originating from the errors provided with the background histograms
(e) SubtractBackground() GetEmatrixSysBackgroundScale() GetDeltaSysBackgroundScale() scale errors on background sources
(i) SetInput() GetEmatrixInput() n.a. statistical uncertainty of the input (the measurement)
(i)+(d)+(e) see above GetEmatrix() n.a. Partial sun of uncertainties: all sources which are propagated to the covariance before unfolding
(i)+(a)+(b)+(c)+(d)+(e) see above GetEmatrixTotal() n.a. All known error sources summed up

Note: (a), (b), (c) are propagated to the result AFTER unfolding, whereas the background errors (d) and (e) are added to the data errors BEFORE unfolding. For this reason the errors of type (d) and (e) are INCLUDED in the standard error matrix and other methods provided by the base class TUnfold, whereas errors of type (a), (b), (c) are NOT INCLUDED in the methods provided by the base class TUnfold.


Version 17.6, with updated doxygen comments

History:

  • Version 17.5, in parallel to changes in TUnfold
  • Version 17.4, in parallel to changes in TUnfoldBinning
  • Version 17.3, in parallel to changes in TUnfoldBinning
  • Version 17.2, add methods to find back systematic and background sources
  • Version 17.1, bug fix with background uncertainty
  • Version 17.0, possibility to specify an error matrix with SetInput
  • Version 16.1, parallel to changes in TUnfold
  • Version 16.0, parallel to changes in TUnfold
  • Version 15, fix bugs with uncorr. uncertainties, add backgnd subtraction
  • Version 14, remove some print-out, do not add unused sys.errors
  • Version 13, support for systematic errors 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/.

Definition at line 55 of file TUnfoldSys.h.

Public Types

enum  ESysErrMode { kSysErrModeMatrix =0 , kSysErrModeShift =1 , kSysErrModeRelative =2 }
 type of matrix specified with AddSysError() More...
 
- Public Types inherited from TUnfold
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 = (1ULL << ( 0 )) , kOverwrite = (1ULL << ( 1 )) , kWriteDelete = (1ULL << ( 2 )) }
 
enum  EDeprecatedStatusBits { kObjInCanvas = (1ULL << ( 3 )) }
 
enum  EStatusBits {
  kCanDelete = (1ULL << ( 0 )) , kMustCleanup = (1ULL << ( 3 )) , kIsReferenced = (1ULL << ( 4 )) , kHasUUID = (1ULL << ( 5 )) ,
  kCannotPick = (1ULL << ( 6 )) , kNoContextMenu = (1ULL << ( 8 )) , kInvalidObject = (1ULL << ( 13 ))
}
 

Public Member Functions

 TUnfoldSys (const TH2 *hist_A, EHistMap histmap, ERegMode regmode=kRegModeSize, EConstraint constraint=kEConstraintArea)
 Set up response matrix A, uncorrelated uncertainties of A and regularisation scheme.
 
 TUnfoldSys (void)
 Only for use by root streamer or derived classes.
 
 ~TUnfoldSys (void) override
 
void AddSysError (const TH2 *sysError, const char *name, EHistMap histmap, ESysErrMode mode)
 Specify a correlated systematic uncertainty.
 
void GetBackground (TH1 *bgr, const char *bgrSource=nullptr, const Int_t *binMap=nullptr, Int_t includeError=3, Bool_t clearHist=kTRUE) const
 Get background into a histogram.
 
TSortedListGetBgrSources (void) const
 Get a new list of all background sources.
 
Double_t GetChi2Sys (void)
 Calculate total chi**2 including all systematic errors.
 
Bool_t GetDeltaSysBackgroundScale (TH1 *delta, const char *source, const Int_t *binMap=nullptr)
 Correlated one-sigma shifts from background normalisation uncertainty.
 
Bool_t GetDeltaSysSource (TH1 *hist_delta, const char *source, const Int_t *binMap=nullptr)
 Correlated one-sigma shifts correspinding to a given systematic uncertainty.
 
Bool_t GetDeltaSysTau (TH1 *delta, const Int_t *binMap=nullptr)
 Correlated one-sigma shifts from shifting tau.
 
void GetEmatrixInput (TH2 *ematrix, const Int_t *binMap=nullptr, Bool_t clearEmat=kTRUE)
 Covariance matrix contribution from input measurement uncertainties.
 
void GetEmatrixSysBackgroundScale (TH2 *ematrix, const char *source, const Int_t *binMap=nullptr, Bool_t clearEmat=kTRUE)
 Covariance contribution from background normalisation uncertainty.
 
void GetEmatrixSysBackgroundUncorr (TH2 *ematrix, const char *source, const Int_t *binMap=nullptr, Bool_t clearEmat=kTRUE)
 Covariance contribution from background uncorrelated uncertainty.
 
void GetEmatrixSysSource (TH2 *ematrix, const char *source, const Int_t *binMap=nullptr, Bool_t clearEmat=kTRUE)
 Covariance contribution from a systematic variation of the response matrix.
 
void GetEmatrixSysTau (TH2 *ematrix, const Int_t *binMap=nullptr, Bool_t clearEmat=kTRUE)
 Covariance matrix contribution from error on regularisation parameter.
 
void GetEmatrixSysUncorr (TH2 *ematrix, const Int_t *binMap=nullptr, Bool_t clearEmat=kTRUE)
 Covariance contribution from uncorrelated uncertainties of the response matrix.
 
void GetEmatrixTotal (TH2 *ematrix, const Int_t *binMap=nullptr)
 Get total error matrix, summing up all contributions.
 
void GetRhoItotal (TH1 *rhoi, const Int_t *binMap=nullptr, TH2 *invEmat=nullptr)
 Get global correlatiocn coefficients, summing up all contributions.
 
TSortedListGetSysSources (void) const
 Get a new list of all systematic uuncertainty sources.
 
TClassIsA () const override
 
Int_t SetInput (const TH1 *hist_y, Double_t scaleBias=0.0, Double_t oneOverZeroError=0.0, const TH2 *hist_vyy=nullptr, const TH2 *hist_vyy_inv=nullptr) override
 Define the input data for subsequent calls to DoUnfold(Double_t).
 
void SetTauError (Double_t delta_tau)
 Specify an uncertainty on tau.
 
void Streamer (TBuffer &) override
 Stream an object of class TObject.
 
void StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)
 
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.
 
- Public Member Functions inherited from TUnfold
 TUnfold (const TH2 *hist_A, EHistMap histmap, ERegMode regmode=kRegModeSize, EConstraint constraint=kEConstraintArea)
 Set up response matrix and regularisation scheme.
 
 TUnfold (void)
 Only for use by root streamer or derived classes.
 
 ~TUnfold (void) override
 
virtual Double_t DoUnfold (Double_t tau)
 Perform the unfolding for a given regularisation parameter tau.
 
Double_t DoUnfold (Double_t tau, const TH1 *hist_y, Double_t scaleBias=0.0)
 Perform the unfolding for a given input and regularisation.
 
void GetBias (TH1 *bias, const Int_t *binMap=nullptr) const
 Get bias vector including bias scale.
 
Double_t GetChi2A (void) const
 get χ2A contribution determined in recent unfolding
 
Double_t GetChi2L (void) const
 Get \( chi^{2}_{L} \) contribution determined in recent unfolding.
 
void GetEmatrix (TH2 *ematrix, const Int_t *binMap=nullptr) const
 Get output covariance matrix, possibly cumulated over several bins.
 
Double_t GetEpsMatrix (void) const
 get numerical accuracy for Eigenvalue analysis when inverting matrices with rank problems
 
void GetFoldedOutput (TH1 *folded, const Int_t *binMap=nullptr) const
 Get unfolding result on detector level.
 
void GetInput (TH1 *inputData, const Int_t *binMap=nullptr) const
 Input vector of measurements.
 
void GetInputInverseEmatrix (TH2 *ematrix)
 Get inverse of the measurement's covariance matrix.
 
void GetL (TH2 *l) const
 Get matrix of regularisation conditions.
 
virtual Double_t GetLcurveX (void) const
 Get value on x-axis of L-curve determined in recent unfolding.
 
virtual Double_t GetLcurveY (void) const
 Get value on y-axis of L-curve determined in recent unfolding.
 
void GetLsquared (TH2 *lsquared) const
 Get matrix of regularisation conditions squared.
 
Int_t GetNdf (void) const
 get number of degrees of freedom determined in recent unfolding
 
void GetNormalisationVector (TH1 *s, const Int_t *binMap=nullptr) const
 Histogram of truth bins, determined from summing over the response matrix.
 
Int_t GetNpar (void) const
 Get number of truth parameters determined in recent unfolding.
 
Int_t GetNr (void) const
 Get number of regularisation conditions.
 
void GetOutput (TH1 *output, const Int_t *binMap=nullptr) const
 Get output distribution, possibly cumulated over several bins.
 
void GetProbabilityMatrix (TH2 *A, EHistMap histmap) const
 Get matrix of probabilities.
 
Double_t GetRhoAvg (void) const
 get average global correlation determined in recent unfolding
 
Double_t GetRhoI (TH1 *rhoi, const Int_t *binMap=nullptr, TH2 *invEmat=nullptr) const
 Get global correlation coefficients, possibly cumulated over several bins.
 
void GetRhoIJ (TH2 *rhoij, const Int_t *binMap=nullptr) const
 Get correlation coefficients, possibly cumulated over several bins.
 
Double_t GetRhoMax (void) const
 get maximum global correlation determined in recent unfolding
 
Double_t GetTau (void) const
 Return regularisation parameter.
 
Int_t RegularizeBins (int start, int step, int nbin, ERegMode regmode)
 Add regularisation conditions for a group of bins.
 
Int_t RegularizeBins2D (int start_bin, int step1, int nbin1, int step2, int nbin2, ERegMode regmode)
 Add regularisation conditions for 2d unfolding.
 
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.
 
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.
 
Int_t RegularizeSize (int bin, Double_t scale=1.0)
 Add a regularisation condition on the magnitude of a truth bin.
 
virtual Int_t ScanLcurve (Int_t nPoint, Double_t tauMin, Double_t tauMax, TGraph **lCurve, TSpline **logTauX=nullptr, TSpline **logTauY=nullptr, TSpline **logTauCurvature=nullptr)
 Scan the L curve, determine tau and unfold at the final value of tau.
 
void SetBias (const TH1 *bias)
 Set bias vector.
 
void SetConstraint (EConstraint constraint)
 Set type of area constraint.
 
void SetEpsMatrix (Double_t eps)
 set numerical accuracy for Eigenvalue analysis when inverting matrices with rank problems
 
void StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)
 
- Public Member Functions inherited from TObject
 TObject ()
 TObject constructor.
 
 TObject (const TObject &object)
 TObject copy ctor.
 
virtual ~TObject ()
 TObject destructor.
 
void AbstractMethod (const char *method) const
 Use this method to implement an "abstract" method that you don't want to leave purely abstract.
 
virtual void AppendPad (Option_t *option="")
 Append graphics object to current pad.
 
virtual void Browse (TBrowser *b)
 Browse object. May be overridden for another default action.
 
ULong_t CheckedHash ()
 Check and record whether this class has a consistent Hash/RecursiveRemove setup (*) and then return the regular Hash value for this object.
 
virtual const char * ClassName () const
 Returns name of class to which the object belongs.
 
virtual void Clear (Option_t *="")
 
virtual TObjectClone (const char *newname="") const
 Make a clone of an object using the Streamer facility.
 
virtual Int_t Compare (const TObject *obj) const
 Compare abstract method.
 
virtual void Copy (TObject &object) const
 Copy this to obj.
 
virtual void Delete (Option_t *option="")
 Delete this object.
 
virtual Int_t DistancetoPrimitive (Int_t px, Int_t py)
 Computes distance from point (px,py) to the object.
 
virtual void Draw (Option_t *option="")
 Default Draw method for all objects.
 
virtual void DrawClass () const
 Draw class inheritance tree of the class to which this object belongs.
 
virtual TObjectDrawClone (Option_t *option="") const
 Draw a clone of this object in the current selected pad with: gROOT->SetSelectedPad(c1).
 
virtual void Dump () const
 Dump contents of object on stdout.
 
virtual void Error (const char *method, const char *msgfmt,...) const
 Issue error message.
 
virtual void Execute (const char *method, const char *params, Int_t *error=nullptr)
 Execute method on this object with the given parameter string, e.g.
 
virtual void Execute (TMethod *method, TObjArray *params, Int_t *error=nullptr)
 Execute method on this object with parameters stored in the TObjArray.
 
virtual void ExecuteEvent (Int_t event, Int_t px, Int_t py)
 Execute action corresponding to an event at (px,py).
 
virtual void Fatal (const char *method, const char *msgfmt,...) const
 Issue fatal error message.
 
virtual TObjectFindObject (const char *name) const
 Must be redefined in derived classes.
 
virtual TObjectFindObject (const TObject *obj) const
 Must be redefined in derived classes.
 
virtual Option_tGetDrawOption () const
 Get option used by the graphics system to draw this object.
 
virtual const char * GetIconName () const
 Returns mime type name of object.
 
virtual const char * GetName () const
 Returns name of object.
 
virtual char * GetObjectInfo (Int_t px, Int_t py) const
 Returns string containing info about the object at position (px,py).
 
virtual Option_tGetOption () const
 
virtual const char * GetTitle () const
 Returns title of object.
 
virtual UInt_t GetUniqueID () const
 Return the unique object id.
 
virtual Bool_t HandleTimer (TTimer *timer)
 Execute action in response of a timer timing out.
 
virtual ULong_t Hash () const
 Return hash value for this object.
 
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.
 
virtual void Info (const char *method, const char *msgfmt,...) const
 Issue info message.
 
virtual Bool_t InheritsFrom (const char *classname) const
 Returns kTRUE if object inherits from class "classname".
 
virtual Bool_t InheritsFrom (const TClass *cl) const
 Returns kTRUE if object inherits from TClass cl.
 
virtual void Inspect () const
 Dump contents of this object in a graphics canvas.
 
void InvertBit (UInt_t f)
 
Bool_t IsDestructed () const
 IsDestructed.
 
virtual Bool_t IsEqual (const TObject *obj) const
 Default equal comparison (objects are equal if they have the same address in memory).
 
virtual Bool_t IsFolder () const
 Returns kTRUE in case object contains browsable objects (like containers or lists of other objects).
 
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.
 
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).
 
virtual Bool_t Notify ()
 This method must be overridden to handle object notification (the base implementation is no-op).
 
void Obsolete (const char *method, const char *asOfVers, const char *removedFromVers) const
 Use this method to declare a method obsolete.
 
void operator delete (void *ptr)
 Operator delete.
 
void operator delete[] (void *ptr)
 Operator delete [].
 
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)
 
TObjectoperator= (const TObject &rhs)
 TObject assignment operator.
 
virtual void Paint (Option_t *option="")
 This method must be overridden if a class wants to paint itself.
 
virtual void Pop ()
 Pop on object drawn in a pad to the top of the display list.
 
virtual void Print (Option_t *option="") const
 This method must be overridden when a class wants to print itself.
 
virtual Int_t Read (const char *name)
 Read contents of object with specified name from the current directory.
 
virtual void RecursiveRemove (TObject *obj)
 Recursively remove this object from a list.
 
void ResetBit (UInt_t f)
 
virtual void SaveAs (const char *filename="", Option_t *option="") const
 Save this object in the file specified by filename.
 
virtual void SavePrimitive (std::ostream &out, Option_t *option="")
 Save a primitive as a C++ statement(s) on output stream "out".
 
void SetBit (UInt_t f)
 
void SetBit (UInt_t f, Bool_t set)
 Set or unset the user status bits as specified in f.
 
virtual void SetDrawOption (Option_t *option="")
 Set drawing option for object.
 
virtual void SetUniqueID (UInt_t uid)
 Set the unique object id.
 
void StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)
 
virtual void SysError (const char *method, const char *msgfmt,...) const
 Issue system error message.
 
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.
 
virtual void Warning (const char *method, const char *msgfmt,...) const
 Issue warning message.
 
virtual Int_t Write (const char *name=nullptr, Int_t option=0, Int_t bufsize=0)
 Write this object to the current directory.
 
virtual Int_t Write (const char *name=nullptr, Int_t option=0, Int_t bufsize=0) const
 Write this object to the current directory.
 

Static Public Member Functions

static TClassClass ()
 
static const char * Class_Name ()
 
static constexpr Version_t Class_Version ()
 
static const char * DeclFileName ()
 
- Static Public Member Functions inherited from TUnfold
static TClassClass ()
 
static const char * Class_Name ()
 
static constexpr Version_t Class_Version ()
 
static const char * DeclFileName ()
 
static const char * GetTUnfoldVersion (void)
 Return a string describing the TUnfold version.
 
- Static Public Member Functions inherited from TObject
static TClassClass ()
 
static const char * Class_Name ()
 
static constexpr Version_t Class_Version ()
 
static const char * DeclFileName ()
 
static Longptr_t GetDtorOnly ()
 Return destructor only flag.
 
static Bool_t GetObjectStat ()
 Get status of object stat flag.
 
static void SetDtorOnly (void *obj)
 Set destructor only flag.
 
static void SetObjectStat (Bool_t stat)
 Turn on/off tracking of objects in the TObjectTable.
 

Protected Member Functions

void ClearResults (void) override
 Clear all data members which depend on the unfolding results.
 
void DoBackgroundSubtraction (void)
 Perform background subtraction.
 
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.
 
TMatrixDSparseGetSummedErrorMatrixXX (void)
 Determine total error matrix on the vector x.
 
TMatrixDSparseGetSummedErrorMatrixYY (void)
 Determine total error matrix on the vector Ax.
 
virtual TMatrixDSparsePrepareCorrEmat (const TMatrixDSparse *m1, const TMatrixDSparse *m2, const TMatrixDSparse *dsys)
 Propagate correlated systematic shift to an output vector.
 
virtual void PrepareSysError (void)
 Matrix calculations required to propagate systematic errors.
 
virtual TMatrixDSparsePrepareUncorrEmat (const TMatrixDSparse *m1, const TMatrixDSparse *m2)
 Propagate uncorrelated systematic errors to a covariance matrix.
 
void ScaleColumnsByVector (TMatrixDSparse *m, const TMatrixTBase< Double_t > *v) const
 Scale columns of a matrix by the corresponding rows of a vector.
 
void VectorMapToHist (TH1 *hist_delta, const TMatrixDSparse *delta, const Int_t *binMap)
 Map delta to hist_delta, possibly summing up bins.
 
- Protected Member Functions inherited from TUnfold
void AddMSparse (TMatrixDSparse *dest, Double_t f, const TMatrixDSparse *src) const
 Add a sparse matrix, scaled by a factor, to another scaled matrix.
 
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.
 
Bool_t AddRegularisationCondition (Int_t nEle, const Int_t *indices, const Double_t *rowData)
 Add a row of regularisation conditions to the matrix L.
 
void ClearHistogram (TH1 *h, Double_t x=0.) const
 Initialize bin contents and bin errors for a given histogram.
 
TMatrixDSparseCreateSparseMatrix (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.
 
virtual Double_t DoUnfold (void)
 Core unfolding algorithm.
 
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.
 
const TMatrixDSparseGetAx (void) const
 vector of folded-back result
 
Int_t GetBinFromRow (int ix) const
 converts matrix row to truth histogram bin number
 
const TMatrixDSparseGetDXDAM (int i) const
 matrix contributions of the derivative dx/dA
 
const TMatrixDSparseGetDXDAZ (int i) const
 vector contributions of the derivative dx/dA
 
const TMatrixDSparseGetDXDtauSquared (void) const
 vector of derivative dx/dtauSquared, using internal bin counting
 
const TMatrixDSparseGetDXDY (void) const
 matrix of derivatives dx/dy
 
const TMatrixDSparseGetE (void) const
 matrix E, using internal bin counting
 
const TMatrixDSparseGetEinv (void) const
 matrix E-1, using internal bin counting
 
Int_t GetNx (void) const
 returns internal number of output (truth) matrix rows
 
Int_t GetNy (void) const
 returns the number of measurement bins
 
virtual TString GetOutputBinName (Int_t iBinX) const
 Get bin name of an output bin.
 
Double_t GetRhoIFromMatrix (TH1 *rhoi, const TMatrixDSparse *eOrig, const Int_t *binMap, TH2 *invEmat) const
 Get global correlation coefficients with arbitrary min map.
 
Int_t GetRowFromBin (int ix) const
 converts truth histogram bin number to matrix row
 
const TMatrixDSparseGetVxx (void) const
 covariance matrix of the result
 
const TMatrixDSparseGetVxxInv (void) const
 inverse of covariance matrix of the result
 
const TMatrixDSparseGetVyyInv (void) const
 inverse of covariance matrix of the data y
 
const TMatrixDGetX (void) const
 vector of the unfolding result
 
TMatrixDSparseInvertMSparseSymmPos (const TMatrixDSparse *A, Int_t *rank) const
 Get the inverse or pseudo-inverse of a positive, sparse matrix.
 
TMatrixDSparseMultiplyMSparseM (const TMatrixDSparse *a, const TMatrixD *b) const
 Multiply sparse matrix and a non-sparse matrix.
 
TMatrixDSparseMultiplyMSparseMSparse (const TMatrixDSparse *a, const TMatrixDSparse *b) const
 Multiply two sparse matrices.
 
TMatrixDSparseMultiplyMSparseMSparseTranspVector (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.
 
TMatrixDSparseMultiplyMSparseTranspMSparse (const TMatrixDSparse *a, const TMatrixDSparse *b) const
 Multiply a transposed Sparse matrix with another sparse matrix,.
 
- 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).
 
void MakeZombie ()
 

Protected Attributes

TMatrixDfAoutside
 Input: underflow/overflow bins.
 
TMapfBgrErrScaleIn
 Input: background sources correlated error.
 
TMapfBgrErrUncorrInSq
 Input: uncorr error squared from bgr sources.
 
TMapfBgrIn
 Input: size of background sources.
 
TMatrixDfDAinColRelSq
 Input: normalized column err.sq. (inp.matr.)
 
TMatrixDSparsefDAinRelSq
 Input: normalized errors from input matrix.
 
TMapfDeltaCorrAx
 Result: syst.shift from fSysIn on fAx.
 
TMapfDeltaCorrX
 Result: syst.shift from fSysIn on fX.
 
TMatrixDSparsefDeltaSysTau
 Result: systematic shift from tau.
 
Double_t fDtau
 Input: error on tau.
 
TMatrixDSparsefEmatUncorrAx
 Result: syst.error from fDA2 on fAx.
 
TMatrixDSparsefEmatUncorrX
 Result: syst.error from fDA2 on fX.
 
TMapfSysIn
 Input: correlated errors.
 
TMatrixDSparsefVyyData
 Input: error on fY prior to bgr subtraction.
 
TMatrixDfYData
 Input: fY prior to bgr subtraction.
 
- Protected Attributes inherited from TUnfold
TMatrixDSparsefA
 response matrix A
 
Double_t fBiasScale
 scale factor for the bias
 
EConstraint fConstraint
 type of constraint to use for the unfolding
 
TArrayI fHistToX
 mapping of histogram bins to matrix indices
 
TMatrixDSparsefL
 regularisation conditions L
 
ERegMode fRegMode
 type of regularisation
 
TArrayD fSumOverY
 truth vector calculated from the non-normalized response matrix
 
Double_t fTauSquared
 regularisation parameter tau squared
 
TMatrixDSparsefVyy
 covariance matrix Vyy corresponding to y
 
TMatrixDfX0
 bias vector x0
 
TArrayI fXToHist
 mapping of matrix indices to histogram bins
 
TMatrixDfY
 input (measured) data y
 

Private Member Functions

void InitTUnfoldSys (void)
 Initialize pointers and TMaps.
 

Additional Inherited Members

- Protected Types inherited from TObject
enum  { kOnlyPrepStep = (1ULL << ( 3 )) }
 
- Static Protected Member Functions inherited from TUnfold
static void DeleteMatrix (TMatrixD **m)
 delete matrix and invalidate pointer
 
static void DeleteMatrix (TMatrixDSparse **m)
 delete sparse matrix and invalidate pointer
 

#include <TUnfoldSys.h>

Inheritance diagram for TUnfoldSys:
[legend]

Member Enumeration Documentation

◆ ESysErrMode

type of matrix specified with AddSysError()

Enumerator
kSysErrModeMatrix 

matrix is an alternative to the default matrix, the errors are the difference to the original matrix

kSysErrModeShift 

matrix gives the absolute shifts

kSysErrModeRelative 

matrix gives the relative shifts

Definition at line 102 of file TUnfoldSys.h.

Constructor & Destructor Documentation

◆ TUnfoldSys() [1/2]

TUnfoldSys::TUnfoldSys ( const TH2 hist_A,
EHistMap  histmap,
ERegMode  regmode = kRegModeSize,
EConstraint  constraint = kEConstraintArea 
)

Set up response matrix A, uncorrelated uncertainties of A and regularisation scheme.

Parameters
[in]hist_Amatrix that describes the migrations
[in]histmapmapping of the histogram axes to the unfolding output
[in]regmode(default=kRegModeSize) global regularisation mode
[in]constraint(default=kEConstraintArea) type of constraint

For further details, consult the constructir of the class TUnfold. The uncertainties of hist_A are taken to be uncorrelated and aper propagated to the unfolding result, method GetEmatrixSysUncorr().

Definition at line 157 of file TUnfoldSys.cxx.

◆ TUnfoldSys() [2/2]

TUnfoldSys::TUnfoldSys ( void  )

Only for use by root streamer or derived classes.

Definition at line 138 of file TUnfoldSys.cxx.

◆ ~TUnfoldSys()

TUnfoldSys::~TUnfoldSys ( void  )
override

Definition at line 119 of file TUnfoldSys.cxx.

Member Function Documentation

◆ AddSysError()

void TUnfoldSys::AddSysError ( const TH2 sysError,
const char *  name,
EHistMap  histmap,
ESysErrMode  mode 
)

Specify a correlated systematic uncertainty.

Parameters
[in]sysErroralternative matrix or matrix of absolute/relative shifts
[in]nameidentifier of the error source
[in]histmapmapping of the histogram axes
[in]modeformat of the error source

sysError corresponds to a one-sigma variation. If may be given in various forms, specified by mode

  • mode=kSysErrModeMatrix the histogram sysError corresponds to an alternative response matrix.
  • mode=kSysErrModeShift the content of the histogram sysError are the absolute shifts of the response matrix
  • mode=kSysErrModeRelative the content of the histogram sysError specifies the relative uncertainties

Internally, all three cases are transformed to the case mode=kSysErrModeMatrix.

Definition at line 247 of file TUnfoldSys.cxx.

◆ Class()

static TClass * TUnfoldSys::Class ( )
static
Returns
TClass describing this class

◆ Class_Name()

static const char * TUnfoldSys::Class_Name ( )
static
Returns
Name of this class

◆ Class_Version()

static constexpr Version_t TUnfoldSys::Class_Version ( )
inlinestaticconstexpr
Returns
Version of this class

Definition at line 142 of file TUnfoldSys.h.

◆ ClearResults()

void TUnfoldSys::ClearResults ( void  )
overrideprotectedvirtual

Clear all data members which depend on the unfolding results.

Reimplemented from TUnfold.

Definition at line 616 of file TUnfoldSys.cxx.

◆ DeclFileName()

static const char * TUnfoldSys::DeclFileName ( )
inlinestatic
Returns
Name of the file containing the class declaration

Definition at line 142 of file TUnfoldSys.h.

◆ DoBackgroundSubtraction()

void TUnfoldSys::DoBackgroundSubtraction ( void  )
protected

Perform background subtraction.

This prepares the data members for the base class TUnfold, such that the background is properly taken into account.

Definition at line 333 of file TUnfoldSys.cxx.

◆ GetBackground()

void TUnfoldSys::GetBackground ( TH1 bgrHist,
const char *  bgrSource = nullptr,
const Int_t binMap = nullptr,
Int_t  includeError = 3,
Bool_t  clearHist = kTRUE 
) const

Get background into a histogram.

Parameters
[in,out]bgrHisttarget histogram, content and errors will be altered
[in]bgrSource(default=0) name of backgrond source or zero to add all sources of background
[in]binMap(default=0) remap histogram bins
[in]includeError(default=3) include uncorrelated(1), correlated (2) or both (3) sources of uncertainty in the histogram errors
[in]clearHist(default=true) reset histogram before adding up the specified background sources

the array binMap is explained with the method GetOutput(). The flag clearHist may be used to add background from several sources in successive calls to GetBackground().

Definition at line 529 of file TUnfoldSys.cxx.

◆ GetBgrSources()

TSortedList * TUnfoldSys::GetBgrSources ( void  ) const

Get a new list of all background sources.

The user is responsible for deleting the list get list of name of background sources

Definition at line 1514 of file TUnfoldSys.cxx.

◆ GetChi2Sys()

Double_t TUnfoldSys::GetChi2Sys ( void  )

Calculate total chi**2 including all systematic errors.

Definition at line 1345 of file TUnfoldSys.cxx.

◆ GetDeltaSysBackgroundScale()

Bool_t TUnfoldSys::GetDeltaSysBackgroundScale ( TH1 hist_delta,
const char *  source,
const Int_t binMap = nullptr 
)

Correlated one-sigma shifts from background normalisation uncertainty.

Parameters
[out]hist_deltahistogram to store shifts
[in]sourceidentifier of the background source
[in]binMap(default=0) remapping of histogram bins

returns true if the background source was found.

This method returns the shifts of the unfolding result induced by varying the normalisation of the identified background by one sigma.

the array binMap is explained with the method GetOutput().

Definition at line 1026 of file TUnfoldSys.cxx.

◆ GetDeltaSysSource()

Bool_t TUnfoldSys::GetDeltaSysSource ( TH1 hist_delta,
const char *  name,
const Int_t binMap = nullptr 
)

Correlated one-sigma shifts correspinding to a given systematic uncertainty.

Parameters
[out]hist_deltahistogram to store shifts
[in]nameidentifier of the background source
[in]binMap(default=0) remapping of histogram bins

returns true if the error source was found.

This method returns the shifts of the unfolding result induced by varying the identified systematic source by one sigma.

the array binMap is explained with the method GetOutput().

Definition at line 999 of file TUnfoldSys.cxx.

◆ GetDeltaSysTau()

Bool_t TUnfoldSys::GetDeltaSysTau ( TH1 hist_delta,
const Int_t binMap = nullptr 
)

Correlated one-sigma shifts from shifting tau.

Parameters
[out]hist_deltahistogram to store shifts
[in]binMap(default=0) remapping of histogram bins

returns true if the background source was found.

This method returns the shifts of the unfolding result induced by varying the normalisation of the identified background by one sigma.

the array binMap is explained with the method GetOutput().

calculate systematic shift from tau variation

Definition at line 1061 of file TUnfoldSys.cxx.

◆ GetEmatrixFromVyy()

void TUnfoldSys::GetEmatrixFromVyy ( const TMatrixDSparse vyy,
TH2 ematrix,
const Int_t binMap,
Bool_t  clearEmat 
)
protected

Propagate an error matrix on the input vector to the unfolding result.

Parameters
[in]vyyinput error matrix
[in,out]ematrixhistogram to be updated
[in]binMapmapping of histogram bins
[in]clearEmatif set, clear histogram before adding this covariance contribution

propagate error matrix vyy to the result

  • vyy: error matrix on input data fY
  • ematrix: output
  • binMap: see method GetEmatrix()
  • clearEmat: set kTRUE to clear the histogram prior to adding the errors

Definition at line 1230 of file TUnfoldSys.cxx.

◆ GetEmatrixInput()

void TUnfoldSys::GetEmatrixInput ( TH2 ematrix,
const Int_t binMap = nullptr,
Bool_t  clearEmat = kTRUE 
)

Covariance matrix contribution from input measurement uncertainties.

Parameters
[in,out]ematrixoutput histogram
[in]binMap(default=0) remapping of histogram bins
[in]clearEmat(default=true) if true, clear the histogram

this method returns the covariance contributions to the unfolding result from the uncertainties or covariance of the input data. In many cases, these are the "statistical uncertainties".

The array binMap is explained with the method GetOutput(). The flag clearEmat may be used to add covariance matrices from several uncertainty sources.

Definition at line 1180 of file TUnfoldSys.cxx.

◆ GetEmatrixSysBackgroundScale()

void TUnfoldSys::GetEmatrixSysBackgroundScale ( TH2 ematrix,
const char *  name,
const Int_t binMap = nullptr,
Bool_t  clearEmat = kTRUE 
)

Covariance contribution from background normalisation uncertainty.

Parameters
[in,out]ematrixoutput histogram
[in]nameidentifier of the background source
[in]binMap(default=0) remapping of histogram bins
[in]clearEmat(default=true) if true, clear the histogram prior to adding the covariance matrix contribution

this method returns the uncertainties on the unfolding result arising from the background source source and its normalisation uncertainty. See method SubtractBackground() how to set the normalisation uncertainty

the array binMap is explained with the method GetOutput(). The flag clearEmat may be used to add covariance matrices from several uncertainty sources.

Definition at line 1116 of file TUnfoldSys.cxx.

◆ GetEmatrixSysBackgroundUncorr()

void TUnfoldSys::GetEmatrixSysBackgroundUncorr ( TH2 ematrix,
const char *  source,
const Int_t binMap = nullptr,
Bool_t  clearEmat = kTRUE 
)

Covariance contribution from background uncorrelated uncertainty.

Parameters
[in]ematrixoutput histogram
[in]sourceidentifier of the background source
[in]binMap(default=0) remapping of histogram bins
[in]clearEmat(default=true) if true, clear the histogram

this method returns the covariance contributions to the unfolding result arising from the background source source and the uncorrelated (background histogram uncertainties). Also see method SubtractBackground()

the array binMap is explained with the method GetOutput(). The flag clearEmat may be used to add covariance matrices from several uncertainty sources.

Definition at line 1202 of file TUnfoldSys.cxx.

◆ GetEmatrixSysSource()

void TUnfoldSys::GetEmatrixSysSource ( TH2 ematrix,
const char *  name,
const Int_t binMap = nullptr,
Bool_t  clearEmat = kTRUE 
)

Covariance contribution from a systematic variation of the response matrix.

Parameters
[in,out]ematrixcovariance matrix histogram
[in]nameidentifier of the systematic variation
[in]binMap(default=0) remapping of histogram bins
[in]clearEmat(default=true) if true, clear the histogram prior to adding the covariance matrix contribution

Returns the covariance matrix contribution from shifting the given uncertainty source within one sigma

the array binMap is explained with the method GetOutput(). The flag clearEmat may be used to add covariance matrices from several uncertainty sources.

Definition at line 1085 of file TUnfoldSys.cxx.

◆ GetEmatrixSysTau()

void TUnfoldSys::GetEmatrixSysTau ( TH2 ematrix,
const Int_t binMap = nullptr,
Bool_t  clearEmat = kTRUE 
)

Covariance matrix contribution from error on regularisation parameter.

Parameters
[in,out]ematrixoutput histogram
[in]binMap(default=0) remapping of histogram bins
[in]clearEmat(default=true) if true, clear the histogram

this method returns the covariance contributions to the unfolding result from the assigned uncertainty on the parameter tau, see method SetTauError().

the array binMap is explained with the method GetOutput(). The flag clearEmat may be used to add covariance matrices from several uncertainty sources.

Calculate error matrix from error in regularisation parameter

  • ematrix: output
  • binMap: see method GetEmatrix()
  • clearEmat: set kTRUE to clear the histogram prior to adding the errors

Definition at line 1153 of file TUnfoldSys.cxx.

◆ GetEmatrixSysUncorr()

void TUnfoldSys::GetEmatrixSysUncorr ( TH2 ematrix,
const Int_t binMap = nullptr,
Bool_t  clearEmat = kTRUE 
)

Covariance contribution from uncorrelated uncertainties of the response matrix.

Parameters
[in,out]ematrixcovariance matrix histogram
[in]binMapmapping of histogram bins
[in]clearEmatif true, ematrix is cleared prior to adding this covariance matrix contribution

This method propagates the uncertainties of the response matrix histogram, specified with the constructor, to the unfolding result. It is assumed that the entries of that histogram are bin-to-bin uncorrelated. In many cases this corresponds to the "Monte Carlo statistical uncertainties".

The array binMap is explained with the method GetOutput(). The flag clearEmat may be used to add covariance matrices from several uncertainty sources.

data members modified: fVYAx, fESparse, fEAtV, fErrorAStat

Definition at line 730 of file TUnfoldSys.cxx.

◆ GetEmatrixTotal()

void TUnfoldSys::GetEmatrixTotal ( TH2 ematrix,
const Int_t binMap = nullptr 
)

Get total error matrix, summing up all contributions.

Parameters
[out]ematrixhistogram which will be filled
[in]binMap(default=0) remapping of histogram bins

the array binMap is explained with the method GetOutput().

get total error including statistical error

Definition at line 1256 of file TUnfoldSys.cxx.

◆ GetRhoItotal()

void TUnfoldSys::GetRhoItotal ( TH1 rhoi,
const Int_t binMap = nullptr,
TH2 invEmat = nullptr 
)

Get global correlatiocn coefficients, summing up all contributions.

Parameters
[out]rhoihistogram which will be filled
[in]binMap(default=0) remapping of histogram bins
[out]invEmat(default=0) inverse of error matrix

return the global correlation coefficients, including all error sources. If invEmat is nonzero, the inverse of the error matrix is returned in that histogram

the array binMap is explained with the method GetOutput().

get global correlation coefficients including systematic,statistical,background,tau errors

  • rhoi: output histogram
  • binMap: for each global bin, indicate in which histogram bin to store its content
  • invEmat: output histogram for inverse of error matrix (pointer may zero if inverse is not requested)

Definition at line 1388 of file TUnfoldSys.cxx.

◆ GetSummedErrorMatrixXX()

TMatrixDSparse * TUnfoldSys::GetSummedErrorMatrixXX ( void  )
protected

Determine total error matrix on the vector x.

Definition at line 1310 of file TUnfoldSys.cxx.

◆ GetSummedErrorMatrixYY()

TMatrixDSparse * TUnfoldSys::GetSummedErrorMatrixYY ( void  )
protected

Determine total error matrix on the vector Ax.

Definition at line 1274 of file TUnfoldSys.cxx.

◆ GetSysSources()

TSortedList * TUnfoldSys::GetSysSources ( void  ) const

Get a new list of all systematic uuncertainty sources.

The user is responsible for deleting the list get list of names of systematic sources

Definition at line 1499 of file TUnfoldSys.cxx.

◆ InitTUnfoldSys()

void TUnfoldSys::InitTUnfoldSys ( void  )
private

Initialize pointers and TMaps.

Definition at line 586 of file TUnfoldSys.cxx.

◆ IsA()

TClass * TUnfoldSys::IsA ( ) const
inlineoverridevirtual
Returns
TClass describing current object

Reimplemented from TUnfold.

Definition at line 142 of file TUnfoldSys.h.

◆ PrepareCorrEmat()

TMatrixDSparse * TUnfoldSys::PrepareCorrEmat ( const TMatrixDSparse m1,
const TMatrixDSparse m2,
const TMatrixDSparse dsys 
)
protectedvirtual

Propagate correlated systematic shift to an output vector.

Parameters
[in]m1coefficients
[in]m2coeffiicients
[in]dsysmatrix of correlated shifts from this source propagate correlated systematic shift to output vector m1,m2 : coefficients for propagating the errors dsys : matrix of correlated shifts from this source

\[ \delta_m = \sum{i,j} { ((*m1)(m,j) * (*fVYAx)(i) - (*m2)(m,i) * (*fX)(j))*dsys(i,j) } = \sum_j (*m1)(m,j) \sum_i dsys(i,j) * (*fVYAx)(i) - \sum_i (*m2)(m,i) \sum_j dsys(i,j) * (*fX)(j) \]

Definition at line 958 of file TUnfoldSys.cxx.

◆ PrepareSysError()

void TUnfoldSys::PrepareSysError ( void  )
protectedvirtual

Matrix calculations required to propagate systematic errors.

data members modified: fEmatUncorrX, fEmatUncorrAx, fDeltaCorrX, fDeltaCorrAx

Definition at line 632 of file TUnfoldSys.cxx.

◆ PrepareUncorrEmat()

TMatrixDSparse * TUnfoldSys::PrepareUncorrEmat ( const TMatrixDSparse m_0,
const TMatrixDSparse m_1 
)
protectedvirtual

Propagate uncorrelated systematic errors to a covariance matrix.

Parameters
[in]m_0coefficients for error propagation
[in]m_1coefficients for error propagation

Returns the covariance matrix, propagates uncorrelated systematic errors to a covariance matrix. m_0,m_1 are the coefficients (matrices) for propagating the errors.

The error matrix is calculated by standard error propagation, where the derivative of the result vector X wrt the matrix A is given by:

\[ \frac{dX_k}{dA_{ij}} = M0_{kj} Z0_i - M1_{ki} Z1_j \]

where: the matrices M0 and M1 are arguments to this function the vectors Z0, Z1 : GetDXDAZ()

The matrix A is calculated from a matrix B as

\[ A_{ij} = \frac{B_{ij}}{\sum_k B_{kj}} \]

where k runs over additional indices of B, not present in A. (underflow and overflow bins, used for efficiency corrections)

define: \( Norm_j = \sum_k B_{kj} \) (data member fSumOverY)

the derivative of A wrt this input matrix B is given by:

\[ \frac{dA_{ij}}{dB_{kj}} = (\delta_{ik} - A_{ij} ) \frac{1}{Norm_j} \]

The covariance matrix Vxx is:

\[ Vxx_{mn} = \sum_{ijlk} \big[ (\frac{dX_m}{dA_{ij}}) (\frac{dA_{ij}}{dB_{}kj}) DB_{kj} (\frac{dX_n}{dA_{lj}}) (\frac{dA_{lj}}{dB_{kj}}) \big] \]

where \( DB_{kj} \) is the error on \( B_{kj} \) squared.

Simplify the sum over k:

\[ \sum_k \big[ (\frac{dA_{ij}}{dB_{kj}}) DB_{kj} (\frac{dA_{lj}}{dB_{kj}}) \big] = \sum_k \big[ (\delta_{ik} - A_{ij} ) \frac{1}{Norm_j} DB_{kj} (\delta_{lk} - A_{lj} ) \frac{1}{Norm_j} \big] = \sum_k \big[ (\delta_{ik} \delta_{lk} - \delta_{ik} A_{lj} - \delta_{lk} A_{ij} + A_{ij} A_{lj} ) \frac{DB_{kj}}{Norm_j^2} \big] \]

introduce normalized errors: \( Rsq_{kj} = \frac{DB_{kj}}{Norm_j^2} \)

after summing over k:

\[ \delta_{ik} \delta_{lk} Rsq_{kj} \to \delta_{il} Rsq_{ij} \]

\[ \delta_{ik} A_{lj} Rsq_{kj} \to A_{lj} Rsq_{ij} \]

\[ \delta_{lk} A_{ij} Rsq_{kj} \to A_{ij} Rsq_{lj} \]

\[ A_{ij} A_{lj} Rsq_{kj} \to A_{ij} A_{lj} \sum_k(Rsq_{kj}) \]

introduce sum of normalized errors squared: \( SRsq_j = \sum_k(Rsq_{kj}) \)

Note: \( Rsq_{ij} \) is stored as fDAinRelSq (excludes extra indices of B) and \( SRsq_j \) is stored as fDAinColRelSq (sum includes all indices of B)

\[ Vxx_{nm} = \sum_{ijl} \big[ (\frac{dX_m}{dA_{ij}}) (\frac{dX_n}{dA_{lj}}) (\delta_{il} Rsq_{ij} - A_{lj} Rsq_{ij} - A_{ij} Rsq_{lj} + A_{ij} A_{lj} SRsq_j) \big] \]

\[ Vxx_nm = \sum_j \big[ F_{mj} F_{nj} SRsq_j \big] - \sum_j \big[ G_{mj} F_{nj} \big] - \sum_j \big[ F_{mj} G_{nj} \big] + \sum_{ij} \big[ (\frac{dX_m}{dA_{ij}}) (\frac{dX_n}{dA_{lj}}) Rsq_{ij} \big] \]

where:

\[ F_{mj} = \sum_i \big[ (\frac{dX_m}{dA_{ij}}) * A_{ij} \big] \]

\[ G_{mj} = \sum_i \big[ (\frac{dX_m}{dA_{ij}}) Rsq_{ij} \big] \]

In order to avoid explicitly calculating the 3-dimensional tensor \((\frac{dX_m}{dA_{ij}}) \) the sums are evaluated further, using:

\[ \frac{dX_k}{dA_{ij}} = M0_{kj} Z0_i - M1_{ki} Z1_j \]

\[ F_{mj} = M0_{mj} * (A\# Z0)_j - (M1 A)_{mj} Z1_j \]

\[ G_{mj} = M0_{mj} * (Rsq\# Z0)_j - (M1 Rsq)_{mj} Z1_j \]

and

\[ \sum_{ij} \big[ (\frac{dX_m}{dA_{ij}}) (\frac{dX_n}{dA_{ij}}) Rsq_{ij} \big] = \sum_j \big[ M0_{mj} M0_nj \big[ \sum_i (Z0_i)^2 Rsq_{ij} \big] \big] + \sum_i \big[ M1_{mi} M1_{ni} \big[ \sum_j (Z1_j)^2 Rsq_{ij} \big] \big] - \sum_i \big[ M1_{mi} H_{ni} + M1_{ni} H_{mi} \big] \]

where:

\[ H_{mi} = Z0_i \sum_j \big[ M0_{mj} Z1_j Rsq_{ij} \big] \]

collect all contributions:

\[ Vxx_nm = r0 -r1 -r2 +r3 +r4 -r5 -r6 \]

\[ r0 = \sum_j \big[ F_{mj} F_nj * SRsq_j \big] \]

\[ r1 = \sum_j \big[ G_{mj} F_nj \big] \]

\[ r2 = \sum_j \big[ F_{mj} G_nj \big] \]

\[ r3 = \sum_j \big[ M0_{mj} M0_nj \big[ \sum_i (Z0_i)^2 Rsq_{ij} \big] \big] \]

\[ r4 = \sum_i \big[ M1_{mi} M1_{ni} \big[ \sum_j (Z1_j)^2 Rsq_{ij} \big] \big] \]

\[ r5 = \sum_i \big[ M1_{mi} H_{ni} \big] \]

\[ r6 = \sum_i \big[ M1_{ni} H_{mi} \big] \]

Definition at line 837 of file TUnfoldSys.cxx.

◆ ScaleColumnsByVector()

void TUnfoldSys::ScaleColumnsByVector ( TMatrixDSparse m,
const TMatrixTBase< Double_t > *  v 
) const
protected

Scale columns of a matrix by the corresponding rows of a vector.

Parameters
[in,out]mmatrix
[in]vvector

the entries mij are multiplied by vj.

scale columns of m by the corresponding rows of v input:

  • m: pointer to sparse matrix of dimension NxM
  • v: pointer to matrix of dimension Mx1

Definition at line 1410 of file TUnfoldSys.cxx.

◆ SetInput()

Int_t TUnfoldSys::SetInput ( const TH1 hist_y,
Double_t  scaleBias = 0.0,
Double_t  oneOverZeroError = 0.0,
const TH2 hist_vyy = nullptr,
const TH2 hist_vyy_inv = nullptr 
)
overridevirtual

Define the input data for subsequent calls to DoUnfold(Double_t).

input: input distribution with errors

  • scaleBias: scale factor applied to the bias
  • oneOverZeroError: for bins with zero error, this number defines 1/error.

Return value: number of bins with bad error +10000*number of unconstrained output bins

Note: return values>=10000 are fatal errors, for the given input, the unfolding can not be done!

Calls the SetInput method of the base class, then renames the input vectors fY and fVyy, then performs the background subtraction

Data members modified: fYData,fY,fVyyData,fVyy,fVyyinvData,fVyyinv

and those modified by TUnfold::SetInput() and those modified by DoBackgroundSubtraction()

Reimplemented from TUnfold.

Definition at line 444 of file TUnfoldSys.cxx.

◆ SetTauError()

void TUnfoldSys::SetTauError ( Double_t  delta_tau)

Specify an uncertainty on tau.

Parameters
[in]delta_taunew uncertainty on tau

The default is to have no uncertyainty on tau.

Definition at line 979 of file TUnfoldSys.cxx.

◆ Streamer()

void TUnfoldSys::Streamer ( TBuffer R__b)
overridevirtual

Stream an object of class TObject.

Reimplemented from TUnfold.

◆ StreamerNVirtual()

void TUnfoldSys::StreamerNVirtual ( TBuffer ClassDef_StreamerNVirtual_b)
inline

Definition at line 142 of file TUnfoldSys.h.

◆ SubtractBackground()

void TUnfoldSys::SubtractBackground ( const TH1 bgr,
const char *  name,
Double_t  scale = 1.0,
Double_t  scale_error = 0.0 
)

Specify a source of background.

Parameters
[in]bgrbackground distribution with uncorrelated errors
[in]nameidentifier for this background source
[in]scalenormalisation factor applied to the background
[in]scale_errornormalisation uncertainty

The contribution scale*bgr is subtracted from the measurement prior to unfolding. The following contributions are added to the input covarianc ematrix

  • using the uncorrelated histogram errors dbgr, the contribution (scale*dbgri)2 is added to the diagonals of the covariance
  • using the histogram contents, the background normalisation uncertainty contribution dscale*bgri dscale*bgrj is added to the covariance matrix

Data members modified: fBgrIn,fBgrErrUncorrInSq,fBgrErrScaleIn and those modified by DoBackgroundSubtraction()

Definition at line 482 of file TUnfoldSys.cxx.

◆ VectorMapToHist()

void TUnfoldSys::VectorMapToHist ( TH1 hist_delta,
const TMatrixDSparse delta,
const Int_t binMap 
)
protected

Map delta to hist_delta, possibly summing up bins.

Parameters
[out]hist_deltaresult histogram
[in]deltavector to be mapped to the histogram
[in]binMapmapping of histogram bins

groups of bins of delta are mapped to bins of hist_delta. The histogram contents are set to the sum over the group of bins. The histogram errors are reset to zero.

The array binMap is explained with the method GetOutput()

sum over bins of *delta, as defined in binMap,fXToHist

  • hist_delta: histogram to return summed vector
  • delta: vector to sum and remap

Definition at line 1463 of file TUnfoldSys.cxx.

Member Data Documentation

◆ fAoutside

TMatrixD* TUnfoldSys::fAoutside
protected

Input: underflow/overflow bins.

Definition at line 64 of file TUnfoldSys.h.

◆ fBgrErrScaleIn

TMap* TUnfoldSys::fBgrErrScaleIn
protected

Input: background sources correlated error.

Definition at line 72 of file TUnfoldSys.h.

◆ fBgrErrUncorrInSq

TMap* TUnfoldSys::fBgrErrUncorrInSq
protected

Input: uncorr error squared from bgr sources.

Definition at line 70 of file TUnfoldSys.h.

◆ fBgrIn

TMap* TUnfoldSys::fBgrIn
protected

Input: size of background sources.

Definition at line 68 of file TUnfoldSys.h.

◆ fDAinColRelSq

TMatrixD* TUnfoldSys::fDAinColRelSq
protected

Input: normalized column err.sq. (inp.matr.)

Definition at line 62 of file TUnfoldSys.h.

◆ fDAinRelSq

TMatrixDSparse* TUnfoldSys::fDAinRelSq
protected

Input: normalized errors from input matrix.

Definition at line 60 of file TUnfoldSys.h.

◆ fDeltaCorrAx

TMap* TUnfoldSys::fDeltaCorrAx
protected

Result: syst.shift from fSysIn on fAx.

Definition at line 86 of file TUnfoldSys.h.

◆ fDeltaCorrX

TMap* TUnfoldSys::fDeltaCorrX
protected

Result: syst.shift from fSysIn on fX.

Definition at line 84 of file TUnfoldSys.h.

◆ fDeltaSysTau

TMatrixDSparse* TUnfoldSys::fDeltaSysTau
protected

Result: systematic shift from tau.

Definition at line 88 of file TUnfoldSys.h.

◆ fDtau

Double_t TUnfoldSys::fDtau
protected

Input: error on tau.

Definition at line 74 of file TUnfoldSys.h.

◆ fEmatUncorrAx

TMatrixDSparse* TUnfoldSys::fEmatUncorrAx
protected

Result: syst.error from fDA2 on fAx.

Definition at line 82 of file TUnfoldSys.h.

◆ fEmatUncorrX

TMatrixDSparse* TUnfoldSys::fEmatUncorrX
protected

Result: syst.error from fDA2 on fX.

Definition at line 80 of file TUnfoldSys.h.

◆ fSysIn

TMap* TUnfoldSys::fSysIn
protected

Input: correlated errors.

Definition at line 66 of file TUnfoldSys.h.

◆ fVyyData

TMatrixDSparse* TUnfoldSys::fVyyData
protected

Input: error on fY prior to bgr subtraction.

Definition at line 78 of file TUnfoldSys.h.

◆ fYData

TMatrixD* TUnfoldSys::fYData
protected

Input: fY prior to bgr subtraction.

Definition at line 76 of file TUnfoldSys.h.

  • hist/unfold/inc/TUnfoldSys.h
  • hist/unfold/src/TUnfoldSys.cxx