TUnfoldDensityV17 Class Reference

An algorithm to unfold distributions from detector to truth level. More...

#include <TUnfoldDensity.h>

Collaboration diagram for TUnfoldDensityV17:

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 Member Functions
	TUnfoldDensityV17 (void)
	only for use by root streamer or derived classes
	TUnfoldDensityV17 (const TH2 hist_A, EHistMap histmap, ERegMode regmode=kRegModeCurvature, EConstraint constraint=kEConstraintArea, EDensityMode densityMode=kDensityModeBinWidthAndUser, const TUnfoldBinningV17 outputBins=0, const TUnfoldBinningV17 inputBins=0, const char regularisationDistribution=0, const char regularisationAxisSteering="[UOB]")
	set up response matrix A, uncorrelated uncertainties of A, regularisation scheme and binning schemes
virtual	~TUnfoldDensityV17 (void)
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=0, const char projectionMode=0, TGraph lCurvePlot=0, TSpline logTauXPlot=0, TSpline *logTauYPlot=0)
	scan a function wrt tau and determine the minimum
virtual Double_t	GetScanVariable (Int_t mode, const char distribution, const char projectionMode)
	calculate the function for ScanTau()
TH1 *	GetOutput (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE) const
	retreive unfolding result as a new histogram
TH1 *	GetBias (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE) const
	retreive bias vector as a new histogram
TH1 *	GetFoldedOutput (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE, Bool_t addBgr=kFALSE) const
	retreive unfolding result folded back as a new histogram
TH1 *	GetBackground (const char histogramName, const char bgrSource=0, const char histogramTitle=0, const char distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE, Int_t includeError=3) const
	retreive a background source in a new histogram
TH1 *	GetInput (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE) const
	retreive input distribution in a new histogram
