TUnfoldBinningV17 Class Reference

Binning schemes for use with the unfolding algorithm TUnfoldDensity. More...

#include <TUnfoldBinning.h>

Collaboration diagram for TUnfoldBinningV17:

Public Types
enum	{ MAXDIM = 32 }
Public Member Functions
	TUnfoldBinningV17 (const char name=0, Int_t nBins=0, const char binNames=0)
	create a new node without axis
	TUnfoldBinningV17 (const TAxis &axis, Int_t includeUnderflow, Int_t includeOverflow)
	create a new node containing a distribution with one axis
TUnfoldBinningV17 *	AddBinning (TUnfoldBinningV17 *binning)
	add a TUnfoldBinning as the last child of this node
TUnfoldBinningV17 *	AddBinning (const char name, Int_t nBins=0, const char binNames=0)
	add a new binning node as last last child of this node
Bool_t	AddAxis (const char name, Int_t nBins, const Double_t binBorders, Bool_t hasUnderflow, Bool_t hasOverflow)
	add an axis with the specified bin borders
Bool_t	AddAxis (const char *name, Int_t nBins, Double_t xMin, Double_t xMax, Bool_t hasUnderflow, Bool_t hasOverflow)
	add an axis with equidistant bins
Bool_t	AddAxis (const TAxis &axis, Bool_t includeUnderflow, Bool_t includeOverflow)
	add an axis to the distribution, using the TAxis as blueprint
virtual	~TUnfoldBinningV17 (void)
void	PrintStream (std::ostream &out, Int_t indent=0, int debug=0) const
	print some information about this binning tree
void	SetBinFactorFunction (Double_t normalisation, TF1 *userFunc=0)
	set normalisation factor and function which are used in calls to GetBinFactor()
TUnfoldBinningV17 const *	GetChildNode (void) const
	first daughter node
TUnfoldBinningV17 const *	GetPrevNode (void) const
	previous sister node
TUnfoldBinningV17 const *	GetNextNode (void) const
	next sister node
TUnfoldBinningV17 const *	GetParentNode (void) const
	mother node
TUnfoldBinningV17 const *	FindNode (char const *name) const
	traverse the tree and return the first node which matches the given name
TUnfoldBinningV17 const *	GetRootNode (void) const
	return root node of the binnig scheme
Int_t	GetTH1xNumberOfBins (Bool_t originalAxisBinning=kTRUE, const char *axisSteering=0) const
	return the number of histogram bins required when storing this binning in a one-dimensional histogram
TH1 *	CreateHistogram (const char histogramName, Bool_t originalAxisBinning=kFALSE, Int_t binMap=0, const char histogramTitle=0, const char *axisSteering=0) const
	create a THxx histogram capable to hold the bins of this binning node and its children
TH2D *	CreateErrorMatrixHistogram (const char histogramName, Bool_t originalAxisBinning, Int_t binMap=0, const char histogramTitle=0, const char *axisSteering=0) const
	create a TH2D histogram capable to hold a covariance matrix
TH1 *	ExtractHistogram (const char histogramName, const TH1 globalBins, const TH2 globalBinsEmatrix=0, Bool_t originalAxisBinning=kTRUE, const char axisSteering=0) const
Int_t *	CreateEmptyBinMap (void) const
	create an empty bin map, useful together with the getter methods of class TUnfold and TUnfoldSys
void	SetBinMapEntry (Int_t *binMap, Int_t globalBin, Int_t destBin) const
	set one entry in a bin map
Int_t	FillBinMap1D (Int_t binMap, const char axisSteering, Int_t firstBinX) const
	map all global bins referenced by this node to the one-dimensional histogram destHist, starting with bin firstBinX
Int_t	GetGlobalBinNumber (Double_t x) const
	locate a bin in a one-dimensional distribution
Int_t	GetGlobalBinNumber (Double_t x, Double_t y) const
	locate a bin in a two-dimensional distribution
Int_t	GetGlobalBinNumber (Double_t x, Double_t y, Double_t z) const
	locate a bin in a three-dimensional distribution
Int_t	GetGlobalBinNumber (Double_t x0, Double_t x1, Double_t x2, Double_t x3) const
	locate a bin in a four-dimensional distribution
Int_t	GetGlobalBinNumber (Double_t x0, Double_t x1, Double_t x2, Double_t x3, Double_t x4) const
	locate a bin in a five-dimensional distribution
Int_t	GetGlobalBinNumber (Double_t x0, Double_t x1, Double_t x2, Double_t x3, Double_t x4, Double_t x5) const
	locate a bin in a six-dimensional distribution
