root/TMVA/PDF.h

0001 // @(#)root/tmva $Id$
0002 // Author: Asen Christov, Andreas Hoecker, Joerg Stelzer, Helge Voss, Kai Voss , Jan Therhaag
0003
0004 /**********************************************************************************
0005  * Project: TMVA - a Root-integrated toolkit for multivariate data analysis       *
0006  * Package: TMVA                                                                  *
0007  * Class  : PDF                                                                   *
0008  *                                             *
0009  *                                                                                *
0010  * Description:                                                                   *
0011  *      PDF wrapper for histograms; uses user-defined spline interpolation        *
0012  *      and kernel density estimation                                             *
0013  *                                                                                *
0014  * Authors (alphabetical):                                                        *
0015  *      Asen Christov   <christov@physik.uni-freiburg.de> - Freiburg U., Germany  *
0016  *      Andreas Hoecker <Andreas.Hocker@cern.ch> - CERN, Switzerland              *
0017  *      Helge Voss      <Helge.Voss@cern.ch>     - MPI-K Heidelberg, Germany      *
0018  *      Kai Voss        <Kai.Voss@cern.ch>       - U. of Victoria, Canada         *
0019  *      Jan Therhaag       <Jan.Therhaag@cern.ch>     - U of Bonn, Germany        *
0020  *                                                                                *
0021  * Copyright (c) 2005-2011:                                                       *
0022  *      CERN, Switzerland                                                         *
0023  *      U. of Victoria, Canada                                                    *
0024  *      MPI-K Heidelberg, Germany                                                 *
0025  *      Freiburg U., Germany                                                      *
0026  *      U. of Bonn, Germany                                                       *
0027  *                                                                                *
0028  * Redistribution and use in source and binary forms, with or without             *
0029  * modification, are permitted according to the terms listed in LICENSE           *
0030  * (see tmva/doc/LICENSE)                                          *
0031  **********************************************************************************/
0032
0033 #ifndef ROOT_TMVA_PDF
0034 #define ROOT_TMVA_PDF
0035
0036 //////////////////////////////////////////////////////////////////////////
0037 //                                                                      //
0038 // PDF                                                                  //
0039 //                                                                      //
0040 // PDF wrapper for histograms; uses user-defined spline interpolation   //
0041 //                                                                      //
0042 //////////////////////////////////////////////////////////////////////////
0043
0044 #include <iosfwd>
0045
0046 #include "TH1.h"
0047 #include "ThreadLocalStorage.h"
0048 #include "TMVA/KDEKernel.h"
0049 #include "TMVA/Configurable.h"
0050
0051 class TSpline;
0052 class TGraph;
0053 class TF1;
0054
0055 namespace TMVA {
0056
0057    class MsgLogger;
0058
0059    class PDF;
0060    std::ostream& operator<< ( std::ostream& os, const PDF& tree );
0061    std::istream& operator>> ( std::istream& istr, PDF& tree);
0062
0063    class PDF : public Configurable {
0064
0065       friend std::ostream& operator<< ( std::ostream& os, const PDF& tree );
0066       friend std::istream& operator>> ( std::istream& istr, PDF& tree);
0067
0068    public:
0069
0070       enum EInterpolateMethod { kSpline0, kSpline1, kSpline2, kSpline3, kSpline5, kKDE };
0071
0072       explicit PDF( const TString& name, Bool_t norm=kTRUE );
0073       explicit PDF( const TString& name, const TH1* theHist, EInterpolateMethod method = kSpline2,
0074                     Int_t minnsmooth = 0, Int_t maxnsmooth = 0, Bool_t checkHist = kFALSE, Bool_t norm=kTRUE );
0075       explicit PDF( const TString& name, const TH1* theHist,
0076                     KDEKernel::EKernelType ktype, KDEKernel::EKernelIter kiter, KDEKernel::EKernelBorder
0077                     kborder, Float_t FineFactor, Bool_t norm=kTRUE );
0078       explicit PDF( const TString& name, const TString& options, const TString& suffix = "", PDF* defaultPDF = nullptr, Bool_t norm=kTRUE);
0079       virtual ~PDF();
0080
0081       //creates the pdf after the definitions have been stored in
0082       void BuildPDF (const TH1* theHist);
0083
0084       // returns probability density at given abscissa
0085       Double_t GetVal       ( Double_t x ) const;
0086       Double_t GetValInverse( Double_t y, Bool_t isMonotonouslyIncreasingFunction=kFALSE ) const;
0087
0088       void AddXMLTo( void* parent );
0089       void ReadXML( void* pdfnode );
0090
0091       // histogram underlying the PDF
0092       TH1*     GetPDFHist()      const { return fPDFHist; }
0093       TGraph*  GetGraph()        const { return fGraph; }
0094       TH1*     GetOriginalHist() const { return fHistOriginal; }
0095       TH1*     GetSmoothedHist() const { return fHist; }
0096       TH1*     GetNSmoothHist()  const { return fNSmoothHist; }
0097
0098       // integral of PDF within given range
0099       Double_t GetIntegral( Double_t xmin, Double_t xmax );
0100
0101       // accessors
0102       TSpline* GetSpline() const { return fSpline; }
0103       Int_t    GetNBins () const { return fHist->GetNbinsX(); }
0104       Double_t GetXmin  () const { return fHist->GetXaxis()->GetXmin();   }
0105       Double_t GetXmax  () const { return fHist->GetXaxis()->GetXmax();   }
0106
0107       // perform series of validation tests
0108       void     ValidatePDF( TH1* original = nullptr ) const;
0109
0110       //gives the number of needed bins in the source histogram
0111       Int_t    GetHistNBins ( Int_t evtNum = 0 );
0112
0113       TMVA::PDF::EInterpolateMethod GetInterpolMethod() { return fInterpolMethod;}
0114
0115       // modified name (remove TMVA::)
0116       const char* GetName() const { return fPDFName; }
0117
0118       // TMVA version control (for weight files)
0119       void   SetReadingVersion( UInt_t rv ) { fReadingVersion = rv; }
0120       UInt_t GetReadingVersion() const { return fReadingVersion; }
0121
0122       //void WriteOptionsToStream ( std::ostream& o, const TString& prefix ) const;
0123       void ProcessOptions();
0124
0125       // reads from and option string the definitions for pdf returns it
0126       void DeclareOptions();
0127
0128    private:
0129
0130       // sanity check of PDF quality (after smoothing): comparison with
0131       // original histogram
0132       void     CheckHist() const;
0133       void     FillSplineToHist();
0134       void     BuildKDEPDF();
0135       void     SmoothHistogram();
0136       void     FillHistToGraph();
0137       Double_t GetIntegral() const;
0138       Double_t GetPdfHistBinWidth() const {
0139          TH1* h = GetPDFHist();
0140          return (fPDFHist) ? (h->GetXaxis()->GetXmax() - h->GetXaxis()->GetXmin())/h->GetNbinsX() : 1;
0141       }
0142
0143       // do we use the original histogram as reference ?
0144       Bool_t   UseHistogram() const { return fUseHistogram; }
0145
0146       void FindBinInverse( const TH1* histogram, Int_t& lowerBin, Int_t& higherBin, Double_t& lowerBinValue, Double_t& higherBinValue,
0147                            Double_t y, Bool_t isMonotonouslyIncreasingFunction=kFALSE ) const;
0148
0149
0150       void     BuildSplinePDF();
0151
0152       // flag that indicates that no splines are produced and no smoothing
0153       // is applied, i.e., the original histogram is used as reference
0154       // this is useful for discrete variables
0155       Bool_t                   fUseHistogram;  // spline0 uses histogram as reference
0156
0157       // static configuration variables ----------------------------
0158       // to increase computation speed, the final PDF is filled in
0159       // a high-binned histogram; "GetValue" then returns the histogram
0160       // entry, linearized between adjacent bins
0161       static const Int_t       fgNbin_PdfHist;        ///< number of bins in high-binned reference histogram
0162       static const Bool_t      fgManualIntegration;   ///< manual integration (sum over bins) or DGAUSS
0163       static const Double_t    fgEpsilon;             ///< minimum PDF return
0164       // -----------------------------------------------------------
0165
0166       TString                  fPDFName;              ///< for output
0167       Int_t                    fNsmooth;              ///< Min number of smoothing iterations
0168       Int_t                    fMinNsmooth;           ///< Min number of smoothing iterations
0169       Int_t                    fMaxNsmooth;           ///< Max number of smoothing iterations
0170       TH1*                     fNSmoothHist;          ///< number of smooth for each bin
0171
0172       TMVA::PDF::EInterpolateMethod fInterpolMethod;  ///< interpolation method
0173       TSpline*                 fSpline;               ///<! the used spline type
0174       TH1*                     fPDFHist;              ///<  the high-binned histogram corresponding to the PDF
0175       TH1*                     fHist;                 ///<  copy of input histogram
0176       TH1*                     fHistOriginal;         ///<  the input histogram
0177       TGraph*                  fGraph;                ///<! needed to create PDF from histogram
0178       TF1*                     fIGetVal;              ///< integration interface
0179
0180       Int_t                    fHistAvgEvtPerBin;     ///< avg event per source hist bin
0181       Int_t                    fHistDefinedNBins;     ///< source hist bin num set by user
0182
0183       TString                  fKDEtypeString;        ///< strings used to read definitions
0184       TString                  fKDEiterString;
0185       TString                  fBorderMethodString;
0186       TString                  fInterpolateString;
0187
0188       KDEKernel::EKernelType   fKDEtype;              ///< Kernel type to use for KDE
0189       KDEKernel::EKernelIter   fKDEiter;              ///< Number of iterations (adaptive or not)
0190       KDEKernel::EKernelBorder fKDEborder;            ///< The method to take care about "border" effects (string)
0191       Float_t                  fFineFactor;           ///< fine tuning factor for Adaptive KDE
0192
0193       UInt_t                   fReadingVersion;       ///< the TMVA version of the weight file
0194
0195       Bool_t                   fCheckHist;            ///< check of source histogram
0196       Bool_t                   fNormalize;            ///< normalize histogram (false for cumulative distribution used in GaussTranform)
0197
0198       TString                  fSuffix;               ///<! the suffix for options
0199       mutable MsgLogger*       fLogger;               ///<! message logger
0200       MsgLogger&               Log() const { return *fLogger; }
0201
0202       // static pointer to this object
0203       // This is a workaround for OSx where static thread_local data members are
0204       // not supported. The C++ solution would indeed be the following:
0205       static PDF*& GetThisPdfThreadLocal() { TTHREAD_TLS(PDF*) fgThisPDF(nullptr); return fgThisPDF; };
0206       static PDF*              ThisPDF( void );
0207
0208       // external auxiliary functions
0209       static Double_t          IGetVal( Double_t*, Double_t* );
0210
0211       ClassDef(PDF,1)  // PDF wrapper for histograms
0212          };
0213
0214 } // namespace TMVA
0215
0216 #endif