// @(#)root/tmva $Id$
// Author: Andreas Hoecker, Joerg Stelzer, Helge Voss, Kai Voss

/**********************************************************************************
 * Project: TMVA - a Root-integrated toolkit for multivariate data analysis       *
 * Package: TMVA                                                                  *
 * Class  : Tools                                                                 *
 * Web    : http://tmva.sourceforge.net                                           *
 *                                                                                *
 * Description:                                                                   *
 *      Global auxiliary applications and data treatment routines                 *
 *                                                                                *
 * Authors (alphabetical):                                                        *
 *      Andreas Hoecker <Andreas.Hocker@cern.ch> - CERN, Switzerland              *
 *      Peter Speckmayer <peter.speckmayer@cern.ch> - CERN, Switzerland           *
 *      Helge Voss      <Helge.Voss@cern.ch>     - MPI-K Heidelberg, Germany      *
 *      Kai Voss        <Kai.Voss@cern.ch>       - U. of Victoria, Canada         *
 *                                                                                *
 * Copyright (c) 2005:                                                            *
 *      CERN, Switzerland                                                         *
 *      U. of Victoria, Canada                                                    *
 *      MPI-K Heidelberg, Germany                                                 *
 *                                                                                *
 * Redistribution and use in source and binary forms, with or without             *
 * modification, are permitted according to the terms listed in LICENSE           *
 * (http://tmva.sourceforge.net/LICENSE)                                          *
 **********************************************************************************/

#ifndef ROOT_TMVA_Tools
#define ROOT_TMVA_Tools

//////////////////////////////////////////////////////////////////////////
//                                                                      //
// Tools (namespace)                                                    //
//                                                                      //
// Global auxiliary applications and data treatment routines            //
//                                                                      //
//////////////////////////////////////////////////////////////////////////

#include <vector>
#include <sstream>
#include <iostream>
#include <iomanip>
#if __cplusplus > 199711L
#include <atomic>
#endif

#ifndef ROOT_TXMLEngine
#include "TXMLEngine.h"
#endif

#ifndef ROOT_TMatrixDSymfwd
#include "TMatrixDSymfwd.h"
#endif

#ifndef ROOT_TMatrixDfwd
#include "TMatrixDfwd.h"
#endif

#ifndef ROOT_TVectorDfwd
#include "TVectorDfwd.h"
#endif

#ifndef ROOT_TVectorDfwd
#include "TVectorDfwd.h"
#endif

#ifndef ROOT_TMVA_Types
#include "TMVA/Types.h"
#endif

#ifndef ROOT_TMVA_VariableTransformBase
#include "TMVA/VariableTransformBase.h"
#endif

class TList;
class TTree;
class TString;
class TH1;
class TH2;
class TH2F;
class TSpline;
class TXMLEngine;

namespace TMVA {

   class Event;
   class PDF;
   class MsgLogger;

   class Tools {

   private:

      Tools();

   public:

      // destructor
      ~Tools();

      // accessor to single instance
      static Tools& Instance();
      static void   DestroyInstance();


      template <typename T> Double_t Mean(Long64_t n, const T *a, const Double_t *w=0);
      template <typename Iterator, typename WeightIterator> Double_t Mean ( Iterator first, Iterator last, WeightIterator w);
      
      template <typename T> Double_t RMS(Long64_t n, const T *a, const Double_t *w=0);
      template <typename Iterator, typename WeightIterator> Double_t RMS(Iterator first, Iterator last, WeightIterator w);

   
      // simple statistics operations on tree entries
      void  ComputeStat( const std::vector<TMVA::Event*>&,
                         std::vector<Float_t>*,
                         Double_t&, Double_t&, Double_t&,
                         Double_t&, Double_t&, Double_t&, Int_t signalClass,
                         Bool_t norm = kFALSE );

      // compute variance from sums
      inline Double_t ComputeVariance( Double_t sumx2, Double_t sumx, Int_t nx );

