root/TMVA/IPruneTool.h

0001 /**********************************************************************************
0002  * Project: TMVA - a Root-integrated toolkit for multivariate data analysis       *
0003  * Package: TMVA                                                                  *
0004  * Class  : TMVA::DecisionTree                                                    *
0005  *                                             *
0006  *                                                                                *
0007  * Description:                                                                   *
0008  *      IPruneTool - a helper interface class to prune a decision tree            *
0009  *                                                                                *
0010  * Authors (alphabetical):                                                        *
0011  *      Doug Schouten <dschoute@sfu.ca> - Simon Fraser U., Canada                 *
0012  *                                                                                *
0013  * Copyright (c) 2005:                                                            *
0014  *      CERN, Switzerland                                                         *
0015  *      MPI-K Heidelberg, Germany                                                 *
0016  *                                                                                *
0017  * Redistribution and use in source and binary forms, with or without             *
0018  * modification, are permitted according to the terms listed in LICENSE           *
0019  * (http://mva.sourceforge.net/license.txt)                                       *
0020  **********************************************************************************/
0021
0022 #ifndef ROOT_TMVA_IPruneTool
0023 #define ROOT_TMVA_IPruneTool
0024
0025 #include <iosfwd>
0026 #include <vector>
0027
0028 #include "TMVA/SeparationBase.h"
0029
0030 #include "TMVA/DecisionTree.h"
0031
0032 namespace TMVA {
0033
0034    //    class MsgLogger;
0035
0036    ////////////////////////////////////////////////////////////
0037    // Basic struct for saving relevant pruning information   //
0038    ////////////////////////////////////////////////////////////
0039    class PruningInfo {
0040
0041    public:
0042
0043    PruningInfo( ) : QualityIndex(0), PruneStrength(0), PruneSequence(0) {}
0044       PruningInfo( Double_t q, Double_t alpha, std::vector<DecisionTreeNode*> sequence );
0045       Double_t QualityIndex; //! quality measure for a pruned subtree T of T_max
0046       Double_t PruneStrength; //! the regularization parameter for pruning
0047       std::vector<DecisionTreeNode*> PruneSequence; //! the sequence of pruning locations in T_max that yields T
0048    };
0049
0050    inline PruningInfo::PruningInfo( Double_t q, Double_t alpha, std::vector<DecisionTreeNode*> sequence )
0051       : QualityIndex(q), PruneStrength(alpha), PruneSequence(sequence) {}
0052
0053 /*! \class TMVA::IPruneTool
0054 \ingroup TMVA
0055 IPruneTool - a helper interface class to prune a decision tree
0056
0057 Any tool which implements the interface should provide two modes for tree pruning:
0058
0059   1. automatically find the "best" prune strength by minimizing the error rate on a test sample
0060      if SetAutomatic() is called, or if automatic = kTRUE argument is set in CalculatePruningInfo()
0061      In this case, the PruningInfo object returned contains the error rate of the optimally pruned
0062      tree, the optimal prune strength, and the sequence of nodes to prune to obtain the optimal
0063      pruned tree from the original DecisionTree
0064
0065   2. a user-provided pruning strength parameter is used to prune the tree, in which case the returned
0066      PruningInfo object has QualityIndex = -1, PruneStrength = user prune strength, and PruneSequence
0067      is the list of nodes to prune
0068 */
0069
0070    class IPruneTool {
0071
0072    public:
0073
0074       typedef std::vector<const Event*> EventSample;
0075
0076       IPruneTool( );
0077       virtual ~IPruneTool();
0078
0079    public:
0080
0081       // returns the PruningInfo object for a given tree and test sample
0082       virtual PruningInfo* CalculatePruningInfo( DecisionTree* dt, const EventSample* testEvents = nullptr,
0083                                                  Bool_t isAutomatic = kFALSE ) = 0;
0084
0085    public:
0086
0087       // set the prune strength parameter to use in pruning
0088       inline void SetPruneStrength( Double_t alpha ) { fPruneStrength = alpha; }
0089       // return the prune strength the tool is using
0090       inline Double_t GetPruneStrength( ) const { return fPruneStrength; }
0091
0092       // if the prune strength parameter is < 0, the tool will automatically find an optimal strength
0093       // set the tool to automatic mode
0094       inline void SetAutomatic( ) { fPruneStrength = -1.0; };
0095       inline Bool_t IsAutomatic( ) const { return fPruneStrength <= 0.0; }
0096
0097    protected:
0098
0099       //       mutable MsgLogger* fLogger; ///<! output stream to save logging information
0100       //       MsgLogger& Log() const { return *fLogger; }
0101       Double_t fPruneStrength; ///<! regularization parameter in pruning
0102
0103
0104       Double_t S, B;
0105    };
0106
0107    inline IPruneTool::IPruneTool( ) :
0108       fPruneStrength(0.0),
0109       S(0),
0110       B(0)
0111          {}
0112 }
0113
0114 #endif