An algorithm to unfold distributions from detector to truth level.

TUnfoldDensity 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, TUnfoldDensity 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. Complex, multidimensional arrangements of signal and background bins are managed with the help of the class TUnfoldBinning.

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:

Set up binning schemes for the truth and measured distributions. The binning schemes may be coded in the XML language, for reading use TUnfoldBinningXML.
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()
- or multiple times in a scan to determine the best chouce of tau, method ScanTau()
Unfolding results are retrieved using various GetXXX() methods

A detailed documentation of the various GetXXX() methods to control systematic uncertainties is given with the method TUnfoldSys.

Why to use complex binning schemes

in literature on unfolding, the "standard" test case is a one-dimensional distribution without underflow or overflow bins. The migration matrix is almost diagonal.
This "standard" case is rarely realized for real problems.
Often one has to deal with multi-dimensional distributions. In addition, there are underflow and overflow bins or other background bins, possibly determined with the help of auxillary measurements.
In TUnfoldDensity, such complex binning schemes are handled with the help of the class TUnfoldBinning. For both the measurement and the truth there is a tree structure. The tree nodes may correspond to single bins (e.g. nuisance parameters) or may hold multi-dimensional distributions.
For example, the "measurement" tree could have two leaves, one for the primary distribution and one for auxillary measurements. Similarly, the "truth" tree could have two leaves, one for the signal and one for the background. Each of the leaves may then have a multi-dimensional distribution.
The class TUnfoldBinning takes care to map all bins of the "measurement" to a one-dimensional vector y. Similarly, the "truth" bins are mapped to the vector x.

How to choose the regularisation settings

In TUnfoldDensity, two methods are implemented to determine tau**2

ScanLcurve() locate the tau where the L-curve plot has a "kink" this function is implemented in the TUnfold class
ScanTau() finds the solution such that some variable (e.g. global correlation coefficient) is minimized. This function is implemented in the TUnfoldDensity class

Each of the algorithms has its own advantages and disadvantages. The algorithm (1) does not work if the input data are too similar to the MC prediction. Typical no-go cases of the L-curve scan are:

the number of measurements is too small (e.g. ny=nx)
the input data have no statistical fluctuations [identical MC events are used to fill the matrix of migrations and the vector y for a "closure test"]

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

The L-curve should have approximate L-shape and the final choice of tau should not be at the very edge of the scanned region
The scan result should have a well-defined minimum and the final choice of tau should sit right in the minimum

Definition at line 52 of file TUnfoldDensity.h.

Public Types
enum	EDensityMode { kDensityModeNone =0 , kDensityModeBinWidth =1 , kDensityModeUser =2 , kDensityModeBinWidthAndUser =3 }
	choice of regularisation scale factors to cinstruct the matrix L More...

enum	EScanTauMode { kEScanTauRhoAvg =0 , kEScanTauRhoMax =1 , kEScanTauRhoAvgSys =2 , kEScanTauRhoMaxSys =3 , kEScanTauRhoSquareAvg =4 , kEScanTauRhoSquareAvgSys =5 }
	scan mode for correlation scan More...

Public Types inherited from TUnfoldSys
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
	TUnfoldDensity (const TH2 hist_A, EHistMap histmap, ERegMode regmode=kRegModeCurvature, EConstraint constraint=kEConstraintArea, EDensityMode densityMode=kDensityModeBinWidthAndUser, const TUnfoldBinning outputBins=nullptr, const TUnfoldBinning inputBins=nullptr, const char regularisationDistribution=nullptr, const char regularisationAxisSteering="[UOB]")
	set up response matrix A, uncorrelated uncertainties of A, regularisation scheme and binning schemes

	TUnfoldDensity (void)
	only for use by root streamer or derived classes

	~TUnfoldDensity (void) override

TH1 *	GetBackground (const char histogramName, const char bgrSource=nullptr, const char histogramTitle=nullptr, const char distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE, Int_t includeError=3) const
	retreive a background source in a new histogram

TH1 *	GetBias (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE) const
	retreive bias vector as a new histogram