      // creates histograms normalized to one
      TH1* projNormTH1F( TTree* theTree, const TString& theVarName,
                         const TString& name, Int_t nbins,
                         Double_t xmin, Double_t xmax, const TString& cut );

      // normalize histogram by its integral
      Double_t NormHist( TH1* theHist, Double_t norm = 1.0 );

      // parser for TString phrase with items separated by a character
      TList* ParseFormatLine( TString theString, const char * sep = ":" );

      // parse option string for ANN methods
      std::vector<Int_t>* ParseANNOptionString( TString theOptions, Int_t nvar,
                                                std::vector<Int_t>* nodes );

      // returns the square-root of a symmetric matrix: symMat = sqrtMat*sqrtMat
      TMatrixD* GetSQRootMatrix( TMatrixDSym* symMat );

      // returns the covariance matrix of of the different classes (and the sum) 
      // given the event sample
      std::vector<TMatrixDSym*>* CalcCovarianceMatrices( const std::vector<Event*>& events, Int_t maxCls, VariableTransformBase* transformBase=0 );
      std::vector<TMatrixDSym*>* CalcCovarianceMatrices( const std::vector<const Event*>& events, Int_t maxCls, VariableTransformBase* transformBase=0 );


      // turns covariance into correlation matrix
      const TMatrixD* GetCorrelationMatrix( const TMatrixD* covMat );

      // check spline quality by comparison with initial histogram
      Bool_t CheckSplines( const TH1*, const TSpline* );

      // normalization of variable output
      Double_t NormVariable( Double_t x, Double_t xmin, Double_t xmax );

      // return separation of two histograms
      Double_t GetSeparation( TH1* S, TH1* B ) const;
      Double_t GetSeparation( const PDF& pdfS, const PDF& pdfB ) const;

      // vector rescaling
      std::vector<Double_t> MVADiff( std::vector<Double_t>&, std::vector<Double_t>& );
      void Scale( std::vector<Double_t>&, Double_t );
      void Scale( std::vector<Float_t>&,  Float_t  );

      // re-arrange a vector of arrays (vectors) in a way such that the first array
      // is ordered, and the other arrays reshuffeld accordingly
      void UsefulSortDescending( std::vector< std::vector<Double_t> >&, std::vector<TString>* vs = 0 );
      void UsefulSortAscending ( std::vector< std::vector<Double_t> >&, std::vector<TString>* vs = 0 );

      void UsefulSortDescending( std::vector<Double_t>& );
      void UsefulSortAscending ( std::vector<Double_t>& );

      Int_t GetIndexMaxElement ( std::vector<Double_t>& );
      Int_t GetIndexMinElement ( std::vector<Double_t>& );

      // check if input string contains regular expression
      Bool_t  ContainsRegularExpression( const TString& s );
      TString ReplaceRegularExpressions( const TString& s, const TString& replace = "+" );

      // routines for formatted output -----------------
      void FormattedOutput( const std::vector<Double_t>&, const std::vector<TString>&, 
                            const TString titleVars, const TString titleValues, MsgLogger& logger,
                            TString format = "%+1.3f" );
      void FormattedOutput( const TMatrixD&, const std::vector<TString>&, MsgLogger& logger );
      void FormattedOutput( const TMatrixD&, const std::vector<TString>& vert, const std::vector<TString>& horiz, 
                            MsgLogger& logger );

      void WriteFloatArbitraryPrecision( Float_t  val, std::ostream& os );
      void ReadFloatArbitraryPrecision ( Float_t& val, std::istream& is );

      // for histogramming
      TString GetXTitleWithUnit( const TString& title, const TString& unit );
      TString GetYTitleWithUnit( const TH1& h, const TString& unit, Bool_t normalised );

      // Mutual Information method for non-linear correlations estimates in 2D histogram
      // Author: Moritz Backes, Geneva (2009)
      Double_t GetMutualInformation( const TH2F& );

      // Correlation Ratio method for non-linear correlations estimates in 2D histogram
      // Author: Moritz Backes, Geneva (2009)
      Double_t GetCorrelationRatio( const TH2F& );
      TH2F*    TransposeHist      ( const TH2F& );

