library: libHist #include "TProfile2D.h"

# TProfile2D

class description - source file - inheritance tree (.ps)

## class TProfile2D : public TH2D

| Inheritance Chart:

`TObject`

<-

`TNamed`

`TAttLine`

`TAttFill`

`TAttMarker`

<-

`TH1`

<-

`TH2`

`TArray`

<-

`TArrayD`

<-

`TH2D`

<-

`TProfile2D`

        private:

          Double_t* GetB()
          Double_t* GetW()
          Double_t* GetW2()

        protected:

          virtual Int_t BufferFill(Axis_t, Stat_t)
          virtual Int_t BufferFill(Axis_t, Axis_t, Stat_t)
          virtual Int_t BufferFill(Axis_t x, Axis_t y, Axis_t z, Stat_t w)

        public:

                           TProfile2D()
                           TProfile2D(const char* name, const char* title, Int_t nbinsx, Axis_t xlow, Axis_t xup, Int_t nbinsy, Axis_t ylow, Axis_t yup, Axis_t zlow, Axis_t zup, Option_t* option)
                           TProfile2D(const char* name, const char* title, Int_t nbinsx, Axis_t xlow, Axis_t xup, Int_t nbinsy, Axis_t ylow, Axis_t yup, Option_t* option)
                           TProfile2D(const char* name, const char* title, Int_t nbinsx, const Double_t* xbins, Int_t nbinsy, Axis_t ylow, Axis_t yup, Option_t* option)
                           TProfile2D(const char* name, const char* title, Int_t nbinsx, Axis_t xlow, Axis_t xup, Int_t nbinsy, const Double_t* ybins, Option_t* option)
                           TProfile2D(const char* name, const char* title, Int_t nbinsx, const Double_t* xbins, Int_t nbinsy, const Double_t* ybins, Option_t* option)
                           TProfile2D(const TProfile2D& profile)
                   virtual ~TProfile2D()
              virtual void Add(TF1* h1, Double_t c1 = 1, Option_t* option)
              virtual void Add(const TH1* h1, Double_t c1 = 1)
              virtual void Add(const TH1* h1, const TH1* h2, Double_t c1 = 1, Double_t c2 = 1)
               static void Approximate(Bool_t approx = kTRUE)
             virtual Int_t BufferEmpty(Bool_t deleteBuffer = kFALSE)
                      void BuildOptions(Double_t zmin, Double_t zmax, Option_t* option)
            static TClass* Class()
              virtual void Copy(TObject& hnew) const
              virtual void Divide(TF1* h1, Double_t c1 = 1)
              virtual void Divide(const TH1* h1)
              virtual void Divide(const TH1* h1, const TH1* h2, Double_t c1 = 1, Double_t c2 = 1, Option_t* option)
              virtual TH1* DrawCopy(Option_t* option) const
             virtual Int_t Fill(Axis_t)
             virtual Int_t Fill(const char*, Stat_t)
             virtual Int_t Fill(Axis_t, Stat_t)
             virtual Int_t Fill(Axis_t x, Axis_t y, Axis_t z)
             virtual Int_t Fill(Axis_t x, const char* namey, Axis_t z)
             virtual Int_t Fill(const char* namex, Axis_t y, Axis_t z)
             virtual Int_t Fill(const char* namex, const char* namey, Axis_t z)
             virtual Int_t Fill(Axis_t x, Axis_t y, Axis_t z, Stat_t w)
            virtual Stat_t GetBinContent(Int_t bin) const
            virtual Stat_t GetBinContent(Int_t binx, Int_t biny) const
            virtual Stat_t GetBinContent(Int_t binx, Int_t biny, Int_t) const
            virtual Stat_t GetBinEntries(Int_t bin) const
            virtual Stat_t GetBinError(Int_t bin) const
            virtual Stat_t GetBinError(Int_t binx, Int_t biny) const
            virtual Stat_t GetBinError(Int_t binx, Int_t biny, Int_t) const
                 Option_t* GetErrorOption() const
              virtual void GetStats(Stat_t* stats) const
          virtual Double_t GetZmax() const
          virtual Double_t GetZmin() const
           virtual TClass* IsA() const
              virtual void LabelsDeflate(Option_t* axis = "X")
              virtual void LabelsInflate(Option_t* axis = "X")
              virtual void LabelsOption(Option_t* option = "h", Option_t* axis = "X")
             virtual Int_t Merge(TCollection* list)
              virtual void Multiply(TF1* h1, Double_t c1 = 1)
              virtual void Multiply(const TH1* h1)
              virtual void Multiply(const TH1* h1, const TH1* h2, Double_t c1 = 1, Double_t c2 = 1, Option_t* option)
               TProfile2D& operator=(const TProfile2D&)
                     TH2D* ProjectionXY(const char* name = "_pxy", Option_t* option = "e") const
              virtual void Reset(Option_t* option)
              virtual void SavePrimitive(ofstream& out, Option_t* option)
              virtual void Scale(Double_t c1 = 1)
              virtual void SetBinEntries(Int_t bin, Stat_t w)
              virtual void SetBins(Int_t, Double_t, Double_t)
              virtual void SetBins(Int_t nbinsx, Double_t xmin, Double_t xmax, Int_t nbinsy, Double_t ymin, Double_t ymax)
              virtual void SetBins(Int_t, Double_t, Double_t, Int_t, Double_t, Double_t, Int_t, Double_t, Double_t)
              virtual void SetBuffer(Int_t buffersize, Option_t* option)
              virtual void SetErrorOption(Option_t* option)
              virtual void ShowMembers(TMemberInspector& insp, char* parent)
              virtual void Streamer(TBuffer& b)
                      void StreamerNVirtual(TBuffer& b)

