class TH2PolyBin: public TObject

TH2Poly: 2D Histogram with Polygonal Bins


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->AddBin(3, x1, y1);
    h2p->AddBin(4, x2, y2);
    h2p->AddBin(5, x3, y3);
    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)

voidTObject::AbstractMethod(const char* method) const
virtual voidTObject::AppendPad(Option_t* option = "")
virtual voidTObject::Browse(TBrowser* b)
static TClass*Class()
virtual const char*TObject::ClassName() const
virtual voidTObject::Clear(Option_t* = "")
virtual TObject*TObject::Clone(const char* newname = "") const
virtual Int_tTObject::Compare(const TObject* obj) const
virtual voidTObject::Copy(TObject& object) const
virtual voidTObject::Delete(Option_t* option = "")MENU
virtual Int_tTObject::DistancetoPrimitive(Int_t px, Int_t py)
virtual voidTObject::Draw(Option_t* option = "")
virtual voidTObject::DrawClass() constMENU
virtual TObject*TObject::DrawClone(Option_t* option = "") constMENU
virtual voidTObject::Dump() constMENU
virtual voidTObject::Error(const char* method, const char* msgfmt) const
virtual voidTObject::Execute(const char* method, const char* params, Int_t* error = 0)
virtual voidTObject::Execute(TMethod* method, TObjArray* params, Int_t* error = 0)
virtual voidTObject::ExecuteEvent(Int_t event, Int_t px, Int_t py)
virtual voidTObject::Fatal(const char* method, const char* msgfmt) const
voidFill(Double_t w)
virtual TObject*TObject::FindObject(const char* name) const
virtual TObject*TObject::FindObject(const TObject* obj) const
Int_tGetBinNumber() const
Bool_tGetChanged() const
Double_tGetContent() const
virtual Option_t*TObject::GetDrawOption() const
static Long_tTObject::GetDtorOnly()
virtual const char*TObject::GetIconName() const
virtual const char*TObject::GetName() const
virtual char*TObject::GetObjectInfo(Int_t px, Int_t py) const
static Bool_tTObject::GetObjectStat()
virtual Option_t*TObject::GetOption() const
TObject*GetPolygon() const
virtual const char*TObject::GetTitle() const
virtual UInt_tTObject::GetUniqueID() const
virtual Bool_tTObject::HandleTimer(TTimer* timer)
virtual ULong_tTObject::Hash() const
virtual voidTObject::Info(const char* method, const char* msgfmt) const
virtual Bool_tTObject::InheritsFrom(const char* classname) const
virtual Bool_tTObject::InheritsFrom(const TClass* cl) const
virtual voidTObject::Inspect() constMENU
voidTObject::InvertBit(UInt_t f)
virtual TClass*IsA() const
virtual Bool_tTObject::IsEqual(const TObject* obj) const
virtual Bool_tTObject::IsFolder() const
Bool_tIsInside(Double_t x, Double_t y) const
Bool_tTObject::IsOnHeap() const
virtual Bool_tTObject::IsSortable() const
Bool_tTObject::IsZombie() const
virtual voidTObject::ls(Option_t* option = "") const
voidTObject::MayNotUse(const char* method) const
virtual Bool_tTObject::Notify()
voidTObject::Obsolete(const char* method, const char* asOfVers, const char* removedFromVers) const
voidTObject::operator delete(void* ptr)
voidTObject::operator delete(void* ptr, void* vp)
voidTObject::operator delete[](void* ptr)
voidTObject::operator delete[](void* ptr, void* vp)
void*TObject::operator new(size_t sz)
void*TObject::operator new(size_t sz, void* vp)
void*TObject::operator new[](size_t sz)
void*TObject::operator new[](size_t sz, void* vp)
TH2PolyBin&operator=(const TH2PolyBin&)
virtual voidTObject::Paint(Option_t* option = "")
virtual voidTObject::Pop()
virtual voidTObject::Print(Option_t* option = "") const
virtual Int_tTObject::Read(const char* name)
virtual voidTObject::RecursiveRemove(TObject* obj)
voidTObject::ResetBit(UInt_t f)
virtual voidTObject::SaveAs(const char* filename = "", Option_t* option = "") constMENU
virtual voidTObject::SavePrimitive(ostream& out, Option_t* option = "")
voidTObject::SetBit(UInt_t f)
voidTObject::SetBit(UInt_t f, Bool_t set)
voidSetChanged(Bool_t flag)
voidSetContent(Double_t content)
virtual voidTObject::SetDrawOption(Option_t* option = "")MENU
static voidTObject::SetDtorOnly(void* obj)
static voidTObject::SetObjectStat(Bool_t stat)
virtual voidTObject::SetUniqueID(UInt_t uid)
virtual voidShowMembers(TMemberInspector& insp) const
virtual voidStreamer(TBuffer&)
voidStreamerNVirtual(TBuffer& ClassDef_StreamerNVirtual_b)
virtual voidTObject::SysError(const char* method, const char* msgfmt) const
Bool_tTObject::TestBit(UInt_t f) const
Int_tTObject::TestBits(UInt_t f) const
TH2PolyBin(const TH2PolyBin&)
TH2PolyBin(TObject* poly, Int_t bin_number)
virtual voidTObject::UseCurrentStyle()
virtual voidTObject::Warning(const char* method, const char* msgfmt) const
virtual Int_tTObject::Write(const char* name = 0, Int_t option = 0, Int_t bufsize = 0)
virtual Int_tTObject::Write(const char* name = 0, Int_t option = 0, Int_t bufsize = 0) const
virtual voidTObject::DoError(int level, const char* location, const char* fmt, va_list va) const