      // check if "silent" or "verbose" option in configuration string
      Bool_t CheckForSilentOption ( const TString& ) const;
      Bool_t CheckForVerboseOption( const TString& ) const;

      // color information
      const TString& Color( const TString& );

      // print welcome message (to be called from, eg, .TMVAlogon)
      enum EWelcomeMessage { kStandardWelcomeMsg = 1,
                             kIsometricWelcomeMsg,
                             kBlockWelcomeMsg,
                             kLeanWelcomeMsg,
                             kLogoWelcomeMsg,
                             kSmall1WelcomeMsg,
                             kSmall2WelcomeMsg,
                             kOriginalWelcomeMsgColor,
                             kOriginalWelcomeMsgBW };

      // print TMVA citation (to be called from, eg, .TMVAlogon)
      enum ECitation { kPlainText = 1,
                       kBibTeX,
                       kLaTeX, 
                       kHtmlLink };

      void TMVAWelcomeMessage();
      void TMVAWelcomeMessage( MsgLogger& logger, EWelcomeMessage m = kStandardWelcomeMsg );
      void TMVAVersionMessage( MsgLogger& logger );
      void ROOTVersionMessage( MsgLogger& logger );

      void TMVACitation( MsgLogger& logger, ECitation citType = kPlainText );

      // string tools

      std::vector<TString> SplitString( const TString& theOpt, const char separator ) const;

      // variables
      const TString fRegexp;
      mutable MsgLogger*    fLogger;
      MsgLogger& Log() const { return *fLogger; }
#if __cplusplus > 199711L
      static std::atomic<Tools*> fgTools;
#else
      static Tools* fgTools;
#endif

      // xml tools

      TString     StringFromInt      ( Long_t i   );
      TString     StringFromDouble   ( Double_t d );
      void        WriteTMatrixDToXML ( void* node, const char* name, TMatrixD* mat );
      void        WriteTVectorDToXML ( void* node, const char* name, TVectorD* vec );
      void        ReadTMatrixDFromXML( void* node, const char* name, TMatrixD* mat );
      void        ReadTVectorDFromXML( void* node, const char* name, TVectorD* vec );
      Bool_t      HistoHasEquidistantBins(const TH1& h);

      Bool_t      HasAttr     ( void* node, const char* attrname );
      template<typename T>
      inline void ReadAttr    ( void* node, const char* , T& value );
      void        ReadAttr    ( void* node, const char* attrname, TString& value );
      template<typename T>
      void        AddAttr     ( void* node, const char* , const T& value, Int_t precision = 16 );
      void        AddAttr     ( void* node, const char* attrname, const char* value );
      void*       AddChild    ( void* parent, const char* childname, const char* content = 0, bool isRootNode = false );
      Bool_t      AddRawLine  ( void* node, const char * raw );
      Bool_t      AddComment  ( void* node, const char* comment );

      void*       GetParent( void* child);
      void*       GetChild    ( void* parent, const char* childname=0 );
      void*       GetNextChild( void* prevchild, const char* childname=0 );
      const char* GetContent  ( void* node );
      const char* GetName     ( void* node );

      TXMLEngine& xmlengine() { return *fXMLEngine; }
      int xmlenginebuffersize() { return 10000000; }
      TXMLEngine* fXMLEngine;

      TH1*       GetCumulativeDist( TH1* h);

   private:

      // utilities for correlation ratio
      Double_t GetYMean_binX( const TH2& , Int_t bin_x );

   }; // Common tools

   Tools& gTools(); // global accessor

} // namespace TMVA

//_______________________________________________________________________
template<typename T> void TMVA::Tools::ReadAttr( void* node, const char* attrname, T& value )
{
   // read attribute from xml
   TString val;
   ReadAttr( node, attrname, val );
   std::stringstream s(val.Data());
   // coverity[tainted_data_argument]
   s >> value;
}


