class TH2Poly: public TH2

```
```

TH2Poly: 2D Histogram with Polygonal Bins

Overview

TH2Poly is a 2D Histogram class (TH2) allowing to define polygonal bins of arbitrary shape.

Each bin in the TH2Poly histogram is a TH2PolyBin object. TH2PolyBin is a very simple class containing the vertices (stored as TGraphs or TMultiGraphs ) and contents of the polygonal bin as well as several related functions.

Essentially, a TH2Poly is a TList of TH2PolyBin objects with methods to manipulate them.

Bins are defined using one of the AddBin() methods. The bin definition should be done before filling.

The histogram can be filled with Fill(Double_t x, Double_t y, Double_t w) . w is the weight. If no weight is specified, it is assumed to be 1.

Not all histogram's area need to be binned. Filling an area without bins, will falls into the overflows. Adding a bin is not retroactive; it doesn't affect previous fillings. A Fill() call, that was previously ignored due to the lack of a bin at the specified location, is not reconsidered when that location is binned later.

If there are two overlapping bins, the first one in the list will be incremented by Fill().

The histogram may automatically extends its limits if a bin outside the histogram limits is added. This is done when the default constructor (with no arguments) is used. It generates a histogram with no limits along the X and Y axis. Adding bins to it will extend it up to a proper size.

TH2Poly implements a partitioning algorithm to speed up bins' filling. The partitioning algorithm divides the histogram into regions called cells. The bins that each cell intersects are recorded in an array of TLists. When a coordinate in the histogram is to be filled; the method (quickly) finds which cell the coordinate belongs. It then only loops over the bins intersecting that cell to find the bin the input coordinate corresponds to. The partitioning of the histogram is updated continuously as each bin is added. The default number of cells on each axis is 25. This number could be set to another value in the constructor or adjusted later by calling the ChangePartition(Int_t, Int_t) method. The partitioning algorithm is considerably faster than the brute force algorithm (i.e. checking if each bin contains the input coordinates), especially if the histogram is to be filled many times.

The following very simple macro shows how to build and fill a TH2Poly:

```{
TH2Poly *h2p = new TH2Poly();
Double_t x1[] = {0, 5, 6};
Double_t y1[] = {0, 0, 5};
Double_t x2[] = {0, -1, -1, 0};
Double_t y2[] = {0, 0, -1, 3};
Double_t x3[] = {4, 3, 0, 1, 2.4};
Double_t y3[] = {4, 3.7, 1, 3.7, 2.5};
h2p->Fill(0.1, 0.01, 3);
h2p->Fill(-0.5, -0.5, 7);
h2p->Fill(-0.7, -0.5, 1);
h2p->Fill(1, 3, 1.5);
}
```

More examples can bin found in \$ROOTSYS/tutorials/hist/th2poly*.C

Partitioning Algorithm

The partitioning algorithm forms an essential part of the TH2Poly class. It is implemented to speed up the filling of bins.

With the brute force approach, the filling is done in the following way: An iterator loops over all bins in the TH2Poly and invokes the method IsInside() for each of them. This method checks if the input location is in that bin. If the filling coordinate is inside, the bin is filled. Looping over all the bin is very slow.

The alternative is to divide the histogram into virtual rectangular regions called "cells". Each cell stores the pointers of the bins intersecting it. When a coordinate is to be filled, the method finds which cell the coordinate falls into. Since the cells are rectangular, this can be done very quickly. It then only loops over the bins associated with that cell.

The addition of bins to the appropriate cells is done when the bin is added to the histogram. To do this, AddBin() calls the AddBinToPartition() method. This method adds the input bin to the partitioning matrix.

The number of partition cells per axis can be specified in the constructor. If it is not specified, the default value of 25 along each axis will be assigned. This value was chosen because it is small enough to avoid slowing down AddBin(), while being large enough to enhance Fill() by a considerable amount. Regardless of how it is initialized at construction time, it can be changed later with the ChangePartition() method. ChangePartition() deletes the old partition matrix and generates a new one with the specified number of cells on each axis.