### Data Members

        protected:

                TArrayD fBinEntries    number of entries per bin
             EErrorType fErrorMode     Option to compute errors
               Double_t fZmin          Lower limit in Z (if set)
               Double_t fZmax          Upper limit in Z (if set)
                 Bool_t fScaling       !True when TProfile2D::Scale is called
                 Stat_t fTsumwz        Total Sum of weight*Z
                 Stat_t fTsumwz2       Total Sum of weight*Z*Z
          static Bool_t fgApproximate  bin error approximation option

## Class Description

      Profile2D histograms are used to display the mean
      value of Z and its RMS for each cell in X,Y.
      Profile2D histograms are in many cases an
      elegant replacement of three-dimensional histograms : the inter-relation of three
      measured quantities X, Y and Z can always be visualized by a three-dimensional
      histogram or scatter-plot; its representation on the line-printer is not particularly
      satisfactory, except for sparse data. If Z is an unknown (but single-valued)
      approximate function of X,Y this function is displayed by a profile2D histogram with
      much better precision than by a scatter-plot.

      The following formulae show the cumulated contents (capital letters) and the values
      displayed by the printing or plotting routines (small letters) of the elements for cell I, J.

                                                            2
          H(I,J)  =  sum Z                  E(I,J)  =  sum Z
          l(I,J)  =  sum l                  L(I,J)  =  sum l
          h(I,J)  =  H(I,J)/L(I,J)          s(I,J)  =  sqrt(E(I,J)/L(I,J)- h(I,J)**2)
          e(I,J)  =  s(I,J)/sqrt(L(I,J))

      In the special case where s(I,J) is zero (eg, case of 1 entry only in one cell)
      e(I,J) is computed from the average of the s(I,J) for all cells.
      This simple/crude approximation was suggested in order to keep the cell
      during a fit operation.

               Example of a profile2D histogram
    {
      TCanvas *c1 = new TCanvas("c1","Profile histogram example",200,10,700,500);
      hprof2d  = new TProfile2D("hprof2d","Profile of pz versus px and py",40,-4,4,40,-4,4,0,20);
      Float_t px, py, pz;
      for ( Int_t i=0; i<25000; i++) {
         gRandom->Rannor(px,py);
         pz = px*px + py*py;
         hprof2d->Fill(px,py,pz,1);
      }
      hprof2d->Draw();
    }

TProfile2D() : TH2D()

    *-*-*-*-*-*Default constructor for Profile2D histograms*-*-*-*-*-*-*-*-*
    *-*        ============================================

