root/TMVA/PDEFoam.h

0001 // @(#)root/tmva $Id$
0002 // Author: S. Jadach, Tancredi Carli, Dominik Dannheim, Alexander Voigt
0003
0004 /**********************************************************************************
0005  * Project: TMVA - a Root-integrated toolkit for multivariate data analysis       *
0006  * Package: TMVA                                                                  *
0007  * Classes: PDEFoam                                                               *
0008  *                                             *
0009  *                                                                                *
0010  * Description:                                                                   *
0011  *      Class for PDEFoam object                                                  *
0012  *                                                                                *
0013  * Authors (alphabetical):                                                        *
0014  *      S. Jadach        - Institute of Nuclear Physics, Cracow, Poland           *
0015  *      Tancredi Carli   - CERN, Switzerland                                      *
0016  *      Dominik Dannheim - CERN, Switzerland                                      *
0017  *      Alexander Voigt  - TU Dresden, Germany                                    *
0018  *                                                                                *
0019  * Copyright (c) 2008, 2010:                                                      *
0020  *      CERN, Switzerland                                                         *
0021  *      MPI-K Heidelberg, Germany                                                 *
0022  *                                                                                *
0023  * Redistribution and use in source and binary forms, with or without             *
0024  * modification, are permitted according to the terms listed in LICENSE           *
0025  * (see tmva/doc/LICENSE)                                          *
0026  **********************************************************************************/
0027
0028 #ifndef ROOT_TMVA_PDEFoam
0029 #define ROOT_TMVA_PDEFoam
0030
0031 #include <iosfwd>
0032 #include <cassert>
0033 #include <vector>
0034 #include <map>
0035
0036 #include "TH2D.h"
0037 #include "TObjArray.h"
0038 #include "TObjString.h"
0039 #include "TVectorT.h"
0040 #include "TString.h"
0041 #include "TMVA/VariableInfo.h"
0042 #include "TMVA/Timer.h"
0043 #include "TObject.h"
0044 #include "TRandom3.h"
0045
0046 namespace TMVA {
0047    class PDEFoamCell;
0048    class PDEFoamVect;
0049    class PDEFoamDensityBase;
0050    class PDEFoamKernelBase;
0051    class PDEFoam;
0052
0053    // separation types
0054    enum EDTSeparation { kFoam, kGiniIndex, kMisClassificationError,
0055                         kCrossEntropy, kGiniIndexWithLaplace, kSdivSqrtSplusB };
0056
0057    // foam types
0058    enum EFoamType { kSeparate, kDiscr, kMonoTarget, kMultiTarget, kMultiClass };
0059
0060    // enum type for possible foam cell values
0061    // kValue         : cell value who's rms is minimized
0062    // kValueError    : error on kValue
0063    // kValueDensity  : kValue / cell volume
0064    // kMeanValue     : mean sampling value (saved in fIntegral)
0065    // kRms           : rms of sampling distribution (saved in fDriver)
0066    // kRmsOvMean     : rms/mean of sampling distribution (saved in
0067    //                  fDriver and fIntegral)
0068    // kCellVolume    : volume of cell
0069    enum ECellValue { kValue, kValueError, kValueDensity, kMeanValue,
0070                      kRms, kRmsOvMean, kCellVolume };
0071 }
0072
0073 #include "TMVA/PDEFoamDensityBase.h"
0074 #include "TMVA/PDEFoamVect.h"
0075 #include "TMVA/PDEFoamCell.h"
0076
0077 namespace TMVA {
0078
0079    class PDEFoam : public TObject {
0080    protected:
0081       // COMPONENTS //
0082       //-------------- Input parameters
0083       TString fName;             ///< Name of a given instance of the FOAM class
0084       Int_t   fDim;              ///< Dimension of the integration/simulation space
0085       Int_t   fNCells;           ///< Maximum number of cells
0086       //-------------------
0087       Int_t   fNBin;             ///< No. of bins in the edge histogram for cell MC exploration
0088       Int_t   fNSampl;           ///< No. of MC events, when dividing (exploring) cell
0089       Int_t   fEvPerBin;         ///< Maximum number of effective (wt=1) events per bin
0090       //-------------------  MULTI-BRANCHING ---------------------
0091       Int_t  *fMaskDiv;          ///<! [fDim] Dynamic Mask for cell division
0092       Int_t  *fInhiDiv;          ///<! [fDim] Flags for inhibiting cell division
0093       //-------------------  GEOMETRY ----------------------------
0094       Int_t   fNoAct;            ///< Number of active cells
0095       Int_t   fLastCe;           ///< Index of the last cell
0096       PDEFoamCell **fCells;      ///< [fNCells] Array of ALL cells
0097       //------------------ M.C. generation----------------------------
0098       TObjArray *fHistEdg;       ///< Histograms of wt, one for each cell edge
0099       Double_t *fRvec;           ///< [fDim] random number vector from r.n. generator fDim+1 maximum elements
0100       //----------- Procedures
0101       TRandom3        *fPseRan;  ///< Pointer to user-defined generator of pseudorandom numbers
0102       //----------  working space for CELL exploration -------------
0103       Double_t *fAlpha;          ///< [fDim] Internal parameters of the hyperrectangle
0104       // ---------  PDE-Foam specific variables
0105       EFoamType fFoamType;     ///< BACKWARDS COMPATIBILITY: type of foam
0106       Double_t *fXmin;         ///< [fDim] minimum for variable transform
0107       Double_t *fXmax;         ///< [fDim] maximum for variable transform
0108       UInt_t fNElements;       ///< BACKWARDS COMPATIBILITY: number of variables in every cell
0109       UInt_t fNmin;            ///< minimal number of events in cell to split cell
0110       UInt_t fMaxDepth;        ///< maximum depth of cell tree
0111       Float_t fVolFrac;        ///< BACKWARDS COMPATIBILITY: volume fraction (with respect to total phase space
0112       Bool_t fFillFoamWithOrigWeights; ///< BACKWARDS COMPATIBILITY: fill the foam with boost or orig. weights
0113       EDTSeparation fDTSeparation; ///< BACKWARDS COMPATIBILITY: split cells according to decision tree logic
0114       Bool_t fPeekMax;         ///< BACKWARDS COMPATIBILITY: peek up cell with max. driver integral for split
0115       PDEFoamDensityBase *fDistr;  ///<! distribution of training events
0116       Timer *fTimer;           ///<! timer for graphical output
0117       TObjArray *fVariableNames;///< collection of all variable names
0118       mutable MsgLogger* fLogger;                     ///<! message logger
0119
0120       /////////////////////////////////////////////////////////////////
0121       //                            METHODS                          //
0122       /////////////////////////////////////////////////////////////////
0123
0124    protected:
0125       // ---------- TMVA console output
0126
0127       void OutputGrow(Bool_t finished = false ); // nice TMVA console output
0128
0129       // ---------- Foam build-up functions
0130
0131       // Internal foam initialization functions
0132       void InitCells();                   // Initialisation of all foam cells
0133       Int_t CellFill(Int_t, PDEFoamCell*);// Allocates new empty cell and return its index
0134       virtual void Explore(PDEFoamCell *Cell); // Exploration of the new cell, determine <wt>, wtMax etc.
0135       void Varedu(Double_t [5], Int_t&, Double_t&,Double_t&); // Determines the best edge, variance reduction
0136       void MakeAlpha();             // Provides random point inside hyperrectangle
0137       void Grow();                  // build up foam
0138       Long_t PeekMax();             // peek cell with max. driver integral
0139       Int_t  Divide(PDEFoamCell *); // Divide iCell into two daughters; iCell retained, taged as inactive
0140       Double_t Eval(Double_t *xRand, Double_t &event_density); // evaluate distribution on point 'xRand'
0141
0142       // ---------- Cell value access functions
0143
0144       // low level functions to access a certain cell value
0145       Double_t GetCellElement(const PDEFoamCell *cell, UInt_t i) const;  // get Element 'i' in cell 'cell'
0146       void SetCellElement(PDEFoamCell *cell, UInt_t i, Double_t value); // set Element 'i' in cell 'cell' to value 'value'
0147
0148       // specific function used during evaluation; determines, whether a cell value is undefined
0149       virtual Bool_t  CellValueIsUndefined( PDEFoamCell* );
0150
0151       // finds cell according to given event variables
0152       PDEFoamCell* FindCell(const std::vector<Float_t>&) const ;
0153       std::vector<TMVA::PDEFoamCell*> FindCells(const std::vector<Float_t>&) const;
0154       std::vector<TMVA::PDEFoamCell*> FindCells(const std::map<Int_t,Float_t>&) const;
0155       void FindCells(const std::map<Int_t, Float_t>&, PDEFoamCell*, std::vector<PDEFoamCell*> &) const;
0156
0157       // get internal density
0158       PDEFoamDensityBase* GetDistr() const { assert(fDistr); return fDistr; }
0159
0160       // Square function (fastest implementation)
0161       template<typename T> T Sqr(T x) const { return x*x; }
0162
0163       PDEFoam(const PDEFoam&);    // Copy Constructor  NOT USED
0164
0165       // ---------- Public functions ----------------------------------
0166    public:
0167       PDEFoam();                  // Default constructor (used only by ROOT streamer)
0168       PDEFoam(const TString&);    // Principal user-defined constructor
0169       virtual ~PDEFoam();         // Default destructor
0170
0171       // ---------- Foam creation functions
0172
0173       void Initialize() {}        // initialize the PDEFoam
0174       void FillBinarySearchTree( const Event* ev ); // fill event into BST
0175       void Create();              // build-up foam
0176
0177       // function to fill created cell with given value
0178       virtual void FillFoamCells(const Event* ev, Float_t wt);
0179
0180       // remove all cell elements
0181       void ResetCellElements();
0182
0183       // function to call after foam is grown
0184       virtual void Finalize() {}
0185
0186       // ---------- Getters and Setters
0187
0188       void SetDim(Int_t kDim); // Sets dimension of cubical space
0189       void SetnCells(Long_t nCells){fNCells =nCells;}  // Sets maximum number of cells
0190       void SetnSampl(Long_t nSampl){fNSampl =nSampl;}  // Sets no of MC events in cell exploration
0191       void SetnBin(Int_t nBin){fNBin = nBin;}          // Sets no of bins in histograms in cell exploration
0192       void SetEvPerBin(Int_t EvPerBin){fEvPerBin =EvPerBin;} // Sets max. no. of effective events per bin
0193       void SetInhiDiv(Int_t, Int_t ); // Set inhibition of cell division along certain edge
0194       void SetDensity(PDEFoamDensityBase *dens) { fDistr = dens; }
0195
0196       // coverity[ -tainted_data_return ]
0197       Int_t    GetTotDim()    const {return fDim;  } // Get total dimension
0198       TString  GetFoamName()  const {return fName; } // Get name of foam
0199       UInt_t   GetNActiveCells()   const {return fNoAct;} // returns number of active cells
0200       UInt_t   GetNInActiveCells() const {return GetNCells()-GetNActiveCells();} // returns number of not active cells
0201       UInt_t   GetNCells()         const {return fNCells;}   // returns number of cells
0202       PDEFoamCell* GetRootCell()   const {return fCells[0];} // get pointer to root cell
0203
0204       // Getters and Setters for user cut options
0205       void     SetNmin(UInt_t val)     { fNmin=val;      }
0206       UInt_t   GetNmin()               { return fNmin;   }
0207       void     SetMaxDepth(UInt_t maxdepth) { fMaxDepth = maxdepth; }
0208       UInt_t   GetMaxDepth() const { return fMaxDepth; }
0209
0210       // Getters and Setters for foam boundaries
0211       void SetXmin(Int_t idim, Double_t wmin);
0212       void SetXmax(Int_t idim, Double_t wmax);
0213       Double_t GetXmin(Int_t idim) const {return fXmin[idim];}
0214       Double_t GetXmax(Int_t idim) const {return fXmax[idim];}
0215
0216       // Getters and Setters for variable names
0217       void AddVariableName(const char *s) { AddVariableName(new TObjString(s)); }
0218       void AddVariableName(TObjString *s) { fVariableNames->Add(s); }
0219       TObjString* GetVariableName(Int_t idx) {return dynamic_cast<TObjString*>(fVariableNames->At(idx));}
0220
0221       // Delete the fDistr object, which contains the binary search
0222       // tree
0223       void DeleteBinarySearchTree();
0224
0225       // ---------- Transformation functions for event variables into foam boundaries
0226       // reason: foam always has boundaries [0, 1]
0227
0228       Float_t VarTransform(Int_t idim, Float_t x) const; // transform [xmin, xmax] --> [0, 1]
0229       std::vector<Float_t> VarTransform(const std::vector<Float_t> &invec) const;
0230       Float_t VarTransformInvers(Int_t idim, Float_t x) const; // transform [0, 1] --> [xmin, xmax]
0231       std::vector<Float_t> VarTransformInvers(const std::vector<Float_t> &invec) const;
0232
0233       // ---------- Debug functions
0234
0235       void     CheckAll(Int_t);  // Checks correctness of the entire data structure in the FOAM object
0236       void     PrintCell(Long_t iCell=0); // Print content of cell
0237       void     PrintCells();     // Prints content of all cells
0238
0239       // Message logger
0240       MsgLogger& Log() const { return *fLogger; }
0241
0242       // ---------- Foam projection methods
0243
0244       // project foam to two-dimensional histogram
0245       virtual TH2D* Project2(Int_t idim1, Int_t idim2, ECellValue cell_value=kValue,
0246                              PDEFoamKernelBase *kernel=nullptr, UInt_t nbin=50);
0247
0248       // Project one-dimensional foam to a 1-dim histogram
0249       TH1D* Draw1Dim(ECellValue cell_value, Int_t nbin, PDEFoamKernelBase *kernel=nullptr);
0250
0251       // Generates C++ code (root macro) for drawing foam with boxes (only 2-dim!)
0252       void RootPlot2dim( const TString& filename, TString opt,
0253                          Bool_t createCanvas = kTRUE, Bool_t colors = kTRUE );
0254
0255       // ---------- Foam evaluation functions
0256
0257       // get cell value for a given event
0258       virtual Float_t GetCellValue( const std::vector<Float_t>& xvec, ECellValue cv, PDEFoamKernelBase*  );
0259
0260       // get cell values for a given (incomplete) event vector
0261       virtual std::vector<Float_t> GetCellValue( const std::map<Int_t,Float_t>& xvec, ECellValue cv );
0262
0263       // get cell value stored in a foam cell
0264       virtual Float_t GetCellValue( const PDEFoamCell* cell, ECellValue cv );
0265
0266       // ---------- friend classes
0267       friend class PDEFoamKernelBase;
0268       friend class PDEFoamKernelTrivial;
0269       friend class PDEFoamKernelLinN;
0270       friend class PDEFoamKernelGauss;
0271
0272       // ---------- ROOT class definition
0273       ClassDef(PDEFoam,7) // Tree of PDEFoamCells
0274          }; // end of PDEFoam
0275
0276 }  // namespace TMVA
0277
0278 // ---------- Inline functions
0279
0280 //_____________________________________________________________________
0281 inline Float_t TMVA::PDEFoam::VarTransform(Int_t idim, Float_t x) const
0282 {
0283    // transform variable x from [xmin, xmax] --> [0, 1]
0284    return (x-fXmin[idim])/(fXmax[idim]-fXmin[idim]);
0285 }
0286
0287 //_____________________________________________________________________
0288 inline std::vector<Float_t> TMVA::PDEFoam::VarTransform(const std::vector<Float_t> &invec) const
0289 {
0290    // transform vector invec from [xmin, xmax] --> [0, 1]
0291    std::vector<Float_t> outvec;
0292    for(UInt_t i=0; i<invec.size(); i++)
0293       outvec.push_back(VarTransform(i, invec.at(i)));
0294    return outvec;
0295 }
0296
0297 //_____________________________________________________________________
0298 inline Float_t TMVA::PDEFoam::VarTransformInvers(Int_t idim, Float_t x) const
0299 {
0300    // transform variable x from [0, 1] --> [xmin, xmax]
0301    return x*(fXmax[idim]-fXmin[idim]) + fXmin[idim];
0302 }
0303
0304 //_____________________________________________________________________
0305 inline std::vector<Float_t> TMVA::PDEFoam::VarTransformInvers(const std::vector<Float_t> &invec) const
0306 {
0307    // transform vector invec from [0, 1] --> [xmin, xmax]
0308    std::vector<Float_t> outvec;
0309    for(UInt_t i=0; i<invec.size(); i++)
0310       outvec.push_back(VarTransformInvers(i, invec.at(i)));
0311    return outvec;
0312 }
0313
0314 #endif