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 subprogram used by Create.  It explores newly defined
 cell with according to the decision tree logic.  The separation
 set by the 'fDTSeparation' option is used (see also
 GetSeparation()).

 The optimal division point for eventual future cell division is
 determined/recorded.  Note that links to parents and initial
 volume = 1/2 parent has to be already defined prior to calling
 this routine.

 Note, that according to the decision tree logic, a cell is only
 split, if the number of (unweighted) events in each dautghter
 cell is greater than fNmin.

 Calculate the separation depending on 'fDTSeparation' for the
 given number of signal and background events 's', 'b'.  Note,
 that if (s+b) < 0 or s < 0 or b < 0 than the return value is 0.

 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 subprogram used by Create.  It finds the last created
 active cell for the purpose of the division.  Analogous to
 PeekMax() it is cut on the number of events in the cell (fNmin)
 and the cell tree depth (GetMaxDepth() > 0).

 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 'iCell'

 Prints geometry of ALL cells of the FOAM

 This function removes a cell iCell, which has a volume equal to zero.
 It works the following way:
 1) find grandparent to iCell
 2) set daughter of the grandparent cell to the sister of iCell

 Result:
 iCell and its parent are alone standing ==> will be removed

 debug function: checks all cells with respect to critical
 values, f.e. cell volume, ...

 This debug function prints the cell elements of all active
 cells.

 creates a TVectorD object with fNElements in every cell
 and initializes them by zero.
 The TVectorD object is used to store classification or
 regression data in every foam cell.

 Parameter:
   allcells == true  : create TVectorD on every cell
   allcells == false : create TVectorD on active cells with
                       cell index <= fLastCe (default)

 Calculate average cell target in every cell and save them to the cell.
 This function is called when the Mono target regression option is set.

 Calc discriminator and its error for every cell and save it to the cell.
 This function is called when the fSigBgSeparated==False option is set.

 Get discriminator saved in cell (previously calculated in CalcCellDiscr())
 which encloses the coordinates given in xvec.
 This function is used, when the fSigBgSeparated==False option is set
 (unified foams).

 This function fills an event into the foam.

 In case of Mono-Target regression this function prepares the
 calculation of the average target value in every cell.  Note,
 that only target 0 is saved in the cell!

 In case of a unified foam this function prepares the calculation of
 the cell discriminator in every cell.

 If 'NoNegWeights' is true, an event with negative weight will
 not be filled into the foam.  (Default value: false)

 Get regression value 0 from cell that contains the event vector xvec.
 This function is used when the MultiTargetRegression==False option is set.

 This function returns the average value 'cv' of only nearest
 neighbor cells.  It is used in cases, where empty cells shall
 not be evaluated.

 Parameters:
 - txvec - event vector, transformed into foam coordinates [0, 1]
 - cv - cell value, see definition of ECellValue

 Returns true, if the value of the given cell is undefined.

 This function is used when the MultiTargetRegression==True
 option is set.  It calculates the mean target or most probable
 target values if 'tvals' variables are given ('tvals' does not
 contain targets)

 Parameters:
 - tvals - transformed event variables (element of [0,1]) (no targets!)
 - ts - method of target selection (kMean, kMpv)

 Result:
 vetor of mean targets or most probable targets over all cells
 which first coordinates enclose 'tvals'

 This function is used when the MultiTargetRegression==True option is set.
 Returns regression value i, given the event variables 'vals'.
 Note: number of foam dimensions = number of variables + number of targets

 Parameters:
 - vals - event variables (no targets)
 - kernel - used kernel (None or Gaus)
 - ts - method of target selection (Mean or Mpv)

 Returns density (=number of entries / volume) of cell that
 encloses the untransformed event vector 'xvec'.  This function
 is called by GetMvaValue() in case of two separated foams
 (signal and background).  'kernel' can be either kNone or kGaus.

 This function returns a value, which was saved in the foam cell,
 depending on the foam type.  The value to return is specified
 with the 'cv' parameter.

 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'.

 Returns the number of events, saved in the 'cell' during foam build-up.
 Only used during foam build-up!

 Returns the cell value, corresponding to 'txvec' (foam
 coordinates [0,1]), weighted by the neighbor cells via a linear
 function.

 Parameters:
  - txvec - event vector, transformed into foam coordinates [0,1]

  - cv - cell value to be weighted

  - dim1, dim2 - dimensions for two-dimensional projection.
    Default values: dim1 = dim2 = -1
    If dim1 and dim2 are set to values >=0 and <fDim, than
    the function GetProjectionCellValue() is used to get cell
    value.  This is used for projection to two dimensions within
    Project2().

  - TreatEmptyCells - if this option is set false (default),
    it is not checked, wether the cell or its neighbors are empty
    or not.  If this option is set true, than only non-empty
    neighbor cells are taken into account for weighting.  If the
    cell, which contains txvec is empty, than its value is
    replaced by the average value of the non-empty neighbor cells

 Returns the gauss weight between the 'cell' and a given coordinate 'txvec'.

 Parameters:
 - cell - the cell

 - txvec - the transformed event variables (in [0,1]) (coordinates <0 are
   set to 0, >1 are set to 1)

 - dim - number of dimensions for the calculation of the euclidean distance.
   If dim=0, all dimensions of the foam are taken.  Else only the first 'dim'
   coordinates of 'txvec' are used for the calculation of the euclidean distance.

 Returns:
 exp(-(d/sigma)^2/2), where
  - d - is the euclidean distance between 'txvec' and the point of the 'cell'
    which is most close to 'txvec' (in order to avoid artefacts because of the
    form of the cells).
  - sigma = 1/VolFrac

 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.)

 This is a helper function for FindCells().  It saves in 'cells'
 all cells, which contain txvec.  It works analogous to
 FindCell().

 Parameters:

 - txvec - vector of variables (no targets!) (transformed into
   foam)

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

 - cells - list of cells 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 - vector of variables (no targets!) (transformed into
   foam)

 Return value:

 - vector of cells, that fit txvec

 Draws 1-dimensional foam (= histogram)

 Parameters:

 - 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

 - nbin - number of bins of result histogram

 Warning: This function is not well tested!

 Project foam variable idim1 and variable idim2 to histogram.

 Parameters:

 - idim1, idim2 - dimensions to project to

 - 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

 - ker - kGaus, kNone (warning: Gaus may be very slow!)

 - nbin - number of bins in x and y direction of result histogram.

 Returns:
 a 2-dimensional histogram

 Helper function for projection function Project2().  It returns
 the cell value of 'cell' corresponding to the given option 'cv'.
 The two dimensions are needed for weighting the return value,
 because Project2() projects the foam to two dimensions.

 Returns cell element i of cell 'cell'.

 Set cell element i of cell to value.

 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

 - log_colors - whether to fill cells with colors (logarithmic scale)

 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 density PDEFoamDistr.

 Delete the fDistr object, which contains the binary search tree

 Initialize binary search tree, stored in object of type
 PDEFoamDistr

 Set the foam type.  This determinates the method of the
 calculation of the density during the foam build-up.

 Read PDEFoam variables from stream 'istr'.

 Write PDEFoam variables to stream 'os'.

 write foam variables to xml

 coverity[ -tainted_data_return ]

 Getters and Setters for user cut options

 Getters and Setters for variable names