root/TMVA/Reader.h

0001 // @(#)root/tmva $Id$
0002 // Author: Andreas Hoecker, Peter Speckmayer, Joerg Stelzer, Helge Voss, Kai Voss, Eckhard von Toerne, Jan Therhaag
0003
0004 /**********************************************************************************
0005  * Project: TMVA - a Root-integrated toolkit for multivariate data analysis       *
0006  * Package: TMVA                                                                  *
0007  * Class  : Reader                                                                *
0008  *                                             *
0009  *                                                                                *
0010  * Description:                                                                   *
0011  *      Reader class to be used in the user application to interpret the trained  *
0012  *      MVAs in an analysis context                                               *
0013  *                                                                                *
0014  * Authors (alphabetical order):                                                  *
0015  *      Andreas Hoecker <Andreas.Hocker@cern.ch> - CERN, Switzerland              *
0016  *      Peter Speckmayer <peter.speckmayer@cern.ch> - CERN, Switzerland           *
0017  *      Joerg Stelzer <Joerg.Stelzer@cern.ch>    - CERN, Switzerland              *
0018  *      Jan Therhaag       <Jan.Therhaag@cern.ch>     - U of Bonn, Germany        *
0019  *      Eckhard v. Toerne  <evt@uni-bonn.de>          - U of Bonn, Germany        *
0020  *      Helge Voss      <Helge.Voss@cern.ch>     - MPI-K Heidelberg, Germany      *
0021  *      Kai Voss        <Kai.Voss@cern.ch>       - U. of Victoria, Canada         *
0022  *                                                                                *
0023  * Copyright (c) 2005-2011:                                                       *
0024  *      CERN, Switzerland                                                         *
0025  *      U. of Victoria, Canada                                                    *
0026  *      MPI-K Heidelberg, Germany                                                 *
0027  *      U. of Bonn, Germany                                                       *
0028  *                                                                                *
0029  * Redistribution and use in source and binary forms, with or without             *
0030  * modification, are permitted according to the terms listed in LICENSE           *
0031  * (see tmva/doc/LICENSE)                                          *
0032  **********************************************************************************/
0033
0034 #ifndef ROOT_TMVA_Reader
0035 #define ROOT_TMVA_Reader
0036
0037 //////////////////////////////////////////////////////////////////////////
0038 //                                                                      //
0039 // Reader                                                               //
0040 //                                                                      //
0041 // Reader class to be used in the user application to interpret the     //
0042 // trained MVAs in an analysis context                                  //
0043 //                                                                      //
0044 //////////////////////////////////////////////////////////////////////////
0045
0046 #include "TMVA/Configurable.h"
0047 #include "TMVA/Types.h"
0048 #include "TMVA/DataSetInfo.h"
0049 #include "TMVA/DataInputHandler.h"
0050 #include "TMVA/DataSetManager.h"
0051
0052 #include <vector>
0053 #include <map>
0054 #include <stdexcept>
0055 #include <string>
0056
0057 namespace TMVA {
0058
0059    class IMethod;
0060    class MethodBase;
0061    class DataSetInfo;
0062    class MethodCuts;
0063
0064    class Reader : public Configurable {
0065
0066    public:
0067
0068       // without prior specification of variables
0069       Reader( const TString& theOption="", Bool_t verbose = 0 );
0070
0071       // STL types
0072       Reader( std::vector<std::string>& varNames, const TString& theOption = "", Bool_t verbose = 0 );
0073       Reader( const std::string& varNames, const TString& theOption, Bool_t verbose = 0 );  // format: "var1:var2:..."
0074
0075       // Root types
0076       Reader( std::vector<TString>& varNames, const TString& theOption = "", Bool_t verbose = 0 );
0077       Reader( const TString& varNames, const TString& theOption, Bool_t verbose = 0 );  // format: "var1:var2:..."
0078
0079       virtual ~Reader( void );
0080
0081       // book MVA method via weight file
0082       IMethod* BookMVA( const TString& methodTag, const TString& weightfile );
0083       IMethod* BookMVA( TMVA::Types::EMVA methodType, const char* xmlstr );
0084       IMethod* FindMVA( const TString& methodTag );
0085
0086       // returns the MVA response for given event
0087       Double_t EvaluateMVA( const std::vector<Float_t> &, const TString& methodTag, Double_t aux = 0 );
0088       Double_t EvaluateMVA( const std::vector<Double_t>&, const TString& methodTag, Double_t aux = 0 );
0089       Double_t EvaluateMVA( MethodBase* method,           Double_t aux = 0 );
0090       Double_t EvaluateMVA( const TString& methodTag,     Double_t aux = 0 );
0091
0092       // returns error on MVA response for given event
0093       // NOTE: must be called AFTER "EvaluateMVA(...)" call !
0094       Double_t GetMVAError() const { return fMvaEventError; }
0095       Double_t GetMVAErrorLower() const { return fMvaEventError; }
0096       Double_t GetMVAErrorUpper() const { return fMvaEventErrorUpper; }
0097
0098       // regression response
0099       const std::vector< Float_t >& EvaluateRegression( const TString& methodTag, Double_t aux = 0 );
0100       const std::vector< Float_t >& EvaluateRegression( MethodBase* method, Double_t aux = 0 );
0101       Float_t  EvaluateRegression( UInt_t tgtNumber, const TString& methodTag, Double_t aux = 0 );
0102
0103       // multiclass response
0104       const std::vector< Float_t >& EvaluateMulticlass( const TString& methodTag, Double_t aux = 0 );
0105       const std::vector< Float_t >& EvaluateMulticlass( MethodBase* method, Double_t aux = 0 );
0106       Float_t  EvaluateMulticlass( UInt_t clsNumber, const TString& methodTag, Double_t aux = 0 );
0107
0108       // probability and rarity accessors (see Users Guide for definition of Rarity)
0109       Double_t GetProba ( const TString& methodTag, Double_t ap_sig=0.5, Double_t mvaVal=-9999999 );
0110       Double_t GetRarity( const TString& methodTag, Double_t mvaVal=-9999999 );
0111
0112       // accessors
0113       virtual const char* GetName() const { return "Reader"; }
0114       Bool_t   Verbose( void ) const  { return fVerbose; }
0115       void     SetVerbose( Bool_t v ) { fVerbose = v; }
0116
0117       const DataSetInfo& DataInfo() const { return fDataSetInfo; }
0118       DataSetInfo&       DataInfo()       { return fDataSetInfo; }
0119
0120       void     AddVariable( const TString& expression, Float_t* );
0121       void     AddVariable( const TString& expression, Int_t* );
0122
0123       void     AddSpectator( const TString& expression, Float_t* );
0124       void     AddSpectator( const TString& expression, Int_t* );
0125
0126    private:
0127
0128       DataSetManager* fDataSetManager; // DSMTEST
0129
0130
0131       TString GetMethodTypeFromFile( const TString& filename );
0132
0133       // this booking method is internal
0134       IMethod* BookMVA( Types::EMVA method,  const TString& weightfile );
0135
0136       DataSetInfo fDataSetInfo; // the data set
0137
0138       DataInputHandler fDataInputHandler;
0139
0140       // Init Reader class
0141       void Init( void );
0142
0143       // Decode Constructor string (or TString) and fill variable name std::vector
0144       void DecodeVarNames( const std::string& varNames );
0145       void DecodeVarNames( const TString& varNames );
0146
0147       void DeclareOptions();
0148
0149       Bool_t    fVerbose;            ///< verbosity
0150       Bool_t    fSilent;             ///< silent mode
0151       Bool_t    fColor;              ///< color mode
0152       Bool_t    fCalculateError;     ///< error calculation mode
0153
0154       Double_t  fMvaEventError;      ///< per-event error returned by MVA
0155       Double_t  fMvaEventErrorUpper; ///< per-event error returned by MVA
0156
0157       std::map<TString, IMethod*> fMethodMap; ///< map of methods
0158
0159       std::vector<Float_t> fTmpEvalVec; ///< temporary evaluation vector (if user input is v<double>)
0160
0161       mutable MsgLogger* fLogger;   ///<! message logger
0162       MsgLogger& Log() const { return *fLogger; }
0163
0164       ClassDef(Reader,0); // Interpret the trained MVAs in an analysis context
0165    };
0166
0167 }
0168
0169 #endif