The optimum number of partition cells per axis changes with the number of times Fill() will be called. Although partitioning greatly speeds up filling, it also adds a constant time delay into the code. When Fill() is to be called many times, it is more efficient to divide the histogram into a large number cells. However, if the histogram is to be filled only a few times, it is better to divide into a small number of cells.

```
```

Function Members (Methods)

public:
protected:
 void AddBinToPartition(TH2PolyBin* bin) virtual Int_t TH2::BufferFill(Double_t, Double_t) virtual Int_t TH2::BufferFill(Double_t x, Double_t y, Double_t w) static bool TH1::CheckAxisLimits(const TAxis* a1, const TAxis* a2) static bool TH1::CheckBinLabels(const TAxis* a1, const TAxis* a2) static bool TH1::CheckBinLimits(const TAxis* a1, const TAxis* a2) static bool TH1::CheckConsistency(const TH1* h1, const TH1* h2) static bool TH1::CheckConsistentSubAxes(const TAxis* a1, Int_t firstBin1, Int_t lastBin1, const TAxis* a2, Int_t firstBin2 = 0, Int_t lastBin2 = 0) static bool TH1::CheckEqualAxes(const TAxis* a1, const TAxis* a2) virtual void TObject::DoError(int level, const char* location, const char* fmt, va_list va) const virtual void TH1::DoFillN(Int_t ntimes, const Double_t* x, const Double_t* w, Int_t stride = 1) virtual void TH2::DoFitSlices(bool onX, TF1* f1, Int_t firstbin, Int_t lastbin, Int_t cut, Option_t* option, TObjArray* arr) virtual Double_t TH1::DoIntegral(Int_t ix1, Int_t ix2, Int_t iy1, Int_t iy2, Int_t iz1, Int_t iz2, Double_t& err, Option_t* opt, Bool_t doerr = kFALSE) const virtual TProfile* TH2::DoProfile(bool onX, const char* name, Int_t firstbin, Int_t lastbin, Option_t* option) const virtual TH1D* TH2::DoProjection(bool onX, const char* name, Int_t firstbin, Int_t lastbin, Option_t* option) const virtual TH1D* TH2::DoQuantiles(bool onX, const char* name, Double_t prob) const virtual Bool_t TH1::FindNewAxisLimits(const TAxis* axis, const Double_t point, Double_t& newMin, Double_t& newMax) virtual Double_t TH1::GetBinErrorSqUnchecked(Int_t bin) const void Initialize(Double_t xlow, Double_t xup, Double_t ylow, Double_t yup, Int_t n, Int_t m) Bool_t IsIntersecting(TH2PolyBin* bin, Double_t xclipl, Double_t xclipr, Double_t yclipb, Double_t yclipt) Bool_t IsIntersectingPolygon(Int_t bn, Double_t* x, Double_t* y, Double_t xclipl, Double_t xclipr, Double_t yclipb, Double_t yclipt) void TObject::MakeZombie() static Bool_t TH1::RecomputeAxisLimits(TAxis& destAxis, const TAxis& anAxis) virtual Double_t RetrieveBinContent(Int_t bin) const static Bool_t TH1::SameLimitsAndNBins(const TAxis& axis1, const TAxis& axis2) virtual void TH1::SavePrimitiveHelp(ostream& out, const char* hname, Option_t* option = "") virtual void UpdateBinContent(Int_t bin, Double_t content)

Data Members

