root/TMVA/MethodPDEFoam.h

0001 // @(#)root/tmva $Id$
0002 // Author: Tancredi Carli, Dominik Dannheim, Alexander Voigt
0003
0004 /**********************************************************************************
0005  * Project: TMVA - a Root-integrated toolkit for multivariate Data analysis       *
0006  * Package: TMVA                                                                  *
0007  * Class  : MethodPDEFoam                                                         *
0008  *                                             *
0009  *                                                                                *
0010  * Description:                                                                   *
0011  *      The PDEFoam method is an extension of the PDERS method, which divides     *
0012  *      the multi-dimensional phase space in a finite number of hyper-rectangles  *
0013  *      (cells) of constant event density. This "foam" of cells is filled with    *
0014  *      averaged probability-density information sampled from a training event    *
0015  *      sample.                                                                   *
0016  *                                                                                *
0017  * Authors (alphabetical):                                                        *
0018  *      Tancredi Carli   - CERN, Switzerland                                      *
0019  *      Dominik Dannheim - CERN, Switzerland                                      *
0020  *      Peter Speckmayer <peter.speckmayer@cern.ch>  - CERN, Switzerland          *
0021  *      Alexander Voigt  - TU Dresden, Germany                                    *
0022  *                                                                                *
0023  * Original author of the TFoam implementation:                                   *
0024  *      S. Jadach - Institute of Nuclear Physics, Cracow, Poland                  *
0025  *                                                                                *
0026  * Copyright (c) 2008, 2010:                                                      *
0027  *      CERN, Switzerland                                                         *
0028  *      MPI-K Heidelberg, Germany                                                 *
0029  *                                                                                *
0030  * Redistribution and use in source and binary forms, with or without             *
0031  * modification, are permitted according to the terms listed in LICENSE           *
0032  * (see tmva/doc/LICENSE)                                          *
0033  **********************************************************************************/
0034
0035 #ifndef ROOT_TMVA_MethodPDEFoam
0036 #define ROOT_TMVA_MethodPDEFoam
0037
0038 //////////////////////////////////////////////////////////////////////////////
0039 //                                                                          //
0040 // MethodPDEFoam                                                            //
0041 //                                                                          //
0042 //////////////////////////////////////////////////////////////////////////////
0043
0044 #include "TMVA/MethodBase.h"
0045
0046 #include "TMVA/PDEFoam.h"
0047
0048 #include "TMVA/PDEFoamDecisionTree.h"
0049 #include "TMVA/PDEFoamEvent.h"
0050 #include "TMVA/PDEFoamDiscriminant.h"
0051 #include "TMVA/PDEFoamTarget.h"
0052 #include "TMVA/PDEFoamMultiTarget.h"
0053
0054 #include "TMVA/PDEFoamDensityBase.h"
0055 #include "TMVA/PDEFoamTargetDensity.h"
0056 #include "TMVA/PDEFoamEventDensity.h"
0057 #include "TMVA/PDEFoamDiscriminantDensity.h"
0058 #include "TMVA/PDEFoamDecisionTreeDensity.h"
0059
0060 #include "TMVA/PDEFoamKernelBase.h"
0061 #include "TMVA/PDEFoamKernelTrivial.h"
0062 #include "TMVA/PDEFoamKernelLinN.h"
0063 #include "TMVA/PDEFoamKernelGauss.h"
0064
0065 #include <vector>
0066
0067 namespace TMVA {
0068
0069    class MethodPDEFoam : public MethodBase {
0070
0071    public:
0072
0073       // kernel types
0074       typedef enum EKernel { kNone=0, kGaus=1, kLinN=2 } EKernel;
0075
0076       MethodPDEFoam( const TString& jobName,
0077                      const TString& methodTitle,
0078                      DataSetInfo& dsi,
0079                      const TString& theOption = "PDEFoam");
0080
0081       MethodPDEFoam( DataSetInfo& dsi,
0082                      const TString& theWeightFile);
0083
0084       virtual ~MethodPDEFoam( void );
0085
0086       virtual Bool_t HasAnalysisType( Types::EAnalysisType type, UInt_t numberClasses, UInt_t numberTargets );
0087
0088       // training methods
0089       void Train( void );
0090       void TrainMonoTargetRegression( void );    // Regression output: one value
0091       void TrainMultiTargetRegression( void );   // Regression output: any number of values
0092       void TrainSeparatedClassification( void ); // Classification: one foam for Sig, one for Bg
0093       void TrainUnifiedClassification( void );   // Classification: one foam for Signal and Bg
0094       void TrainMultiClassification();           // Classification: one foam for every class
0095
0096       using MethodBase::ReadWeightsFromStream;
0097
0098       // write weights to stream
0099       void AddWeightsXMLTo( void* parent ) const;
0100
0101       // read weights from stream
0102       void ReadWeightsFromStream( std::istream & i );
0103       void ReadWeightsFromXML   ( void* wghtnode );
0104
0105       // write/read pure foams to/from file
0106       void WriteFoamsToFile() const;
0107       void ReadFoamsFromFile();
0108       PDEFoam* ReadClonedFoamFromFile(TFile*, const TString&);
0109
0110       // calculate the MVA value
0111       Double_t GetMvaValue( Double_t* err = nullptr, Double_t* errUpper = nullptr );
0112
0113       // calculate multiclass MVA values
0114       const std::vector<Float_t>& GetMulticlassValues();
0115
0116       // regression procedure
0117       virtual const std::vector<Float_t>& GetRegressionValues();
0118
0119       // reset the method
0120       virtual void Reset();
0121
0122       // ranking of input variables
0123       const Ranking* CreateRanking();
0124
0125       // get number of cuts in every dimension, starting at cell
0126       void GetNCuts(PDEFoamCell *cell, std::vector<UInt_t> &nCuts);
0127
0128       // helper functions to convert enum types to UInt_t and back
0129       EKernel GetKernel( void ) { return fKernel; }
0130       UInt_t KernelToUInt(EKernel ker) const { return UInt_t(ker); }
0131       EKernel UIntToKernel(UInt_t iker);
0132       UInt_t TargetSelectionToUInt(ETargetSelection ts) const { return UInt_t(ts); }
0133       ETargetSelection UIntToTargetSelection(UInt_t its);
0134
0135    protected:
0136
0137       // make ROOT-independent C++ class for classifier response (classifier-specific implementation)
0138       void MakeClassSpecific( std::ostream&, const TString& ) const;
0139
0140       // get help message text
0141       void GetHelpMessage() const;
0142
0143       // calculate the error on the Mva value
0144       Double_t CalculateMVAError();
0145
0146       // calculate Xmin and Xmax for Foam
0147       void CalcXminXmax();
0148
0149       // Set Xmin, Xmax in foam with index 'foam_index'
0150       void SetXminXmax(TMVA::PDEFoam*);
0151
0152       // create foam and set foam options
0153       PDEFoam* InitFoam(TString, EFoamType, UInt_t cls=0);
0154
0155       // create pdefoam kernel
0156       PDEFoamKernelBase* CreatePDEFoamKernel();
0157
0158       // delete all trained foams
0159       void DeleteFoams();
0160
0161       // fill variable names into foam
0162       void FillVariableNamesToFoam() const;
0163
0164    private:
0165
0166       // the option handling methods
0167       void DeclareOptions();
0168       void DeclareCompatibilityOptions();
0169       void ProcessOptions();
0170
0171       // nice output
0172       void PrintCoefficients( void );
0173
0174       // Square function (fastest implementation)
0175       template<typename T> T Sqr(T x) const { return x*x; }
0176
0177       // options to be used
0178       Bool_t        fSigBgSeparated;  ///< Separate Sig and Bg, or not
0179       Float_t       fFrac;            ///< Fraction used for calc of Xmin, Xmax
0180       Float_t       fDiscrErrCut;     ///< cut on discriminant error
0181       Float_t       fVolFrac;         ///< volume fraction (used for density calculation during buildup)
0182       Int_t         fnCells;          ///< Number of Cells  (1000)
0183       Int_t         fnActiveCells;    ///< Number of active cells
0184       Int_t         fnSampl;          ///< Number of MC events per cell in build-up (1000)
0185       Int_t         fnBin;            ///< Number of bins in build-up (100)
0186       Int_t         fEvPerBin;        ///< Maximum events (equiv.) per bin in build-up (1000)
0187
0188       Bool_t        fCompress;        ///< compress foam output file
0189       Bool_t        fMultiTargetRegression; ///< do regression on multiple targets
0190       UInt_t        fNmin;            ///< minimal number of events in cell necessary to split cell"
0191       Bool_t        fCutNmin;         ///< Keep for bw compatibility: Grabbing cell with maximal RMS to split next (TFoam default)
0192       UInt_t        fMaxDepth;        ///< maximum depth of cell tree
0193
0194       TString       fKernelStr;       ///< Kernel for GetMvaValue() (option string)
0195       EKernel       fKernel;          ///< Kernel for GetMvaValue()
0196       PDEFoamKernelBase *fKernelEstimator; ///< Kernel estimator
0197       TString       fTargetSelectionStr;   ///< method of selecting the target (only mulit target regr.)
0198       ETargetSelection fTargetSelection;   ///< method of selecting the target (only mulit target regr.)
0199       Bool_t        fFillFoamWithOrigWeights; ///< fill the foam with boost weights
0200       Bool_t        fUseYesNoCell;    ///< return -1 or 1 for bg or signal like event
0201       TString       fDTLogic;         ///< use DT algorithm to split cells
0202       EDTSeparation fDTSeparation;    ///< enum which specifies the separation to use for the DT logic
0203       Bool_t        fPeekMax;         ///< BACKWARDS COMPATIBILITY: peek up cell with max. driver integral for split
0204
0205       std::vector<Float_t> fXmin, fXmax; ///< range for histograms and foams
0206
0207       std::vector<PDEFoam*> fFoam;    ///< grown PDEFoams
0208
0209       // default initialisation called by all constructors
0210       void Init( void );
0211
0212       ClassDef(MethodPDEFoam,0); // Multi-dimensional probability density estimator using TFoam (PDE-Foam)
0213    };
0214
0215 } // namespace TMVA
0216
0217 #endif // MethodPDEFoam_H