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

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 recipe 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 choice of tau, method ScanLCurve()
    • or multiple times in a scan to determine the best choice 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 auxiliary 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 auxiliary 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

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

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:

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

This file is part of TUnfold.

TUnfold is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

TUnfold is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with TUnfold. If not, see http://www.gnu.org/licenses/.

Version 17.6, with updated doxygen comments and bug-fixes in TUnfoldBinning

History:

  • Version 17.5, bug fix in TUnfold also corrects GetEmatrixSysUncorr()
  • Version 17.4, in parallel to changes in TUnfoldBinning
  • Version 17.3, in parallel to changes in TUnfoldBinning
  • Version 17.2, with new options 'N' and 'c' for axis regularisation steering
  • Version 17.1, add scan type RhoSquare, small bug fixes with useAxisBinning
  • Version 17.0, support for density regularisation, complex binning schemes, tau scan

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

Static Public Member Functions

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

Protected Member Functions

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 output 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 of 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.
 
TMatrixDSparseGetSummedErrorMatrixXX (void)
 Determine total error matrix on the vector x.
 
TMatrixDSparseGetSummedErrorMatrixYY (void)
 Determine total error matrix on the vector Ax.
 
virtual TMatrixDSparsePrepareCorrEmat (const TMatrixDSparse *m1, const TMatrixDSparse *m2, const TMatrixDSparse *dsys)
 Propagate correlated systematic shift to an output vector.
 
virtual void PrepareSysError (void)
 Matrix calculations required to propagate systematic errors.
 
virtual TMatrixDSparsePrepareUncorrEmat (const TMatrixDSparse *m1, const TMatrixDSparse *m2)
 Propagate uncorrelated systematic errors to a covariance matrix.
 
void ScaleColumnsByVector (TMatrixDSparse *m, const TMatrixTBase< Double_t > *v) const
 Scale columns of a matrix by the corresponding rows of a vector.
 
void VectorMapToHist (TH1 *hist_delta, const TMatrixDSparse *delta, const Int_t *binMap)
 Map delta to hist_delta, possibly summing up bins.
 
- Protected Member Functions inherited from TUnfold
void AddMSparse (TMatrixDSparse *dest, Double_t f, const TMatrixDSparse *src) const
 Add a sparse matrix, scaled by a factor, to another scaled matrix.
 
Bool_t AddRegularisationCondition (Int_t i0, Double_t f0, Int_t i1=-1, Double_t f1=0., Int_t i2=-1, Double_t f2=0.)
 Add a row of regularisation conditions to the matrix L.
 
Bool_t AddRegularisationCondition (Int_t nEle, const Int_t *indices, const Double_t *rowData)
 Add a row of regularisation conditions to the matrix L.
 
void ClearHistogram (TH1 *h, Double_t x=0.) const
 Initialize bin contents and bin errors for a given histogram.
 
TMatrixDSparseCreateSparseMatrix (Int_t nrow, Int_t ncol, Int_t nele, Int_t *row, Int_t *col, Double_t *data) const
 Create a sparse matrix, given the nonzero elements.
 
virtual Double_t DoUnfold (void)
 Core unfolding algorithm.
 
void ErrorMatrixToHist (TH2 *ematrix, const TMatrixDSparse *emat, const Int_t *binMap, Bool_t doClear) const
 Add up an error matrix, also respecting the bin mapping.
 
const TMatrixDSparseGetAx (void) const
 vector of folded-back result
 
Int_t GetBinFromRow (int ix) const
 converts matrix row to truth histogram bin number
 
const TMatrixDSparseGetDXDAM (int i) const
 matrix contributions of the derivative dx/dA
 
const TMatrixDSparseGetDXDAZ (int i) const
 vector contributions of the derivative dx/dA
 
const TMatrixDSparseGetDXDtauSquared (void) const
 vector of derivative dx/dtauSquared, using internal bin counting
 
const TMatrixDSparseGetDXDY (void) const
 matrix of derivatives dx/dy
 
const TMatrixDSparseGetE (void) const
 matrix E, using internal bin counting
 
const TMatrixDSparseGetEinv (void) const
 matrix E-1, using internal bin counting
 
Int_t GetNx (void) const
 returns internal number of output (truth) matrix rows
 
Int_t GetNy (void) const
 returns the number of measurement bins
 
