TUnfold: TUnfoldBinning.h Source File

00001 // Author: Stefan Schmitt
00002 // DESY, 10/08/11
00003 
00004 //  Version 17.5, in parallel to changes in TUnfold
00005 //
00006 //  History:
00007 //    Version 17.4, bug fix with error handling
00008 //    Version 17.3, bug fix with underflow/overflow bins
00009 //    Version 17.2, new option isPeriodic
00010 //    Version 17.1, in parallel to TUnfold
00011 //    Version 17.0, initial version, numbered in parallel to TUnfold
00012 
00013 #ifndef ROOT_TUnfoldBinning
00014 #define ROOT_TUnfoldBinning
00015 
00016 
00017 //////////////////////////////////////////////////////////////////////////
00018 //                                                                      //
00019 //                                                                      //
00020 //  TUnfoldBinning, an auxillary class to provide                       //
00021 //  complex binning schemes as input to TUnfoldDensity                  //
00022 //                                                                      //
00023 //  Citation: S.Schmitt, JINST 7 (2012) T10003 [arXiv:1205.6201]        //
00024 //                                                                      //
00025 //////////////////////////////////////////////////////////////////////////
00026 
00027 /*
00028   This file is part of TUnfold.
00029 
00030   TUnfold is free software: you can redistribute it and/or modify
00031   it under the terms of the GNU General Public License as published by
00032   the Free Software Foundation, either version 3 of the License, or
00033   (at your option) any later version.
00034 
00035   TUnfold is distributed in the hope that it will be useful,
00036   but WITHOUT ANY WARRANTY; without even the implied warranty of
00037   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00038   GNU General Public License for more details.
00039 
00040   You should have received a copy of the GNU General Public License
00041   along with TUnfold.  If not, see <http://www.gnu.org/licenses/>.
00042 */
00043 
00044 #include "TUnfold.h"
00045 #include <iostream>
00046 #include <TNamed.h>
00047 #include <TObjArray.h>
00048 #include <TObjString.h>
00049 #include <TAxis.h>
00050 #include <TF1.h>
00051 
00052 #define TUnfoldBinning TUnfoldBinningV17
00053 
00054 class TUnfoldBinningV17 : public TNamed {
00055  protected:
00056    /// mother node
00057    TUnfoldBinningV17 *parentNode;
00058    /// first daughter node
00059    TUnfoldBinningV17 *childNode;
00060    /// next sister
00061    TUnfoldBinningV17 *nextNode;
00062    /// previous sister
00063    TUnfoldBinningV17 *prevNode;
00064    /// for each axis the bin borders (TVectorD)
00065    TObjArray *fAxisList;
00066    /// for each axis its name (TObjString), or names of unconnected bins
00067    TObjArray *fAxisLabelList;
00068    /// bit fields indicating whether there are underflow bins on the axes
00069    Int_t fHasUnderflow;
00070    /// bit fields indicating whether there are overflow bins on the axes
00071    Int_t fHasOverflow;
00072    /// number of bins in this node's distribution
00073    Int_t fDistributionSize;
00074    /// global bin number of the first bin
00075    Int_t fFirstBin;
00076    /// global bin number of the last(+1) bin, including daughters
00077    Int_t fLastBin;
00078    /// function to calculate a scale factor from bin centres (may be a TF1 or a TVectorD
00079    TObject *fBinFactorFunction;
00080    /// common scale factor for all bins of this node
00081    Double_t fBinFactorConstant;
00082  public:
00083    /********************* setup **************************/
00084    enum {
00085       /// maximum numner of axes per distribution
00086       MAXDIM=32
00087    };
00088    TUnfoldBinningV17(const char *name=0,Int_t nBins=0,const char *binNames=0); // create a new root node with a given number of unconnected bins
00089    TUnfoldBinningV17(const TAxis &axis,Int_t includeUnderflow,Int_t includeOverflow); // create a binning scheme with one axis
00090    TUnfoldBinningV17 *AddBinning
00091       (TUnfoldBinningV17 *binning); // add a new node to the TUnfoldBinning tree
00092    TUnfoldBinningV17 *AddBinning(const char *name,Int_t nBins=0,const char *binNames=0); // add a new node to the TUnfoldBinning tree
00093    Bool_t AddAxis(const char *name,Int_t nBins,const Double_t *binBorders,
00094                 Bool_t hasUnderflow,Bool_t hasOverflow); // add an axis (variable bins) to the distribution associated with this node
00095    Bool_t AddAxis(const char *name,Int_t nBins,Double_t xMin,Double_t xMax,
00096                 Bool_t hasUnderflow,Bool_t hasOverflow); // add an axis (equidistant bins) to the distribution associated with this node
00097    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
00098    virtual ~TUnfoldBinningV17(void);
00099    void PrintStream(std::ostream &out,Int_t indent=0,int debug=0) const;
00100    void SetBinFactorFunction(Double_t normalisation,TF1 *userFunc=0); // define function to calculate bin factor. Note: the function is not owned by this class
00101 
00102    /********************* Navigation **********************/
00103    /// first daughter node
00104    inline TUnfoldBinningV17 const *GetChildNode(void) const { return childNode; }
00105    /// previous sister node
00106    inline TUnfoldBinningV17 const *GetPrevNode(void) const { return prevNode; }
00107    /// next sister node
00108    inline TUnfoldBinningV17 const *GetNextNode(void) const { return nextNode; }
00109    /// mother node
00110    inline TUnfoldBinningV17 const *GetParentNode(void) const { return parentNode; }
00111    TUnfoldBinningV17 const *FindNode(char const *name) const; // find node by name
00112    /// return root node of the binnig scheme
00113    TUnfoldBinningV17 const *GetRootNode(void) const;
00114 
00115    /********************* Create THxx histograms **********/
00116    Int_t GetTH1xNumberOfBins(Bool_t originalAxisBinning=kTRUE,const char *axisSteering=0) const; // get number of bins of a one-dimensional histogram TH1
00117    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
00118    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
00119    static TH2D *CreateHistogramOfMigrations(TUnfoldBinningV17 const *xAxis,
00120                                            TUnfoldBinningV17 const *yAxis,
00121                                            char const *histogramName,
00122                                            Bool_t originalXAxisBinning=kFALSE,
00123                                            Bool_t originalYAxisBinning=kFALSE,
00124                                            char const *histogramTitle=0); // create 2D histogram with one binning on the x axis and the other binning on the y axis
00125    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
00126    /********************* Create and manipulate bin map ****/
00127    Int_t *CreateEmptyBinMap(void) const; // create empty bin map
00128    void SetBinMapEntry(Int_t *binMap,Int_t globalBin,Int_t destBin) const; // change mapping for a given global bin
00129    Int_t FillBinMap1D(Int_t *binMap,const char *axisSteering,
00130                       Int_t firstBinX) const; // map bins from this distribution to destHist
00131    /********************* Calculate global bin number ******/
00132    Int_t GetGlobalBinNumber(Double_t x) const; // get bin number 1-dim distribution
00133    Int_t GetGlobalBinNumber(Double_t x,Double_t y) const; // get bin number 2-dim distribution
00134    Int_t GetGlobalBinNumber(Double_t x,Double_t y,Double_t z) const; // get bin number 3-dim distribution
00135    Int_t GetGlobalBinNumber(Double_t x0,Double_t x1,Double_t x2,Double_t x3) const; // get bin number four-dimensional binning
00136    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
00137    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
00138    Int_t GetGlobalBinNumber(const Double_t *x,Int_t *isBelow=0,Int_t *isAbove=0) const; // get bin number, up to 32 dimensional binning 
00139    /// first bin of this node
00140    inline Int_t GetStartBin(void) const { return fFirstBin; }
00141    /// last+1 bin of this node (includes children)
00142    inline Int_t GetEndBin(void) const { return fLastBin; }
00143    virtual Bool_t IsBinFactorGlobal(void) const; // check whether global or local bin factor must be used
00144    Double_t GetGlobalFactor(void) const; // return global factor
00145 
00146     /********************* access by global bin number ******/
00147    TString GetBinName(Int_t iBin) const; // return bin name
00148    Double_t GetBinSize(Int_t iBin) const; // return bin size (in N dimensions)
00149    virtual Double_t GetBinFactor(Int_t iBin) const; // return user factor
00150    void GetBinUnderflowOverflowStatus(Int_t iBin,Int_t *uStatus,Int_t *oStatus) const; // return bit map indicating underflow and overflow status
00151    Int_t GetBinNeighbours(Int_t globalBin,Int_t axis,
00152                           Int_t *prev,Double_t *distPrev,
00153                           Int_t *next,Double_t *distNext,
00154                           Bool_t isPeriodic=kFALSE) const; // get neighbour bins along an axis
00155    /********************** access distribution properties *************/
00156    /// number of bins in the distribution possibly including under/overflow
00157    inline Int_t GetDistributionNumberOfBins(void) const { return fDistributionSize; }
00158    /// query dimension of this node's distribution
00159    inline Int_t GetDistributionDimension(void) const {  return fAxisList->GetEntriesFast(); }
00160    virtual Double_t GetDistributionAverageBinSize(Int_t axis,Bool_t includeUnderflow, Bool_t includeOverflow) const; // get average bin size
00161    /// get vector of bin borders for one axis
00162    inline TVectorD const *GetDistributionBinning(Int_t axis) const {
00163       return (TVectorD const *)fAxisList->At(axis); }
00164    /// get name of an axis
00165    inline TString GetDistributionAxisLabel(Int_t axis) const {
00166       return ((TObjString * const)fAxisLabelList->At(axis))->GetString(); }
00167 
00168    virtual Double_t GetDistributionUnderflowBinWidth(Int_t axis) const; // width of underflow bin on the given axis
00169    virtual Double_t GetDistributionOverflowBinWidth(Int_t axis) const; // width of overflow bin on the given axis
00170    virtual Double_t GetDistributionBinCenter(Int_t axis,Int_t bin) const; // position of bin center on the given axis
00171    Bool_t HasUnconnectedBins(void) const; // check whether this node has bins without axis
00172    const TObjString *GetUnconnectedBinName(Int_t bin) const; // return bin name (if any)
00173    /// check whether an axis has an underflow bin
00174    Bool_t HasUnderflow(int axis) const { return fHasUnderflow & (1<<axis); }
00175    /// check whether the axis has an overflow bin
00176    Bool_t HasOverflow(int axis) const { return fHasOverflow & (1<<axis); }
00177    void DecodeAxisSteering(const char *axisSteering,const char *options,
00178               Int_t *isOptionGiven) const; // decode axis steering options
00179  protected:
00180    /// return root node
00181    TUnfoldBinningV17 *GetRootNode(void);
00182    void Initialize(Int_t nBins);
00183    Int_t UpdateFirstLastBin(Bool_t startWithRootNode=kTRUE); // update fFirstBin and fLastBin
00184    TUnfoldBinningV17 const *ToAxisBins(Int_t globalBin,Int_t *axisBins) const; // return distribution in which the bin is located
00185    Int_t ToGlobalBin(Int_t const *axisBins,Int_t *isBelow=0,Int_t *isAbove=0) const; // return -1 if not inside distribution
00186    TString BuildHistogramTitle(const char *histogramName,const char *histogramTitle,
00187                                Int_t const *axisList) const; // construct histogram title
00188    TString BuildHistogramTitle2D(const char *histogramName,const char *histogramTitle,
00189                                  Int_t xAxis,const TUnfoldBinningV17 *yAxisBinning,Int_t yAxis) const; // construct histogram title
00190    Int_t GetTHxxBinning(Int_t maxDim,Int_t *axisBins,Int_t *axisList,const char *axisSteering) const; // get binning information for creating a THxx
00191    Int_t GetTHxxBinningSingleNode(Int_t maxDim,Int_t *axisBins,Int_t *axisList,const char *axisSteering) const; // get binning information for creating a THxx
00192    Int_t GetTHxxBinsRecursive(const char *axisSteering) const; // get binning information for creating a THxx
00193    const TUnfoldBinningV17 *GetNonemptyNode(void) const; // get the only nodes with non-empty distributions if there are multiple nodes, return 0
00194    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
00195    Int_t FillBinMapRecursive(Int_t startBin,const char *axisSteering,
00196                             Int_t *binMap) const; // fill bin map recursively
00197    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
00198    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
00199 
00200    ClassDef(TUnfoldBinningV17, TUnfold_CLASS_VERSION) //Complex binning schemes for TUnfoldDensity
00201 };
00202 
00203 #endif