public:
 static TH1::(anonymous) TH1::kAllAxes static TObject::(anonymous) TObject::kBitMask static TObject::EStatusBits TObject::kCanDelete static TH1::(anonymous) TH1::kCanRebin static TObject::EStatusBits TObject::kCannotPick static TObject::EStatusBits TObject::kHasUUID static TObject::EStatusBits TObject::kInvalidObject static TH1::(anonymous) TH1::kIsAverage static TH1::(anonymous) TH1::kIsNotW static TObject::(anonymous) TObject::kIsOnHeap static TObject::EStatusBits TObject::kIsReferenced static TH1::(anonymous) TH1::kIsZoomed static TH1::(anonymous) TH1::kLogX static TObject::EStatusBits TObject::kMustCleanup static TH1::(anonymous) TH1::kNoAxis static TObject::EStatusBits TObject::kNoContextMenu static TH1::(anonymous) TH1::kNoStats static TH1::(anonymous) TH1::kNoTitle static TH1::EBinErrorOpt TH1::kNormal static TObject::(anonymous) TObject::kNotDeleted static TH1::(anonymous) TH1::kNstat static TObject::EStatusBits TObject::kObjInCanvas static TObject::(anonymous) TObject::kOverwrite static TH1::EBinErrorOpt TH1::kPoisson static TH1::EBinErrorOpt TH1::kPoisson2 static TObject::(anonymous) TObject::kSingleKey static TH1::(anonymous) TH1::kUserContour static TObject::(anonymous) TObject::kWriteDelete static TH1::(anonymous) TH1::kXaxis static TH1::(anonymous) TH1::kYaxis static TH1::(anonymous) TH1::kZaxis static TObject::(anonymous) TObject::kZombie
protected:
 Short_t TH1::fBarOffset (1000*offset) for bar charts or legos Short_t TH1::fBarWidth (1000*width) for bar charts or legos Bool_t fBinContentChanged !For the 3D Painter TH1::EBinErrorOpt TH1::fBinStatErrOpt option for bin statistical errors TList* fBins List of bins. The list owns the contained objects Double_t* TH1::fBuffer [fBufferSize] entry buffer Int_t TH1::fBufferSize fBuffer size Int_t fCellX Number of partition cells in the x-direction of the histogram Int_t fCellY Number of partition cells in the y-direction of the histogram TList* fCells [fNCells] The array of TLists that store the bins that intersect with each cell. List do not own the contained objects Bool_t* fCompletelyInside [fNCells] The array that returns true if the cell at the given coordinate is completely inside a bin TArrayD TH1::fContour Array to display contour levels Int_t TH1::fDimension !Histogram dimension (1, 2 or 3 dim) TDirectory* TH1::fDirectory !Pointer to directory holding this histogram Double_t TH1::fEntries Number of entries Color_t TAttFill::fFillColor fill area color Style_t TAttFill::fFillStyle fill area style Bool_t fFloat When set to kTRUE, allows the histogram to expand if a bin outside the limits is added. TList* TH1::fFunctions ->Pointer to list of functions (fits and user) Double_t* TH1::fIntegral !Integral of bins used by GetRandom Bool_t* fIsEmpty [fNCells] The array that returns true if the cell at the given coordinate is empty Color_t TAttLine::fLineColor line color Style_t TAttLine::fLineStyle line style Width_t TAttLine::fLineWidth line width Color_t TAttMarker::fMarkerColor Marker color index Size_t TAttMarker::fMarkerSize Marker size Style_t TAttMarker::fMarkerStyle Marker style Double_t TH1::fMaximum Maximum value for plotting Double_t TH1::fMinimum Minimum value for plotting Int_t fNCells Number of partition cells: fCellX*fCellY TString TNamed::fName object identifier Int_t TH1::fNcells number of bins(1D), cells (2D) +U/Overflows Bool_t fNewBinAdded !For the 3D Painter Double_t TH1::fNormFactor Normalization factor TString TH1::fOption histogram options Double_t fOverflow[9] Overflow bins TVirtualHistPainter* TH1::fPainter !pointer to histogram painter Double_t TH2::fScalefactor Scale factor Double_t fStepX Dimensions of a partition cell Double_t fStepY Dimensions of a partition cell TArrayD TH1::fSumw2 Array of sum of squares of weights TString TNamed::fTitle object title Double_t TH1::fTsumw Total Sum of weights Double_t TH1::fTsumw2 Total Sum of squares of weights Double_t TH1::fTsumwx Total Sum of weight*X Double_t TH1::fTsumwx2 Total Sum of weight*X*X Double_t TH2::fTsumwxy Total Sum of weight*X*Y Double_t TH2::fTsumwy Total Sum of weight*Y Double_t TH2::fTsumwy2 Total Sum of weight*Y*Y TAxis TH1::fXaxis X axis descriptor TAxis TH1::fYaxis Y axis descriptor TAxis TH1::fZaxis Z axis descriptor static Bool_t TH1::fgAddDirectory !flag to add histograms to the directory static Int_t TH1::fgBufferSize !default buffer size for automatic histograms static Bool_t TH1::fgDefaultSumw2 !flag to call TH1::Sumw2 automatically at histogram creation time static Bool_t TH1::fgStatOverflows !flag to use under/overflows in statistics