~TProfile2D()

    *-*-*-*-*-*Default destructor for Profile2D histograms*-*-*-*-*-*-*-*-*
    *-*        ===========================================

TProfile2D(const char *name,const char *title,Int_t nx,Axis_t xlow,Axis_t xup,Int_t ny,Axis_t ylow,Axis_t yup,Option_t *option) : TH2D(name,title,nx,xlow,xup,ny,ylow,yup)

    *-*-*-*-*-*Normal Constructor for Profile histograms*-*-*-*-*-*-*-*-*-*
    *-*        ==========================================

      The first eight parameters are similar to TH2D::TH2D.
      All values of z are accepted at filling time.
      To fill a profile2D histogram, one must use TProfile2D::Fill function.

      Note that when filling the profile histogram the function Fill
      checks if the variable z is betyween fZmin and fZmax.
      If a minimum or maximum value is set for the Z scale before filling,
      then all values below zmin or above zmax will be discarded.
      Setting the minimum or maximum value for the Z scale before filling
      has the same effect as calling the special TProfile2D constructor below
      where zmin and zmax are specified.

      H(I,J) is printed as the cell contents. The errors computed are s(I,J) if CHOPT='S'
      (spread option), or e(I,J) if CHOPT=' ' (error on mean).

            See TProfile2D::BuildOptions for explanation of parameters

       see other constructors below with all possible combinations of
       fix and variable bin size like in TH2D.

TProfile2D(const char *name,const char *title,Int_t nx,const Double_t *xbins,Int_t ny,Axis_t ylow,Axis_t yup,Option_t *option) : TH2D(name,title,nx,xbins,ny,ylow,yup)

      Create a 2-D Profile with variable bins in X and fix bins in Y

TProfile2D(const char *name,const char *title,Int_t nx,Axis_t xlow,Axis_t xup,Int_t ny,const Double_t *ybins,Option_t *option) : TH2D(name,title,nx,xlow,xup,ny,ybins)

      Create a 2-D Profile with fix bins in X and variable bins in Y

TProfile2D(const char *name,const char *title,Int_t nx,const Double_t *xbins,Int_t ny,const Double_t *ybins,Option_t *option) : TH2D(name,title,nx,xbins,ny,ybins)

      Create a 2-D Profile with variable bins in X and variable bins in Y

TProfile2D(const char *name,const char *title,Int_t nx,Axis_t xlow,Axis_t xup,Int_t ny, Axis_t ylow,Axis_t yup,Axis_t zlow,Axis_t zup,Option_t *option) : TH2D(name,title,nx,xlow,xup,ny,ylow,yup)

    *-*-*-*-*-*Constructor for Profile2D histograms with range in z*-*-*-*-*-*
    *-*        ====================================================
      The first eight parameters are similar to TH2D::TH2D.
      Only the values of Z between ZMIN and ZMAX will be considered at filling time.
      zmin and zmax will also be the maximum and minimum values
      on the z scale when drawing the profile2D.

            See TProfile2D::BuildOptions for more explanations on errors