Data Members

static TObject::(anonymous)TObject::kBitMask
static TObject::EStatusBitsTObject::kCanDelete
static TObject::EStatusBitsTObject::kCannotPick
static TObject::EStatusBitsTObject::kHasUUID
static TObject::EStatusBitsTObject::kInvalidObject
static TObject::(anonymous)TObject::kIsOnHeap
static TObject::EStatusBitsTObject::kIsReferenced
static TObject::EStatusBitsTObject::kMustCleanup
static TObject::EStatusBitsTObject::kNoContextMenu
static TObject::(anonymous)TObject::kNotDeleted
static TObject::EStatusBitsTObject::kObjInCanvas
static TObject::(anonymous)TObject::kOverwrite
static TObject::(anonymous)TObject::kSingleKey
static TObject::(anonymous)TObject::kWriteDelete
static TObject::(anonymous)TObject::kZombie
Double_tfAreaBin area
Bool_tfChangedFor the 3D Painter
Double_tfContentBin content
Int_tfNumberBin number of the bin in TH2Poly
TObject*fPolyObject holding the polygon definition
Double_tfXmaxX maximum value
Double_tfXminX minimum value
Double_tfYmaxY maximum value
Double_tfYminY minimum value

Class Charts

Inheritance Inherited Members Includes Libraries
Class Charts

Function documentation

 Default constructor.
TH2PolyBin(TObject* poly, Int_t bin_number)
 Normal constructor.
Double_t GetArea()
 Returns the area of the bin.
Double_t GetXMax()
 Returns the maximum value for the x coordinates of the bin.
Double_t GetXMin()
 Returns the minimum value for the x coordinates of the bin.
Double_t GetYMax()
 Returns the maximum value for the y coordinates of the bin.
Double_t GetYMin()
 Returns the minimum value for the y coordinates of the bin.
Bool_t IsInside(Double_t x, Double_t y) const
 Return "true" if the point (x,y) is inside the bin.
void ClearContent()
{fContent = 0;}
void Fill(Double_t w)
Double_t GetContent() const
{return fContent;}
Bool_t GetChanged() const
{return fChanged;}
Int_t GetBinNumber() const
{return fNumber;}
TObject * GetPolygon() const
{return fPoly;}
void SetChanged(Bool_t flag)
{fChanged = flag;}
void SetContent(Double_t content)
{fContent = content; SetChanged(true);}