TH1 *	GetDeltaSysBackgroundScale (const char bgrSource, const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
	retreive systematic 1-sigma shift corresponding to a background scale uncertainty

TH1 *	GetDeltaSysSource (const char source, const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
	retreive a correlated systematic 1-sigma shift

TH1 *	GetDeltaSysTau (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
	retreive1-sigma shift corresponding to the previously specified uncertainty on tau

TH2 *	GetDXDY (const char histogramName, const char histogramTitle=nullptr, bool useAxisBinning=true) const
	get matrix DX/DY in a new histogram

TH2 *	GetEmatrixInput (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
	get covariance contribution from the input uncertainties (data statistical uncertainties)

TH2 *	GetEmatrixSysBackgroundUncorr (const char bgrSource, const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char *projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
	retreive covariance contribution from uncorrelated background uncertainties

TH2 *	GetEmatrixSysUncorr (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
	retreive covaraince contribution from uncorrelated (statistical) uncertainties of the response matrix

TH2 *	GetEmatrixTotal (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
	get covariance matrix including all contributions

TH1 *	GetFoldedOutput (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE, Bool_t addBgr=kFALSE) const
	retreive unfolding result folded back as a new histogram

TH1 *	GetInput (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE) const
	retreive input distribution in a new histogram

const TUnfoldBinning *	GetInputBinning (const char *distributionName=nullptr) const
	locate a binning node for the input (measured) quantities

TH2 *	GetL (const char histogramName, const char histogramTitle=nullptr, Bool_t useAxisBinning=kTRUE)
	access matrix of regularisation conditions in a new histogram

TUnfoldBinning *	GetLBinning (void) const
	return binning scheme for regularisation conditions (matrix L)

TH1 *	GetLxMinusBias (const char histogramName, const char histogramTitle=nullptr)
	get regularisation conditions multiplied by result vector minus bias L(x-biasScale*biasVector)

TH1 *	GetOutput (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE) const
	retreive unfolding result as a new histogram

const TUnfoldBinning *	GetOutputBinning (const char *distributionName=nullptr) const
	locate a binning node for the unfolded (truth level) quantities

TH2 *	GetProbabilityMatrix (const char histogramName, const char histogramTitle=nullptr, Bool_t useAxisBinning=kTRUE) const
	get matrix of probabilities in a new histogram

TH2 *	GetRhoIJtotal (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE)
	retreive correlation coefficients, including all uncertainties

TH1 *	GetRhoIstatbgr (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE, TH2 **ematInv=nullptr)
	retreive global correlation coefficients including input (statistical) and background uncertainties

TH1 *	GetRhoItotal (const char histogramName, const char histogramTitle=nullptr, const char distributionName=nullptr, const char projectionMode=nullptr, Bool_t useAxisBinning=kTRUE, TH2 **ematInv=nullptr)
	retreive global correlation coefficients including all uncertainty sources

virtual Double_t	GetScanVariable (Int_t mode, const char distribution, const char projectionMode)
	calculate the function for ScanTau()

TClass *	IsA () const override

void	RegularizeDistribution (ERegMode regmode, EDensityMode densityMode, const char distribution, const char axisSteering)
	set up regularisation conditions

virtual Int_t	ScanTau (Int_t nPoint, Double_t tauMin, Double_t tauMax, TSpline *scanResult, Int_t mode=kEScanTauRhoAvg, const char distribution=nullptr, const char projectionMode=nullptr, TGraph lCurvePlot=nullptr, TSpline logTauXPlot=nullptr, TSpline *logTauYPlot=nullptr)
	scan a function wrt tau and determine the minimum

void	Streamer (TBuffer &) override
	Stream an object of class TObject.

void	StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)

Public Member Functions inherited from 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

	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

TSortedList *	GetBgrSources (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.

TSortedList *	GetSysSources (void) const
	Get a new list of all systematic uuncertainty sources.

TClass *	IsA () 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 input data for subsequent calls to DoUnfold(tau)

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 χ²_A contribution determined in recent unfolding

Double_t	GetChi2L (void) const
	get χ²_L contribution determined in recent unfolding

double	GetDF (void) const
	return the effecive number of degrees of freedom See e.g.

void	GetDXDY (TH2 *dxdy) const
	get matrix connecting input and output changes

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 suming 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 coefficiencts, possibly cumulated over several bins

void	GetRhoIJ (TH2 rhoij, const Int_t binMap=nullptr) const
	get correlation coefficiencts, possibly cumulated over several bins

Double_t	GetRhoMax (void) const
	get maximum global correlation determined in recent unfolding

TVectorD	GetSqrtEvEmatrix (void) const

double	GetSURE (void) const
	return Stein's unbiased risk estimator See e.g.

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

virtual Int_t	ScanSURE (Int_t nPoint, Double_t tauMin, Double_t tauMax, TGraph logTauSURE=nullptr, TGraph df_chi2A=nullptr, TGraph **lCurve=nullptr)
	minimize Stein's unbiased risk estimator "SURE" using successive calls to DoUnfold at various 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 TObject *	Clone (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 TObject *	DrawClone (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 TObject *	FindObject (const char *name) const
	Must be redefined in derived classes.

virtual TObject *	FindObject (const TObject *obj) const
	Must be redefined in derived classes.

virtual Option_t *	GetDrawOption () 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_t *	GetOption () 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, void vp)
	Only called by placement new when throwing an exception.

void	operator delete[] (void *ptr)
	Operator delete [].

void	operator delete[] (void ptr, void vp)
	Only called by placement new[] when throwing an exception.

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.

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 TClass *	Class ()

static const char *	Class_Name ()

static constexpr Version_t	Class_Version ()

static const char *	DeclFileName ()

Static Public Member Functions inherited from TUnfoldSys
static TClass *	Class ()

static const char *	Class_Name ()

static constexpr Version_t	Class_Version ()

static const char *	DeclFileName ()

Static Public Member Functions inherited from TUnfold
static TClass *	Class ()

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 TClass *	Class ()

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
Double_t	GetDensityFactor (EDensityMode densityMode, Int_t iBin) const
	density correction factor for a given bin

TString	GetOutputBinName (Int_t iBinX) const override
	Get bin name of an outpt bin.

void	RegularizeDistributionRecursive (const TUnfoldBinning binning, ERegMode regmode, EDensityMode densityMode, const char distribution, const char *axisSteering)
	recursively add regularisation conditions for this node and its children

void	RegularizeOneDistribution (const TUnfoldBinning binning, ERegMode regmode, EDensityMode densityMode, const char axisSteering)
	regularize the distribution fof the given node

Protected Member Functions inherited from TUnfoldSys
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

TMatrixDSparse *	GetSummedErrorMatrixXX (void)
	determine total error matrix on the vector x

TMatrixDSparse *	GetSummedErrorMatrixYY (void)
	determine total error matrix on the vector Ax

virtual TMatrixDSparse *	PrepareCorrEmat (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 TMatrixDSparse *	PrepareUncorrEmat (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.

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

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 TMatrixDSparse *	GetAx (void) const
	vector of folded-back result

Int_t	GetBinFromRow (int ix) const
	converts matrix row to truth histogram bin number

const TMatrixDSparse *	GetDXDAM (int i) const
	matrix contributions of the derivative dx/dA

const TMatrixDSparse *	GetDXDAZ (int i) const
	vector contributions of the derivative dx/dA

const TMatrixDSparse *	GetDXDtauSquared (void) const
	vector of derivative dx/dtauSquared, using internal bin counting

const TMatrixDSparse *	GetDXDY (void) const
	matrix of derivatives dx/dy

const TMatrixDSparse *	GetE (void) const
	matrix E, using internal bin counting

const TMatrixDSparse *	GetEinv (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

Double_t	GetRhoIFromMatrix (TH1 rhoi, const TMatrixDSparse eOrig, const Int_t binMap, TH2 invEmat) const

Int_t	GetRowFromBin (int ix) const
	converts truth histogram bin number to matrix row

const TMatrixDSparse *	GetVxx (void) const
	covariance matrix of the result

const TMatrixDSparse *	GetVxxInv (void) const
	inverse of covariance matrix of the result

const TMatrixDSparse *	GetVyyInv (void) const
	inverse of covariance matrix of the data y

const TMatrixD *	GetX (void) const
	vector of the unfolding result

TMatrixDSparse *	InvertMSparseSymmPos (const TMatrixDSparse A, Int_t rank) const
	get the inverse or pseudo-inverse of a positive, sparse matrix

TMatrixDSparse *	MultiplyMSparseM (const TMatrixDSparse a, const TMatrixD b) const
	multiply sparse matrix and a non-sparse matrix

TMatrixDSparse *	MultiplyMSparseMSparse (const TMatrixDSparse a, const TMatrixDSparse b) const
	multiply two sparse matrices

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

TMatrixDSparse *	MultiplyMSparseTranspMSparse (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
const TUnfoldBinning *	fConstInputBins
	binning scheme for the input (detector level)

const TUnfoldBinning *	fConstOutputBins
	binning scheme for the output (truth level)

TUnfoldBinning *	fOwnedInputBins
	pointer to input binning scheme if owned by this class

TUnfoldBinning *	fOwnedOutputBins
	pointer to output binning scheme if owned by this class

TUnfoldBinning *	fRegularisationConditions
	binning scheme for the regularisation conditions

Protected Attributes inherited from TUnfoldSys
TMatrixD *	fAoutside
	Input: underflow/overflow bins.

TMap *	fBgrErrScaleIn
	Input: background sources correlated error.

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

TMap *	fBgrIn
	Input: size of background sources.

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

TMatrixDSparse *	fDAinRelSq
	Input: normalized errors from input matrix.

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

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

TMatrixDSparse *	fDeltaSysTau
	Result: systematic shift from tau.

Double_t	fDtau
	Input: error on tau.

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

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

TMap *	fSysIn
	Input: correlated errors.

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

TMatrixD *	fYData
	Input: fY prior to bgr subtraction.

Protected Attributes inherited from TUnfold
TMatrixDSparse *	fA
	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

TMatrixDSparse *	fL
	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

TMatrixDSparse *	fVyy
	covariance matrix Vyy corresponding to y

TMatrixD *	fX0
	bias vector x0

TArrayI	fXToHist
	mapping of matrix indices to histogram bins

TMatrixD *	fY
	input (measured) data y

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

Inheritance diagram for TUnfoldDensity:

[legend]

Member Enumeration Documentation

◆ EDensityMode

enum TUnfoldDensity::EDensityMode

choice of regularisation scale factors to cinstruct the matrix L

Enumerator
kDensityModeNone	no scale factors, matrix L is similar to unity matrix
kDensityModeBinWidth	scale factors from multidimensional bin width
kDensityModeUser	scale factors from user function in TUnfoldBinning
kDensityModeBinWidthAndUser	scale factors from multidimensional bin width and user function

Definition at line 67 of file TUnfoldDensity.h.

◆ EScanTauMode

enum TUnfoldDensity::EScanTauMode

scan mode for correlation scan

Enumerator
kEScanTauRhoAvg	average global correlation coefficient (from TUnfold::GetRhoI())
kEScanTauRhoMax	maximum global correlation coefficient (from TUnfold::GetRhoI())
kEScanTauRhoAvgSys	average global correlation coefficient (from TUnfoldSys::GetRhoItotal())
kEScanTauRhoMaxSys	maximum global correlation coefficient (from TUnfoldSys::GetRhoItotal())
kEScanTauRhoSquareAvg	average global correlation coefficient squared (from TUnfold::GetRhoI())
kEScanTauRhoSquareAvgSys	average global correlation coefficient squared (from TUnfoldSys::GetRhoItotal())

Definition at line 109 of file TUnfoldDensity.h.

Constructor & Destructor Documentation

◆ TUnfoldDensity() [1/2]

TUnfoldDensity::TUnfoldDensity ( void )

only for use by root streamer or derived classes

Definition at line 181 of file TUnfoldDensity.cxx.

◆ TUnfoldDensity() [2/2]

TUnfoldDensity::TUnfoldDensity	(	const TH2 *	hist_A,
		EHistMap	histmap,
		ERegMode	regmode = `kRegModeCurvature`,
		EConstraint	constraint = `kEConstraintArea`,
		EDensityMode	densityMode = `kDensityModeBinWidthAndUser`,
		const TUnfoldBinning *	outputBins = `nullptr`,
		const TUnfoldBinning *	inputBins = `nullptr`,
		const char *	regularisationDistribution = `nullptr`,
		const char *	regularisationAxisSteering = `"*[UOB]"`
	)

set up response matrix A, uncorrelated uncertainties of A, regularisation scheme and binning schemes

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
[in]	densityMode	(default=kDensityModeBinWidthAndUser) regularisation scale factors to construct the matrix L
[in]	outputBins	(default=nullptr) binning scheme for truth (unfolding output)
[in]	inputBins	(default=nullptr) binning scheme for measurement (unfolding input)
[in]	regularisationDistribution	(default=nullptr) selectin of regularized distribution
[in]	regularisationAxisSteering	(default=nullptr) detailed regularisation steeringfor selected distribution

The parameters hist_A, histmap, constraint are explained with the TUnfoldSys constructor.
The parameters outputBins,inputBins set the binning schemes. If these arguments are zero, simple binning schemes are constructed which correspond to the axes of the histogram hist_A.
The parameters regmode, densityMode, regularisationDistribution, regularisationAxisSteering together control how the initial matrix L of regularisation conditions is constructed. as explained in RegularizeDistribution().

Definition at line 220 of file TUnfoldDensity.cxx.

◆ ~TUnfoldDensity()

TUnfoldDensity::~TUnfoldDensity ( void )

override

Definition at line 170 of file TUnfoldDensity.cxx.

Member Function Documentation

◆ Class()

static TClass * TUnfoldDensity::Class ( )

static

Returns: TClass describing this class

◆ Class_Name()

static const char * TUnfoldDensity::Class_Name ( )

static

Returns: Name of this class

◆ Class_Version()

static constexpr Version_t TUnfoldDensity::Class_Version ( )

inlinestaticconstexpr

Returns: Version of this class

Definition at line 205 of file TUnfoldDensity.h.

◆ DeclFileName()

static const char * TUnfoldDensity::DeclFileName ( )

inlinestatic

Returns: Name of the file containing the class declaration

Definition at line 205 of file TUnfoldDensity.h.

◆ GetBackground()

TH1 * TUnfoldDensity::GetBackground	(	const char *	histogramName,
		const char *	bgrSource = `nullptr`,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`,
		Int_t	includeError = `3`
	)		const

retreive a background source in a new histogram

Parameters

[in]	histogramName	name of the histogram
[in]	bgrSource	the background source to retreive
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels
[in]	includeError	(default=3) type of background errors to be included (+1 uncorrelated bgr errors, +2 correlated bgr errors)

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 751 of file TUnfoldDensity.cxx.

◆ GetBias()

TH1 * TUnfoldDensity::GetBias	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)		const

retreive bias vector as a new histogram

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 685 of file TUnfoldDensity.cxx.

◆ GetDeltaSysBackgroundScale()

TH1 * TUnfoldDensity::GetDeltaSysBackgroundScale	(	const char *	bgrSource,
		const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)

retreive systematic 1-sigma shift corresponding to a background scale uncertainty

Parameters

[in]	bgrSource	identifier of the background
[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 944 of file TUnfoldDensity.cxx.

◆ GetDeltaSysSource()

TH1 * TUnfoldDensity::GetDeltaSysSource	(	const char *	source,
		const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)

retreive a correlated systematic 1-sigma shift

Parameters

[in]	source	identifier of the systematic uncertainty source
[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 911 of file TUnfoldDensity.cxx.

◆ GetDeltaSysTau()

TH1 * TUnfoldDensity::GetDeltaSysTau	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)

retreive1-sigma shift corresponding to the previously specified uncertainty on tau

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 976 of file TUnfoldDensity.cxx.

◆ GetDensityFactor()

Double_t TUnfoldDensity::GetDensityFactor	(	EDensityMode	densityMode,
		Int_t	iBin
	)		const

protected

density correction factor for a given bin

Parameters

[in]	densityMode	type of factor to calculate
[in]	iBin	bin number

return a multiplicative factor, for scaling the regularisation conditions from this bin.
For densityMode=kDensityModeNone the factor is set to unity. For densityMode=kDensityModeBinWidth the factor is set to 1/binArea where the binArea is the product of the bin widths in all dimensions. If the width of a bin is zero or can not be determined, the factor is set to zero. For densityMode=kDensityModeUser the factor is determined from the method TUnfoldBinning::GetBinFactor(). For densityMode=kDensityModeBinWidthAndUser, the results of kDensityModeBinWidth and kDensityModeUser are multiplied.

Definition at line 335 of file TUnfoldDensity.cxx.

◆ GetDXDY()

TH2 * TUnfoldDensity::GetDXDY	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		bool	useAxisBinning = `true`
	)		const

get matrix DX/DY in a new histogram

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. if histogramTitle is null, choose a title automatically.

Definition at line 1166 of file TUnfoldDensity.cxx.

◆ GetEmatrixInput()

TH2 * TUnfoldDensity::GetEmatrixInput	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)

get covariance contribution from the input uncertainties (data statistical uncertainties)

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 1119 of file TUnfoldDensity.cxx.

◆ GetEmatrixSysBackgroundUncorr()

TH2 * TUnfoldDensity::GetEmatrixSysBackgroundUncorr	(	const char *	bgrSource,
		const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)

retreive covariance contribution from uncorrelated background uncertainties

Parameters

[in]	bgrSource	identifier of the background
[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 1088 of file TUnfoldDensity.cxx.

◆ GetEmatrixSysUncorr()

TH2 * TUnfoldDensity::GetEmatrixSysUncorr	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)

retreive covaraince contribution from uncorrelated (statistical) uncertainties of the response matrix

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 1058 of file TUnfoldDensity.cxx.

◆ GetEmatrixTotal()

TH2 * TUnfoldDensity::GetEmatrixTotal	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)

get covariance matrix including all contributions

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 1191 of file TUnfoldDensity.cxx.

◆ GetFoldedOutput()

TH1 * TUnfoldDensity::GetFoldedOutput	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`,
		Bool_t	addBgr = `kFALSE`
	)		const

retreive unfolding result folded back as a new histogram

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels
[in]	addBgr	(default=false) if true, include the background contribution (useful for direct comparison to data)

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 716 of file TUnfoldDensity.cxx.

◆ GetInput()

TH1 * TUnfoldDensity::GetInput	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)		const

retreive input distribution in a new histogram

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 781 of file TUnfoldDensity.cxx.

◆ GetInputBinning()

const TUnfoldBinning * TUnfoldDensity::GetInputBinning ( const char * distributionName = nullptr ) const

locate a binning node for the input (measured) quantities

Parameters

[in] distributionName (default=nullptr) distribution to look for. if zero, return the root node

returns: pointer to a TUnfoldBinning object or zero if not found

Definition at line 1293 of file TUnfoldDensity.cxx.

◆ GetL()

TH2 * TUnfoldDensity::GetL	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)

access matrix of regularisation conditions in a new histogram

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. if histogramTitle is null, choose a title automatically.

Definition at line 1218 of file TUnfoldDensity.cxx.

◆ GetLBinning()

TUnfoldBinning * TUnfoldDensity::GetLBinning ( void ) const

inline

return binning scheme for regularisation conditions (matrix L)

Definition at line 203 of file TUnfoldDensity.h.

◆ GetLxMinusBias()

TH1 * TUnfoldDensity::GetLxMinusBias	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`
	)

get regularisation conditions multiplied by result vector minus bias L(x-biasScale*biasVector)

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram

returns a new histogram. This is a measure of the level of regulartisation required per regularisation condition. If there are (negative or positive) spikes, these regularisation conditions dominate over the other regularisation conditions and may introduce the largest biases.

Definition at line 1255 of file TUnfoldDensity.cxx.

◆ GetOutput()

TH1 * TUnfoldDensity::GetOutput	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)		const

retreive unfolding result as a new histogram

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

return value: pointer to a new histogram. If useAxisBinning is set and if the selected distribution fits into a root histogram (1,2,3 dimensions) then return a histogram with the proper binning on each axis. Otherwise, return a 1D histogram with equidistant binning. If the histogram title is zero, a title is assigned automatically.

The axisSteering is defines as follows: "axis[mode];axis[mode];..." where:

axis = name of an axis or *
mode = any combination of the letters CUO0123456789
- C collapse axis into one bin (add up results). If any of the numbers 0-9 are given in addition, only these bins are added up. Here bins are counted from zero, whereas in root, bins are counted from 1. Obviously, this only works for up to 10 bins.
- U discarde underflow bin
- O discarde overflow bin

examples: imagine the binning has two axis, named x and y.

"*[UO]" exclude underflow and overflow bins for all axis. So here a TH2 is returned but all undeflow and overflow bins are empty
"x[UOC123]" integrate over the variable x but only using the bins 1,2,3 and not the underflow and overflow in x. Here a TH1 is returned, the axis is labelled "y" and the underflow and overflow (in y) are filled. However only the x-bins 1,2,3 are used to determine the content.
"x[C];y[UO]" integrate over the variable x, including underflow and overflow but exclude underflow and overflow in y. Here a TH1 is returned, the axis is labelled "y". The underflow and overflow in y are empty.

Definition at line 654 of file TUnfoldDensity.cxx.

◆ GetOutputBinName()

TString TUnfoldDensity::GetOutputBinName ( Int_t iBinX ) const

overrideprotectedvirtual

Get bin name of an outpt bin.

Parameters

[in] iBinX bin number

Return value: name of the bin. The name is constructed from the entries in the binning scheme and includes information about the bin borders etc.

Reimplemented from TUnfold.

Definition at line 311 of file TUnfoldDensity.cxx.

◆ GetOutputBinning()

const TUnfoldBinning * TUnfoldDensity::GetOutputBinning ( const char * distributionName = nullptr ) const

locate a binning node for the unfolded (truth level) quantities

Parameters

[in] distributionName (default=nullptr) distribution to look for. if zero, return the root node

returns: pointer to a TUnfoldBinning object or zero if not found

Definition at line 1309 of file TUnfoldDensity.cxx.

◆ GetProbabilityMatrix()

TH2 * TUnfoldDensity::GetProbabilityMatrix	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)		const

get matrix of probabilities in a new histogram

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. if histogramTitle is null, choose a title automatically.

Definition at line 1145 of file TUnfoldDensity.cxx.

◆ GetRhoIJtotal()

TH2 * TUnfoldDensity::GetRhoIJtotal	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`
	)

retreive correlation coefficients, including all uncertainties

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels

returns a new histogram. See method GetOutput() for a detailed description of the arguments

Definition at line 1007 of file TUnfoldDensity.cxx.

◆ GetRhoIstatbgr()

TH1 * TUnfoldDensity::GetRhoIstatbgr	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`,
		TH2 **	ematInv = `nullptr`
	)

retreive global correlation coefficients including input (statistical) and background uncertainties

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels
[out]	ematInv	(default=nullptr) to return the inverse covariance matrix

returns a new histogram. See method GetOutput() for a detailed description of the arguments. The inverse of the covariance matrix is stored in a new histogram returned by ematInv if that pointer is non-zero.

Definition at line 863 of file TUnfoldDensity.cxx.

◆ GetRhoItotal()

TH1 * TUnfoldDensity::GetRhoItotal	(	const char *	histogramName,
		const char *	histogramTitle = `nullptr`,
		const char *	distributionName = `nullptr`,
		const char *	axisSteering = `nullptr`,
		Bool_t	useAxisBinning = `kTRUE`,
		TH2 **	ematInv = `nullptr`
	)

retreive global correlation coefficients including all uncertainty sources

Parameters

[in]	histogramName	name of the histogram
[in]	histogramTitle	(default=nullptr) title of the histogram
[in]	distributionName	(default=nullptr) identifier of the distribution to be extracted
[in]	axisSteering	(default=nullptr) detailed steering within the extracted distribution
[in]	useAxisBinning	(default=true) if set to true, try to extract a histogram with proper binning and axis labels
[out]	ematInv	(default=nullptr) to return the inverse covariance matrix

returns a new histogram. See method GetOutput() for a detailed description of the arguments. The inverse of the covariance matrix is stored in a new histogram returned by ematInv if that pointer is non-zero.

Definition at line 813 of file TUnfoldDensity.cxx.

◆ GetScanVariable()

Double_t TUnfoldDensity::GetScanVariable	(	Int_t	mode,
		const char *	distribution,
		const char *	axisSteering
	)

virtual

calculate the function for ScanTau()

Parameters

[in]	mode	the variable to be calculated
[in]	distribution	distribution for which the variable is to be calculated
[in]	axisSteering	detailed steering for selecting bins on the axes of the distribution (see method GetRhoItotal())

return value: the scan result for the given choice of tau (for which the unfolding was performed prior to calling this method)
In ScanTau() the unfolding is repeated for various choices of tau. For each tau, after unfolding, GetScanVariable() is called to determine the scan result for this choice of tau.
the following modes are implemented

kEScanTauRhoAvg : average (stat+bgr) global correlation
kEScanTauRhoSquaredAvg : average (stat+bgr) global correlation squared
kEScanTauRhoMax : maximum (stat+bgr) global correlation
kEScanTauRhoAvgSys : average (stat+bgr+sys) global correlation
kEScanTauRhoAvgSquaredSys : average (stat+bgr+sys) global correlation squared
kEScanTauRhoMaxSys : maximum (stat+bgr+sys) global correlation

Definition at line 1680 of file TUnfoldDensity.cxx.

◆ IsA()

TClass * TUnfoldDensity::IsA ( ) const

inlineoverridevirtual

Returns: TClass describing current object

Reimplemented from TUnfold.

Definition at line 205 of file TUnfoldDensity.h.

◆ RegularizeDistribution()

void TUnfoldDensity::RegularizeDistribution	(	ERegMode	regmode,
		EDensityMode	densityMode,
		const char *	distribution,
		const char *	axisSteering
	)

set up regularisation conditions

Parameters

[in]	regmode	basic regularisation mode (see class TUnfold)
[in]	densityMode	how to apply bin-wise factors
[in]	distribution	name of the TUnfoldBinning node for which the regularisation conditions shall be set (zero matches all nodes)
[in]	axisSteering	regularisation fine-tuning

axisSteering is a string with several tokens, separated by a semicolon: "axisName[options];axisName[options];...".

axisName: the name of an axis. The special name * matches all. So the argument distribution selects one (or all) distributions. Witin the selected distribution(s), steering options may be specified for each axis (or for all axes) to define the regularisation conditions.
options: one or several character as follows
u : exclude underflow bin from derivatives along this axis
o : exclude overflow bin from derivatives along this axis
U : exclude underflow bin
O : exclude overflow bin
b : use bin width for derivative calculation
B : same as 'b', in addition normalize to average bin width
N : completely exclude derivatives along this axis
p : axis is periodic (e.g. azimuthal angle), so include derivatives built from combinations involving bins at both ends of the axis "wrap around"

example: axisSteering="*[UOB]" uses bin widths to calculate derivatives but underflow/overflow bins are not regularized

Definition at line 386 of file TUnfoldDensity.cxx.

◆ RegularizeDistributionRecursive()

void TUnfoldDensity::RegularizeDistributionRecursive	(	const TUnfoldBinning *	binning,
		ERegMode	regmode,
		EDensityMode	densityMode,
		const char *	distribution,
		const char *	axisSteering
	)

protected

recursively add regularisation conditions for this node and its children

Parameters

[in]	binning	current node
[in]	regmode	regularisation mode
[in]	densityMode	type of regularisation scaling
[in]	distribution	target distribution(s) name
[in]	axisSteering	steering within the target distribution(s)

Definition at line 403 of file TUnfoldDensity.cxx.

◆ RegularizeOneDistribution()

void TUnfoldDensity::RegularizeOneDistribution	(	const TUnfoldBinning *	binning,
		ERegMode	regmode,
		EDensityMode	densityMode,
		const char *	axisSteering
	)

protected

regularize the distribution fof the given node

Parameters

[in]	binning	current node
[in]	regmode	regularisation mode
[in]	densityMode	type of regularisation scaling
[in]	axisSteering	detailed steering for the axes of the distribution

Definition at line 424 of file TUnfoldDensity.cxx.

◆ ScanTau()

Int_t TUnfoldDensity::ScanTau	(	Int_t	nPoint,
		Double_t	tauMin,
		Double_t	tauMax,
		TSpline **	scanResult,
		Int_t	mode = `kEScanTauRhoAvg`,
		const char *	distribution = `nullptr`,
		const char *	axisSteering = `nullptr`,
		TGraph **	lCurvePlot = `nullptr`,
		TSpline **	logTauXPlot = `nullptr`,
		TSpline **	logTauYPlot = `nullptr`
	)

virtual

scan a function wrt tau and determine the minimum

Parameters

[in]	nPoint	number of points to be scanned
[in]	tauMin	smallest tau value to study
[in]	tauMax	largest tau value to study
[out]	scanResult	the scanned function wrt log(tau)
[in]	mode	1st parameter for the scan function
[in]	distribution	2nd parameter for the scan function
[in]	projectionMode	3rd parameter for the scan function
[out]	lCurvePlot	for monitoring, shows the L-curve
[out]	logTauXPlot	for monitoring, L-curve(X) as a function of log(tau)
[out]	logTauYPlot	for monitoring, L-curve(Y) as a function of log(tau)

Return value: the coordinate number on the curve scanResult which corresponds to the minimum
The function is scanned by repeating the following steps nPoint times

Choose a value of tau
Perform the unfolding for this choice of tau, DoUnfold(tau)
Determinethe scan variable GetScanVariable()

The method GetScanVariable() defines scans of correlation coefficients, where mode is chosen from the enum EScanTauMode. In addition one may set distribution and/or projectionMode to refine the calculation of correlations (e.g. restrict the calcuation to the signal distribution and/or exclude underflow and overflow bins). See the documentation of GetScanVariable() for details. Alternative scan variables may be defined by overriding the GetScanVariable() method.
Automatic choice of scan range: if (tauMin,tauMax) do not correspond to a valid tau range (e.g. tauMin=tauMax=0.0) then the tau range is determined automatically. Use with care!

Definition at line 1354 of file TUnfoldDensity.cxx.

◆ Streamer()

void TUnfoldDensity::Streamer ( TBuffer & R__b )

overridevirtual

Stream an object of class TObject.

Reimplemented from TUnfold.

◆ StreamerNVirtual()

void TUnfoldDensity::StreamerNVirtual ( TBuffer & ClassDef_StreamerNVirtual_b )

inline

Definition at line 205 of file TUnfoldDensity.h.

Member Data Documentation

◆ fConstInputBins

const TUnfoldBinning* TUnfoldDensity::fConstInputBins

protected

binning scheme for the input (detector level)

Definition at line 57 of file TUnfoldDensity.h.

◆ fConstOutputBins

const TUnfoldBinning* TUnfoldDensity::fConstOutputBins

protected

binning scheme for the output (truth level)

Definition at line 55 of file TUnfoldDensity.h.

◆ fOwnedInputBins

TUnfoldBinning* TUnfoldDensity::fOwnedInputBins

protected

pointer to input binning scheme if owned by this class

Definition at line 61 of file TUnfoldDensity.h.

◆ fOwnedOutputBins

TUnfoldBinning* TUnfoldDensity::fOwnedOutputBins

protected

pointer to output binning scheme if owned by this class

Definition at line 59 of file TUnfoldDensity.h.

◆ fRegularisationConditions

TUnfoldBinning* TUnfoldDensity::fRegularisationConditions

protected

binning scheme for the regularisation conditions

Definition at line 63 of file TUnfoldDensity.h.

hist/unfold/inc/TUnfoldDensity.h

hist/unfold/src/TUnfoldDensity.cxx

Brief recipy to use TUnfoldSys:

Why to use complex binning schemes

How to choose the regularisation settings

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Member Enumeration Documentation

◆ EDensityMode

◆ EScanTauMode

Constructor & Destructor Documentation

◆ TUnfoldDensity() [1/2]

◆ TUnfoldDensity() [2/2]

◆ ~TUnfoldDensity()

Member Function Documentation

◆ Class()

◆ Class_Name()

◆ Class_Version()

◆ DeclFileName()

◆ GetBackground()

◆ GetBias()

◆ GetDeltaSysBackgroundScale()

◆ GetDeltaSysSource()

◆ GetDeltaSysTau()

◆ GetDensityFactor()

◆ GetDXDY()

◆ GetEmatrixInput()

◆ GetEmatrixSysBackgroundUncorr()

◆ GetEmatrixSysUncorr()

◆ GetEmatrixTotal()

◆ GetFoldedOutput()

◆ GetInput()

◆ GetInputBinning()

◆ GetL()

◆ GetLBinning()

◆ GetLxMinusBias()

◆ GetOutput()

◆ GetOutputBinName()

◆ GetOutputBinning()

◆ GetProbabilityMatrix()

◆ GetRhoIJtotal()

◆ GetRhoIstatbgr()

◆ GetRhoItotal()

◆ GetScanVariable()

◆ IsA()

◆ RegularizeDistribution()

◆ RegularizeDistributionRecursive()

◆ RegularizeOneDistribution()

◆ ScanTau()

◆ Streamer()

◆ StreamerNVirtual()

Member Data Documentation

◆ fConstInputBins

◆ fConstOutputBins

◆ fOwnedInputBins

◆ fOwnedOutputBins

◆ fRegularisationConditions