Function documentation

TH2Poly()
``` Default Constructor. No boundaries specified.
```
TH2Poly(const char* name, const char* title, Double_t xlow, Double_t xup, Double_t ylow, Double_t yup)
``` Constructor with specified name and boundaries,
but no partition cell number.
```
TH2Poly(const char* name, const char* title, Int_t nX, Double_t xlow, Double_t xup, Int_t nY, Double_t ylow, Double_t yup)
``` Constructor with specified name and boundaries and partition cell number.
```
~TH2Poly()
``` Destructor.
```
``` Adds a new bin to the histogram. It can be any object having the method
IsInside(). It returns the bin number in the histogram. It returns 0 if
it failed to add. To allow the histogram limits to expand when a bin
```
Int_t AddBin(Int_t n, const Double_t* x, const Double_t* y)
``` Adds a new bin to the histogram. The number of vertices and their (x,y)
coordinates are required as input. It returns the bin number in the
histogram.
```
Int_t AddBin(Double_t x1, Double_t y1, Double_t x2, Double_t y2)
``` Add a new bin to the histogram. The bin shape is a rectangle.
It returns the bin number of the bin in the histogram.
```
Bool_t Add(const TH1* h1, Double_t c1)
``` Performs the operation: this = this + c1*h1.
```
Bool_t Add(TF1* h1, Double_t c1 = 1, Option_t* option = "")
``` Performs the operation: this = this + c1*f1.
```
Bool_t Add(const TH1* h1, const TH1* h2, Double_t c1 = 1, Double_t c2 = 1)
``` Replace contents of this histogram by the addition of h1 and h2.
```
``` Adds the input bin into the partition cell matrix. This method is called
```
void ChangePartition(Int_t n, Int_t m)
``` Changes the number of partition cells in the histogram.
Deletes the old partition and constructs a new one.
```
TObject* Clone(const char* newname = "") const
``` Make a complete copy of the underlying object.  If 'newname' is set,
the copy's name will be set to that name.
```
void ClearBinContents()
``` Clears the contents of all bins in the histogram.
```
void Reset(Option_t* option)
``` Reset this histogram: contents, errors, etc.
```
Int_t FindBin(Double_t x, Double_t y, Double_t z = 0)
``` Returns the bin number of the bin at the given coordinate. -1 to -9 are
the overflow and underflow bins.  overflow bin -5 is the unbinned areas in
the histogram (also called "the sea"). The third parameter can be left
blank.
The overflow/underflow bins are:

-1 | -2 | -3

-4 | -5 | -6

-7 | -8 | -9

where -5 means is the "sea" bin (i.e. unbinned areas)
```

``` Increment the bin containing (x,y) by 1.
Uses the partitioning algorithm.
```