Double_t GetRhoIFromMatrix (TH1 *rhoi, const TMatrixDSparse *eOrig, const Int_t *binMap, TH2 *invEmat) const
 Get global correlation coefficients with arbitrary min map.
 
Int_t GetRowFromBin (int ix) const
 converts truth histogram bin number to matrix row
 
const TMatrixDSparseGetVxx (void) const
 covariance matrix of the result
 
const TMatrixDSparseGetVxxInv (void) const
 inverse of covariance matrix of the result
 
const TMatrixDSparseGetVyyInv (void) const
 inverse of covariance matrix of the data y
 
const TMatrixDGetX (void) const
 vector of the unfolding result
 
TMatrixDSparseInvertMSparseSymmPos (const TMatrixDSparse *A, Int_t *rank) const
 Get the inverse or pseudo-inverse of a positive, sparse matrix.
 
TMatrixDSparseMultiplyMSparseM (const TMatrixDSparse *a, const TMatrixD *b) const
 Multiply sparse matrix and a non-sparse matrix.
 
TMatrixDSparseMultiplyMSparseMSparse (const TMatrixDSparse *a, const TMatrixDSparse *b) const
 Multiply two sparse matrices.
 
TMatrixDSparseMultiplyMSparseMSparseTranspVector (const TMatrixDSparse *m1, const TMatrixDSparse *m2, const TMatrixTBase< Double_t > *v) const
 Calculate a sparse matrix product \( M1*V*M2^{T} \) where the diagonal matrix V is given by a vector.
 
TMatrixDSparseMultiplyMSparseTranspMSparse (const TMatrixDSparse *a, const TMatrixDSparse *b) const
 Multiply a transposed Sparse matrix with another sparse matrix,.
 
- Protected Member Functions inherited from TObject
virtual void DoError (int level, const char *location, const char *fmt, va_list va) const
 Interface to ErrorHandler (protected).
 
void MakeZombie ()
 

Protected Attributes

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

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

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 63 of file TUnfoldDensity.h.

◆ 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 105 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 177 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]" 
)

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

Parameters
[in]hist_Amatrix that describes the migrations
[in]histmapmapping of the histogram axes to the unfolding output
[in]regmode(default=kRegModeSize) global regularisation mode
[in]constraint(default=kEConstraintArea) type of constraint
[in]densityMode(default=kDensityModeBinWidthAndUser) regularisation scale factors to construct the matrix L
[in]outputBins(default=0) binning scheme for truth (unfolding output)
[in]inputBins(default=0) binning scheme for measurement (unfolding input)
[in]regularisationDistribution(default=0) selection of regularized distribution
[in]regularisationAxisSteering(default=0) detailed regularisation steering for 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 217 of file TUnfoldDensity.cxx.

◆ ~TUnfoldDensity()

TUnfoldDensity::~TUnfoldDensity ( void  )
override

Definition at line 166 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 199 of file TUnfoldDensity.h.

◆ DeclFileName()

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

Definition at line 199 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

Retrieve a background source in a new histogram.

Parameters
[in]histogramNamename of the histogram
[in]bgrSourcethe background source to retrieve
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 758 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

Retrieve bias vector as a new histogram.

Parameters
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 690 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 
)

Retrieve systematic 1-sigma shift corresponding to a background scale uncertainty.

Parameters
[in]bgrSourceidentifier of the background
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 954 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 
)

Retrieve a correlated systematic 1-sigma shift.

Parameters
[in]sourceidentifier of the systematic uncertainty source
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 920 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 
)

Retrieve 1-sigma shift corresponding to the previously specified uncertainty on tau.

Parameters
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 987 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]densityModetype of factor to calculate
[in]iBinbin 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 332 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]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 1133 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 
)

Retrieve covariance contribution from uncorrelated background uncertainties.

Parameters
[in]bgrSourceidentifier of the background
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 1102 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 
)

Retrieve covariance contribution from uncorrelated (statistical) uncertainties of the response matrix.

Parameters
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 1071 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]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 1185 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

Retrieve unfolding result folded back as a new histogram.

Parameters
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 722 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

Retrieve input distribution in a new histogram.

Parameters
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 788 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=0) distribution to look for. if zero, return the root node

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

Definition at line 1289 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]histogramNamename of the histogram
[in]histogramTitle(default=0) 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 1212 of file TUnfoldDensity.cxx.