void BuildOptions(Double_t zmin, Double_t zmax, Option_t *option)

    *-*-*-*-*-*-*Set Profile2D histogram structure and options*-*-*-*-*-*-*-*-*
    *-*          =============================================

        If a cell has N data points all with the same value Z (especially
        possible when dealing with integers), the spread in Z for that cell
        is zero, and the uncertainty assigned is also zero, and the cell is
        ignored in making subsequent fits. If SQRT(Z) was the correct error
        in the case above, then SQRT(Z)/SQRT(N) would be the correct error here.
        In fact, any cell with non-zero number of entries N but with zero spread
        should have an uncertainty SQRT(Z)/SQRT(N).

        Now, is SQRT(Z)/SQRT(N) really the correct uncertainty?
        that it is only in the case where the Z variable is some sort
        of counting statistics, following a Poisson distribution. This should
        probably be set as the default case. However, Z can be any variable
        from an original NTUPLE, not necessarily distributed "Poissonly".
        The computation of errors is based on the parameter option:
        option:
         ' '  (Default) Errors are Spread/SQRT(N) for Spread.ne.0. ,
                          "     "  SQRT(Z)/SQRT(N) for Spread.eq.0,N.gt.0 ,
                          "     "  0.  for N.eq.0
         's'            Errors are Spread  for Spread.ne.0. ,
                          "     "  SQRT(Z)  for Spread.eq.0,N.gt.0 ,
                          "     "  0.  for N.eq.0
         'i'            Errors are Spread/SQRT(N) for Spread.ne.0. ,
                          "     "  1./SQRT(12.*N) for Spread.eq.0,N.gt.0 ,
                          "     "  0.  for N.eq.0

        The third case above corresponds to Integer Z values for which the
        uncertainty is +-0.5, with the assumption that the probability that Z
        takes any value between Z-0.5 and Z+0.5 is uniform (the same argument
        goes for Z uniformly distributed between Z and Z+1); this would be
        useful if Z is an ADC measurement, for example. Other, fancier options
        would be possible, at the cost of adding one more parameter to the PROFILE2D
        For example, if all Z variables are distributed according to some
        known Gaussian of standard deviation Sigma, then:
         'G'            Errors are Spread/SQRT(N) for Spread.ne.0. ,
                          "     "  Sigma/SQRT(N) for Spread.eq.0,N.gt.0 ,
                          "     "  0.  for N.eq.0
        For example, this would be useful when all Z's are experimental quantities
        measured with the same instrument with precision Sigma.

TProfile2D(const TProfile2D &profile) : TH2D()

void Add(TF1 *, Double_t , Option_t*)

     Performs the operation: this = this + c1*f1

void Add(const TH1 *h1, Double_t c1)

     Performs the operation: this = this + c1*h1

void Add(const TH1 *h1, const TH1 *h2, Double_t c1, Double_t c2)

    *-*-*-*-*Replace contents of this profile2D by the addition of h1 and h2*-*-*
    *-*      ===============================================================

       this = c1*h1 + c2*h2

void Approximate(Bool_t approx)

         static function
     set the fgApproximate flag. When the flag is true, the function GetBinError
     will approximate the bin error with the average profile error on all bins
     in the following situation only
      - the number of bins in the profile2D is less than 10404 (eg 100x100)
      - the bin number of entries is small ( <5)
      - the estimated bin error is extremely small compared to the bin content
      (see TProfile2D::GetBinError)

Int_t BufferEmpty(Bool_t deleteBuffer)

     Fill histogram with all entries in the buffer.
     The buffer is deleted if deleteBuffer is true.

Int_t BufferFill(Axis_t x, Axis_t y, Axis_t z, Stat_t w)

     accumulate arguments in buffer. When buffer is full, empty the buffer
     fBuffer[0] = number of entries in buffer
     fBuffer[1] = w of first entry
     fBuffer[2] = x of first entry

void Copy(TObject &obj) const

    *-*-*-*-*-*-*-*Copy a Profile2D histogram to a new profile2D histogram*-*-*-*
    *-*            =======================================================

void Divide(TF1 *, Double_t )

     Performs the operation: this = this/(c1*f1)

void Divide(const TH1 *h1)

    *-*-*-*-*-*-*-*-*-*-*Divide this profile2D by h1*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                  ===========================

       this = this/h1

void Divide(const TH1 *h1, const TH1 *h2, Double_t c1, Double_t c2, Option_t *option)

    *-*-*-*-*Replace contents of this profile2D by the division of h1 by h2*-*-*
    *-*      ==============================================================

       this = c1*h1/(c2*h2)

TH1* DrawCopy(Option_t *option) const

    *-*-*-*-*-*-*-*Draw a copy of this profile2D histogram*-*-*-*-*-*-*-*-*-*-*
    *-*            =======================================

Int_t Fill(Axis_t x, Axis_t y, Axis_t z)

    *-*-*-*-*-*-*-*-*-*-*Fill a Profile2D histogram (no weights)*-*-*-*-*-*-*-*
    *-*                  =======================================

Int_t Fill(Axis_t x, const char *namey, Axis_t z)

     Fill a Profile2D histogram (no weights)

