Hist2D

class HepHist2D

two-dimensional histogram

A HepHist2D two-dimensional histogram is a collection of bins corresponding (X,Y) pairs. The assignment of a point (X,Y) to a bin is based on uniform partitionings of the specified X and Y ranges. Overflow and underflow bins along all edges are also tracked.

These are weighted histograms; the accumulate() method takes X, Y and optionally a weight, which defaults to 1.0 if no value is presented.

A closely related class is HepHistProf, which accepts the same form of weighted 2-D points, but tracks only the first and second moments of the Y-distribution within each X bin.

Methods

Creating a histogram or histogram array

Accumulating data

Retrieving Hist2D data

Accessing class information

Histogram arithmetic

Typical uses of this class

Example One

Methods

Creating a histogram or histogram array

Accumulating data

Retrieving Hist2D data

Accessing class information

Histogram arithmetic

Creating a histogram or histogram array

The user does not directly instantiate a HepHist2D object. Instead, a reference (a HepHist2D & is obtained by calling the hist2D() method in the manager.

These methods are not methods of HepHist2D but are documented here for convenience.

A fresh HepHist2D:

HepFileManager:: hist2D(

const string& title,
const int nBinsX, const float minX, const float maxX,
const int nBinsY, const float minY, const float maxY,
const int id = 0);

Both the title and the id must be unique within a directory. If the id is 0 (default) then the manager assigns a new unique id to the HepHist2D.
For example, if m points to the manager, the user might do:


                myhist = m->hist2D( "X,Y", 100, 0., 1., 50, 0., 2. );

                myhist.accumulate( x, y ); 

                // and when finished -- 

                myhist.release();

A fresh HepHist2D array:

HepFileManager:: hist2DArray(

const int size,
const string& prefix,
const int nBinsX, const float minX, const float maxX,
const int nBinsY, const float minY, const float maxY,
const int id = 0);

This will instantiate acollectionset of size HepHist2D objects, all with the same values for nBinsX, nBinsY, minX, minY, maxX and maxY. These will have titles made up of the concatenation of prefix with the index into the array. This keeps all the titles unique. Both the prefix and the id must be unique within a directory. If the id is 0 (default) then the manager assigns new unique id's to the collection of HepHist2D's. Note that this will "use up" size id's - one for each HepHist2D object in the array so that, for example, if size = 10 and id = 50, id's 50 through 59 will be taken.
We point out that our operator overload of [] returns a HepHist2D & so that myhists[k] in the following example is a HepHist2D and all of the methods that act on objects of that type are available.
For example, if m points to the manager, the user might do:


		myhists = m->hist2DArray( 10, "X-Y pairs", 1000, 0.5, 1.5, 1000, 0.5, 1.5 );

		for( int k=0; k<10; ++k) {
		
		myhists[k].accumulate(x[k], y[k]); 

		
		}

		// and when finished -- 

		delete myhists;

Construct a HepHist2D refering to one existing in the manager (for retrieval and/or update access):

HepFileManager:: retrieveHist2D( const string& title, const int id=0 );

The method name starts with retrieve to indicate that memory has been allocated and that release() should be invoked when the histogram is no longer needed.
(Information is available about accessing existing histograms.)

Construct a HepHist2DArray refering to one existing in the manager (for retrieval and/or update access):

HepFileManager:: retrieveHist2DArray( const int size, const string& prefix, const int id=0 );

It is the user's responsibility to supply the correct values for size and prefix. As for retrieveHist2D the method name starts with retrieve to indicate that memory has been allocated and that release() should be invoked when the histogram is no longer needed.
(Information is available about accessing existing histograms.)

Copying and Cloning

Clone this HepHist2D or HepHist2DArray, including all accumulated data:

HepHist2D & makeClone( const string title, const int id = 0 );

HepHist2DArray & makeClone( const string title, const int id = 0 );

HepHist2D & makeClone(HepFileManager *mgr, const string& title, const int id = 0);

HepHist2DArray & makeClone(HepFileManager *mgr, const string& title, const int id = 0);

Create a fresh empty HepHist2D or HepHist2DArray with binning identical to that of this HepHist2D:

HepHist2D & makeEmpty( const string title, const int id = 0 );

HepHist2DArray & makeEmpty( const string title, const int id = 0 );

HepHist2D & makeEmpty(HepFileManager *mgr, const string& title, const int id = 0);

HepHist2DArray & makeEmpty(HepFileManager *mgr, const string& title, const int id = 0);

In both cases, the new HepHist2D or HepHist2DArray has either the same manager as the parent either the specified manager, and resides in the current working directory for that manager.

Top | Methods | Related Classes

Accumulating data

Increase the value of the bin for datapoint X,Y by a given weight:

void accumulate( float x, float y, float weight = 1.0 );

Set the contents of all bins and accumulated statistics to zero:

void reset();

Top | Methods | Related Classes

Retrieving class data

Retrieve the value of the bin at X,Y.

float bin(const int binNumX, const int BinNumY) const;

Retrieve the error of the bin at X,Y.

float binError(const int binNumX, const int BinNumY) const;

Total Number of entries:

float entries() const;

Sum of weight in all bins:

float weight() const;

Sum of squares of weights in all bins:

float weight2() const;

(Weighted) sum of X values

float sumX() const;

(Weighted) sum of X**2 values

float sumX2() const;

(Weighted) sum of Y values

float sumY() const;

(Weighted) sum of Y**2 values

float sumY2() const;

(Weighted) sum of X*Y values

float sumXY() const;

Get the contents of all bins

void getContents( float * data ) const;
The array represented by *data must be large enough to hold (nBinsX*nBinsY) data items.

Block fill the histogram contents from the specified array
(Available with the HBook and Root managers only.)

void putContents( float * data ) const;
The array represented by *data must be large enough to hold (nBinsX*nBinsY) data items.

Get the errors of all bins

void getErrors( float * data ) const;
The array represented by *data must be large enough to hold (nBinsX*nBinsY) data items.

Block fill the histogram errors from the specified array
(Available with the HBook and Root managers only.)

void putErrors( float * data ) const;
The array represented by *data must be large enough to hold (nBinsX*nBinsY) data items.

Get various statistics all at once

void getStatistics( int & numEntries, float & sumW, float & sumW2,
double & sumWX, double & sumWX2 ) const;

Get all overflows at once

void getOverflows( float * XOverYOver, float * XOverYUnder, float * XUnderYUnder,
float * XUnderYOver, float * Top, float * Right, float * Bottom, float * Left ) const;

Define centered axis labels (Root only. Dummies otherwise.)

void setXTitle(const string& XTitle) ;

void setYTitle(const string& YTitle) ;

void setZTitle(const string& ZTitle) ;

Define new overall title (Root only. ZMexception otherwise.)
[See a separate note here for some important details about using this function.]

void setTitle(const string& Title) ;
Note. In the case of an array of Hist2D objects, one can say
array2D[i].setTitle("Some string");

Top | Methods | Related Classes

Accessing class information

Title of the Histogram

string title() const;

Directory of the Histogram (internal to file manager)

string dir() const;

HepFileManager managing this Histogram

HepFileManager * Manager() const;

The id (assigned by the manager or user):

int id() const;

The type of the object:

char type() const;

Each class has a static data member named typeId containing its type indentification letter. Only full types (HepNtuple, HepHist1D, HepHist2D, HepHistProf and HepDir, for directories) have one.

For example HepHist2D::typeId

The number of in-range bins and low and high ranges

int nBinsX() const;

float minX() const;

float maxX() const;

int nBinsY() const;

float minY() const;

float maxY() const;

Top | Methods | Related Classes

Histogram arithmetic

Add, bin-by-bin

HepHist2D & operator += ( const HepHist2D & h);

Subtract, bin-by-bin

HepHist2D & operator -= ( const HepHist2D & h);

Multiply, bin-by-bin

HepHist2D & operator *= ( const HepHist2D & h);

Divide, bin-by-bin

HepHist2D & operator /= ( const HepHist2D & h);