include/root/TUnuranEmpDist.h

0001 // @(#)root/unuran:$Id$
0002 // Authors: L. Moneta, J. Leydold Wed Feb 28 2007
0003
0004 /**********************************************************************
0005  *                                                                    *
0006  * Copyright (c) 2006  LCG ROOT Math Team, CERN/PH-SFT                *
0007  *                                                                    *
0008  *                                                                    *
0009  **********************************************************************/
0010
0011 // Header file for class TUnuranEmpDist
0012
0013
0014 #ifndef ROOT_Math_TUnuranEmpDist
0015 #define ROOT_Math_TUnuranEmpDist
0016
0017
0018 #include "TUnuranBaseDist.h"
0019
0020 #include <vector>
0021
0022 class TH1;
0023
0024
0025 /**
0026    \class TUnuranEmpDist
0027    \ingroup Unuran
0028
0029    TUnuranEmpDist class for describing empirical distributions. It is used by TUnuran
0030    to generate double random number according to this distribution via TUnuran::Sample() or
0031    TUnuran::Sample(double *) in case of multi-dimensional empirical distributions.
0032
0033    An empirical distribution can be one or multi-dimension constructed from a set of unbinned data,
0034    (the class can be constructed from an iterator to a vector of data) or by using an histogram
0035    (with a pointer to the TH1 class). If the histogram contains a buffer with the original data they are used by
0036    default to estimate the empirical distribution, otherwise the bins information is used. In this binned case
0037    only one dimension is now supported.
0038
0039    In the case of unbinned data the density distribution is estimated by UNURAN using kernel smoothing and
0040    then random numbers are generated. In the case of bin data (which can only be one dimension)
0041    the probability density is estimated directly from the histograms and the random numbers are generated according
0042    to the histogram (like in TH1::GetRandom). This method requires some initialization time but it is faster
0043    in generating the random numbers than TH1::GetRandom and it becomes convenient to use when generating
0044    a large amount of data.
0045
0046 */
0047
0048
0049 class TUnuranEmpDist : public TUnuranBaseDist {
0050
0051 public:
0052
0053
0054    /**
0055       Constructor from a TH1 objects.
0056       If the histogram has a buffer by default the unbinned data are used
0057    */
0058    TUnuranEmpDist (const TH1 * h1 = nullptr, bool useBuffer = true );
0059
0060    /**
0061       Constructor from a set of data using an iterator to specify begin/end of the data
0062       In the case of multi-dimension the data are assumed to be passed in this order
0063       x0,y0,...x1,y1,..x2,y2,...
0064    */
0065    template<class Iterator>
0066    TUnuranEmpDist (Iterator begin, Iterator end, unsigned int dim = 1) :
0067       fData(std::vector<double>(begin,end) ),
0068       fDim(dim),
0069       fMin(0), fMax(0),
0070       fBinned(false)  {}
0071
0072    /**
0073       Constructor from a set of 1D data
0074    */
0075    TUnuranEmpDist (unsigned int n, double * x);
0076
0077    /**
0078       Constructor from a set of 2D data
0079    */
0080    TUnuranEmpDist (unsigned int n, double * x, double * y);
0081
0082    /**
0083       Constructor from a set of 3D data
0084    */
0085    TUnuranEmpDist (unsigned int n, double * x, double * y, double * z);
0086
0087
0088    /**
0089       Destructor (no operations)
0090    */
0091    ~TUnuranEmpDist () override {}
0092
0093
0094    /**
0095       Copy constructor
0096    */
0097    TUnuranEmpDist(const TUnuranEmpDist &);
0098
0099
0100    /**
0101       Assignment operator
0102    */
0103    TUnuranEmpDist & operator = (const TUnuranEmpDist & rhs);
0104
0105    /**
0106       Clone (required by base class)
0107     */
0108    TUnuranEmpDist * Clone() const override { return new TUnuranEmpDist(*this); }
0109
0110
0111    /**
0112       Return reference to data vector (unbinned or binned data)
0113     */
0114    const std::vector<double> & Data() const { return fData; }
0115
0116    /**
0117       Flag to control if data are binned
0118     */
0119    bool IsBinned() const { return fBinned; }
0120
0121    /**
0122       Min value of binned data
0123       (return 0 for unbinned data)
0124     */
0125    double LowerBin() const { return fMin; }
0126
0127    /**
0128       upper value of binned data
0129       (return 0 for unbinned data)
0130     */
0131    double UpperBin() const { return fMax; }
0132
0133    /**
0134       Number of data dimensions
0135     */
0136    unsigned int NDim() const { return fDim; }
0137
0138
0139 private:
0140
0141    std::vector<double>  fData;       ///< pointer to the data vector (used for generation from un-binned data)
0142    unsigned int fDim;                ///< data dimensionality
0143    double fMin;                      ///< min values (used in the binned case)
0144    double fMax;                      ///< max values (used in the binned case)
0145    bool   fBinned;                   ///< flag for binned/unbinned data
0146
0147    ClassDefOverride(TUnuranEmpDist,1)        //Wrapper class for empirical distribution
0148
0149
0150 };
0151
0152
0153
0154 #endif /* ROOT_Math_TUnuranEmpDist */