root/TMVA/MethodPDERS.h

0001 // @(#)root/tmva $Id$
0002 // Author: Andreas Hoecker, Yair Mahalalel, Joerg Stelzer, Helge Voss, Kai Voss
0003
0004 /**********************************************************************************
0005  * Project: TMVA - a Root-integrated toolkit for multivariate data analysis       *
0006  * Package: TMVA                                                                  *
0007  * Class  : MethodPDERS                                                           *
0008  *                                             *
0009  *                                                                                *
0010  * Description:                                                                   *
0011  *      Multidimensional Likelihood using the "Probability density estimator      *
0012  *      range search" (PDERS) method suggested in                                 *
0013  *      T. Carli and B. Koblitz, NIM A 501, 576 (2003)                            *
0014  *                                                                                *
0015  *      The multidimensional PDFs for signal and background are modeled           *
0016  *      by counting the events in the "vicinity" of a test point. The volume      *
0017  *      that describes "vicinity" is user-defined through the option string.      *
0018  *      A search method based on binary-trees is used to improve the selection    *
0019  *      efficiency of the volume search.                                          *
0020  *                                                                                *
0021  * Authors (alphabetical):                                                        *
0022  *      Andreas Hoecker <Andreas.Hocker@cern.ch> - CERN, Switzerland              *
0023  *      Yair Mahalalel  <Yair.Mahalalel@cern.ch> - CERN, Switzerland              *
0024  *      Peter Speckmayer <peter.speckmayer@cern.ch>  - CERN, Switzerland          *
0025  *      Helge Voss      <Helge.Voss@cern.ch>     - MPI-K Heidelberg, Germany      *
0026  *      Kai Voss        <Kai.Voss@cern.ch>       - U. of Victoria, Canada         *
0027  *                                                                                *
0028  * Copyright (c) 2005:                                                            *
0029  *      CERN, Switzerland                                                         *
0030  *      U. of Victoria, Canada                                                    *
0031  *      MPI-K Heidelberg, Germany                                                 *
0032  *                                                                                *
0033  * Redistribution and use in source and binary forms, with or without             *
0034  * modification, are permitted according to the terms listed in LICENSE           *
0035  * (see tmva/doc/LICENSE)                                          *
0036  **********************************************************************************/
0037
0038 #ifndef ROOT_TMVA_MethodPDERS
0039 #define ROOT_TMVA_MethodPDERS
0040
0041 //////////////////////////////////////////////////////////////////////////
0042 //                                                                      //
0043 // MethodPDERS                                                          //
0044 //                                                                      //
0045 // Multidimensional Likelihood using the "Probability density           //
0046 // estimator range search" (PDERS) method                               //
0047 //                                                                      //
0048 //////////////////////////////////////////////////////////////////////////
0049
0050 #include "TMVA/MethodBase.h"
0051 #include "TMVA/BinarySearchTree.h"
0052 #include "TVector.h"
0053 #include "ThreadLocalStorage.h"
0054 #include <vector>
0055
0056 namespace TMVA {
0057
0058    class Volume;
0059    class Event;
0060
0061    class MethodPDERS : public MethodBase {
0062
0063    public:
0064
0065       MethodPDERS( const TString& jobName,
0066                    const TString& methodTitle,
0067                    DataSetInfo& theData,
0068                    const TString& theOption);
0069
0070       MethodPDERS( DataSetInfo& theData,
0071                    const TString& theWeightFile);
0072
0073       virtual ~MethodPDERS( void );
0074
0075       virtual Bool_t HasAnalysisType( Types::EAnalysisType type, UInt_t numberClasses, UInt_t numberTargets );
0076
0077
0078       // training method
0079       void Train( void );
0080
0081       // write weights to file
0082       void WriteWeightsToStream( TFile& rf ) const;
0083       void AddWeightsXMLTo( void* parent ) const;
0084
0085       // read weights from file
0086       void ReadWeightsFromStream( std::istream& istr );
0087       void ReadWeightsFromStream( TFile& istr );
0088       void ReadWeightsFromXML( void* wghtnode );
0089
0090       // calculate the MVA value
0091       Double_t GetMvaValue( Double_t* err = nullptr, Double_t* errUpper = nullptr );
0092
0093       // calculate the MVA value
0094       const std::vector<Float_t>& GetRegressionValues();
0095    public:
0096
0097       // for root finder
0098       static Double_t IGetVolumeContentForRoot( Double_t );
0099       Double_t         GetVolumeContentForRoot( Double_t );
0100
0101       // static pointer to this object
0102       static MethodPDERS* ThisPDERS( void );
0103
0104    protected:
0105
0106       // make ROOT-independent C++ class for classifier response (classifier-specific implementation)
0107       void MakeClassSpecific( std::ostream&, const TString& ) const;
0108
0109       // get help message text
0110       void GetHelpMessage() const;
0111
0112       Volume*      fHelpVolume; // auxiliary variable
0113       Int_t        fFcnCall;    // number of external function calls (RootFinder)
0114
0115       // accessors
0116       BinarySearchTree* GetBinaryTree( void ) const { return fBinaryTree; }
0117
0118       Double_t             CKernelEstimate( const Event&, std::vector<const BinarySearchTreeNode*>&, Volume& );
0119       void                 RKernelEstimate( const Event&, std::vector<const BinarySearchTreeNode*>&, Volume&, std::vector<Float_t> *pdfSum );
0120
0121       Double_t ApplyKernelFunction( Double_t normalized_distance );
0122       Double_t KernelNormalization( Double_t pdf );
0123       Double_t GetNormalizedDistance( const TMVA::Event &base_event,
0124                                       const BinarySearchTreeNode &sample_event,
0125                                       Double_t *dim_normalization);
0126       Double_t NormSinc( Double_t x );
0127       Double_t LanczosFilter( Int_t level, Double_t x );
0128
0129       // ranking of input variables
0130       const Ranking* CreateRanking() { return nullptr; }
0131
0132    private:
0133
0134       // the option handling methods
0135       void DeclareOptions();
0136       void ProcessOptions();
0137
0138       // calculate the averages of the input variables needed for adaptive training
0139       void CalcAverages();
0140
0141       // create binary search trees for signal and background
0142       void CreateBinarySearchTree( Types::ETreeType type );
0143
0144       // get sample of training events
0145       void GetSample( const Event &e, std::vector<const BinarySearchTreeNode*>& events, Volume *volume);
0146
0147       // option
0148       TString fVolumeRange;    // option volume range
0149       TString fKernelString;   // option kernel estimator
0150
0151       enum EVolumeRangeMode {
0152          kUnsupported = 0,
0153          kMinMax,
0154          kRMS,
0155          kAdaptive,
0156          kUnscaled,
0157          kkNN
0158       } fVRangeMode;
0159
0160       enum EKernelEstimator {
0161          kBox = 0,
0162          kSphere,
0163          kTeepee,
0164          kGauss,
0165          kSinc3,     ///< the sinc enumerators must be consecutive and in order!
0166          kSinc5,
0167          kSinc7,
0168          kSinc9,
0169          kSinc11,
0170          kLanczos2,
0171          kLanczos3,
0172          kLanczos5,
0173          kLanczos8,
0174          kTrim
0175       } fKernelEstimator;
0176
0177       BinarySearchTree*  fBinaryTree;   ///< binary tree
0178
0179       std::vector<Float_t>*   fDelta;         ///< size of volume
0180       std::vector<Float_t>*   fShift;         ///< volume center
0181       std::vector<Float_t>    fAverageRMS;    ///< average RMS of signal and background
0182
0183       Float_t            fScaleS;        ///< weight for signal events
0184       Float_t            fScaleB;        ///< weight for background events
0185       Float_t            fDeltaFrac;     ///< fraction of RMS
0186       Double_t           fGaussSigma;    ///< size of Gauss in adaptive volume
0187       Double_t           fGaussSigmaNorm;///< size of Gauss in adaptive volume (normalised to dimensions)
0188
0189       Double_t           fNRegOut;       // number of output dimensions for regression
0190
0191       // input for adaptive volume adjustment
0192       Float_t            fNEventsMin;    ///< minimum number of events in adaptive volume
0193       Float_t            fNEventsMax;    ///< maximum number of events in adaptive volume
0194       Float_t            fMaxVIterations;///< maximum number of iterations to adapt volume size
0195       Float_t            fInitialScale;  ///< initial scale for adaptive volume
0196
0197       Bool_t             fInitializedVolumeEle; ///< is volume element initialized ?
0198
0199       Int_t              fkNNMin;        ///< min number of events in kNN tree
0200       Int_t              fkNNMax;        ///< max number of events in kNN tree
0201
0202       Double_t           fMax_distance;  ///< maximum distance
0203       Bool_t             fPrinted;       ///< print
0204       Bool_t             fNormTree;      ///< binary-search tree is normalised
0205
0206       void    SetVolumeElement ( void );
0207
0208       Double_t              CRScalc           ( const Event& );
0209       void                  RRScalc           ( const Event&, std::vector<Float_t>* count );
0210
0211       Float_t GetError         ( Float_t countS, Float_t countB,
0212                                  Float_t sumW2S, Float_t sumW2B ) const;
0213
0214       // This is a workaround for OSx where static thread_local data members are
0215       // not supported. The C++ solution would indeed be the following:
0216       static MethodPDERS*& GetMethodPDERSThreadLocal() {TTHREAD_TLS(MethodPDERS*) fgThisPDERS(nullptr); return fgThisPDERS;};
0217       void UpdateThis();
0218
0219       void Init( void );
0220
0221       ClassDef(MethodPDERS,0); // Multi-dimensional probability density estimator range search (PDERS) method
0222    };
0223
0224 } // namespace TMVA
0225
0226 #endif // MethodPDERS_H