class TMVA::PDEFoam: public TObject

 Default constructor for streamer, user should not use it.

 User constructor, to be employed by the user

 Default destructor

 Copy Constructor  NOT IMPLEMENTED (NEVER USED)

 Sets dimension of cubical space

 set lower foam bound in dimension idim

 set upper foam bound in dimension idim

 Basic initialization of FOAM invoked by the user.
 IMPORTANT: Random number generator and the distribution object has to be
 provided using SetPseRan and SetRho prior to invoking this initializator!

 After the foam is grown, space for 2 variables is reserved in
 every cell.  They are used for filling the foam cells.

 Internal subprogram used by Create.
 It initializes "root part" of the FOAM of the tree of cells.

 Internal subprogram used by Create.
 It initializes content of the newly allocated active cell.

 Internal subprogram used by Create.
 It explores newly defined cell with help of special short MC sampling.
 As a result, estimates of kTRUE and drive volume is defined/determined
 Average and dispersion of the weight distribution will is found along
 each edge and the best edge (minimum dispersion, best maximum weight)
 is memorized for future use.
 The optimal division point for eventual future cell division is
 determined/recorded. Recorded are also minimum and maximum weight etc.
 The volume estimate in all (inactive) parent cells is updated.
 Note that links to parents and initial volume = 1/2 parent has to be
 already defined prior to calling this routine.

 If fNmin > 0 then the total number of (training) events found in
 the cell during the exploration is stored in the cell.  This
 information is used withing PeekMax() to avoid splitting cells
 which contain less than fNmin events.

 Internal subrogram used by Create.
 In determines the best edge candidate and the position of the cell division plane
 in case of the variance reduction for future cell division,
 using results of the MC exploration run stored in fHistEdg

 Internal subrogram used by Create.
 Provides random vector Alpha  0< Alpha(i) < 1

 Internal subprogram used by Create.  It finds cell with maximal
 driver integral for the purpose of the division.  This function
 is overridden by the PDEFoam Class to apply cuts on the number
 of events in the cell (fNmin) and the cell tree depth
 (GetMaxDepth() > 0) during cell buildup.

 Internal subrogram used by Create.
 It divides cell iCell into two daughter cells.
 The iCell is retained and tagged as inactive, daughter cells are appended
 at the end of the buffer.
 New vertex is added to list of vertices.
 List of active cells is updated, iCell removed, two daughters added
 and their properties set with help of MC sampling (PDEFoam_Explore)
 Returns Code RC=-1 of buffer limit is reached,  fLastCe=fnBuf.

 Internal subprogram.
 Evaluates (training) distribution.

 Internal subrogram used by Create.
 It grow new cells by the binary division process.
 This function is overridden by the PDEFoam class to stop the foam buildup process
 if one of the cut conditions stop the cell split.

 This can be called before Create, after setting kDim
 It defines which variables are excluded in the process of the cell division.
 For example 'FoamX->SetInhiDiv(1, 1);' inhibits division of y-variable.

  User utility, miscellaneous and debug.
  Checks all pointers in the tree of cells. This is useful autodiagnostic.
  level=0, no printout, failures causes STOP
  level=1, printout, failures lead to WARNINGS only

 Prints geometry of and elements of 'iCell', as well as relations
 to parent and daughter cells.

 Prints geometry of ALL cells of the FOAM

 This function fills a weight 'wt' into the PDEFoam cell, which
 corresponds to the given event 'ev'.  Per default cell element 0
 is filled with the weight 'wt', and cell element 1 is filled
 with the squared weight.  This function can be overridden by a
 subclass in order to change the values stored in the foam cells.

 Remove the cell elements from all cells.

 Returns true, if the value of the given cell is undefined.
 Default value: kFALSE.  This function can be overridden by
 sub-classes.

 This function finds the cell, which corresponds to the given
 untransformed event vector 'xvec' and return its value, which is
 given by the parameter 'cv'.  If kernel != NULL, then
 PDEFoamKernelBase::Estimate() is called on the transformed event
 variables.

 Parameters:

 - xvec - event vector (untransformed, [fXmin,fXmax])

 - cv - the cell value to return

 - kernel - PDEFoam kernel estimator.  If NULL is given, than the
   pure cell value is returned

 Return:

 The cell value, corresponding to 'xvec', estimated by the given
 kernel.

 This function finds all cells, which corresponds to the given
 (incomplete) untransformed event vector 'xvec' and returns the
 cell values, according to the parameter 'cv'.

 Parameters:

 - xvec - map for the untransformed vector.  The key (Int_t) is
   the dimension, and the value (Float_t) is the event
   coordinate.  Note that not all coordinates have to be
   specified.

 - cv - cell values to return

 Return:

 cell values from all cells that were found

 Find cell that contains 'xvec' (in foam coordinates [0,1]).

 Loop to find cell that contains 'xvec' starting at root cell,
 and traversing binary tree to find the cell quickly.  Note, that
 if 'xvec' lies outside the foam, the cell which is nearest to
 'xvec' is returned.  (The returned pointer should never be
 NULL.)

 Parameters:

 - xvec - event vector (in foam coordinates [0,1])

 Return:

 PDEFoam cell corresponding to 'xvec'

 This is a helper function for std::vector<PDEFoamCell*>
 FindCells(...) and a generalisation of PDEFoamCell* FindCell().
 It saves in 'cells' all cells, which contain the coordinates
 specifies in 'txvec'.  Note, that not all coordinates have to be
 specified in 'txvec'.

 Parameters:

 - txvec - event vector in foam coordinates [0,1].  The key is
   the dimension and the value is the event coordinate.  Note,
   that not all coordinates have to be specified.

 - cell - cell to start searching with (usually root cell
   fCells[0])

 - cells - list of cells that were found

 Find all cells, that contain txvec.  This function can be used,
 when the dimension of the foam is greater than the dimension of
 txvec.  E.g. this is the case for multi-target regression.

 Parameters:

 - txvec - event vector of variables, transformed into foam
   coordinates [0,1].  The size of txvec can be smaller than the
   dimension of the foam.

 Return value:

 - vector of cells, that fit txvec

 Find all cells, that contain the coordinates specified in txvec.
 The key in 'txvec' is the dimension, and the corresponding value
 is the coordinate.  Note, that not all coordinates have to be
 specified in txvec.

 Parameters:

 - txvec - map of coordinates (transformed into foam coordinates
   [0,1])

 Return value:

 - vector of cells, that fit txvec

 Draws 1-dimensional foam (= histogram)

 Parameters:

 - cell_value - the cell value to draw

 - nbin - number of bins of result histogram

 - kernel - a PDEFoam kernel.

 Project foam variable idim1 and variable idim2 to histogram.

 Parameters:

 - idim1, idim2 - dimensions to project to

 - cell_value - the cell value to draw

 - kernel - a PDEFoam kernel (optional).  If NULL is given, the
            kernel is ignored and the pure cell values are
            plotted.

 - nbin - number of bins in x and y direction of result histogram
          (optional, default is 50).

 Returns:
 a 2-dimensional histogram

 Returns the cell value of 'cell' corresponding to the given
 option 'cv'.  This function should be overridden by the subclass
 in order to specify which cell elements to return for a given
 cell value 'cv'.  By default kValue returns cell element 0, and
 kValueError returns cell element 1.

 Returns cell element i of cell 'cell'.  If the cell has no
 elements or the index 'i' is out of range, than 0 is returned.

 Set cell element i of cell to value.  If the cell element i does
 not exist, it is created.

 Overridden function of PDEFoam to avoid native foam output.
 Draw TMVA-process bar instead.

 Debugging tool which plots the cells of a 2-dimensional PDEFoam
 as rectangles in C++ format readable for ROOT.

 Parameters:
 - filename - filename of ouput root macro

 - opt - cell_value, rms, rms_ov_mean
   If cell_value is set, the following values will be filled into
   the result histogram:
    - number of events - in case of classification with 2 separate
                         foams or multi-target regression
    - discriminator    - in case of classification with one
                         unified foam
    - target           - in case of mono-target regression
   If none of {cell_value, rms, rms_ov_mean} is given, the cells
   will not be filled.
   If 'opt' contains the string 'cellnumber', the index of
   each cell is draw in addition.

 - createCanvas - whether to create a new canvas or not

 - colors - whether to fill cells with colors or shades of grey

 Example:

   The following commands load a mono-target regression foam from
   file 'foam.root' and create a ROOT macro 'output.C', which
   draws all PDEFoam cells with little boxes.  The latter are
   filled with colors according to the target value stored in the
   cell.  Also the cell number is drawn.

   TFile file("foam.root");
   TMVA::PDEFoam *foam = (TMVA::PDEFoam*) gDirectory->Get("MonoTargetRegressionFoam");
   foam->RootPlot2dim("output.C","cell_value,cellnumber");
   gROOT->Macro("output.C");

 Insert event to internal foam's density estimator
 PDEFoamDensityBase.

 Delete the foam's density estimator, which contains the binary
 search tree.

 get internal density

 ---------- Foam creation functions

 function to call after foam is grown

 coverity[ -tainted_data_return ]

 Getters and Setters for user cut options

 Getters and Setters for variable names