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 = 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
	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. More...

	TUnfoldSys (void)
	Only for use by root streamer or derived classes. More...

virtual	~TUnfoldSys (void)

void	AddSysError (const TH2 sysError, const char name, EHistMap histmap, ESysErrMode mode)
	Specify a correlated systematic uncertainty. More...

void	GetBackground (TH1 bgr, const char bgrSource=0, const Int_t *binMap=0, Int_t includeError=3, Bool_t clearHist=kTRUE) const
	Get background into a histogram. More...

TSortedList *	GetBgrSources (void) const
	Get a new list of all background sources. More...

Double_t	GetChi2Sys (void)
	Calculate total chi**2 including all systematic errors. More...

Bool_t	GetDeltaSysBackgroundScale (TH1 delta, const char source, const Int_t *binMap=0)
	Correlated one-sigma shifts from background normalisation uncertainty. More...

Bool_t	GetDeltaSysSource (TH1 hist_delta, const char source, const Int_t *binMap=0)
	Correlated one-sigma shifts correspinding to a given systematic uncertainty. More...

Bool_t	GetDeltaSysTau (TH1 delta, const Int_t binMap=0)
	Correlated one-sigma shifts from shifting tau. More...

void	GetEmatrixInput (TH2 ematrix, const Int_t binMap=0, Bool_t clearEmat=kTRUE)
	Covariance matrix contribution from input measurement uncertainties. More...

void	GetEmatrixSysBackgroundScale (TH2 ematrix, const char source, const Int_t *binMap=0, Bool_t clearEmat=kTRUE)
	Covariance contribution from background normalisation uncertainty. More...

void	GetEmatrixSysBackgroundUncorr (TH2 ematrix, const char source, const Int_t *binMap=0, Bool_t clearEmat=kTRUE)
	Covariance contribution from background uncorrelated uncertainty. More...

void	GetEmatrixSysSource (TH2 ematrix, const char source, const Int_t *binMap=0, Bool_t clearEmat=kTRUE)
	Covariance contribution from a systematic variation of the response matrix. More...

void	GetEmatrixSysTau (TH2 ematrix, const Int_t binMap=0, Bool_t clearEmat=kTRUE)
	Covariance matrix contribution from error on regularisation parameter. More...

void	GetEmatrixSysUncorr (TH2 ematrix, const Int_t binMap=0, Bool_t clearEmat=kTRUE)
	Covariance contribution from uncorrelated uncertainties of the response matrix. More...

void	GetEmatrixTotal (TH2 ematrix, const Int_t binMap=0)
	Get total error matrix, summing up all contributions. More...

void	GetRhoItotal (TH1 rhoi, const Int_t binMap=0, TH2 *invEmat=0)
	Get global correlatiocn coefficients, summing up all contributions. More...

TSortedList *	GetSysSources (void) const
	Get a new list of all systematic uuncertainty sources. 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 the input data for subsequent calls to DoUnfold(Double_t). More...

void	SetTauError (Double_t delta_tau)
	Specify an uncertainty on tau. More...

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. More...

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. 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 χ²_A 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 ()
	Check and record whether 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)

void	SetBit (UInt_t f, Bool_t set)
	Set or unset the user status bits as specified in f. More...

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...

Protected Member Functions
virtual void	ClearResults (void)
	Clear all data members which depend on the unfolding results. More...

void	DoBackgroundSubtraction (void)
	Perform background subtraction. More...

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. More...

TMatrixDSparse *	GetSummedErrorMatrixXX (void)
	Determine total error matrix on the vector x. More...

TMatrixDSparse *	GetSummedErrorMatrixYY (void)
	Determine total error matrix on the vector Ax. More...

virtual TMatrixDSparse *	PrepareCorrEmat (const TMatrixDSparse m1, const TMatrixDSparse m2, const TMatrixDSparse *dsys)
	Propagate correlated systematic shift to an output vector. More...

virtual void	PrepareSysError (void)
	Matrix calculations required to propagate systematic errors. More...

virtual TMatrixDSparse *	PrepareUncorrEmat (const TMatrixDSparse m1, const TMatrixDSparse m2)
	Propagate uncorrelated systematic errors to a covariance matrix. More...

void	ScaleColumnsByVector (TMatrixDSparse m, const TMatrixTBase< Double_t > v) const
	Scale columns of a matrix by the corresponding rows of a vector. More...