Int_t Fill(const char *namex, const char *namey, Axis_t z)

     Fill a Profile2D histogram (no weights)

Int_t Fill(const char *namex, Axis_t y, Axis_t z)

     Fill a Profile2D histogram (no weights)

Int_t Fill(Axis_t x, Axis_t y, Axis_t z, Stat_t w)

    *-*-*-*-*-*-*-*-*-*-*Fill a Profile2D histogram with weights*-*-*-*-*-*-*-*
    *-*                  =======================================

Stat_t GetBinContent(Int_t bin) const

    *-*-*-*-*-*-*Return bin content of a Profile2D histogram*-*-*-*-*-*-*-*-*
    *-*          ===========================================

Stat_t GetBinEntries(Int_t bin) const

    *-*-*-*-*-*-*Return bin entries of a Profile2D histogram*-*-*-*-*-*-*-*-*
    *-*          ===========================================

Stat_t GetBinError(Int_t bin) const

    *-*-*-*-*-*-*Return bin error of a Profile2D histogram*-*-*-*-*-*-*-*-*

     Computing errors: A moving field
     =================================
     The computation of errors for a TProfile2D has evolved with the versions
     of ROOT. The difficulty is in computing errors for bins with low statistics.
     - prior to version 3.10, we had no special treatment of low statistic bins.
       As a result, these bins had huge errors. The reason is that the
       expression eprim2 is very close to 0 (rounding problems) or 0.
     - The algorithm is modified/protected for the case
       when a TProfile2D is projected (ProjectionX). The previous algorithm
       generated a N^2 problem when projecting a TProfile2D with a large number of
       bins (eg 100000).
     - in version 3.10/02, a new static function TProfile::Approximate
       is introduced to enable or disable (default) the approximation.
       (see also comments in TProfile::GetBinError)

Option_t* GetErrorOption() const

    *-*-*-*-*-*-*-*-*-*Return option to compute profile2D errors*-*-*-*-*-*-*-*
    *-*                =========================================

void GetStats(Stat_t *stats) const

     fill the array stats from the contents of this profile
     The array stats must be correctly dimensionned in the calling program.
     stats[0] = sumw
     stats[1] = sumw2
     stats[2] = sumwx
     stats[3] = sumwx2
     stats[4] = sumwy
     stats[5] = sumwy2
     stats[6] = sumwxy
     stats[7] = sumwz
     stats[8] = sumwz2

     The function recomputes the statistics quantities
     from the bin contents in the current axis range.

void LabelsDeflate(Option_t *ax)

     Reduce the number of bins for this axis to the number of bins having a label.

void LabelsInflate(Option_t *ax)

     Double the number of bins for axis.
     Refill histogram
     This function is called by TAxis::FindBin(const char *label)

void LabelsOption(Option_t *option, Option_t *ax)

      Set option(s) to draw axis with labels
      option = "a" sort by alphabetic order
             = ">" sort by decreasing values
             = "<" sort by increasing values
             = "h" draw labels horizonthal
             = "v" draw labels vertical
             = "u" draw labels up (end of label right adjusted)
             = "d" draw labels down (start of label left adjusted)

Int_t Merge(TCollection *list)

    Merge all histograms in the collection in this histogram.
    This function computes the min/max for the axes,
    compute a new number of bins, if necessary,
    add bin contents, errors and statistics.
    The function returns the merged number of entries if the merge is
    successfull, -1 otherwise.

    IMPORTANT remark. The 2 axis x and y may have different number
    of bins and different limits, BUT the largest bin width must be
    a multiple of the smallest bin width.

void Multiply(TF1 *, Double_t )

     Performs the operation: this = this*c1*f1

void Multiply(const TH1 *)

    *-*-*-*-*-*-*-*-*-*-*Multiply this profile2D by h1*-*-*-*-*-*-*-*-*-*-*-*
    *-*                  =============================

       this = this*h1

void Multiply(const TH1 *, const TH1 *, Double_t, Double_t, Option_t *)

    *-*-*-*-*Replace contents of this profile2D by multiplication of h1 by h2*-*
    *-*      ================================================================

       this = (c1*h1)*(c2*h2)