//_______________________________________________________________________
template<typename T>
void TMVA::Tools::AddAttr( void* node, const char* attrname, const T& value, Int_t precision )
{
   // add attribute to xml
   std::stringstream s;
   s.precision( precision );
   s << std::scientific << value;
   AddAttr( node, attrname, s.str().c_str() );
}

//_______________________________________________________________________
inline Double_t TMVA::Tools::ComputeVariance( Double_t sumx2, Double_t sumx, Int_t nx )
{
   // compute variance from given sums
   if (nx<2) return 0;
   return (sumx2 - ((sumx*sumx)/static_cast<Double_t>(nx)))/static_cast<Double_t>(nx-1);
}


  
#endif

 Tools.h:1
 Tools.h:2
 Tools.h:3
 Tools.h:4
 Tools.h:5
 Tools.h:6
 Tools.h:7
 Tools.h:8
 Tools.h:9
 Tools.h:10
 Tools.h:11
 Tools.h:12
 Tools.h:13
 Tools.h:14
 Tools.h:15
 Tools.h:16
 Tools.h:17
 Tools.h:18
 Tools.h:19
 Tools.h:20
 Tools.h:21
 Tools.h:22
 Tools.h:23
 Tools.h:24
 Tools.h:25
 Tools.h:26
 Tools.h:27
 Tools.h:28
 Tools.h:29
 Tools.h:30
 Tools.h:31
 Tools.h:32
 Tools.h:33
 Tools.h:34
 Tools.h:35
 Tools.h:36
 Tools.h:37
 Tools.h:38
 Tools.h:39
 Tools.h:40
 Tools.h:41
 Tools.h:42
 Tools.h:43
 Tools.h:44
 Tools.h:45
 Tools.h:46
 Tools.h:47
 Tools.h:48
 Tools.h:49
 Tools.h:50
 Tools.h:51
 Tools.h:52
 Tools.h:53
 Tools.h:54
 Tools.h:55
 Tools.h:56
 Tools.h:57
 Tools.h:58
 Tools.h:59
 Tools.h:60
 Tools.h:61
 Tools.h:62
 Tools.h:63
 Tools.h:64
 Tools.h:65
 Tools.h:66
 Tools.h:67
 Tools.h:68
 Tools.h:69
 Tools.h:70
 Tools.h:71
 Tools.h:72
 Tools.h:73
 Tools.h:74
 Tools.h:75
 Tools.h:76
 Tools.h:77
 Tools.h:78
 Tools.h:79
 Tools.h:80
 Tools.h:81
 Tools.h:82
 Tools.h:83
 Tools.h:84
 Tools.h:85
 Tools.h:86
 Tools.h:87
 Tools.h:88
 Tools.h:89
 Tools.h:90
 Tools.h:91
 Tools.h:92
 Tools.h:93
 Tools.h:94
 Tools.h:95
 Tools.h:96
 Tools.h:97
 Tools.h:98
 Tools.h:99
 Tools.h:100
 Tools.h:101
 Tools.h:102
 Tools.h:103
 Tools.h:104
 Tools.h:105
 Tools.h:106
 Tools.h:107
 Tools.h:108
 Tools.h:109
 Tools.h:110
 Tools.h:111
 Tools.h:112
 Tools.h:113
 Tools.h:114
 Tools.h:115
 Tools.h:116
 Tools.h:117
 Tools.h:118
 Tools.h:119
 Tools.h:120
 Tools.h:121
 Tools.h:122
 Tools.h:123
 Tools.h:124
 Tools.h:125
 Tools.h:126
 Tools.h:127
 Tools.h:128
 Tools.h:129
 Tools.h:130
 Tools.h:131
 Tools.h:132
 Tools.h:133
 Tools.h:134
 Tools.h:135
 Tools.h:136
 Tools.h:137
 Tools.h:138
 Tools.h:139
 Tools.h:140
 Tools.h:141
 Tools.h:142
 Tools.h:143
 Tools.h:144
 Tools.h:145
 Tools.h:146
 Tools.h:147
 Tools.h:148
 Tools.h:149
 Tools.h:150
 Tools.h:151
 Tools.h:152
 Tools.h:153
 Tools.h:154
 Tools.h:155
 Tools.h:156
 Tools.h:157
 Tools.h:158
 Tools.h:159
 Tools.h:160
 Tools.h:161
 Tools.h:162
 Tools.h:163
 Tools.h:164
 Tools.h:165
 Tools.h:166
 Tools.h:167
 Tools.h:168
 Tools.h:169
 Tools.h:170
 Tools.h:171
 Tools.h:172
 Tools.h:173
 Tools.h:174
 Tools.h:175
 Tools.h:176
 Tools.h:177
 Tools.h:178
 Tools.h:179
 Tools.h:180
 Tools.h:181
 Tools.h:182
 Tools.h:183
 Tools.h:184
 Tools.h:185
 Tools.h:186
 Tools.h:187
 Tools.h:188
 Tools.h:189
 Tools.h:190
 Tools.h:191
 Tools.h:192
 Tools.h:193
 Tools.h:194
 Tools.h:195
 Tools.h:196
 Tools.h:197
 Tools.h:198
 Tools.h:199
 Tools.h:200
 Tools.h:201
 Tools.h:202
 Tools.h:203
 Tools.h:204
 Tools.h:205
 Tools.h:206
 Tools.h:207
 Tools.h:208
 Tools.h:209
 Tools.h:210
 Tools.h:211
 Tools.h:212
 Tools.h:213
 Tools.h:214
 Tools.h:215
 Tools.h:216
 Tools.h:217
 Tools.h:218
 Tools.h:219
 Tools.h:220
 Tools.h:221
 Tools.h:222
 Tools.h:223
 Tools.h:224
 Tools.h:225
 Tools.h:226
 Tools.h:227
 Tools.h:228
 Tools.h:229
 Tools.h:230
 Tools.h:231
 Tools.h:232
 Tools.h:233
 Tools.h:234
 Tools.h:235
 Tools.h:236
 Tools.h:237
 Tools.h:238
 Tools.h:239
 Tools.h:240
 Tools.h:241
 Tools.h:242
 Tools.h:243
 Tools.h:244
 Tools.h:245
 Tools.h:246
 Tools.h:247
 Tools.h:248
 Tools.h:249
 Tools.h:250
 Tools.h:251
 Tools.h:252
 Tools.h:253
 Tools.h:254
 Tools.h:255
 Tools.h:256
 Tools.h:257
 Tools.h:258
 Tools.h:259
 Tools.h:260
 Tools.h:261
 Tools.h:262
 Tools.h:263
 Tools.h:264
 Tools.h:265
 Tools.h:266
 Tools.h:267
 Tools.h:268
 Tools.h:269
 Tools.h:270
 Tools.h:271
 Tools.h:272
 Tools.h:273
 Tools.h:274
 Tools.h:275
 Tools.h:276
 Tools.h:277
 Tools.h:278
 Tools.h:279
 Tools.h:280
 Tools.h:281
 Tools.h:282
 Tools.h:283
 Tools.h:284
 Tools.h:285
 Tools.h:286
 Tools.h:287
 Tools.h:288
 Tools.h:289
 Tools.h:290
 Tools.h:291
 Tools.h:292
 Tools.h:293
 Tools.h:294
 Tools.h:295
 Tools.h:296
 Tools.h:297
 Tools.h:298
 Tools.h:299
 Tools.h:300
 Tools.h:301
 Tools.h:302
 Tools.h:303
 Tools.h:304
 Tools.h:305
 Tools.h:306
 Tools.h:307
 Tools.h:308
 Tools.h:309
 Tools.h:310
 Tools.h:311
 Tools.h:312
 Tools.h:313
 Tools.h:314
 Tools.h:315
 Tools.h:316
 Tools.h:317
 Tools.h:318
 Tools.h:319
 Tools.h:320
 Tools.h:321
 Tools.h:322
 Tools.h:323
 Tools.h:324
 Tools.h:325
 Tools.h:326
 Tools.h:327
 Tools.h:328