void	VectorMapToHist (TH1 hist_delta, const TMatrixDSparse delta, const Int_t *binMap)
	Map delta to hist_delta, possibly summing up bins. More...

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. 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 $M1VM2^{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 ()

Protected Attributes
TMatrixD *	fAoutside
	Input: underflow/overflow bins. More...

TMap *	fBgrErrScaleIn
	Input: background sources correlated error. More...

TMap *	fBgrErrUncorrInSq
	Input: uncorr error squared from bgr sources. More...

TMap *	fBgrIn
	Input: size of background sources. More...

TMatrixD *	fDAinColRelSq
	Input: normalized column err.sq. (inp.matr.) More...

TMatrixDSparse *	fDAinRelSq
	Input: normalized errors from input matrix. More...

TMap *	fDeltaCorrAx
	Result: syst.shift from fSysIn on fAx. More...

TMap *	fDeltaCorrX
	Result: syst.shift from fSysIn on fX. More...

TMatrixDSparse *	fDeltaSysTau
	Result: systematic shift from tau. More...

Double_t	fDtau
	Input: error on tau. More...

TMatrixDSparse *	fEmatUncorrAx
	Result: syst.error from fDA2 on fAx. More...

TMatrixDSparse *	fEmatUncorrX
	Result: syst.error from fDA2 on fX. More...

TMap *	fSysIn
	Input: correlated errors. More...

TMatrixDSparse *	fVyyData
	Input: error on fY prior to bgr subtraction. More...

TMatrixD *	fYData
	Input: fY prior to bgr subtraction. More...

Protected Attributes inherited from TUnfold
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	InitTUnfoldSys (void)
	Initialize pointers and TMaps. More...

Additional Inherited Members
Static Public Member Functions inherited from TUnfold
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...

Static Protected Member Functions inherited from TUnfold
static void	DeleteMatrix (TMatrixD **m)
	delete matrix and invalidate pointer More...

static void	DeleteMatrix (TMatrixDSparse **m)
	delete sparse matrix and invalidate pointer More...

#include <TUnfoldSys.h>

Inheritance diagram for TUnfoldSys:

[legend]

Member Enumeration Documentation

◆ ESysErrMode

enum TUnfoldSys::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_A	matrix that describes the migrations
[in]	histmap	mapping 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 158 of file TUnfoldSys.cxx.

◆ TUnfoldSys() [2/2]

TUnfoldSys::TUnfoldSys ( void )

Only for use by root streamer or derived classes.

Definition at line 139 of file TUnfoldSys.cxx.

◆ ~TUnfoldSys()

TUnfoldSys::~TUnfoldSys ( void )

virtual

Definition at line 120 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]	sysError	alternative matrix or matrix of absolute/relative shifts
[in]	name	identifier of the error source
[in]	histmap	mapping of the histogram axes
[in]	mode	format 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 248 of file TUnfoldSys.cxx.

◆ ClearResults()

void TUnfoldSys::ClearResults ( void )

protectedvirtual

Clear all data members which depend on the unfolding results.

Reimplemented from TUnfold.

Definition at line 667 of file TUnfoldSys.cxx.

◆ 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 334 of file TUnfoldSys.cxx.

◆ GetBackground()

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

Get background into a histogram.

Parameters

[in,out]	bgrHist	target 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 550 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 1585 of file TUnfoldSys.cxx.

◆ GetChi2Sys()

Double_t TUnfoldSys::GetChi2Sys ( void )

Calculate total chi**2 including all systematic errors.

Definition at line 1416 of file TUnfoldSys.cxx.

◆ GetDeltaSysBackgroundScale()

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

Correlated one-sigma shifts from background normalisation uncertainty.

Parameters

[out]	hist_delta	histogram to store shifts
[in]	source	identifier 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 1082 of file TUnfoldSys.cxx.

◆ GetDeltaSysSource()

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

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

Parameters

[out]	hist_delta	histogram to store shifts
[in]	name	identifier 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 1055 of file TUnfoldSys.cxx.

◆ GetDeltaSysTau()

Bool_t TUnfoldSys::GetDeltaSysTau	(	TH1 *	hist_delta,
		const Int_t *	binMap = `0`
	)

Correlated one-sigma shifts from shifting tau.

Parameters

[out]	hist_delta	histogram to store shifts
[in]	source	identifier 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().

calculate systematic shift from tau variation

ematrix: output
binMap: see method GetEmatrix()

Definition at line 1118 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]	vyy	input error matrix
[in,out]	ematrix	histogram to be updated
[in]	binMap	mapping of histogram bins
[in]	clearEmat	if 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 1287 of file TUnfoldSys.cxx.

◆ GetEmatrixInput()

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

Covariance matrix contribution from input measurement uncertainties.

Parameters

[in,out]	ematrix	output 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 1237 of file TUnfoldSys.cxx.

◆ GetEmatrixSysBackgroundScale()

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

Covariance contribution from background normalisation uncertainty.

Parameters

[in,out]	ematrix	output histogram
[in]	source	identifier 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 1173 of file TUnfoldSys.cxx.

◆ GetEmatrixSysBackgroundUncorr()

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

Covariance contribution from background uncorrelated uncertainty.

Parameters

[in]	ematrix	output histogram
[in]	source	identifier 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 1259 of file TUnfoldSys.cxx.

◆ GetEmatrixSysSource()

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

Covariance contribution from a systematic variation of the response matrix.

Parameters

[in,out]	ematrix	covariance matrix histogram
[in]	name	identifier 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 1142 of file TUnfoldSys.cxx.

◆ GetEmatrixSysTau()

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

Covariance matrix contribution from error on regularisation parameter.

Parameters

[in,out]	ematrix	output 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 1210 of file TUnfoldSys.cxx.

