Logo ROOT   6.12/07
Reference Guide
TUnfoldBinning.h
Go to the documentation of this file.
1 // Author: Stefan Schmitt
2 // DESY, 10/08/11
3 
4 // Version 17.5, in parallel to changes in TUnfold
5 //
6 // History:
7 // Version 17.4, bug fix with error handling
8 // Version 17.3, bug fix with underflow/overflow bins
9 // Version 17.2, new option isPeriodic
10 // Version 17.1, in parallel to TUnfold
11 // Version 17.0, initial version, numbered in parallel to TUnfold
12 
13 #ifndef ROOT_TUnfoldBinning
14 #define ROOT_TUnfoldBinning
15 
16 
17 //////////////////////////////////////////////////////////////////////////
18 // //
19 // //
20 // TUnfoldBinning, an auxillary class to provide //
21 // complex binning schemes as input to TUnfoldDensity //
22 // //
23 // Citation: S.Schmitt, JINST 7 (2012) T10003 [arXiv:1205.6201] //
24 // //
25 //////////////////////////////////////////////////////////////////////////
26 
27 /*
28  This file is part of TUnfold.
29 
30  TUnfold is free software: you can redistribute it and/or modify
31  it under the terms of the GNU General Public License as published by
32  the Free Software Foundation, either version 3 of the License, or
33  (at your option) any later version.
34 
35  TUnfold is distributed in the hope that it will be useful,
36  but WITHOUT ANY WARRANTY; without even the implied warranty of
37  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
38  GNU General Public License for more details.
39 
40  You should have received a copy of the GNU General Public License
41  along with TUnfold. If not, see <http://www.gnu.org/licenses/>.
42 */
43 
44 #include "TUnfold.h"
45 #include <iostream>
46 #include <TNamed.h>
47 #include <TObjArray.h>
48 #include <TObjString.h>
49 #include <TAxis.h>
50 #include <TF1.h>
51 
52 
53 class TUnfoldBinning : public TNamed {
54  protected:
55  /// mother node
57  /// first daughter node
59  /// next sister
61  /// previous sister
63  /// for each axis the bin borders (TVectorD)
65  /// for each axis its name (TObjString), or names of unconnected bins
67  /// bit fields indicating whether there are underflow bins on the axes
69  /// bit fields indicating whether there are overflow bins on the axes
71  /// number of bins in this node's distribution
73  /// global bin number of the first bin
75  /// global bin number of the last(+1) bin, including daughters
77  /// function to calculate a scale factor from bin centres (may be a TF1 or a TVectorD
79  /// common scale factor for all bins of this node
81  public:
82  /********************* setup **************************/
83  enum {
84  /// maximum numner of axes per distribution
85  MAXDIM=32
86  };
87  TUnfoldBinning(const char *name=0,Int_t nBins=0,const char *binNames=0); // create a new root node with a given number of unconnected bins
88  TUnfoldBinning(const TAxis &axis,Int_t includeUnderflow,Int_t includeOverflow); // create a binning scheme with one axis
90  (TUnfoldBinning *binning); // add a new node to the TUnfoldBinning tree
91  TUnfoldBinning *AddBinning(const char *name,Int_t nBins=0,const char *binNames=0); // add a new node to the TUnfoldBinning tree
92  Bool_t AddAxis(const char *name,Int_t nBins,const Double_t *binBorders,
93  Bool_t hasUnderflow,Bool_t hasOverflow); // add an axis (variable bins) to the distribution associated with this node
94  Bool_t AddAxis(const char *name,Int_t nBins,Double_t xMin,Double_t xMax,
95  Bool_t hasUnderflow,Bool_t hasOverflow); // add an axis (equidistant bins) to the distribution associated with this node
96  Bool_t AddAxis(const TAxis &axis,Bool_t includeUnderflow,Bool_t includeOverflow); // add an axis (from TAxis instance) to the distribution associated with this node
97  virtual ~TUnfoldBinning(void);
98  void PrintStream(std::ostream &out,Int_t indent=0,int debug=0) const;
99  void SetBinFactorFunction(Double_t normalisation,TF1 *userFunc=0); // define function to calculate bin factor. Note: the function is not owned by this class
100 
101  /********************* Navigation **********************/
102  /// first daughter node
103  inline TUnfoldBinning const *GetChildNode(void) const { return childNode; }
104  /// previous sister node
105  inline TUnfoldBinning const *GetPrevNode(void) const { return prevNode; }
106  /// next sister node
107  inline TUnfoldBinning const *GetNextNode(void) const { return nextNode; }
108  /// mother node
109  inline TUnfoldBinning const *GetParentNode(void) const { return parentNode; }
110  TUnfoldBinning const *FindNode(char const *name) const; // find node by name
111  /// return root node of the binnig scheme
112  TUnfoldBinning const *GetRootNode(void) const;
113 
114  /********************* Create THxx histograms **********/
115  Int_t GetTH1xNumberOfBins(Bool_t originalAxisBinning=kTRUE,const char *axisSteering=0) const; // get number of bins of a one-dimensional histogram TH1
116  TH1 *CreateHistogram(const char *histogramName,Bool_t originalAxisBinning=kFALSE,Int_t **binMap=0,const char *histogramTitle=0,const char *axisSteering=0) const; // create histogram and bin map for this node
117  TH2D *CreateErrorMatrixHistogram(const char *histogramName,Bool_t originalAxisBinning,Int_t **binMap=0,const char *histogramTitle=0,const char *axisSteering=0) const; // create histogram and bin map for this node
118  static TH2D *CreateHistogramOfMigrations(TUnfoldBinning const *xAxis,
119  TUnfoldBinning const *yAxis,
120  char const *histogramName,
121  Bool_t originalXAxisBinning=kFALSE,
122  Bool_t originalYAxisBinning=kFALSE,
123  char const *histogramTitle=0); // create 2D histogram with one binning on the x axis and the other binning on the y axis
124  TH1 *ExtractHistogram(const char *histogramName,const TH1 *globalBins,const TH2 *globalBinsEmatrix=0,Bool_t originalAxisBinning=kTRUE,const char *axisSteering=0) const; // extract a distribution from the given set of global bins
125  /********************* Create and manipulate bin map ****/
126  Int_t *CreateEmptyBinMap(void) const; // create empty bin map
127  void SetBinMapEntry(Int_t *binMap,Int_t globalBin,Int_t destBin) const; // change mapping for a given global bin
128  Int_t FillBinMap1D(Int_t *binMap,const char *axisSteering,
129  Int_t firstBinX) const; // map bins from this distribution to destHist
130  /********************* Calculate global bin number ******/
131  Int_t GetGlobalBinNumber(Double_t x) const; // get bin number 1-dim distribution
132  Int_t GetGlobalBinNumber(Double_t x,Double_t y) const; // get bin number 2-dim distribution
133  Int_t GetGlobalBinNumber(Double_t x,Double_t y,Double_t z) const; // get bin number 3-dim distribution
134  Int_t GetGlobalBinNumber(Double_t x0,Double_t x1,Double_t x2,Double_t x3) const; // get bin number four-dimensional binning
135  Int_t GetGlobalBinNumber(Double_t x0,Double_t x1,Double_t x2,Double_t x3,Double_t x4) const; // get bin number five-dimensional binning
136  Int_t GetGlobalBinNumber(Double_t x0,Double_t x1,Double_t x2,Double_t x3,Double_t x4,Double_t x5) const; // get bin number six-dimensional binning
137  Int_t GetGlobalBinNumber(const Double_t *x,Int_t *isBelow=0,Int_t *isAbove=0) const; // get bin number, up to 32 dimensional binning
138  /// first bin of this node
139  inline Int_t GetStartBin(void) const { return fFirstBin; }
140  /// last+1 bin of this node (includes children)
141  inline Int_t GetEndBin(void) const { return fLastBin; }
142  virtual Bool_t IsBinFactorGlobal(void) const; // check whether global or local bin factor must be used
143  Double_t GetGlobalFactor(void) const; // return global factor
144 
145  /********************* access by global bin number ******/
146  TString GetBinName(Int_t iBin) const; // return bin name
147  Double_t GetBinSize(Int_t iBin) const; // return bin size (in N dimensions)
148  virtual Double_t GetBinFactor(Int_t iBin) const; // return user factor
149  void GetBinUnderflowOverflowStatus(Int_t iBin,Int_t *uStatus,Int_t *oStatus) const; // return bit map indicating underflow and overflow status
150  Int_t GetBinNeighbours(Int_t globalBin,Int_t axis,
151  Int_t *prev,Double_t *distPrev,
152  Int_t *next,Double_t *distNext,
153  Bool_t isPeriodic=kFALSE) const; // get neighbour bins along an axis
154  /********************** access distribution properties *************/
155  /// number of bins in the distribution possibly including under/overflow
156  inline Int_t GetDistributionNumberOfBins(void) const { return fDistributionSize; }
157  /// query dimension of this node's distribution
158  inline Int_t GetDistributionDimension(void) const { return fAxisList->GetEntriesFast(); }
159  virtual Double_t GetDistributionAverageBinSize(Int_t axis,Bool_t includeUnderflow, Bool_t includeOverflow) const; // get average bin size
160  /// get vector of bin borders for one axis
161  inline TVectorD const *GetDistributionBinning(Int_t axis) const {
162  return (TVectorD const *)fAxisList->At(axis); }
163  /// get name of an axis
165  return ((TObjString * const)fAxisLabelList->At(axis))->GetString(); }
166 
167  virtual Double_t GetDistributionUnderflowBinWidth(Int_t axis) const; // width of underflow bin on the given axis
168  virtual Double_t GetDistributionOverflowBinWidth(Int_t axis) const; // width of overflow bin on the given axis
169  virtual Double_t GetDistributionBinCenter(Int_t axis,Int_t bin) const; // position of bin center on the given axis
170  Bool_t HasUnconnectedBins(void) const; // check whether this node has bins without axis
171  const TObjString *GetUnconnectedBinName(Int_t bin) const; // return bin name (if any)
172  /// check whether an axis has an underflow bin
173  Bool_t HasUnderflow(int axis) const { return fHasUnderflow & (1<<axis); }
174  /// check whether the axis has an overflow bin
175  Bool_t HasOverflow(int axis) const { return fHasOverflow & (1<<axis); }
176  void DecodeAxisSteering(const char *axisSteering,const char *options,
177  Int_t *isOptionGiven) const; // decode axis steering options
178  protected:
179  /// return root node
181  void Initialize(Int_t nBins);
182  Int_t UpdateFirstLastBin(Bool_t startWithRootNode=kTRUE); // update fFirstBin and fLastBin
183  TUnfoldBinning const *ToAxisBins(Int_t globalBin,Int_t *axisBins) const; // return distribution in which the bin is located
184  Int_t ToGlobalBin(Int_t const *axisBins,Int_t *isBelow=0,Int_t *isAbove=0) const; // return -1 if not inside distribution
185  TString BuildHistogramTitle(const char *histogramName,const char *histogramTitle,
186  Int_t const *axisList) const; // construct histogram title
187  TString BuildHistogramTitle2D(const char *histogramName,const char *histogramTitle,
188  Int_t xAxis,const TUnfoldBinning *yAxisBinning,Int_t yAxis) const; // construct histogram title
189  Int_t GetTHxxBinning(Int_t maxDim,Int_t *axisBins,Int_t *axisList,const char *axisSteering) const; // get binning information for creating a THxx
190  Int_t GetTHxxBinningSingleNode(Int_t maxDim,Int_t *axisBins,Int_t *axisList,const char *axisSteering) const; // get binning information for creating a THxx
191  Int_t GetTHxxBinsRecursive(const char *axisSteering) const; // get binning information for creating a THxx
192  const TUnfoldBinning *GetNonemptyNode(void) const; // get the only nodes with non-empty distributions if there are multiple nodes, return 0
193  Int_t *CreateBinMap(const TH1 *hist,Int_t nDim,const Int_t *axisList,const char *axisSteering) const; // create mapping from global bins to a histogram
194  Int_t FillBinMapRecursive(Int_t startBin,const char *axisSteering,
195  Int_t *binMap) const; // fill bin map recursively
196  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
197  void SetBinFactor(Double_t normalisation,TObject *factors); // define function to calculate bin factor. Note: the object is owned by this class, unless it is a function
198 
199  ClassDef(TUnfoldBinning, TUnfold_CLASS_VERSION) //Complex binning schemes for TUnfoldDensity
200 };
201 
202 #endif
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.
const TObjString * GetUnconnectedBinName(Int_t bin) const
Return the bin names of unconnected bins.
TUnfoldBinning const * GetChildNode(void) const
first daughter node
An array of TObjects.
Definition: TObjArray.h:37
TUnfoldBinning * parentNode
mother node
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.
virtual Double_t GetDistributionBinCenter(Int_t axis, Int_t bin) const
return bin center for a given axis and bin number
const TUnfoldBinning * GetNonemptyNode(void) const
Find a node which has non-empty distributions if there is none or if there are many, return zero.
Bool_t HasOverflow(int axis) const
check whether the axis has an overflow bin
Collectable string class.
Definition: TObjString.h:28
Int_t fDistributionSize
number of bins in this node&#39;s distribution
TUnfoldBinning * childNode
first daughter node
virtual Double_t GetDistributionAverageBinSize(Int_t axis, Bool_t includeUnderflow, Bool_t includeOverflow) const
Get average bin size on the specified axis.
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.
TString BuildHistogramTitle2D(const char *histogramName, const char *histogramTitle, Int_t xAxis, const TUnfoldBinning *yAxisBinning, Int_t yAxis) const
Construct a histogram title for a 2D histogram with different binning schemes on x and y axis...
TUnfoldBinning const * ToAxisBins(Int_t globalBin, Int_t *axisBins) const
Return distribution in which the bin is located and bin numbers on the corresponding axes...
Double_t GetBinSize(Int_t iBin) const
Get N-dimensional bin size.
TUnfoldBinning * nextNode
next sister
void GetBinUnderflowOverflowStatus(Int_t iBin, Int_t *uStatus, Int_t *oStatus) const
Return bit maps indicating underflow and overflow status.
Basic string class.
Definition: TString.h:125
void SetBinFactor(Double_t normalisation, TObject *factors)
Set normalisation factors which are used in calls to GetBinFactor().
int Int_t
Definition: RtypesCore.h:41
bool Bool_t
Definition: RtypesCore.h:59
Int_t fHasOverflow
bit fields indicating whether there are overflow bins on the axes
Int_t fHasUnderflow
bit fields indicating whether there are underflow bins on the axes
void PrintStream(std::ostream &out, Int_t indent=0, int debug=0) const
Print some information about this binning tree.
TObject * At(Int_t idx) const
Definition: TObjArray.h:165
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.
virtual ~TUnfoldBinning(void)
TUnfoldBinning const * GetNextNode(void) const
next sister node
maximum numner of axes per distribution
Int_t UpdateFirstLastBin(Bool_t startWithRootNode=kTRUE)
Update fFirstBin and fLastBin members of this node and its children.
Int_t ToGlobalBin(Int_t const *axisBins, Int_t *isBelow=0, Int_t *isAbove=0) const
Get global bin number, given axis bin numbers.
Double_t fBinFactorConstant
common scale factor for all bins of this node
static const double x2[5]
Double_t x[n]
Definition: legend1.C:17
Int_t GetEndBin(void) const
last+1 bin of this node (includes children)
#define ClassDef(name, id)
Definition: Rtypes.h:320
void SetBinMapEntry(Int_t *binMap, Int_t globalBin, Int_t destBin) const
Set one entry in a bin map.
The TNamed class is the base class for all named ROOT classes.
Definition: TNamed.h:29
Double_t GetGlobalFactor(void) const
Return global scaling factor for this node.
Int_t fLastBin
global bin number of the last(+1) bin, including daughters
TObjArray * fAxisLabelList
for each axis its name (TObjString), or names of unconnected bins
void Initialize(Int_t nBins)
Initialize variables for a given number of bins.
static const double x4[22]
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 GetStartBin(void) const
first bin of this node
TVectorD const * GetDistributionBinning(Int_t axis) const
get vector of bin borders for one axis
Int_t GetDistributionDimension(void) const
query dimension of this node&#39;s distribution
TUnfoldBinning const * GetParentNode(void) const
mother node
TH1 * ExtractHistogram(const char *histogramName, const TH1 *globalBins, const TH2 *globalBinsEmatrix=0, Bool_t originalAxisBinning=kTRUE, const char *axisSteering=0) const
Extract a distribution from the given set of global bins.
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.
void DecodeAxisSteering(const char *axisSteering, const char *options, Int_t *isOptionGiven) const
Decode axis steering.
void SetBinFactorFunction(Double_t normalisation, TF1 *userFunc=0)
Set normalisation factor and function which are used in calls to GetBinFactor().
Int_t fFirstBin
global bin number of the first bin
Service class for 2-Dim histogram classes.
Definition: TH2.h:30
Class to manage histogram axis.
Definition: TAxis.h:30
virtual Double_t GetDistributionUnderflowBinWidth(Int_t axis) const
Return bin width assigned to the underflow bin.
Int_t GetEntriesFast() const
Definition: TObjArray.h:64
virtual Bool_t IsBinFactorGlobal(void) const
Check whether there is only a global scaling factor for this node.
TUnfoldBinning const * GetPrevNode(void) const
previous sister node
Bool_t HasUnderflow(int axis) const
check whether an axis has an underflow bin
static TH2D * CreateHistogramOfMigrations(TUnfoldBinning const *xAxis, TUnfoldBinning 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...
const Bool_t kFALSE
Definition: RtypesCore.h:88
Binning schemes for use with the unfolding algorithm TUnfoldDensity.
TString GetDistributionAxisLabel(Int_t axis) const
get name of an axis
static const double x1[5]
TObject * fBinFactorFunction
function to calculate a scale factor from bin centres (may be a TF1 or a TVectorD ...
double Double_t
Definition: RtypesCore.h:55
TUnfoldBinning * prevNode
previous sister
Double_t y[n]
Definition: legend1.C:17
The TH1 histogram class.
Definition: TH1.h:56
Int_t * CreateEmptyBinMap(void) const
Create an empty bin map, useful together with the getter methods of class TUnfold and TUnfoldSys...
Int_t GetDistributionNumberOfBins(void) const
number of bins in the distribution possibly including under/overflow
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.
#define TUnfold_CLASS_VERSION
Definition: TUnfold.h:101
Int_t GetGlobalBinNumber(Double_t x) const
Locate a bin in a one-dimensional distribution.
TString GetBinName(Int_t iBin) const
Get the name of a bin.
Mother of all ROOT objects.
Definition: TObject.h:37
you should not use this method at all Int_t Int_t z
Definition: TRolke.cxx:630
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...
Int_t FillBinMapRecursive(Int_t startBin, const char *axisSteering, Int_t *binMap) const
Recursively fill bin map.
Bool_t HasUnconnectedBins(void) const
Check whether there are bins but no axis.
TUnfoldBinning const * GetRootNode(void) const
return root node of the binnig scheme
TObjArray * fAxisList
for each axis the bin borders (TVectorD)
virtual Double_t GetDistributionOverflowBinWidth(Int_t axis) const
Return bin width assigned to the overflow bin.
1-Dim function class
Definition: TF1.h:211
TUnfoldBinning(const char *name=0, Int_t nBins=0, const char *binNames=0)
Create a new node without axis.
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...
TString BuildHistogramTitle(const char *histogramName, const char *histogramTitle, Int_t const *axisList) const
Construct a title.
Int_t GetTHxxBinsRecursive(const char *axisSteering) const
Calculate number of bins required to store this binning with the given axisSteering.
const Bool_t kTRUE
Definition: RtypesCore.h:87
TUnfoldBinning * AddBinning(TUnfoldBinning *binning)
Add a TUnfoldBinning as the last child of this node.
TUnfoldBinning const * FindNode(char const *name) const
Traverse the tree and return the first node which matches the given name.
char name[80]
Definition: TGX11.cxx:109
virtual Double_t GetBinFactor(Int_t iBin) const
Return scaling factor for the given global bin number.
static const double x3[11]
2-D histogram with a double per channel (see TH1 documentation)}
Definition: TH2.h:290