root/TMVA/MethodANNBase.h

0001 // @(#)root/tmva $Id$
0002 // Author: Andreas Hoecker, Peter Speckmayer, Matt Jachowski, Jan Therhaag
0003
0004 /**********************************************************************************
0005  * Project: TMVA - a Root-integrated toolkit for multivariate data analysis       *
0006  * Package: TMVA                                                                  *
0007  * Class  : MethodANNBase                                                         *
0008  *                                             *
0009  *                                                                                *
0010  * Description:                                                                   *
0011  *      Artificial neural network base class for the discrimination of signal     *
0012  *      from background.                                                          *
0013  *                                                                                *
0014  * Authors (alphabetical):                                                        *
0015  *      Andreas Hoecker  <Andreas.Hocker@cern.ch> - CERN, Switzerland             *
0016  *      Matt Jachowski   <jachowski@stanford.edu> - Stanford University, USA      *
0017  *      Peter Speckmayer <Peter.Speckmayer@cern.ch>  - CERN, Switzerland          *
0018  *      Joerg Stelzer   <Joerg.Stelzer@cern.ch>   - CERN, Switzerland             *
0019  *      Jan Therhaag       <Jan.Therhaag@cern.ch>     - U of Bonn, Germany        *
0020  *                                                                                *
0021  * Small changes (regression):                                                    *
0022  *      Krzysztof Danielowski <danielow@cern.ch>  - IFJ PAN & AGH, Poland         *
0023  *      Kamil Kraszewski      <kalq@cern.ch>      - IFJ PAN & UJ , Poland         *
0024  *      Maciej Kruk           <mkruk@cern.ch>     - IFJ PAN & AGH, Poland         *
0025  *                                                                                *
0026  * Copyright (c) 2005-2011:                                                       *
0027  *      CERN, Switzerland                                                         *
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_MethodANNBase
0035 #define ROOT_TMVA_MethodANNBase
0036
0037 //////////////////////////////////////////////////////////////////////////
0038 //                                                                      //
0039 // MethodANNBase                                                        //
0040 //                                                                      //
0041 // Base class for all TMVA methods using artificial neural networks     //
0042 //                                                                      //
0043 //////////////////////////////////////////////////////////////////////////
0044
0045 #include "TString.h"
0046 #include <vector>
0047 #include "TTree.h"
0048 #include "TObjArray.h"
0049 #include "TRandom3.h"
0050 #include "TMatrix.h"
0051
0052 #include "TMVA/MethodBase.h"
0053 #include "TMVA/TActivation.h"
0054 #include "TMVA/TNeuron.h"
0055 #include "TMVA/TNeuronInput.h"
0056
0057 class TH1;
0058 class TH1F;
0059
0060 namespace TMVA {
0061
0062    class MethodANNBase : public MethodBase {
0063
0064    public:
0065
0066       // constructors dictated by subclassing off of MethodBase
0067       MethodANNBase( const TString& jobName,
0068                      Types::EMVA methodType,
0069                      const TString& methodTitle,
0070                      DataSetInfo& theData,
0071                      const TString& theOption );
0072
0073       MethodANNBase( Types::EMVA methodType,
0074                      DataSetInfo& theData,
0075                      const TString& theWeightFile);
0076
0077       virtual ~MethodANNBase();
0078
0079       // this does the real initialization work
0080       void InitANNBase();
0081
0082       // setters for subclasses
0083       void SetActivation(TActivation* activation) {
0084          if (fActivation != nullptr) delete fActivation;
0085          fActivation = activation;
0086       }
0087       void SetNeuronInputCalculator(TNeuronInput* inputCalculator) {
0088          if (fInputCalculator != nullptr) delete fInputCalculator;
0089          fInputCalculator = inputCalculator;
0090       }
0091
0092       // this will have to be overridden by every subclass
0093       virtual void Train() = 0;
0094
0095       // print network, for debugging
0096       virtual void PrintNetwork() const;
0097
0098
0099       // call this function like that:
0100       // ...
0101       // MethodMLP* mlp = dynamic_cast<MethodMLP*>(method);
0102       // std::vector<float> layerValues;
0103       // mlp->GetLayerActivation (2, std::back_inserter(layerValues));
0104       // ... do now something with the layerValues
0105       //
0106       template <typename WriteIterator>
0107          void GetLayerActivation (size_t layer, WriteIterator writeIterator);
0108
0109       using MethodBase::ReadWeightsFromStream;
0110
0111       // write weights to file
0112       void AddWeightsXMLTo( void* parent ) const;
0113       void ReadWeightsFromXML( void* wghtnode );
0114
0115       // read weights from file
0116       virtual void ReadWeightsFromStream( std::istream& istr );
0117
0118       // calculate the MVA value
0119       virtual Double_t GetMvaValue( Double_t* err = nullptr, Double_t* errUpper = nullptr );
0120
0121       virtual const std::vector<Float_t> &GetRegressionValues();
0122
0123       virtual const std::vector<Float_t> &GetMulticlassValues();
0124
0125       // write method specific histos to target file
0126       virtual void WriteMonitoringHistosToFile() const;
0127
0128       // ranking of input variables
0129       const Ranking* CreateRanking();
0130
0131       // the option handling methods
0132       virtual void DeclareOptions();
0133       virtual void ProcessOptions();
0134
0135       Bool_t Debug() const;
0136
0137       enum EEstimator      { kMSE=0,kCE};
0138
0139       TObjArray*    fNetwork;         // TObjArray of TObjArrays representing network
0140
0141    protected:
0142
0143       virtual void MakeClassSpecific( std::ostream&, const TString& ) const;
0144
0145       std::vector<Int_t>* ParseLayoutString( TString layerSpec );
0146       virtual void        BuildNetwork( std::vector<Int_t>* layout, std::vector<Double_t>* weights = nullptr,
0147                                         Bool_t fromFile = kFALSE );
0148       void     ForceNetworkInputs( const Event* ev, Int_t ignoreIndex = -1 );
0149       Double_t GetNetworkOutput() { return GetOutputNeuron()->GetActivationValue(); }
0150
0151       // debugging utilities
0152       void     PrintMessage( TString message, Bool_t force = kFALSE ) const;
0153       void     ForceNetworkCalculations();
0154       void     WaitForKeyboard();
0155
0156       // accessors
0157       Int_t    NumCycles()  { return fNcycles;   }
0158       TNeuron* GetInputNeuron (Int_t index)       { return (TNeuron*)fInputLayer->At(index); }
0159       TNeuron* GetOutputNeuron(Int_t index = 0)   { return fOutputNeurons.at(index); }
0160
0161       // protected variables
0162       TObjArray*    fSynapses;        // array of pointers to synapses, no structural data
0163       TActivation*  fActivation;      // activation function to be used for hidden layers
0164       TActivation*  fOutput;          // activation function to be used for output layers, depending on estimator
0165       TActivation*  fIdentity;        // activation for input and output layers
0166       TRandom3*     frgen;            // random number generator for various uses
0167       TNeuronInput* fInputCalculator; // input calculator for all neurons
0168
0169       std::vector<Int_t>        fRegulatorIdx;  //index to different priors from every synapses
0170       std::vector<Double_t>     fRegulators;    //the priors as regulator
0171       EEstimator                fEstimator;
0172       TString                   fEstimatorS;
0173
0174       // monitoring histograms
0175       TH1F* fEstimatorHistTrain; // monitors convergence of training sample
0176       TH1F* fEstimatorHistTest;  // monitors convergence of independent test sample
0177
0178       // monitoring histograms (not available for regression)
0179       void CreateWeightMonitoringHists( const TString& bulkname, std::vector<TH1*>* hv = nullptr ) const;
0180       std::vector<TH1*> fEpochMonHistS; // epoch monitoring histograms for signal
0181       std::vector<TH1*> fEpochMonHistB; // epoch monitoring histograms for background
0182       std::vector<TH1*> fEpochMonHistW; // epoch monitoring histograms for weights
0183
0184
0185       // general
0186       TMatrixD           fInvHessian;           ///< zjh
0187       bool               fUseRegulator;         ///< zjh
0188
0189    protected:
0190       Int_t                   fRandomSeed;      ///< random seed for initial synapse weights
0191
0192       Int_t                   fNcycles;         ///< number of epochs to train
0193
0194       TString                 fNeuronType;      ///< name of neuron activation function class
0195       TString                 fNeuronInputType; ///< name of neuron input calculator class
0196
0197
0198    private:
0199
0200       // helper functions for building network
0201       void BuildLayers(std::vector<Int_t>* layout, Bool_t from_file = false);
0202       void BuildLayer(Int_t numNeurons, TObjArray* curLayer, TObjArray* prevLayer,
0203                       Int_t layerIndex, Int_t numLayers, Bool_t from_file = false);
0204       void AddPreLinks(TNeuron* neuron, TObjArray* prevLayer);
0205
0206       // helper functions for weight initialization
0207       void InitWeights();
0208       void ForceWeights(std::vector<Double_t>* weights);
0209
0210       // helper functions for deleting network
0211       void DeleteNetwork();
0212       void DeleteNetworkLayer(TObjArray*& layer);
0213
0214       // debugging utilities
0215       void PrintLayer(TObjArray* layer) const;
0216       void PrintNeuron(TNeuron* neuron) const;
0217
0218       // private variables
0219       TObjArray*              fInputLayer;      ///< cache this for fast access
0220       std::vector<TNeuron*>   fOutputNeurons;   ///< cache this for fast access
0221       TString                 fLayerSpec;       ///< layout specification option
0222
0223       // some static flags
0224       static const Bool_t fgDEBUG      = kTRUE;  ///< debug flag
0225
0226       ClassDef(MethodANNBase,0); // Base class for TMVA ANNs
0227    };
0228
0229
0230
0231    template <typename WriteIterator>
0232       inline void MethodANNBase::GetLayerActivation (size_t layerNumber, WriteIterator writeIterator)
0233       {
0234          // get the activation values of the nodes in layer "layer"
0235          // write the node activation values into the writeIterator
0236          // assumes, that the network has been computed already (by calling
0237          // "GetRegressionValues")
0238
0239          if (layerNumber >= (size_t)fNetwork->GetEntriesFast())
0240             return;
0241
0242          TObjArray* layer = (TObjArray*)fNetwork->At(layerNumber);
0243          UInt_t nNodes    = layer->GetEntriesFast();
0244          for (UInt_t iNode = 0; iNode < nNodes; iNode++)
0245             {
0246                (*writeIterator) = ((TNeuron*)layer->At(iNode))->GetActivationValue();
0247                ++writeIterator;
0248             }
0249       }
0250
0251
0252 } // namespace TMVA
0253
0254 #endif