TH1 *	GetDeltaSysSource (const char source, const char histogramName, const char histogramTitle=0, const char distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
	retreive a correlated systematic 1-sigma shift
TH1 *	GetDeltaSysBackgroundScale (const char bgrSource, const char histogramName, const char histogramTitle=0, const char distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
	retreive systematic 1-sigma shift corresponding to a background scale uncertainty
TH1 *	GetDeltaSysTau (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE)
	retreive1-sigma shift corresponding to the previously specified uncertainty on tau
TH2 *	GetEmatrixSysUncorr (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE)
	retreive covaraince contribution from uncorrelated (statistical) uncertainties of the response matrix
TH2 *	GetEmatrixSysBackgroundUncorr (const char bgrSource, const char histogramName, const char histogramTitle=0, const char distributionName=0, const char *projectionMode=0, Bool_t useAxisBinning=kTRUE)
	retreive covariance contribution from uncorrelated background uncertainties
TH2 *	GetEmatrixInput (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE)
	get covariance contribution from the input uncertainties (data statistical uncertainties)
TH2 *	GetEmatrixTotal (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE)
	get covariance matrix including all contributions
TH1 *	GetRhoIstatbgr (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE, TH2 **ematInv=0)
	retreive global correlation coefficients including input (statistical) and background uncertainties
TH1 *	GetRhoItotal (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE, TH2 **ematInv=0)
	retreive global correlation coefficients including all uncertainty sources
TH2 *	GetRhoIJtotal (const char histogramName, const char histogramTitle=0, const char distributionName=0, const char projectionMode=0, Bool_t useAxisBinning=kTRUE)
	retreive correlation coefficients, including all uncertainties
TH2 *	GetL (const char histogramName, const char histogramTitle=0, Bool_t useAxisBinning=kTRUE)
	access matrix of regularisation conditions in a new histogram
TH1 *	GetLxMinusBias (const char histogramName, const char histogramTitle=0)
	get regularisation conditions multiplied by result vector minus bias L(x-biasScale*biasVector)
TH2 *	GetProbabilityMatrix (const char histogramName, const char histogramTitle=0, Bool_t useAxisBinning=kTRUE) const
	get matrix of probabilities in a new histogram
const TUnfoldBinningV17 *	GetInputBinning (const char *distributionName=0) const
	locate a binning node for the input (measured) quantities
const TUnfoldBinningV17 *	GetOutputBinning (const char *distributionName=0) const
	locate a binning node for the unfolded (truth level) quantities
TUnfoldBinningV17 *	GetLBinning (void) const
	return binning scheme for regularisation conditions (matrix L)
Protected Member Functions
virtual TString	GetOutputBinName (Int_t iBinX) const
	Get bin name of an outpt bin.
Double_t	GetDensityFactor (EDensityMode densityMode, Int_t iBin) const
	density correction factor for a given bin
void	RegularizeDistributionRecursive (const TUnfoldBinningV17 binning, ERegMode regmode, EDensityMode densityMode, const char distribution, const char *axisSteering)
	recursively add regularisation conditions for this node and its children
void	RegularizeOneDistribution (const TUnfoldBinningV17 binning, ERegMode regmode, EDensityMode densityMode, const char axisSteering)
	regularize the distribution fof the given node
Protected Attributes
const TUnfoldBinningV17 *	fConstOutputBins
	binning scheme for the output (truth level)
const TUnfoldBinningV17 *	fConstInputBins
	binning scheme for the input (detector level)
TUnfoldBinningV17 *	fOwnedOutputBins
	pointer to output binning scheme if owned by this class
TUnfoldBinningV17 *	fOwnedInputBins
	pointer to input binning scheme if owned by this class
TUnfoldBinningV17 *	fRegularisationConditions
	binning scheme for the regularisation conditions

Detailed Description

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://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 49 of file TUnfoldDensity.h.

Member Enumeration Documentation

enum TUnfoldDensityV17::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 64 of file TUnfoldDensity.h.

enum TUnfoldDensityV17::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 106 of file TUnfoldDensity.h.

Constructor & Destructor Documentation

TUnfoldDensityV17::TUnfoldDensityV17 ( void )

only for use by root streamer or derived classes

Definition at line 178 of file TUnfoldDensityV17.cxx.

TUnfoldDensityV17::TUnfoldDensityV17	(	const TH2 *	hist_A,
		EHistMap	histmap,
		ERegMode	regmode = `kRegModeCurvature`,
		EConstraint	constraint = `kEConstraintArea`,
		EDensityMode	densityMode = `kDensityModeBinWidthAndUser`,
		const TUnfoldBinningV17 *	outputBins = `0`,
		const TUnfoldBinningV17 *	inputBins = `0`,
		const char *	regularisationDistribution = `0`,
		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=0) binning scheme for truth (unfolding output)
`[in]`	inputBins	(default=0) binning scheme for measurement (unfolding input)
`[in]`	regularisationDistribution	(default=0) selectin of regularized distribution
`[in]`	regularisationAxisSteering	(default=0) 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 218 of file TUnfoldDensityV17.cxx.

virtual TUnfoldDensityV17::~TUnfoldDensityV17 ( void ) [virtual]

Member Function Documentation

TH1 * TUnfoldDensityV17::GetBackground	(	const char *	histogramName,
		const char *	bgrSource = `0`,
		const char *	histogramTitle = `0`,
		const char *	distributionName = `0`,
		const char *	axisSteering = `0`,
		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=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 748 of file TUnfoldDensityV17.cxx.

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

retreive bias vector as a new histogram

Parameters:

`[in]`	histogramName	name 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 682 of file TUnfoldDensityV17.cxx.

TH1 * TUnfoldDensityV17::GetDeltaSysBackgroundScale	(	const char *	bgrSource,
		const char *	histogramName,
		const char *	histogramTitle = `0`,
		const char *	distributionName = `0`,
		const char *	axisSteering = `0`,
		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=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 941 of file TUnfoldDensityV17.cxx.

TH1 * TUnfoldDensityV17::GetDeltaSysSource	(	const char *	source,
		const char *	histogramName,
		const char *	histogramTitle = `0`,
		const char *	distributionName = `0`,
		const char *	axisSteering = `0`,
		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=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 908 of file TUnfoldDensityV17.cxx.

TH1 * TUnfoldDensityV17::GetDeltaSysTau	(	const char *	histogramName,
		const char *	histogramTitle = `0`,
		const char *	distributionName = `0`,
		const char *	axisSteering = `0`,
		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=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 973 of file TUnfoldDensityV17.cxx.

Double_t TUnfoldDensityV17::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 332 of file TUnfoldDensityV17.cxx.

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

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

Parameters:

`[in]`	histogramName	name 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 1116 of file TUnfoldDensityV17.cxx.

TH2 * TUnfoldDensityV17::GetEmatrixSysBackgroundUncorr	(	const char *	bgrSource,
		const char *	histogramName,
		const char *	histogramTitle = `0`,
		const char *	distributionName = `0`,
		const char *	axisSteering = `0`,
		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=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 1085 of file TUnfoldDensityV17.cxx.

TH2 * TUnfoldDensityV17::GetEmatrixSysUncorr	(	const char *	histogramName,
		const char *	histogramTitle = `0`,
		const char *	distributionName = `0`,
		const char *	axisSteering = `0`,
		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=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 1055 of file TUnfoldDensityV17.cxx.

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

get covariance matrix including all contributions

Parameters:

`[in]`	histogramName	name 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 1167 of file TUnfoldDensityV17.cxx.

TH1 * TUnfoldDensityV17::GetFoldedOutput	(	const char *	histogramName,
		const char *	histogramTitle = `0`,
		const char *	distributionName = `0`,
		const char *	axisSteering = `0`,
		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=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 713 of file TUnfoldDensityV17.cxx.

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

retreive input distribution in a new histogram

Parameters:

`[in]`	histogramName	name 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 778 of file TUnfoldDensityV17.cxx.

const TUnfoldBinning * TUnfoldDensityV17::GetInputBinning ( const char * distributionName = 0 ) 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 1269 of file TUnfoldDensityV17.cxx.

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

access matrix of regularisation conditions in a new histogram

Parameters:

`[in]`	histogramName	name 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 1194 of file TUnfoldDensityV17.cxx.

TUnfoldBinningV17* TUnfoldDensityV17::GetLBinning ( void ) const [inline]

return binning scheme for regularisation conditions (matrix L)

Definition at line 198 of file TUnfoldDensity.h.

TH1 * TUnfoldDensityV17::GetLxMinusBias	(	const char *	histogramName,
		const char *	histogramTitle = `0`
	)

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

Parameters:

`[in]`	histogramName	name of the histogram
`[in]`	histogramTitle	(default=0) 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 1231 of file TUnfoldDensityV17.cxx.

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

retreive unfolding result as a new histogram

Parameters:

`[in]`	histogramName	name 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 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 651 of file TUnfoldDensityV17.cxx.

TString TUnfoldDensityV17::GetOutputBinName ( Int_t iBinX ) const [protected, virtual]

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

Definition at line 307 of file TUnfoldDensityV17.cxx.

const TUnfoldBinning * TUnfoldDensityV17::GetOutputBinning ( const char * distributionName = 0 ) 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 1285 of file TUnfoldDensityV17.cxx.

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

get matrix of probabilities in a new histogram

Parameters:

`[in]`	histogramName	name 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 1142 of file TUnfoldDensityV17.cxx.

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

retreive correlation coefficients, including all uncertainties

Parameters:

`[in]`	histogramName	name 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 1004 of file TUnfoldDensityV17.cxx.

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

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

Parameters:

`[in]`	histogramName	name 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 860 of file TUnfoldDensityV17.cxx.

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

retreive global correlation coefficients including all uncertainty sources

Parameters:

`[in]`	histogramName	name 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 810 of file TUnfoldDensityV17.cxx.

Double_t TUnfoldDensityV17::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 1656 of file TUnfoldDensityV17.cxx.

void TUnfoldDensityV17::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 383 of file TUnfoldDensityV17.cxx.

void TUnfoldDensityV17::RegularizeDistributionRecursive	(	const TUnfoldBinningV17 *	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 400 of file TUnfoldDensityV17.cxx.

void TUnfoldDensityV17::RegularizeOneDistribution	(	const TUnfoldBinningV17 *	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 421 of file TUnfoldDensityV17.cxx.

Int_t TUnfoldDensityV17::ScanTau	(	Int_t	nPoint,
		Double_t	tauMin,
		Double_t	tauMax,
		TSpline **	scanResult,
		Int_t	mode = `kEScanTauRhoAvg`,
		const char *	distribution = `0`,
		const char *	axisSteering = `0`,
		TGraph **	lCurvePlot = `0`,
		TSpline **	logTauXPlot = `0`,
		TSpline **	logTauYPlot = `0`
	)			`[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 1330 of file TUnfoldDensityV17.cxx.