◆ GetLBinning()

TUnfoldBinning * TUnfoldDensity::GetLBinning ( void  ) const
inline

return binning scheme for regularisation conditions (matrix L)

Definition at line 197 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]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram

returns a new histogram. This is a measure of the level of regularization 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 1250 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

retrieve unfolding result as a new histogram

Parameters
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 discard underflow bin
  • O discard 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 658 of file TUnfoldDensity.cxx.

◆ GetOutputBinName()

TString TUnfoldDensity::GetOutputBinName ( Int_t  iBinX) const
overrideprotectedvirtual

Get bin name of an output bin.

Parameters
[in]iBinXbin 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 307 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=0) distribution to look for. if zero, return the root node

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

Definition at line 1305 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]histogramNamename of the histogram
[in]histogramTitle(default=0) 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 1160 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 
)

Retrieve correlation coefficients, including all uncertainties.

Parameters
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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 1019 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 
)

Retrieve global correlation coefficients including input (statistical) and background uncertainties.

Parameters
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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=0) 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 872 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 
)

Retrieve global correlation coefficients including all uncertainty sources.

Parameters
[in]histogramNamename of the histogram
[in]histogramTitle(default=0) title of the histogram
[in]distributionName(default=0) identifier of the distribution to be extracted
[in]axisSteering(default=0) 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=0) 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 821 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]modethe variable to be calculated
[in]distributiondistribution for which the variable is to be calculated
[in]axisSteeringdetailed 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 1675 of file TUnfoldDensity.cxx.

◆ IsA()

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

Reimplemented from TUnfold.

Definition at line 199 of file TUnfoldDensity.h.

◆ RegularizeDistribution()

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

Set up regularisation conditions.

Parameters
[in]regmodebasic regularisation mode (see class TUnfold)
[in]densityModehow to apply bin-wise factors
[in]distributionname of the TUnfoldBinning node for which the regularisation conditions shall be set (zero matches all nodes)
[in]axisSteeringregularisation 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. Within 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 383 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]binningcurrent node
[in]regmoderegularisation mode
[in]densityModetype of regularisation scaling
[in]distributiontarget distribution(s) name
[in]axisSteeringsteering within the target distribution(s)

Definition at line 401 of file TUnfoldDensity.cxx.

◆ RegularizeOneDistribution()

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

Regularize the distribution of the given node.

Parameters
[in]binningcurrent node
[in]regmoderegularisation mode
[in]densityModetype of regularisation scaling
[in]axisSteeringdetailed steering for the axes of the distribution

Definition at line 422 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]nPointnumber of points to be scanned
[in]tauMinsmallest tau value to study
[in]tauMaxlargest tau value to study
[out]scanResultthe scanned function wrt log(tau)
[in]mode1st parameter for the scan function
[in]distribution2nd parameter for the scan function
[in]axisSteering3rd parameter for the scan function
[out]lCurvePlotfor monitoring, shows the L-curve
[out]logTauXPlotfor monitoring, L-curve(X) as a function of log(tau)
[out]logTauYPlotfor 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

  1. Choose a value of tau
  2. Perform the unfolding for this choice of tau, DoUnfold(tau)
  3. Determine the 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 calculation 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 1351 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 199 of file TUnfoldDensity.h.

Member Data Documentation

◆ fConstInputBins

const TUnfoldBinning* TUnfoldDensity::fConstInputBins
protected

binning scheme for the input (detector level)

Definition at line 53 of file TUnfoldDensity.h.

◆ fConstOutputBins

const TUnfoldBinning* TUnfoldDensity::fConstOutputBins
protected

binning scheme for the output (truth level)

Definition at line 51 of file TUnfoldDensity.h.

◆ fOwnedInputBins

TUnfoldBinning* TUnfoldDensity::fOwnedInputBins
protected

pointer to input binning scheme if owned by this class

Definition at line 57 of file TUnfoldDensity.h.

◆ fOwnedOutputBins

TUnfoldBinning* TUnfoldDensity::fOwnedOutputBins
protected

pointer to output binning scheme if owned by this class

Definition at line 55 of file TUnfoldDensity.h.

◆ fRegularisationConditions

TUnfoldBinning* TUnfoldDensity::fRegularisationConditions
protected

binning scheme for the regularisation conditions

Definition at line 59 of file TUnfoldDensity.h.

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