TH2D* ProjectionXY(const char *name, Option_t *option) const

    *-*-*-*-*Project this profile2D into a 2-D histogram along X,Y*-*-*-*-*-*-*
    *-*      =====================================================

       The projection is always of the type TH2D.

       if option "E" is specified, the errors are computed. (default)

void Reset(Option_t *option)

    *-*-*-*-*-*-*-*-*-*Reset contents of a Profile2D histogram*-*-*-*-*-*-*-*
    *-*                =======================================

void SavePrimitive(ofstream &out, Option_t *option)

     Save primitive as a C++ statement(s) on output stream out

void Scale(Double_t c1)

    *-*-*-*-*Multiply this profile2D by a constant c1*-*-*-*-*-*-*-*-*
    *-*      ========================================

       this = c1*this

     This function uses the services of TProfile2D::Add

void SetBinEntries(Int_t bin, Stat_t w)

    *-*-*-*-*-*-*-*-*Set the number of entries in bin*-*-*-*-*-*-*-*-*-*-*-*
    *-*              ================================

void SetBins(Int_t nx, Double_t xmin, Double_t xmax, Int_t ny, Double_t ymin, Double_t ymax)

    *-*-*-*-*-*-*-*-*Redefine  x axis parameters*-*-*-*-*-*-*-*-*-*-*-*
    *-*              ===========================

void SetBuffer(Int_t buffersize, Option_t *)

     set the buffer size in units of 8 bytes (double)

void SetErrorOption(Option_t *option)

    *-*-*-*-*-*-*-*-*-*Set option to compute profile2D errors*-*-*-*-*-*-*-*
    *-*                =======================================

        The computation of errors is based on the parameter option:
        option:
         ' '  (Default) Errors are Spread/SQRT(N) for Spread.ne.0. ,
                          "     "  SQRT(Z)/SQRT(N) for Spread.eq.0,N.gt.0 ,
                          "     "  0.  for N.eq.0
         's'            Errors are Spread  for Spread.ne.0. ,
                          "     "  SQRT(Z)  for Spread.eq.0,N.gt.0 ,
                          "     "  0.  for N.eq.0
         'i'            Errors are Spread/SQRT(N) for Spread.ne.0. ,
                          "     "  1./SQRT(12.*N) for Spread.eq.0,N.gt.0 ,
                          "     "  0.  for N.eq.0
       See TProfile2D::BuildOptions for explanation of all options

void Streamer(TBuffer &R__b)

     Stream an object of class TProfile2D.

### Inline Functions

                  Int_t BufferFill(Axis_t, Axis_t, Stat_t)
                  Int_t BufferFill(Axis_t x, Axis_t y, Axis_t z, Stat_t w)
              Double_t* GetB()
              Double_t* GetW()
              Double_t* GetW2()
                  Int_t Fill(const char* namex, Axis_t y, Axis_t z)
                  Int_t Fill(const char* namex, const char* namey, Axis_t z)
                  Int_t Fill(Axis_t x, Axis_t y, Axis_t z, Stat_t w)
                 Stat_t GetBinContent(Int_t binx, Int_t biny) const
                 Stat_t GetBinContent(Int_t binx, Int_t biny, Int_t) const
                 Stat_t GetBinError(Int_t binx, Int_t biny) const
                 Stat_t GetBinError(Int_t binx, Int_t biny, Int_t) const
               Double_t GetZmin() const
               Double_t GetZmax() const
                   void SetBins(Int_t nbinsx, Double_t xmin, Double_t xmax, Int_t nbinsy, Double_t ymin, Double_t ymax)
                   void SetBins(Int_t, Double_t, Double_t, Int_t, Double_t, Double_t, Int_t, Double_t, Double_t)
                TClass* Class()
                TClass* IsA() const
                   void ShowMembers(TMemberInspector& insp, char* parent)
                   void StreamerNVirtual(TBuffer& b)
            TProfile2D& operator=(const TProfile2D&)

Author: Rene Brun 16/04/2000
Last update: root/hist:$Name: $:$Id: TProfile2D.cxx,v 1.24 2004/05/26 11:32:00 brun Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *