Logo ROOT   6.30.04
Reference Guide
 All Namespaces Files Pages
PDEFoam.h
Go to the documentation of this file.
1 // @(#)root/tmva $Id$
2 // Author: S. Jadach, Tancredi Carli, Dominik Dannheim, Alexander Voigt
3 
4 /**********************************************************************************
5  * Project: TMVA - a Root-integrated toolkit for multivariate data analysis *
6  * Package: TMVA *
7  * Classes: PDEFoam *
8  * Web : http://tmva.sourceforge.net *
9  * *
10  * Description: *
11  * Class for PDEFoam object *
12  * *
13  * Authors (alphabetical): *
14  * S. Jadach - Institute of Nuclear Physics, Cracow, Poland *
15  * Tancredi Carli - CERN, Switzerland *
16  * Dominik Dannheim - CERN, Switzerland *
17  * Alexander Voigt - TU Dresden, Germany *
18  * *
19  * Copyright (c) 2008, 2010: *
20  * CERN, Switzerland *
21  * MPI-K Heidelberg, Germany *
22  * *
23  * Redistribution and use in source and binary forms, with or without *
24  * modification, are permitted according to the terms listed in LICENSE *
25  * (http://tmva.sourceforge.net/LICENSE) *
26  **********************************************************************************/
27 
28 #ifndef ROOT_TMVA_PDEFoam
29 #define ROOT_TMVA_PDEFoam
30 
31 #include <iosfwd>
32 #include <cassert>
33 
34 #include "TH2D.h"
35 #include "TObjArray.h"
36 #include "TObjString.h"
37 #include "TVectorT.h"
38 #include "TString.h"
39 #include "TMVA/VariableInfo.h"
40 #include "TMVA/Timer.h"
41 #include "TObject.h"
42 #include "TRandom3.h"
43 
44 namespace TMVA {
45  class PDEFoamCell;
46  class PDEFoamVect;
47  class PDEFoamDensityBase;
48  class PDEFoamKernelBase;
49  class PDEFoam;
50 
51  // separation types
52  enum EDTSeparation { kFoam, kGiniIndex, kMisClassificationError,
53  kCrossEntropy, kGiniIndexWithLaplace, kSdivSqrtSplusB };
54 
55  // foam types
56  enum EFoamType { kSeparate, kDiscr, kMonoTarget, kMultiTarget, kMultiClass };
57 
58  // enum type for possible foam cell values
59  // kValue : cell value who's rms is minimized
60  // kValueError : error on kValue
61  // kValueDensity : kValue / cell volume
62  // kMeanValue : mean sampling value (saved in fIntegral)
63  // kRms : rms of sampling distribution (saved in fDriver)
64  // kRmsOvMean : rms/mean of sampling distribution (saved in
65  // fDriver and fIntegral)
66  // kCellVolume : volume of cell
67  enum ECellValue { kValue, kValueError, kValueDensity, kMeanValue,
68  kRms, kRmsOvMean, kCellVolume };
69 }
70 
71 #include "TMVA/PDEFoamDensityBase.h"
72 #include "TMVA/PDEFoamVect.h"
73 #include "TMVA/PDEFoamCell.h"
74 
75 namespace TMVA {
76 
77  class PDEFoam : public TObject {
78  protected:
79  // COMPONENTS //
80  //-------------- Input parameters
81  TString fName; // Name of a given instance of the FOAM class
82  Int_t fDim; // Dimension of the integration/simulation space
83  Int_t fNCells; // Maximum number of cells
84  //-------------------
85  Int_t fNBin; // No. of bins in the edge histogram for cell MC exploration
86  Int_t fNSampl; // No. of MC events, when dividing (exploring) cell
87  Int_t fEvPerBin; // Maximum number of effective (wt=1) events per bin
88  //------------------- MULTI-BRANCHING ---------------------
89  Int_t *fMaskDiv; //! [fDim] Dynamic Mask for cell division
90  Int_t *fInhiDiv; //! [fDim] Flags for inhibiting cell division
91  //------------------- GEOMETRY ----------------------------
92  Int_t fNoAct; // Number of active cells
93  Int_t fLastCe; // Index of the last cell
94  PDEFoamCell **fCells; // [fNCells] Array of ALL cells
95  //------------------ M.C. generation----------------------------
96  TObjArray *fHistEdg; // Histograms of wt, one for each cell edge
97  Double_t *fRvec; // [fDim] random number vector from r.n. generator fDim+1 maximum elements
98  //----------- Procedures
99  TRandom3 *fPseRan; // Pointer to user-defined generator of pseudorandom numbers
100  //---------- working space for CELL exploration -------------
101  Double_t *fAlpha; // [fDim] Internal parameters of the hyperrectangle
102  // --------- PDE-Foam specific variables
103  EFoamType fFoamType; // BACKWARDS COMPATIBILITY: type of foam
104  Double_t *fXmin; // [fDim] minimum for variable transform
105  Double_t *fXmax; // [fDim] maximum for variable transform
106  UInt_t fNElements; // BACKWARDS COMPATIBILITY: number of variables in every cell
107  UInt_t fNmin; // minimal number of events in cell to split cell
108  UInt_t fMaxDepth; // maximum depth of cell tree
109  Float_t fVolFrac; // BACKWARDS COMPATIBILITY: volume fraction (with respect to total phase space
110  Bool_t fFillFoamWithOrigWeights; // BACKWARDS COMPATIBILITY: fill the foam with boost or orig. weights
111  EDTSeparation fDTSeparation; // BACKWARDS COMPATIBILITY: split cells according to decision tree logic
112  Bool_t fPeekMax; // BACKWARDS COMPATIBILITY: peek up cell with max. driver integral for split
113  PDEFoamDensityBase *fDistr; //! distribution of training events
114  Timer *fTimer; //! timer for graphical output
115  TObjArray *fVariableNames;// collection of all variable names
116  mutable MsgLogger* fLogger; //! message logger
117 
118  /////////////////////////////////////////////////////////////////
119  // METHODS //
120  /////////////////////////////////////////////////////////////////
121 
122  protected:
123  // ---------- TMVA console output
124 
125  void OutputGrow(Bool_t finished = false ); // nice TMVA console output
126 
127  // ---------- Foam build-up functions
128 
129  // Internal foam initialization functions
130  void InitCells(); // Initialisation of all foam cells
131  Int_t CellFill(Int_t, PDEFoamCell*);// Allocates new empty cell and return its index
132  virtual void Explore(PDEFoamCell *Cell); // Exploration of the new cell, determine <wt>, wtMax etc.
133  void Varedu(Double_t [], Int_t&, Double_t&,Double_t&); // Determines the best edge, variance reduction
134  void MakeAlpha(); // Provides random point inside hyperrectangle
135  void Grow(); // build up foam
136  Long_t PeekMax(); // peek cell with max. driver integral
137  Int_t Divide(PDEFoamCell *); // Divide iCell into two daughters; iCell retained, taged as inactive
138  Double_t Eval(Double_t *xRand, Double_t &event_density); // evaluate distribution on point 'xRand'
139 
140  // ---------- Cell value access functions
141 
142  // low level functions to access a certain cell value
143  Double_t GetCellElement(const PDEFoamCell *cell, UInt_t i) const; // get Element 'i' in cell 'cell'
144  void SetCellElement(PDEFoamCell *cell, UInt_t i, Double_t value); // set Element 'i' in cell 'cell' to value 'value'
145 
146  // specific function used during evaluation; determines, whether a cell value is undefined
147  virtual Bool_t CellValueIsUndefined( PDEFoamCell* );
148 
149  // finds cell according to given event variables
150  PDEFoamCell* FindCell(const std::vector<Float_t>&) const ;
151  std::vector<TMVA::PDEFoamCell*> FindCells(const std::vector<Float_t>&) const;
152  std::vector<TMVA::PDEFoamCell*> FindCells(const std::map<Int_t,Float_t>&) const;
153  void FindCells(const std::map<Int_t, Float_t>&, PDEFoamCell*, std::vector<PDEFoamCell*> &) const;
154 
155  // get internal density
156  PDEFoamDensityBase* GetDistr() const { assert(fDistr); return fDistr; }
157 
158  // Square function (fastest implementation)
159  template<typename T> T Sqr(T x) const { return x*x; }
160 
161  PDEFoam(const PDEFoam&); // Copy Constructor NOT USED
162 
163  // ---------- Public functions ----------------------------------
164  public:
165  PDEFoam(); // Default constructor (used only by ROOT streamer)
166  PDEFoam(const TString&); // Principal user-defined constructor
167  virtual ~PDEFoam(); // Default destructor
168 
169  // ---------- Foam creation functions
170 
171  void Initialize() {} // initialize the PDEFoam
172  void FillBinarySearchTree( const Event* ev ); // fill event into BST
173  void Create(); // build-up foam
174 
175  // function to fill created cell with given value
176  virtual void FillFoamCells(const Event* ev, Float_t wt);
177 
178  // remove all cell elements
179  void ResetCellElements();
180 
181  // function to call after foam is grown
182  virtual void Finalize() {}
183 
184  // ---------- Getters and Setters
185 
186  void SetDim(Int_t kDim); // Sets dimension of cubical space
187  void SetnCells(Long_t nCells){fNCells =nCells;} // Sets maximum number of cells
188  void SetnSampl(Long_t nSampl){fNSampl =nSampl;} // Sets no of MC events in cell exploration
189  void SetnBin(Int_t nBin){fNBin = nBin;} // Sets no of bins in histograms in cell exploration
190  void SetEvPerBin(Int_t EvPerBin){fEvPerBin =EvPerBin;} // Sets max. no. of effective events per bin
191  void SetInhiDiv(Int_t, Int_t ); // Set inhibition of cell division along certain edge
192  void SetDensity(PDEFoamDensityBase *dens) { fDistr = dens; }
193 
194  // coverity[ -tainted_data_return ]
195  Int_t GetTotDim() const {return fDim; } // Get total dimension
196  TString GetFoamName() const {return fName; } // Get name of foam
197  UInt_t GetNActiveCells() const {return fNoAct;} // returns number of active cells
198  UInt_t GetNInActiveCells() const {return GetNCells()-GetNActiveCells();} // returns number of not active cells
199  UInt_t GetNCells() const {return fNCells;} // returns number of cells
200  PDEFoamCell* GetRootCell() const {return fCells[0];} // get pointer to root cell
201 
202  // Getters and Setters for user cut options
203  void SetNmin(UInt_t val) { fNmin=val; }
204  UInt_t GetNmin() { return fNmin; }
205  void SetMaxDepth(UInt_t maxdepth) { fMaxDepth = maxdepth; }
206  UInt_t GetMaxDepth() const { return fMaxDepth; }
207 
208  // Getters and Setters for foam boundaries
209  void SetXmin(Int_t idim, Double_t wmin);
210  void SetXmax(Int_t idim, Double_t wmax);
211  Double_t GetXmin(Int_t idim) const {return fXmin[idim];}
212  Double_t GetXmax(Int_t idim) const {return fXmax[idim];}
213 
214  // Getters and Setters for variable names
215  void AddVariableName(const char *s) { AddVariableName(new TObjString(s)); }
216  void AddVariableName(TObjString *s) { fVariableNames->Add(s); }
217  TObjString* GetVariableName(Int_t idx) {return dynamic_cast<TObjString*>(fVariableNames->At(idx));}
218 
219  // Delete the fDistr object, which contains the binary search
220  // tree
221  void DeleteBinarySearchTree();
222 
223  // ---------- Transformation functions for event variables into foam boundaries
224  // reason: foam always has boundaries [0, 1]
225 
226  Float_t VarTransform(Int_t idim, Float_t x) const; // transform [xmin, xmax] --> [0, 1]
227  std::vector<Float_t> VarTransform(const std::vector<Float_t> &invec) const;
228  Float_t VarTransformInvers(Int_t idim, Float_t x) const; // transform [0, 1] --> [xmin, xmax]
229  std::vector<Float_t> VarTransformInvers(const std::vector<Float_t> &invec) const;
230 
231  // ---------- Debug functions
232 
233  void CheckAll(Int_t); // Checks correctness of the entire data structure in the FOAM object
234  void PrintCell(Long_t iCell=0); // Print content of cell
235  void PrintCells(); // Prints content of all cells
236 
237  // Message logger
238  MsgLogger& Log() const { return *fLogger; }
239 
240  // ---------- Foam projection methods
241 
242  // project foam to two-dimensional histogram
243  virtual TH2D* Project2(Int_t idim1, Int_t idim2, ECellValue cell_value=kValue,
244  PDEFoamKernelBase *kernel=NULL, UInt_t nbin=50);
245 
246  // Project one-dimensional foam to a 1-dim histogram
247  TH1D* Draw1Dim(ECellValue cell_value, Int_t nbin, PDEFoamKernelBase *kernel=NULL);
248 
249  // Generates C++ code (root macro) for drawing foam with boxes (only 2-dim!)
250  void RootPlot2dim( const TString& filename, TString opt,
251  Bool_t createCanvas = kTRUE, Bool_t colors = kTRUE );
252 
253  // ---------- Foam evaluation functions
254 
255  // get cell value for a given event
256  virtual Float_t GetCellValue( const std::vector<Float_t>& xvec, ECellValue cv, PDEFoamKernelBase* );
257 
258  // get cell values for a given (incomplete) event vector
259  virtual std::vector<Float_t> GetCellValue( const std::map<Int_t,Float_t>& xvec, ECellValue cv );
260 
261  // get cell value stored in a foam cell
262  virtual Float_t GetCellValue( const PDEFoamCell* cell, ECellValue cv );
263 
264  // ---------- friend classes
265  friend class PDEFoamKernelBase;
266  friend class PDEFoamKernelTrivial;
267  friend class PDEFoamKernelLinN;
268  friend class PDEFoamKernelGauss;
269 
270  // ---------- ROOT class definition
271  ClassDef(PDEFoam,7) // Tree of PDEFoamCells
272  }; // end of PDEFoam
273 
274 } // namespace TMVA
275 
276 // ---------- Inline functions
277 
278 //_____________________________________________________________________
279 inline Float_t TMVA::PDEFoam::VarTransform(Int_t idim, Float_t x) const
280 {
281  // transform variable x from [xmin, xmax] --> [0, 1]
282  return (x-fXmin[idim])/(fXmax[idim]-fXmin[idim]);
283 }
284 
285 //_____________________________________________________________________
286 inline std::vector<Float_t> TMVA::PDEFoam::VarTransform(const std::vector<Float_t> &invec) const
287 {
288  // transform vector invec from [xmin, xmax] --> [0, 1]
289  std::vector<Float_t> outvec;
290  for(UInt_t i=0; i<invec.size(); i++)
291  outvec.push_back(VarTransform(i, invec.at(i)));
292  return outvec;
293 }
294 
295 //_____________________________________________________________________
296 inline Float_t TMVA::PDEFoam::VarTransformInvers(Int_t idim, Float_t x) const
297 {
298  // transform variable x from [0, 1] --> [xmin, xmax]
299  return x*(fXmax[idim]-fXmin[idim]) + fXmin[idim];
300 }
301 
302 //_____________________________________________________________________
303 inline std::vector<Float_t> TMVA::PDEFoam::VarTransformInvers(const std::vector<Float_t> &invec) const
304 {
305  // transform vector invec from [0, 1] --> [xmin, xmax]
306  std::vector<Float_t> outvec;
307  for(UInt_t i=0; i<invec.size(); i++)
308  outvec.push_back(VarTransformInvers(i, invec.at(i)));
309  return outvec;
310 }
311 
312 #endif