Int_t	GetGlobalBinNumber (const Double_t x, Int_t isBelow=0, Int_t *isAbove=0) const
	locate a bin in an N-dimensional distribution
Int_t	GetStartBin (void) const
	first bin of this node
Int_t	GetEndBin (void) const
	last+1 bin of this node (includes children)
virtual Bool_t	IsBinFactorGlobal (void) const
	check whether there is only a global scaling factor for this node
Double_t	GetGlobalFactor (void) const
	return global scaling factor for this node
TString	GetBinName (Int_t iBin) const
	get the name of a bin
Double_t	GetBinSize (Int_t iBin) const
	get N-dimensional bin size
virtual Double_t	GetBinFactor (Int_t iBin) const
	return scaling factor for the given global bin number
void	GetBinUnderflowOverflowStatus (Int_t iBin, Int_t uStatus, Int_t oStatus) const
	return bit maps indicating underflow and overflow status
Int_t	GetBinNeighbours (Int_t globalBin, Int_t axis, Int_t prev, Double_t distPrev, Int_t next, Double_t distNext, Bool_t isPeriodic=kFALSE) const
	get neighbour bins along the specified axis
Int_t	GetDistributionNumberOfBins (void) const
	number of bins in the distribution possibly including under/overflow
Int_t	GetDistributionDimension (void) const
	query dimension of this node's distribution
virtual Double_t	GetDistributionAverageBinSize (Int_t axis, Bool_t includeUnderflow, Bool_t includeOverflow) const
	get average bin size on the specified axis
TVectorD const *	GetDistributionBinning (Int_t axis) const
	get vector of bin borders for one axis
TString	GetDistributionAxisLabel (Int_t axis) const
	get name of an axis
virtual Double_t	GetDistributionUnderflowBinWidth (Int_t axis) const
	return bin width assigned to the underflow bin
virtual Double_t	GetDistributionOverflowBinWidth (Int_t axis) const
	return bin width assigned to the overflow bin
virtual Double_t	GetDistributionBinCenter (Int_t axis, Int_t bin) const
	return bin center for a given axis and bin number
Bool_t	HasUnconnectedBins (void) const
	check whether there are bins but no axis
const TObjString *	GetUnconnectedBinName (Int_t bin) const
	return the bin names of unconnected bins
Bool_t	HasUnderflow (int axis) const
	check whether an axis has an underflow bin
Bool_t	HasOverflow (int axis) const
	check whether the axis has an overflow bin
void	DecodeAxisSteering (const char axisSteering, const char options, Int_t *isOptionGiven) const
	decode axis steering
Static Public Member Functions
static TH2D *	CreateHistogramOfMigrations (TUnfoldBinningV17 const xAxis, TUnfoldBinningV17 const yAxis, char const histogramName, Bool_t originalXAxisBinning=kFALSE, Bool_t originalYAxisBinning=kFALSE, char const histogramTitle=0)
	create a TH2D histogram capable to hold the bins of the two input binning schemes on the x and y axes, respectively
Protected Member Functions
TUnfoldBinningV17 *	GetRootNode (void)
	return root node
void	Initialize (Int_t nBins)
	initialize variables for a given number of bins
Int_t	UpdateFirstLastBin (Bool_t startWithRootNode=kTRUE)
	update fFirstBin and fLastBin members of this node and its children
TUnfoldBinningV17 const *	ToAxisBins (Int_t globalBin, Int_t *axisBins) const
	return distribution in which the bin is located and bin numbers on the corresponding axes
Int_t	ToGlobalBin (Int_t const axisBins, Int_t isBelow=0, Int_t *isAbove=0) const
	get global bin number, given axis bin numbers
TString	BuildHistogramTitle (const char histogramName, const char histogramTitle, Int_t const *axisList) const
	construct a title
TString	BuildHistogramTitle2D (const char histogramName, const char histogramTitle, Int_t xAxis, const TUnfoldBinningV17 *yAxisBinning, Int_t yAxis) const
	construct a histogram title for a 2D histogram with different binning schemes on x and y axis
Int_t	GetTHxxBinning (Int_t maxDim, Int_t axisBins, Int_t axisList, const char *axisSteering) const
	calculate properties of a THxx histogram to store this binning
Int_t	GetTHxxBinningSingleNode (Int_t maxDim, Int_t axisBins, Int_t axisList, const char *axisSteering) const
	get the properties of a histogram capable to hold the distribution attached to this node
Int_t	GetTHxxBinsRecursive (const char *axisSteering) const
	calculate number of bins required to store this binning with teh given axisSteering
const TUnfoldBinningV17 *	GetNonemptyNode (void) const
	find a node which has non-empty distributions if there is none or if there are many, return zero
