ROOT_528-00b_version: tmva/inc/Tools.h Source File

00001 // @(#)root/tmva $Id: Tools.h 37986 2011-02-04 21:42:15Z pcanal $
00002 // Author: Andreas Hoecker, Joerg Stelzer, Helge Voss, Kai Voss
00003 
00004 /**********************************************************************************
00005  * Project: TMVA - a Root-integrated toolkit for multivariate data analysis       *
00006  * Package: TMVA                                                                  *
00007  * Class  : Tools                                                                 *
00008  * Web    : http://tmva.sourceforge.net                                           *
00009  *                                                                                *
00010  * Description:                                                                   *
00011  *      Global auxiliary applications and data treatment routines                 *
00012  *                                                                                *
00013  * Authors (alphabetical):                                                        *
00014  *      Andreas Hoecker <Andreas.Hocker@cern.ch> - CERN, Switzerland              *
00015  *      Helge Voss      <Helge.Voss@cern.ch>     - MPI-K Heidelberg, Germany      *
00016  *      Kai Voss        <Kai.Voss@cern.ch>       - U. of Victoria, Canada         *
00017  *                                                                                *
00018  * Copyright (c) 2005:                                                            *
00019  *      CERN, Switzerland                                                         *
00020  *      U. of Victoria, Canada                                                    *
00021  *      MPI-K Heidelberg, Germany                                                 *
00022  *                                                                                *
00023  * Redistribution and use in source and binary forms, with or without             *
00024  * modification, are permitted according to the terms listed in LICENSE           *
00025  * (http://tmva.sourceforge.net/LICENSE)                                          *
00026  **********************************************************************************/
00027 
00028 #ifndef ROOT_TMVA_Tools
00029 #define ROOT_TMVA_Tools
00030 
00031 //////////////////////////////////////////////////////////////////////////
00032 //                                                                      //
00033 // Tools (namespace)                                                    //
00034 //                                                                      //
00035 // Global auxiliary applications and data treatment routines            //
00036 //                                                                      //
00037 //////////////////////////////////////////////////////////////////////////
00038 
00039 #include <vector>
00040 #include <sstream>
00041 #include <iostream>
00042 #include <iomanip>
00043 
00044 #ifndef ROOT_TXMLEngine
00045 #include "TXMLEngine.h"
00046 #endif
00047 
00048 #ifndef ROOT_TMatrixDSymfwd
00049 #include "TMatrixDSymfwd.h"
00050 #endif
00051 
00052 #ifndef ROOT_TMatrixDfwd
00053 #include "TMatrixDfwd.h"
00054 #endif
00055 
00056 #ifndef ROOT_TVectorDfwd
00057 #include "TVectorDfwd.h"
00058 #endif
00059 
00060 #ifndef ROOT_TVectorDfwd
00061 #include "TVectorDfwd.h"
00062 #endif
00063 
00064 #ifndef ROOT_TMVA_Types
00065 #include "TMVA/Types.h"
00066 #endif
00067 
00068 class TList;
00069 class TTree;
00070 class TString;
00071 class TH1;
00072 class TH2;
00073 class TH2F;
00074 class TSpline;
00075 class TXMLEngine;
00076 
00077 namespace TMVA {
00078 
00079    class Event;
00080    class PDF;
00081    class MsgLogger;
00082 
00083    class Tools {
00084 
00085    private:
00086 
00087       Tools();
00088 
00089    public:
00090 
00091       // destructor
00092       ~Tools();
00093 
00094       // accessor to single instance
00095       static Tools& Instance();
00096       static void   DestroyInstance();
00097 
00098       // simple statistics operations on tree entries
00099       void  ComputeStat( const std::vector<TMVA::Event*>&,
00100                          std::vector<Float_t>*,
00101                          Double_t&, Double_t&, Double_t&,
00102                          Double_t&, Double_t&, Double_t&, Int_t signalClass,
00103                          Bool_t norm = kFALSE );
00104 
00105       // compute variance from sums
00106       inline Double_t ComputeVariance( Double_t sumx2, Double_t sumx, Int_t nx );
00107 
00108       // creates histograms normalized to one
00109       TH1* projNormTH1F( TTree* theTree, const TString& theVarName,
00110                          const TString& name, Int_t nbins,
00111                          Double_t xmin, Double_t xmax, const TString& cut );
00112 
00113       // normalize histogram by its integral
00114       Double_t NormHist( TH1* theHist, Double_t norm = 1.0 );
00115 
00116       // parser for TString phrase with items separated by a character
00117       TList* ParseFormatLine( TString theString, const char * sep = ":" );
00118 
00119       // parse option string for ANN methods
00120       std::vector<Int_t>* ParseANNOptionString( TString theOptions, Int_t nvar,
00121                                                 std::vector<Int_t>* nodes );
00122 
00123       // returns the square-root of a symmetric matrix: symMat = sqrtMat*sqrtMat
00124       TMatrixD* GetSQRootMatrix( TMatrixDSym* symMat );
00125 
00126       // returns the covariance matrix of of the different classes (and the sum) 
00127       // given the event sample
00128       std::vector<TMatrixDSym*>* CalcCovarianceMatrices( const std::vector<Event*>& events, Int_t maxCls );
00129 
00130 
00131       // turns covariance into correlation matrix
00132       const TMatrixD* GetCorrelationMatrix( const TMatrixD* covMat );
00133 
00134       // check spline quality by comparison with initial histogram
00135       Bool_t CheckSplines( const TH1*, const TSpline* );
00136 
00137       // normalization of variable output
00138       Double_t NormVariable( Double_t x, Double_t xmin, Double_t xmax );
00139 
00140       // return separation of two histograms
00141       Double_t GetSeparation( TH1* S, TH1* B ) const;
00142       Double_t GetSeparation( const PDF& pdfS, const PDF& pdfB ) const;
00143 
00144       // vector rescaling
00145       std::vector<Double_t> MVADiff( std::vector<Double_t>&, std::vector<Double_t>& );
00146       void Scale( std::vector<Double_t>&, Double_t );
00147       void Scale( std::vector<Float_t>&,  Float_t  );
00148 
00149       // re-arrange a vector of arrays (vectors) in a way such that the first array
00150       // is ordered, and the other arrays reshuffeld accordingly
00151       void UsefulSortDescending( std::vector< std::vector<Double_t> >&, std::vector<TString>* vs = 0 );
00152       void UsefulSortAscending ( std::vector< std::vector<Double_t> >&, std::vector<TString>* vs = 0 );
00153 
00154       void UsefulSortDescending( std::vector<Double_t>& );
00155       void UsefulSortAscending ( std::vector<Double_t>& );
00156 
00157       Int_t GetIndexMaxElement ( std::vector<Double_t>& );
00158       Int_t GetIndexMinElement ( std::vector<Double_t>& );
00159 
00160       // check if input string contains regular expression
00161       Bool_t  ContainsRegularExpression( const TString& s );
00162       TString ReplaceRegularExpressions( const TString& s, const TString& replace = "+" );
00163 
00164       // routines for formatted output -----------------
00165       void FormattedOutput( const std::vector<Double_t>&, const std::vector<TString>&, 
00166                             const TString titleVars, const TString titleValues, MsgLogger& logger,
00167                             TString format = "%+1.3f" );
00168       void FormattedOutput( const TMatrixD&, const std::vector<TString>&, MsgLogger& logger );
00169       void FormattedOutput( const TMatrixD&, const std::vector<TString>& vert, const std::vector<TString>& horiz, 
00170                             MsgLogger& logger );
00171 
00172       void WriteFloatArbitraryPrecision( Float_t  val, ostream& os );
00173       void ReadFloatArbitraryPrecision ( Float_t& val, istream& is );
00174 
00175       // for histogramming
00176       TString GetXTitleWithUnit( const TString& title, const TString& unit );
00177       TString GetYTitleWithUnit( const TH1& h, const TString& unit, Bool_t normalised );
00178 
00179       // Mutual Information method for non-linear correlations estimates in 2D histogram
00180       // Author: Moritz Backes, Geneva (2009)
00181       Double_t GetMutualInformation( const TH2F& );
00182 
00183       // Correlation Ratio method for non-linear correlations estimates in 2D histogram
00184       // Author: Moritz Backes, Geneva (2009)
00185       Double_t GetCorrelationRatio( const TH2F& );
00186       TH2F*    TransposeHist      ( const TH2F& );
00187 
00188       // check if "silent" or "verbose" option in configuration string
00189       Bool_t CheckForSilentOption ( const TString& ) const;
00190       Bool_t CheckForVerboseOption( const TString& ) const;
00191 
00192       // color information
00193       const TString& Color( const TString& );
00194 
00195       // print welcome message (to be called from, eg, .TMVAlogon)
00196       enum EWelcomeMessage { kStandardWelcomeMsg = 1,
00197                              kIsometricWelcomeMsg,
00198                              kBlockWelcomeMsg,
00199                              kLeanWelcomeMsg,
00200                              kLogoWelcomeMsg,
00201                              kSmall1WelcomeMsg,
00202                              kSmall2WelcomeMsg,
00203                              kOriginalWelcomeMsgColor,
00204                              kOriginalWelcomeMsgBW };
00205 
00206       // print TMVA citation (to be called from, eg, .TMVAlogon)
00207       enum ECitation { kPlainText = 1,
00208                        kBibTeX,
00209                        kLaTeX, 
00210                        kHtmlLink };
00211 
00212       void TMVAWelcomeMessage();
00213       void TMVAWelcomeMessage( MsgLogger& logger, EWelcomeMessage m = kStandardWelcomeMsg );
00214       void TMVAVersionMessage( MsgLogger& logger );
00215       void ROOTVersionMessage( MsgLogger& logger );
00216 
00217       void TMVACitation( MsgLogger& logger, ECitation citType = kPlainText );
00218 
00219       // string tools
00220 
00221       std::vector<TString> SplitString( const TString& theOpt, const char separator ) const;
00222 
00223       // variables
00224       const TString fRegexp;
00225       mutable MsgLogger*    fLogger;
00226       MsgLogger& Log() const { return *fLogger; }
00227       static Tools* fgTools;
00228 
00229       // xml tools
00230 
00231       TString     StringFromInt      ( Long_t i   );
00232       TString     StringFromDouble   ( Double_t d );
00233       void        WriteTMatrixDToXML ( void* node, const char* name, TMatrixD* mat );
00234       void        WriteTVectorDToXML ( void* node, const char* name, TVectorD* vec );
00235       void        ReadTMatrixDFromXML( void* node, const char* name, TMatrixD* mat );
00236       void        ReadTVectorDFromXML( void* node, const char* name, TVectorD* vec );
00237       Bool_t      HistoHasEquidistantBins(const TH1& h);
00238 
00239       Bool_t      HasAttr     ( void* node, const char* attrname );
00240       template<typename T>
00241       inline void ReadAttr    ( void* node, const char* , T& value );
00242       void        ReadAttr    ( void* node, const char* attrname, TString& value );
00243       template<typename T>
00244       void        AddAttr     ( void* node, const char* , const T& value, Int_t precision = 16 );
00245       void        AddAttr     ( void* node, const char* attrname, const char* value );
00246       void*       AddChild    ( void* parent, const char* childname, const char* content = 0, bool isRootNode = false );
00247       Bool_t      AddRawLine  ( void* node, const char * raw );
00248       Bool_t      AddComment  ( void* node, const char* comment );
00249 
00250       void*       GetParent( void* child);
00251       void*       GetChild    ( void* parent, const char* childname=0 );
00252       void*       GetNextChild( void* prevchild, const char* childname=0 );
00253       const char* GetContent  ( void* node );
00254       const char* GetName     ( void* node );
00255 
00256       TXMLEngine& xmlengine() { return *fXMLEngine; }
00257       TXMLEngine* fXMLEngine;
00258 
00259    private:
00260 
00261       // utilities for correlation ratio
00262       Double_t GetYMean_binX( const TH2& , Int_t bin_x );
00263 
00264    }; // Common tools
00265 
00266    Tools& gTools(); // global accessor
00267 
00268 } // namespace TMVA
00269 
00270 //_______________________________________________________________________
00271 template<typename T> void TMVA::Tools::ReadAttr( void* node, const char* attrname, T& value )
00272 {
00273    // read attribute from xml
00274    TString val;
00275    ReadAttr( node, attrname, val );
00276    std::stringstream s(val.Data());
00277    // coverity[tainted_data_argument]
00278    s >> value;
00279 }
00280 
00281 
00282 //_______________________________________________________________________
00283 template<typename T>
00284 void TMVA::Tools::AddAttr( void* node, const char* attrname, const T& value, Int_t precision )
00285 {
00286    // add attribute to xml
00287    std::stringstream s;
00288    s.precision( precision );
00289    s << std::scientific << value;
00290    AddAttr( node, attrname, s.str().c_str() );
00291 }
00292 
00293 //_______________________________________________________________________
00294 inline Double_t TMVA::Tools::ComputeVariance( Double_t sumx2, Double_t sumx, Int_t nx )
00295 {
00296    // compute variance from given sums
00297    if (nx<2) return 0;
00298    return (sumx2 - ((sumx*sumx)/static_cast<Double_t>(nx)))/static_cast<Double_t>(nx-1);
00299 }
00300 
00301 
00302 #endif
00303