ROOT logo
// @(#)root/tmva $Id: MethodCuts.h 40005 2011-06-27 15:29:10Z stelzer $
// Author: Andreas Hoecker, Matt Jachowski, Peter Speckmayer, Helge Voss, Kai Voss

/**********************************************************************************
 * Project: TMVA - a Root-integrated toolkit for multivariate data analysis       *
 * Package: TMVA                                                                  *
 * Class  : MethodCuts                                                            *
 * Web    : http://tmva.sourceforge.net                                           *
 *                                                                                *
 * Description:                                                                   *
 *      Multivariate optimisation of signal efficiency for given background       *
 *      efficiency, using rectangular minimum and maximum requirements on         *
 *      input variables                                                           *
 *                                                                                *
 * Authors (alphabetical):                                                        *
 *      Andreas Hoecker  <Andreas.Hocker@cern.ch> - CERN, Switzerland             *
 *      Matt Jachowski   <jachowski@stanford.edu> - Stanford University, USA      *
 *      Peter Speckmayer <speckmay@mail.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                                                 *
 *      LAPP, Annecy, France                                                      *
 *                                                                                *
 * 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_MethodCuts
#define ROOT_TMVA_MethodCuts

//////////////////////////////////////////////////////////////////////////
//                                                                      //
// MethodCuts                                                           //
//                                                                      //
// Multivariate optimisation of signal efficiency for given background  //
// efficiency, using rectangular minimum and maximum requirements on    //
// input variables                                                      //
//                                                                      //
//////////////////////////////////////////////////////////////////////////

#include <vector>
#include <map>

#ifndef ROOT_TMVA_MethodBase
#include "TMVA/MethodBase.h"
#endif
#ifndef ROOT_TMVA_BinarySearchTree
#include "TMVA/BinarySearchTree.h"
#endif
#ifndef ROOT_TMVA_PDF
#include "TMVA/PDF.h"
#endif
#ifndef ROOT_TMVA_TMatrixDfwd
#ifndef ROOT_TMatrixDfwd
#include "TMatrixDfwd.h"
#endif
#endif
#ifndef ROOT_TMVA_IFitterTarget
#ifndef ROOT_IFitterTarget
#include "IFitterTarget.h"
#endif
#endif

class TRandom;

namespace TMVA {

   class Interval;

   class MethodCuts : public MethodBase, public IFitterTarget {

   public:

      MethodCuts( const TString& jobName,
                  const TString& methodTitle, 
                  DataSetInfo& theData,
                  const TString& theOption = "MC:150:10000:",
                  TDirectory* theTargetFile = 0 );

      MethodCuts( DataSetInfo& theData,
                  const TString& theWeightFile,
                  TDirectory* theTargetDir = NULL );

      // this is a workaround which is necessary since CINT is not capable of handling dynamic casts
      static MethodCuts* DynamicCast( IMethod* method ) { return dynamic_cast<MethodCuts*>(method); }

      virtual ~MethodCuts( void );

      virtual Bool_t HasAnalysisType( Types::EAnalysisType type, UInt_t numberClasses, UInt_t numberTargets );

      // training method
      void Train( void );

      using MethodBase::ReadWeightsFromStream;

      void AddWeightsXMLTo      ( void* parent ) const;

      void ReadWeightsFromStream( std::istream & i );
      void ReadWeightsFromXML   ( void* wghtnode );

      // calculate the MVA value (for CUTs this is just a dummy)
      Double_t GetMvaValue( Double_t* err = 0, Double_t* errUpper = 0 );

      // write method specific histos to target file
      void WriteMonitoringHistosToFile( void ) const;

      // test the method
      void TestClassification();
     
      // also overwrite --> not computed for cuts
      Double_t GetSeparation  ( TH1*, TH1* ) const { return -1; }
      Double_t GetSeparation  ( PDF* = 0, PDF* = 0 ) const { return -1; }
      Double_t GetSignificance( void )       const { return -1; }
      Double_t GetmuTransform ( TTree *)           { return -1; }
      Double_t GetEfficiency  ( const TString&, Types::ETreeType, Double_t& );
      Double_t GetTrainingEfficiency(const TString& );

      // rarity distributions (signal or background (default) is uniform in [0,1])
      Double_t GetRarity( Double_t, Types::ESBType ) const { return 0; }

      // accessors for Minuit
      Double_t ComputeEstimator( std::vector<Double_t> & );
      
      Double_t EstimatorFunction( std::vector<Double_t> & );
      Double_t EstimatorFunction( Int_t ievt1, Int_t ievt2 );

      void     SetTestSignalEfficiency( Double_t effS ) { fTestSignalEff = effS; }

      // retrieve cut values for given signal efficiency
      void     PrintCuts( Double_t effS ) const;
      Double_t GetCuts  ( Double_t effS, std::vector<Double_t>& cutMin, std::vector<Double_t>& cutMax ) const;
      Double_t GetCuts  ( Double_t effS, Double_t* cutMin, Double_t* cutMax ) const;

      // ranking of input variables (not available for cuts)
      const Ranking* CreateRanking() { return 0; }

      void DeclareOptions();
      void ProcessOptions();

      // maximum |cut| value
      static const Double_t fgMaxAbsCutVal;

      // no check of options at this place
      void CheckSetup() {}

   protected:

      // make ROOT-independent C++ class for classifier response (classifier-specific implementation)
      void MakeClassSpecific( std::ostream&, const TString& ) const;

      // get help message text
      void GetHelpMessage() const;

   private:

      // optimisation method
      enum EFitMethodType { kUseMonteCarlo = 0,
                            kUseGeneticAlgorithm,
                            kUseSimulatedAnnealing,
                            kUseMinuit,
                            kUseEventScan,
                            kUseMonteCarloEvents };

      // efficiency calculation method
      // - kUseEventSelection: computes efficiencies from given data sample
      // - kUsePDFs          : creates smoothed PDFs from data samples, and 
      //                       uses this to compute efficiencies
      enum EEffMethod     { kUseEventSelection = 0,
                            kUsePDFs };

      // improve the Monte Carlo by providing some additional information
      enum EFitParameters { kNotEnforced = 0,
                            kForceMin,
                            kForceMax,
                            kForceSmart };

      // general
      TString                 fFitMethodS;         // chosen fit method (string)
      EFitMethodType          fFitMethod;          // chosen fit method
      TString                 fEffMethodS;         // chosen efficiency calculation method (string)
      EEffMethod              fEffMethod;          // chosen efficiency calculation method
      std::vector<EFitParameters>* fFitParams;     // vector for series of fit methods
      Double_t                fTestSignalEff;      // used to test optimized signal efficiency
      Double_t                fEffSMin;            // used to test optimized signal efficiency
      Double_t                fEffSMax;            // used to test optimized signal efficiency
      Double_t*               fCutRangeMin;        // minimum of allowed cut range
      Double_t*               fCutRangeMax;        // maximum of allowed cut range
      std::vector<Interval*>  fCutRange;           // allowed ranges for cut optimisation

      // for the use of the binary tree method
      BinarySearchTree*       fBinaryTreeS;
      BinarySearchTree*       fBinaryTreeB;

      // MC method
      Double_t**              fCutMin;             // minimum requirement
      Double_t**              fCutMax;             // maximum requirement
      Double_t*               fTmpCutMin;          // temporary minimum requirement
      Double_t*               fTmpCutMax;          // temporary maximum requirement
      TString*                fAllVarsI;           // what to do with variables

      // relevant for all methods
      Int_t                   fNpar;               // number of parameters in fit (default: 2*Nvar)
      Double_t                fEffRef;             // reference efficiency
      std::vector<Int_t>*     fRangeSign;          // used to match cuts to fit parameters (and vice versa)
      TRandom*                fRandom;             // random generator for MC optimisation method

      // basic statistics
      std::vector<Double_t>*  fMeanS;              // means of variables (signal)
      std::vector<Double_t>*  fMeanB;              // means of variables (background)
      std::vector<Double_t>*  fRmsS;               // RMSs of variables (signal)
      std::vector<Double_t>*  fRmsB;               // RMSs of variables (background)

      TH1*                    fEffBvsSLocal;       // intermediate eff. background versus eff signal histo

      // PDF section
      std::vector<TH1*>*      fVarHistS;           // reference histograms (signal)
      std::vector<TH1*>*      fVarHistB;           // reference histograms (background)
      std::vector<TH1*>*      fVarHistS_smooth;    // smoothed reference histograms (signal)        
      std::vector<TH1*>*      fVarHistB_smooth;    // smoothed reference histograms (background)
      std::vector<PDF*>*      fVarPdfS;            // reference PDFs (signal)
      std::vector<PDF*>*      fVarPdfB;            // reference PDFs (background)

      // negative efficiencies
      Bool_t                  fNegEffWarning;      // flag risen in case of negative efficiency warning


      // the definition of fit parameters can be different from the actual 
      // cut requirements; these functions provide the matching
      void     MatchParsToCuts( const std::vector<Double_t>&, Double_t*, Double_t* );
      void     MatchParsToCuts( Double_t*, Double_t*, Double_t* );

      void     MatchCutsToPars( std::vector<Double_t>&, Double_t*, Double_t* );
      void     MatchCutsToPars( std::vector<Double_t>&, Double_t**, Double_t**, Int_t ibin );

      // creates PDFs in case these are used to compute efficiencies 
      // (corresponds to: EffMethod == kUsePDFs)
      void     CreateVariablePDFs( void );

      // returns signal and background efficiencies for given cuts - using event counting
      void     GetEffsfromSelection( Double_t* cutMin, Double_t* cutMax,
                                     Double_t& effS, Double_t& effB );
      // returns signal and background efficiencies for given cuts - using PDFs
      void     GetEffsfromPDFs( Double_t* cutMin, Double_t* cutMax,
                                Double_t& effS, Double_t& effB );

      // default initialisation method called by all constructors
      void     Init( void );

      ClassDef(MethodCuts,0)  // Multivariate optimisation of signal efficiency
   };

} // namespace TMVA

#endif
 MethodCuts.h:1
 MethodCuts.h:2
 MethodCuts.h:3
 MethodCuts.h:4
 MethodCuts.h:5
 MethodCuts.h:6
 MethodCuts.h:7
 MethodCuts.h:8
 MethodCuts.h:9
 MethodCuts.h:10
 MethodCuts.h:11
 MethodCuts.h:12
 MethodCuts.h:13
 MethodCuts.h:14
 MethodCuts.h:15
 MethodCuts.h:16
 MethodCuts.h:17
 MethodCuts.h:18
 MethodCuts.h:19
 MethodCuts.h:20
 MethodCuts.h:21
 MethodCuts.h:22
 MethodCuts.h:23
 MethodCuts.h:24
 MethodCuts.h:25
 MethodCuts.h:26
 MethodCuts.h:27
 MethodCuts.h:28
 MethodCuts.h:29
 MethodCuts.h:30
 MethodCuts.h:31
 MethodCuts.h:32
 MethodCuts.h:33
 MethodCuts.h:34
 MethodCuts.h:35
 MethodCuts.h:36
 MethodCuts.h:37
 MethodCuts.h:38
 MethodCuts.h:39
 MethodCuts.h:40
 MethodCuts.h:41
 MethodCuts.h:42
 MethodCuts.h:43
 MethodCuts.h:44
 MethodCuts.h:45
 MethodCuts.h:46
 MethodCuts.h:47
 MethodCuts.h:48
 MethodCuts.h:49
 MethodCuts.h:50
 MethodCuts.h:51
 MethodCuts.h:52
 MethodCuts.h:53
 MethodCuts.h:54
 MethodCuts.h:55
 MethodCuts.h:56
 MethodCuts.h:57
 MethodCuts.h:58
 MethodCuts.h:59
 MethodCuts.h:60
 MethodCuts.h:61
 MethodCuts.h:62
 MethodCuts.h:63
 MethodCuts.h:64
 MethodCuts.h:65
 MethodCuts.h:66
 MethodCuts.h:67
 MethodCuts.h:68
 MethodCuts.h:69
 MethodCuts.h:70
 MethodCuts.h:71
 MethodCuts.h:72
 MethodCuts.h:73
 MethodCuts.h:74
 MethodCuts.h:75
 MethodCuts.h:76
 MethodCuts.h:77
 MethodCuts.h:78
 MethodCuts.h:79
 MethodCuts.h:80
 MethodCuts.h:81
 MethodCuts.h:82
 MethodCuts.h:83
 MethodCuts.h:84
 MethodCuts.h:85
 MethodCuts.h:86
 MethodCuts.h:87
 MethodCuts.h:88
 MethodCuts.h:89
 MethodCuts.h:90
 MethodCuts.h:91
 MethodCuts.h:92
 MethodCuts.h:93
 MethodCuts.h:94
 MethodCuts.h:95
 MethodCuts.h:96
 MethodCuts.h:97
 MethodCuts.h:98
 MethodCuts.h:99
 MethodCuts.h:100
 MethodCuts.h:101
 MethodCuts.h:102
 MethodCuts.h:103
 MethodCuts.h:104
 MethodCuts.h:105
 MethodCuts.h:106
 MethodCuts.h:107
 MethodCuts.h:108
 MethodCuts.h:109
 MethodCuts.h:110
 MethodCuts.h:111
 MethodCuts.h:112
 MethodCuts.h:113
 MethodCuts.h:114
 MethodCuts.h:115
 MethodCuts.h:116
 MethodCuts.h:117
 MethodCuts.h:118
 MethodCuts.h:119
 MethodCuts.h:120
 MethodCuts.h:121
 MethodCuts.h:122
 MethodCuts.h:123
 MethodCuts.h:124
 MethodCuts.h:125
 MethodCuts.h:126
 MethodCuts.h:127
 MethodCuts.h:128
 MethodCuts.h:129
 MethodCuts.h:130
 MethodCuts.h:131
 MethodCuts.h:132
 MethodCuts.h:133
 MethodCuts.h:134
 MethodCuts.h:135
 MethodCuts.h:136
 MethodCuts.h:137
 MethodCuts.h:138
 MethodCuts.h:139
 MethodCuts.h:140
 MethodCuts.h:141
 MethodCuts.h:142
 MethodCuts.h:143
 MethodCuts.h:144
 MethodCuts.h:145
 MethodCuts.h:146
 MethodCuts.h:147
 MethodCuts.h:148
 MethodCuts.h:149
 MethodCuts.h:150
 MethodCuts.h:151
 MethodCuts.h:152
 MethodCuts.h:153
 MethodCuts.h:154
 MethodCuts.h:155
 MethodCuts.h:156
 MethodCuts.h:157
 MethodCuts.h:158
 MethodCuts.h:159
 MethodCuts.h:160
 MethodCuts.h:161
 MethodCuts.h:162
 MethodCuts.h:163
 MethodCuts.h:164
 MethodCuts.h:165
 MethodCuts.h:166
 MethodCuts.h:167
 MethodCuts.h:168
 MethodCuts.h:169
 MethodCuts.h:170
 MethodCuts.h:171
 MethodCuts.h:172
 MethodCuts.h:173
 MethodCuts.h:174
 MethodCuts.h:175
 MethodCuts.h:176
 MethodCuts.h:177
 MethodCuts.h:178
 MethodCuts.h:179
 MethodCuts.h:180
 MethodCuts.h:181
 MethodCuts.h:182
 MethodCuts.h:183
 MethodCuts.h:184
 MethodCuts.h:185
 MethodCuts.h:186
 MethodCuts.h:187
 MethodCuts.h:188
 MethodCuts.h:189
 MethodCuts.h:190
 MethodCuts.h:191
 MethodCuts.h:192
 MethodCuts.h:193
 MethodCuts.h:194
 MethodCuts.h:195
 MethodCuts.h:196
 MethodCuts.h:197
 MethodCuts.h:198
 MethodCuts.h:199
 MethodCuts.h:200
 MethodCuts.h:201
 MethodCuts.h:202
 MethodCuts.h:203
 MethodCuts.h:204
 MethodCuts.h:205
 MethodCuts.h:206
 MethodCuts.h:207
 MethodCuts.h:208
 MethodCuts.h:209
 MethodCuts.h:210
 MethodCuts.h:211
 MethodCuts.h:212
 MethodCuts.h:213
 MethodCuts.h:214
 MethodCuts.h:215
 MethodCuts.h:216
 MethodCuts.h:217
 MethodCuts.h:218
 MethodCuts.h:219
 MethodCuts.h:220
 MethodCuts.h:221
 MethodCuts.h:222
 MethodCuts.h:223
 MethodCuts.h:224
 MethodCuts.h:225
 MethodCuts.h:226
 MethodCuts.h:227
 MethodCuts.h:228
 MethodCuts.h:229
 MethodCuts.h:230
 MethodCuts.h:231
 MethodCuts.h:232
 MethodCuts.h:233
 MethodCuts.h:234
 MethodCuts.h:235
 MethodCuts.h:236
 MethodCuts.h:237
 MethodCuts.h:238
 MethodCuts.h:239
 MethodCuts.h:240
 MethodCuts.h:241
 MethodCuts.h:242
 MethodCuts.h:243
 MethodCuts.h:244
 MethodCuts.h:245
 MethodCuts.h:246
 MethodCuts.h:247
 MethodCuts.h:248
 MethodCuts.h:249
 MethodCuts.h:250
 MethodCuts.h:251
 MethodCuts.h:252
 MethodCuts.h:253
 MethodCuts.h:254
 MethodCuts.h:255
 MethodCuts.h:256
 MethodCuts.h:257
 MethodCuts.h:258
 MethodCuts.h:259