Int_t *	CreateBinMap (const TH1 hist, Int_t nDim, const Int_t axisList, const char *axisSteering) const
	create mapping from global bin number to a histogram for this node
Int_t	FillBinMapRecursive (Int_t startBin, const char axisSteering, Int_t binMap) const
	recursively fill bin map
Int_t	FillBinMapSingleNode (const TH1 hist, Int_t startBin, Int_t nDim, const Int_t axisList, const char axisSteering, Int_t binMap) const
	fill bin map for a single node
void	SetBinFactor (Double_t normalisation, TObject *factors)
	set normalisation factors which are used in calls to GetBinFactor()
Protected Attributes
TUnfoldBinningV17 *	parentNode
	mother node
TUnfoldBinningV17 *	childNode
	first daughter node
TUnfoldBinningV17 *	nextNode
	next sister
TUnfoldBinningV17 *	prevNode
	previous sister
TObjArray *	fAxisList
	for each axis the bin borders (TVectorD)
TObjArray *	fAxisLabelList
	for each axis its name (TObjString), or names of unconnected bins
Int_t	fHasUnderflow
	bit fields indicating whether there are underflow bins on the axes
Int_t	fHasOverflow
	bit fields indicating whether there are overflow bins on the axes
Int_t	fDistributionSize
	number of bins in this node's distribution
Int_t	fFirstBin
	global bin number of the first bin
Int_t	fLastBin
	global bin number of the last(+1) bin, including daughters