``` Increment the bin containing (x,y) by w.
Uses the partitioning algorithm.
```
Int_t Fill(const char* name, Double_t w)
``` Increment the bin named "name" by w.
```
void FillN(Int_t ntimes, const Double_t* x, const Double_t* y, const Double_t* w, Int_t stride = 1)
``` Fills a 2-D histogram with an array of values and weights.

ntimes:  number of entries in arrays x and w
(array size must be ntimes*stride)
x:       array of x values to be histogrammed
y:       array of y values to be histogrammed
w:       array of weights
stride:  step size through arrays x, y and w
```
Double_t Integral(Option_t* option = "") const
``` Returns the integral of bin contents.
By default the integral is computed as the sum of bin contents.
If option "width" or "area" is specified, the integral is the sum of
the bin contents multiplied by the area of the bin.
```
Double_t GetBinContent(Int_t bin) const
``` Returns the content of the input bin
For the overflow/underflow/sea bins:

-1 | -2 | -3
---+----+----
-4 | -5 | -6
---+----+----
-7 | -8 | -9

where -5 is the "sea" bin (i.e. unbinned areas)
```
Double_t GetBinError(Int_t bin) const
``` Returns the value of error associated to bin number bin.
If the sum of squares of weights has been defined (via Sumw2),
this function returns the sqrt(sum of w2).
otherwise it returns the sqrt(contents) for this bin.
```
const char * GetBinName(Int_t bin) const
``` Returns the bin name.
```
const char * GetBinTitle(Int_t bin) const
``` Returns the bin title.
```
Double_t GetMaximum() const
``` Returns the maximum value of the histogram.
```
Double_t GetMaximum(Double_t maxval) const
``` Returns the maximum value of the histogram that is less than maxval.
```
Double_t GetMinimum() const
``` Returns the minimum value of the histogram.
```
Double_t GetMinimum(Double_t minval) const
``` Returns the minimum value of the histogram that is greater than minval.
```
void Honeycomb(Double_t xstart, Double_t ystart, Double_t a, Int_t k, Int_t s)
``` Bins the histogram using a honeycomb structure
```
void Initialize(Double_t xlow, Double_t xup, Double_t ylow, Double_t yup, Int_t n, Int_t m)
``` Initializes the TH2Poly object.  This method is called by the constructor.
```
Bool_t IsIntersecting(TH2PolyBin* bin, Double_t xclipl, Double_t xclipr, Double_t yclipb, Double_t yclipt)
``` Returns kTRUE if the input bin is intersecting with the
input rectangle (xclipl, xclipr, yclipb, yclipt)
```
Bool_t IsIntersectingPolygon(Int_t bn, Double_t* x, Double_t* y, Double_t xclipl, Double_t xclipr, Double_t yclipb, Double_t yclipt)
``` Returns kTRUE if the input polygon (bn, x, y) is intersecting with the
input rectangle (xclipl, xclipr, yclipb, yclipt)
```
void SavePrimitive(ostream& out, Option_t* option = "")
``` Save primitive as a C++ statement(s) on output stream out
```
void Scale(Double_t c1 = 1, Option_t* option = "")
``` Multiply this histogram by a constant c1.
```
void SetBinContent(Int_t bin, Double_t content)
``` Sets the contents of the input bin to the input content
Negative values between -1 and -9 are for the overflows and the sea
```
void SetFloat(Bool_t flag = true)
``` When set to kTRUE, allows the histogram to expand if a bin outside the
```
void Fill(Double_t )
`{fContent = fContent+w; SetChanged(true);}`
TH2Poly()

Int_t Fill(const char* name, Double_t w)
void FillN(Int_t ntimes, const Double_t* x, const Double_t* y, const Double_t* w, Int_t stride = 1)
TList * GetBins()
`{return fBins;}`
Double_t GetBinContent(Int_t bin) const
Double_t GetBinContent(Int_t , Int_t ) const
`{return 0;}`
Bool_t GetBinContentChanged() const
`{return fBinContentChanged;}`
Double_t GetBinError(Int_t bin) const
Double_t GetBinError(Int_t , Int_t ) const
`{return 0;}`

`{return fFloat;}`
`{return fNewBinAdded;}`
Int_t GetNumberOfBins() const
`{return fNcells;}`
Double_t Integral(Option_t* option = "") const
Double_t Integral(Int_t , Int_t , const Option_t* ) const
`{return 0;}`
Double_t Integral(Int_t , Int_t , Int_t , Int_t , const Option_t* ) const
`{return 0;}`
void SetBinContent(Int_t bin, Double_t content)
void SetBinContent(Int_t , Int_t , Double_t )
`{return;}`
void SetBinContentChanged(Bool_t flag)
`{fBinContentChanged = flag;}`
`{fNewBinAdded = flag;}`
Double_t RetrieveBinContent(Int_t bin) const
``` needed by TH1 - no need to have a separate implementation
```
`{ return GetBinContent(bin); }`
void UpdateBinContent(Int_t bin, Double_t content)
`{ return SetBinContent(bin,content); }`