◆ GetEmatrixSysUncorr()

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

Covariance contribution from uncorrelated uncertainties of the response matrix.

Parameters

[in,out]	ematrix	covariance matrix histogram
[in]	binMap	mapping of histogram bins
[in]	clearEmat	if 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 786 of file TUnfoldSys.cxx.

◆ GetEmatrixTotal()

void TUnfoldSys::GetEmatrixTotal	(	TH2 *	ematrix,
		const Int_t *	binMap = `0`
	)

Get total error matrix, summing up all contributions.

Parameters

[out]	ematrix	histogram 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

ematrix: output
binMap: see method GetEmatrix()

Definition at line 1313 of file TUnfoldSys.cxx.

◆ GetRhoItotal()

void TUnfoldSys::GetRhoItotal	(	TH1 *	rhoi,
		const Int_t *	binMap = `0`,
		TH2 *	invEmat = `0`
	)

Get global correlatiocn coefficients, summing up all contributions.

Parameters

[out]	rhoi	histogram 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 1459 of file TUnfoldSys.cxx.

◆ GetSummedErrorMatrixXX()

TMatrixDSparse * TUnfoldSys::GetSummedErrorMatrixXX ( void )

protected

Determine total error matrix on the vector x.

Definition at line 1374 of file TUnfoldSys.cxx.

◆ GetSummedErrorMatrixYY()

TMatrixDSparse * TUnfoldSys::GetSummedErrorMatrixYY ( void )

protected

Determine total error matrix on the vector Ax.

Definition at line 1331 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 1570 of file TUnfoldSys.cxx.

◆ InitTUnfoldSys()

void TUnfoldSys::InitTUnfoldSys ( void )

private

Initialize pointers and TMaps.

Definition at line 625 of file TUnfoldSys.cxx.

◆ PrepareCorrEmat()

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

protectedvirtual

Propagate correlated systematic shift to an output vector.

Parameters

[in]	m1	coefficients
[in]	m2	coeffiicients
[in]	dsys	matrix 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 1014 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 683 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_0	coefficients for error propagation
[in]	m_1	coefficients 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 893 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]	m	matrix
[in]	v	vector

the entries m_ij are multiplied by v_j.

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 1481 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 = `0`,
		const TH2 *	hist_vyy_inv = `0`
	)

virtual

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 465 of file TUnfoldSys.cxx.

◆ SetTauError()

void TUnfoldSys::SetTauError ( Double_t delta_tau )

Specify an uncertainty on tau.

Parameters

[in] delta_tau new uncertainty on tau

The default is to have no uncertyainty on tau.

Definition at line 1035 of file TUnfoldSys.cxx.

◆ 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]	bgr	background distribution with uncorrelated errors
[in]	name	identifier for this background source
[in]	scale	normalisation factor applied to the background
[in]	scaleError	normalisation 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*dbgr_i)² is added to the diagonals of the covariance
using the histogram contents, the background normalisation uncertainty contribution dscale*bgr_i dscale*bgr_j is added to the covariance matrix

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

Definition at line 503 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_delta	result histogram
[in]	delta	vector to be mapped to the histogram
[in]	binMap	mapping 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 1534 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.

Libraries for TUnfoldSys:

[legend]

History:

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Additional Inherited Members

Member Enumeration Documentation

◆ ESysErrMode

Constructor & Destructor Documentation

◆ TUnfoldSys() [1/2]

◆ TUnfoldSys() [2/2]

◆ ~TUnfoldSys()

Member Function Documentation

◆ AddSysError()

◆ ClearResults()

◆ DoBackgroundSubtraction()

◆ GetBackground()

◆ GetBgrSources()

◆ GetChi2Sys()

◆ GetDeltaSysBackgroundScale()

◆ GetDeltaSysSource()

◆ GetDeltaSysTau()

◆ GetEmatrixFromVyy()

◆ GetEmatrixInput()

◆ GetEmatrixSysBackgroundScale()

◆ GetEmatrixSysBackgroundUncorr()

◆ GetEmatrixSysSource()

◆ GetEmatrixSysTau()

◆ GetEmatrixSysUncorr()

◆ GetEmatrixTotal()

◆ GetRhoItotal()

◆ GetSummedErrorMatrixXX()

◆ GetSummedErrorMatrixYY()

◆ GetSysSources()

◆ InitTUnfoldSys()

◆ PrepareCorrEmat()

◆ PrepareSysError()

◆ PrepareUncorrEmat()

◆ ScaleColumnsByVector()

◆ SetInput()

◆ SetTauError()

◆ SubtractBackground()

◆ VectorMapToHist()

Member Data Documentation

◆ fAoutside

◆ fBgrErrScaleIn

◆ fBgrErrUncorrInSq

◆ fBgrIn

◆ fDAinColRelSq

◆ fDAinRelSq

◆ fDeltaCorrAx

◆ fDeltaCorrX

◆ fDeltaSysTau

◆ fDtau

◆ fEmatUncorrAx

◆ fEmatUncorrX

◆ fSysIn

◆ fVyyData

◆ fYData