TObject *	fBinFactorFunction
	function to calculate a scale factor from bin centres (may be a TF1 or a TVectorD
Double_t	fBinFactorConstant
	common scale factor for all bins of this node

Detailed Description

Binning schemes for use with the unfolding algorithm TUnfoldDensity.

Binning schemes are used to map analysis bins on a single histogram axis and back. The analysis bins may include unconnected bins (e.g nuisances for background normalisation) or various multidimensional histograms (signal bins, differential background normalisation bins, etc).
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

Functionality

The TUnfoldBinning objects are connected by a tree-like structure. The structure does not hold any data, but is only responsible for arranging the analysis bins in the proper order. Each node of the tree is responsible for a group of bins. That group may consist of

several unconnected bins, each with a dedicated name.
bins organized in a multidimensional distribution, defined by a set of axes. The axes are defined by a number of bins N and by (N+1) bin borders. In addition to the N bins inside there may be an underflow and an overflow bin

Each bin has a "global" bin number, which can be found using the GetGlobalBinNumber() methods. The global bin number 0 is reserved and corresponds to the case where no bin is found in the TUnfoldBinning tree.

Use in the analysis

Booking histograms:

Define binning schemes on detector level and on truth level. This can be done using the XML language, use the class TUnfoldBinningXML to read the binning scheme. The TUnfoldBinning objects can be written to a root file, preferentially together with the corresponding histograms.
For Monte Carlo, book histograms for the response matrix (detector vs truth level) using the method CreateHistogramOfMigrations()
For data and background, book histograms using the "detector level" binning scheme and the method CreateHistogram()
(if required) for the data covarianve matrix, book a histogram using the "detector level" binning scheme and the method CreateErrorMatrixHistogram()
For truth histograms, book histograms using the "truth level" binning scheme and the method CreateHistogram()

The histograms which are booked have all analysis bins arranged on one axis (global bin number). TUnfoldBinning provides methods to locate the global bin number:

Use the method FindNode() to locate a group of bins (e.g. signal, control distribution, etc) by their name, then:
Use the method GetGlobalBinNumber() to locate a bin in a distribution, then:
Use the TH1::Fill() method and the bin number to fill the appropriate bin in one of the histograms booked above.

Unfolding: Specify the response matrix and the binning schemes when constructing a TUnfoldDensity object. Tell TUnfoldDensity about the data, bakcground, systematic error histograms using the corresponding methods of class TUnfoldDensity. Then run the unfolding. Use the GetXXX() methods to retreive the unfolding results into properly binned multidimensional histograms.

Definition at line 54 of file TUnfoldBinning.h.

Member Enumeration Documentation

anonymous enum

Enumerator:

MAXDIM

maximum numner of axes per distribution

Definition at line 84 of file TUnfoldBinning.h.

Constructor & Destructor Documentation

TUnfoldBinningV17::TUnfoldBinningV17	(	const char *	name = `0`,
		Int_t	nBins = `0`,
		const char *	binNames = `0`
	)

create a new node without axis

Parameters:

`[in]`	name	identifier of the node
`[in]`	nBin	number of unconnected bins (could be zero)
`[in]`	binNames	(optional) names of the bins separated by ';'

Definition at line 207 of file TUnfoldBinningV17.cxx.

TUnfoldBinningV17::TUnfoldBinningV17	(	const TAxis &	axis,
		Int_t	includeUnderflow,
		Int_t	includeOverflow
	)

create a new node containing a distribution with one axis

Parameters:

`[in]`	axis	the axis to represent
`[in]`	includeUnderflow	true if underflow bin should be included
`[in]`	includeOverflow	true if overflow bin should be included

Definition at line 226 of file TUnfoldBinningV17.cxx.

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

Member Function Documentation

Bool_t TUnfoldBinningV17::AddAxis	(	const TAxis &	axis,
		Bool_t	hasUnderflow,
		Bool_t	hasOverflow
	)

add an axis to the distribution, using the TAxis as blueprint

Parameters:

`[in]`	axis	blueprint of the axis
`[in]`	hasUnderflow	decide whether the underflow bin should be included
`[in]`	hasOverflow	decide whether the overflow bin should be included

returns true if the axis has been added Note: axis labels are not imported

Definition at line 344 of file TUnfoldBinningV17.cxx.

Bool_t TUnfoldBinningV17::AddAxis	(	const char *	name,
		Int_t	nBin,
		Double_t	xMin,
		Double_t	xMax,
		Bool_t	hasUnderflow,
		Bool_t	hasOverflow
	)

add an axis with equidistant bins

Parameters:

`[in]`	name	name of the axis
`[in]`	nBin	number of bins
`[in]`	xMin	lower edge of the first bin
`[in]`	xMax	upper edge of the last bin
`[in]`	hasUnderflow	decide whether the axis has an underflow bin
`[in]`	hasOverflow	decide whether the axis has an overflow bin

returns true if the axis has been added

Definition at line 309 of file TUnfoldBinningV17.cxx.

Bool_t TUnfoldBinningV17::AddAxis	(	const char *	name,
		Int_t	nBin,
		const Double_t *	binBorders,
		Bool_t	hasUnderflow,
		Bool_t	hasOverflow
	)

add an axis with the specified bin borders

Parameters:

`[in]`	name	name of the axis
`[in]`	nBin	number of bins
`[in]`	binBorders	array of bin borders, with nBin+1 elements
`[in]`	hasUnderflow	decide whether the axis has an underflow bin
`[in]`	hasOverflow	decide whether the axis has an overflow bin

returns true if the axis has been added

Definition at line 369 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldBinningXMLV17::AddAxisXML().

TUnfoldBinningV17 * TUnfoldBinningV17::AddBinning	(	const char *	name,
		Int_t	nBins = `0`,
		const char *	binNames = `0`
	)

add a new binning node as last last child of this node

Parameters:

`[in]`	name	name of the node
`[in]`	nBin	number of extra bins
`[in]`	binNames	(optional) names of the bins sepatared by ';'

this is a shortcut for AddBinning(new TUnfoldBinning(name,nBins,binNames))

Definition at line 243 of file TUnfoldBinningV17.cxx.

TUnfoldBinningV17 * TUnfoldBinningV17::AddBinning ( TUnfoldBinningV17 * binning )

add a TUnfoldBinning as the last child of this node

Parameters:

[in] binning the new binning to be added

return value: if succeeded, return "binning" otherwise return 0

Definition at line 255 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldBinningXMLV17::ImportXMLNode().

TString TUnfoldBinningV17::BuildHistogramTitle	(	const char *	histogramName,
		const char *	histogramTitle,
		Int_t const *	axisList
	)			const `[protected]`

construct a title

Parameters:

`[in]`	histogramName	distribution name
`[in]`	histogramTitle	default title
`[in]`	axisList	array indicating wqhich axis of this node is mapped to which histogram axis

if histogramTitle!=0 thsi title is used. Otherwise, the title is composed as: histogramName;axisname[axisList[0]];axisname[axisList[1]];...

Definition at line 574 of file TUnfoldBinningV17.cxx.

TString TUnfoldBinningV17::BuildHistogramTitle2D	(	const char *	histogramName,
		const char *	histogramTitle,
		Int_t	xAxis,
		const TUnfoldBinningV17 *	yAxisBinning,
		Int_t	yAxis
	)			const `[protected]`

construct a histogram title for a 2D histogram with different binning schemes on x and y axis

Parameters:

`[in]`	histogramName	distribution name
`[in]`	histogramTitle	default title
`[in]`	xAxis	indicates which x-axis name to use
`[in]`	yAxisBinning	binning scheme for y-axis
`[in]`	yAxis	indicates which y-axis name to use

Definition at line 609 of file TUnfoldBinningV17.cxx.

Referenced by CreateHistogramOfMigrations().

Int_t * TUnfoldBinningV17::CreateBinMap	(	const TH1 *	hist,
		Int_t	nDim,
		const Int_t *	axisList,
		const char *	axisSteering
	)			const `[protected]`

create mapping from global bin number to a histogram for this node

Parameters:

`[in]`	hist	destination histogram
`[in]`	nDim	target dimension
`[in]`	axisList	map axes in the binning scheme to histogram axes
`[in]`	axisSteering	steering for underflow/overflow/projections

The axisSteering is explained with the method CreateHistogram()

Definition at line 1088 of file TUnfoldBinningV17.cxx.

Int_t * TUnfoldBinningV17::CreateEmptyBinMap ( void ) const

create an empty bin map, useful together with the getter methods of class TUnfold and TUnfoldSys

returns: a new Int array of the proper size, all eleemnts set to -1

Definition at line 1019 of file TUnfoldBinningV17.cxx.

TH2D * TUnfoldBinningV17::CreateErrorMatrixHistogram	(	const char *	histogramName,
		Bool_t	originalAxisBinning,
		Int_t **	binMap = `0`,
		const char *	histogramTitle = `0`,
		const char *	axisSteering = `0`
	)			const

create a TH2D histogram capable to hold a covariance matrix

Parameters:

`[in]`	histogramName	name of the histogram which is created
`[in]`	originalAxisBinning	if true, try to preserve the axis binning
`[out]`	(default=0)	binMap mapping of global bins to histogram bins. if(binMap==0), no binMap is created
`[in]`	(default=0)	histogramTitle title o fthe histogram. If zero, a title is selected automatically
`[in]`	(default=0)	axisSteering steer the handling of underflow/overflow and projections

returns a new TH2D. The options are described in greater detail with the CreateHistogram() method.

Definition at line 786 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldDensityV17::GetEmatrixInput(), TUnfoldDensityV17::GetEmatrixSysBackgroundUncorr(), TUnfoldDensityV17::GetEmatrixSysUncorr(), and TUnfoldDensityV17::GetEmatrixTotal().

TH1 * TUnfoldBinningV17::CreateHistogram	(	const char *	histogramName,
		Bool_t	originalAxisBinning = `kFALSE`,
		Int_t **	binMap = `0`,
		const char *	histogramTitle = `0`,
		const char *	axisSteering = `0`
	)			const

create a THxx histogram capable to hold the bins of this binning node and its children

Parameters:

`[in]`	histogramName	name of the histogram which is created
`[in]`	originalAxisBinning	if true, try to preserve the axis binning
`[out]`	(default=0)	binMap mapping of global bins to histogram bins. if(binMap==0), no binMap is created
`[in]`	(default=0)	histogramTitle title o fthe histogram. If zero, a title is selected automatically
`[in]`	(default=0)	axisSteering steer the handling of underflow/overflow and projections

returns a new histogram (TH1D, TH2D or TH3D)
if the parameter originalAxisBinning parameter is true, the resulting histogram has bin widths and histogram dimension (TH1D, TH2D, TH3D) in parallel to this binning node, if possible.
The binMap is an array which translates global bin numbers to bin numbers in the histogram returned by this method. The global bin numbers correspond to the bin numbers in a histogram created by calling GetRootNode()->CreateHistogram(name,false,0,0,0)
The axisSteering is a string to steer whether underflow and overflow bins are included in the bin map. Furthermore, it is possible to "collapse" axes, such that their content is summed and the axis does not show up in the created histogram.
The string looks like this: "axis[options];axis[options];..." where

axis is the name of an axis or equal to *, the latter matches all axes
options is a combination of characters chosen from OUC0123456789
- if O is included, the overflow bin of that axis is discarded
- if U is included, the underflow bin of that axis is discarded
- if C is included, the bins on that axes are collapsed, i.e. the corresponding histogram axis is not present in the output. The corrsponding bin contents are added up (projected onto the remaining axes). Using the characters O and U one can decide to exclude underflow or overflow from the projection. Using a selection of the characters 0123456789 one can restrict the sum further to only include the corresponding bins. In this counting, the first non-underflow bin corresponds to the character 0. This obviously only works for up to ten bins.

Definition at line 725 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldDensityV17::GetBackground(), TUnfoldDensityV17::GetBias(), TUnfoldDensityV17::GetDeltaSysBackgroundScale(), TUnfoldDensityV17::GetDeltaSysSource(), TUnfoldDensityV17::GetDeltaSysTau(), TUnfoldDensityV17::GetFoldedOutput(), TUnfoldDensityV17::GetInput(), TUnfoldDensityV17::GetOutput(), TUnfoldDensityV17::GetRhoIstatbgr(), and TUnfoldDensityV17::GetRhoItotal().

TH2D * TUnfoldBinningV17::CreateHistogramOfMigrations	(	TUnfoldBinningV17 const *	xAxis,
		TUnfoldBinningV17 const *	yAxis,
		char const *	histogramName,
		Bool_t	originalXAxisBinning = `kFALSE`,
		Bool_t	originalYAxisBinning = `kFALSE`,
		char const *	histogramTitle = `0`
	)			`[static]`

create a TH2D histogram capable to hold the bins of the two input binning schemes on the x and y axes, respectively

[in] xAxis binning scheme for the x axis

Parameters:

`[in]`	yAxis	binning scheme for the y axis
`[in]`	histogramName	name of the histogram which is created
`[in]`	originalXAxisBinning	preserve x-axis bin widths if possible
`[in]`	originalXAxisBinning	preserve y-axis bin widths if possible
`[in]`	histogramTitle	if is non-zero, it is taken as histogram title otherwise, the title is created automatically

returns a new TH2D.

Definition at line 829 of file TUnfoldBinningV17.cxx.

void TUnfoldBinningV17::DecodeAxisSteering	(	const char *	axisSteering,
		const char *	options,
		Int_t *	isOptionGiven
	)			const

decode axis steering

Parameters:

`[in]`	axisSteering	the steering to decode
`[in]`	options	the allowed options to extract
`[out]`	isOptionGiven	array of decoded steering options, the dimension equal to the number of characters in options

the axis steering is given in the form "axis[option];axis[option];..."
axis : the name of the axis for which the optionlist is relevant the character * matches all axes
option : a list of characters taken from options
for each match the corresponding bit number corresponding to the axis number is set in isOptionGiven[i], where i is the position of the matching option character in options

Definition at line 2081 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldDensityV17::RegularizeOneDistribution().

TH1 * TUnfoldBinningV17::ExtractHistogram	(	const char *	histogramName,
		const TH1 *	globalBins,
		const TH2 *	globalBinsEmatrix = `0`,
		Bool_t	originalAxisBinning = `kTRUE`,
		const char *	axisSteering = `0`
	)			const

Definition at line 1332 of file TUnfoldBinningV17.cxx.

Int_t TUnfoldBinningV17::FillBinMap1D	(	Int_t *	binMap,
		const char *	axisSteering,
		Int_t	firstBinX
	)			const

map all global bins referenced by this node to the one-dimensional histogram destHist, starting with bin firstBinX

Parameters:

`[out]`	binMap	to be used with TUnfoldSys::GetOutput() etc
`[in]`	axisSteering	steering for underflow/overflow/projections
`[in]`	firstBinX	first bin of destination histogram to be filled

returns: highest bin number in destibation histogram plus 1
The parameter axisSteering is explained with the method CreateHistogram()

Definition at line 1061 of file TUnfoldBinningV17.cxx.

Int_t TUnfoldBinningV17::FillBinMapRecursive	(	Int_t	startBin,
		const char *	axisSteering,
		Int_t *	binMap
	)			const `[protected]`

recursively fill bin map

Parameters:

`[in]`	startBin	first histogram bin
`[in]`	axisSteering	see CreateHistogram() method
`[out]`	binMap	the bin mapping which is to be filled

the positions binMap[GetStartBin()]...binMap[GetEndBin()-1] are filled

Definition at line 1152 of file TUnfoldBinningV17.cxx.

Int_t TUnfoldBinningV17::FillBinMapSingleNode	(	const TH1 *	hist,
		Int_t	startBin,
		Int_t	nDim,
		const Int_t *	axisList,
		const char *	axisSteering,
		Int_t *	binMap
	)			const `[protected]`

fill bin map for a single node

Parameters:

`[in]`	hist	the histogram representing this node (used if nDim>0)
`[in]`	startBin	start bin in the bin map
`[in]`	nDim	number of dimensions to resolve
`[in]`	axisList[3]	TUnfoldBinning axis numbers corresponding to the axes of hist
`[in]`	axisSteering	see documentation of CreateHistogram()
`[out]`	binMap	the bin map to fill

returns the number of bins mapped.
The result depends on the parameter nDim as follows

nDim==0: bins are mapped in linear order, ignore hist and axisList
nDim==hist->GetDimension(): bins are mapped to "hist" bin numbers the corresponding TUnfoldBinning axes are taken from axisList[]
nDim=1 and hist->GetDimension()>1: bins are mapped to the x-axis of "hist" the corresponding TUnfoldBinning axis is taken from axisList[0]

Definition at line 1190 of file TUnfoldBinningV17.cxx.

TUnfoldBinningV17 const * TUnfoldBinningV17::FindNode ( char const * name ) const

traverse the tree and return the first node which matches the given name

Parameters:

[in] name the identifier of the node to find (zero matches the first node)

returns the node found or zero

Definition at line 529 of file TUnfoldBinningV17.cxx.

Double_t TUnfoldBinningV17::GetBinFactor ( Int_t iBin ) const [virtual]

return scaling factor for the given global bin number

Parameters:

[in] iBin global bin number

returns the scaling factor for this bin. The scaling factors can be set using the method SetBinFactorFunction()

Definition at line 1724 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldBinningXMLV17::ExportXML(), and PrintStream().

TString TUnfoldBinningV17::GetBinName ( Int_t iBin ) const

get the name of a bin

Parameters:

[in] iBin global bin number

returns a string describing the bin

Definition at line 1636 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldDensityV17::GetOutputBinName(), and PrintStream().

Int_t TUnfoldBinningV17::GetBinNeighbours	(	Int_t	bin,
		Int_t	axis,
		Int_t *	prev,
		Double_t *	distPrev,
		Int_t *	next,
		Double_t *	distNext,
		Bool_t	isPeriodic = `kFALSE`
	)			const

get neighbour bins along the specified axis

Parameters:

`[in]`	bin	global bin number
`[in]`	axis	axis number of interest
`[out]`	prev	bin number of previous bin or -1 if not existing
`[out]`	distPrev	distance between bin centres
`[out]`	next	bin number of next bin or -1 if not existing
`[out]`	distNext	distance between bin centres
`[in]`	isPeriodic	(default=false) if true, the first bin is counted as neighbour of the last bin

return code

0 everything is fine
1,2,3 isPeriodic option was reset to false, because underflow/overflow bins are present
- +1 invalid isPeriodic option was specified with underflow bin
- +2 invalid isPeriodic option was specified with overflow bin

Definition at line 1784 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldDensityV17::RegularizeOneDistribution().

Double_t TUnfoldBinningV17::GetBinSize ( Int_t iBin ) const

get N-dimensional bin size

Parameters:

[in] iBin global bin number

Definition at line 1681 of file TUnfoldBinningV17.cxx.

Referenced by PrintStream().

void TUnfoldBinningV17::GetBinUnderflowOverflowStatus	(	Int_t	iBin,
		Int_t *	uStatus,
		Int_t *	oStatus
	)			const

return bit maps indicating underflow and overflow status

Parameters:

`[in]`	iBin	global bin number
`[out]`	uStatus	bit map indicating whether the bin is underflow
`[out]`	oStatus	bit map indicating whether the bin is overflow

Definition at line 1837 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldDensityV17::RegularizeOneDistribution().

TUnfoldBinningV17 const* TUnfoldBinningV17::GetChildNode ( void ) const [inline]

first daughter node

Definition at line 104 of file TUnfoldBinning.h.

Referenced by TUnfoldBinningXMLV17::ExportXML(), FindNode(), GetNonemptyNode(), GetTHxxBinsRecursive(), PrintStream(), TUnfoldDensityV17::RegularizeDistributionRecursive(), and UpdateFirstLastBin().

Double_t TUnfoldBinningV17::GetDistributionAverageBinSize	(	Int_t	axis,
		Bool_t	includeUnderflow,
		Bool_t	includeOverflow
	)			const `[virtual]`

get average bin size on the specified axis

Parameters:

`[in]`	axis	axis number
`[in]`	includeUnderflow	whether to include the underflow bin
`[in]`	includeOverflow	whether to include the overflow bin

Definition at line 1881 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldDensityV17::RegularizeOneDistribution().

TString TUnfoldBinningV17::GetDistributionAxisLabel ( Int_t axis ) const [inline]

get name of an axis

Definition at line 165 of file TUnfoldBinning.h.

Referenced by BuildHistogramTitle2D(), TUnfoldBinningXMLV17::ExportXML(), GetBinName(), PrintStream(), and TUnfoldDensityV17::RegularizeOneDistribution().

Double_t TUnfoldBinningV17::GetDistributionBinCenter	(	Int_t	axis,
		Int_t	bin
	)			const `[virtual]`

return bin center for a given axis and bin number

Parameters:

`[in]`	axis	axis number
`[in]`	bin	local bin number on the specified axis

returns the geometrical bin center. for underflow and overflow, the calculation is using the GetDistributionUnderflowBinWidth() and GetDistributionOverflowBinWidth() methods.

Definition at line 1952 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldBinningXMLV17::ExportXML(), GetBinFactor(), and GetBinNeighbours().

TVectorD const* TUnfoldBinningV17::GetDistributionBinning ( Int_t axis ) const [inline]

get vector of bin borders for one axis

Definition at line 162 of file TUnfoldBinning.h.

Referenced by CreateHistogram(), TUnfoldBinningXMLV17::ExportXML(), GetBinName(), GetBinSize(), GetBinUnderflowOverflowStatus(), GetDistributionOverflowBinWidth(), GetDistributionUnderflowBinWidth(), and PrintStream().

Int_t TUnfoldBinningV17::GetDistributionDimension ( void ) const [inline]

query dimension of this node's distribution

Definition at line 159 of file TUnfoldBinning.h.

Referenced by TUnfoldBinningXMLV17::ExportXML(), GetBinFactor(), GetBinName(), GetBinNeighbours(), GetBinSize(), GetBinUnderflowOverflowStatus(), GetGlobalBinNumber(), HasUnconnectedBins(), PrintStream(), TUnfoldDensityV17::RegularizeOneDistribution(), and UpdateFirstLastBin().

Int_t TUnfoldBinningV17::GetDistributionNumberOfBins ( void ) const [inline]

number of bins in the distribution possibly including under/overflow

Definition at line 157 of file TUnfoldBinning.h.

Referenced by TUnfoldBinningXMLV17::ExportXML(), GetNonemptyNode(), HasUnconnectedBins(), TUnfoldBinningXMLV17::ImportXMLNode(), PrintStream(), TUnfoldDensityV17::RegularizeOneDistribution(), and UpdateFirstLastBin().

Double_t TUnfoldBinningV17::GetDistributionOverflowBinWidth ( Int_t axis ) const [virtual]

return bin width assigned to the overflow bin

Parameters:

[in] axis axis number

the bin width of the last bin is returned. The method is virtual, so this behaviour can be adjusted.

Definition at line 1933 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldBinningXMLV17::ExportXML(), and GetBinSize().

Double_t TUnfoldBinningV17::GetDistributionUnderflowBinWidth ( Int_t axis ) const [virtual]

return bin width assigned to the underflow bin

Parameters:

[in] axis axis number

the bin width of the first bin is returned. The method is virtual, so this behaviour can be adjusted.

Definition at line 1918 of file TUnfoldBinningV17.cxx.

Referenced by TUnfoldBinningXMLV17::ExportXML(), and GetBinSize().

Int_t TUnfoldBinningV17::GetEndBin ( void ) const [inline]

last+1 bin of this node (includes children)

Definition at line 142 of file TUnfoldBinning.h.

Referenced by CreateEmptyBinMap(), ExtractHistogram(), FillBinMapSingleNode(), PrintStream(), and UpdateFirstLastBin().

Int_t TUnfoldBinningV17::GetGlobalBinNumber	(	const Double_t *	x,
		Int_t *	isBelow = `0`,
		Int_t *	isAbove = `0`
	)			const

locate a bin in an N-dimensional distribution

Parameters:

`[in]`	x	array of coordinates
`[out]`	isBelow	pointer to an integer (bit vector) to indicate coordinates which do not fit in the binning scheme
`[out]`	isAbove	pointer to an integer (bit vector) to indicate coordinates which do not fit in the binning scheme

returns the global bin number within the distribution attached to this node. The global bin number is valid for the root node of the binning scheme. If some coordinates do not fit, zero is returned. The integers pointed to by isBelow and isAbove are set to zero. However, if coordinate i is below the lowest bin border and there is no underflow bin, the bin i is set in (*isBelow). Overflows are handled in a similar manner with (*isAbove).
If a coordinate is NaN, the result is undefined for TUnfold Version<17.6. As of version 17.6, NaN is expected to end up in the underflow or by setting the corresponding bit in (*isBelow).

Definition at line 1585 of file TUnfoldBinningV17.cxx.

Int_t TUnfoldBinningV17::GetGlobalBinNumber	(	Double_t	x0,
		Double_t	x1,
		Double_t	x2,
		Double_t	x3,
		Double_t	x4,
		Double_t	x5
	)			const

locate a bin in a six-dimensional distribution

Parameters:

`[in]`	x0	coordinate on first axis
`[in]`	x1	coordinate on second axis
`[in]`	x2	coordinate on third axis
`[in]`	x3	coordinate on fourth axis
`[in]`	x4	coordinate on fifth axis
`[in]`	x5	coordinate on sixth axis