class TH2Poly: public TH2

TH2Poly: 2D Histogram with Polygonal Bins

Overview

TH2Poly is a 2D Histogram class (TH2) allowing to define polygonal bins of arbitary 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, 5};
   Double_t y1[] = {0, 0, 5};
   Double_t x2[] = {0, -1, -1, 0};
   Double_t y2[] = {0, 0, -1, -1};
   Double_t x3[] = {4, 3, 0, 1, 2.4};
   Double_t y3[] = {4, 3.7, 1, 4.7, 3.5};
   h2p->AddBin(3, x1, y1);
   h2p->AddBin(3, x2, y2);
   h2p->AddBin(3, x3, y3);
   h2p->Fill(   3,    1, 3); // fill bin 1
   h2p->Fill(-0.5, -0.5, 7); // fill bin 2
   h2p->Fill(-0.7, -0.5, 1); // fill bin 2
   h2p->Fill(   1,    3, 5); // fill bin 3
}

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.