HepHistProf

class HepHistProf

two-dimensional histogram

A HepHistProf profile histogram is a collection corresponding to (X,Y) pairs of data, binned in the X direction. The assignment of a point (X,Y) to an X bin is based on a uniform partitionings of a specified X ranges. Overflow and underflow bins in X are also tracked.

The information kept in each X bin is a "profile" of the Y values for each entry falling in that bin: The number of entries, the sum of the Y values, and the sum of Y squared. Thus for each X-slice one can retrieve a gaussian distribution reflecting the Y values in that slice.

These are weighted histograms; the accumulate() method takes X, Y and optionally a weight. The number of entries in a bin is actually the sum of weights, and the two sums kept are weighted sums of Y and Y**2.

A closely related class is HepHist2D, which accepts the same form of weighted 2-D points. Assuming the Y values for a given X are gaussian-distributed samples based on some single-valued function, HepHistProf keeps the relevant information in 3 or 4 Nx words, rather than Nx * Ny words -- substantially less space. And, to quote the HBook manual, "... this function is displayed by a profile histogram with much better precision than by a scatter-plot."

Methods

Creating a histogram or histogram array

Accumulating data

Retrieving histogram data

Accessing class information

Histogram arithmetic

Typical uses of this class

Example One

Methods

Creating a histogram or histogram array

Accumulating data

Retrieving histogram data

Accessing class information

Creating a histogram or histogram array

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

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

A fresh HepHistProf:

HepFileManager:: histProf(

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

HepFileManager:: histProf(

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

The errorMethod argument selects which of three possible methods to use when calculating the uncertainty from the spread in Y values.

' '

'S'

'I'

See page 52 of the HBook manual for more explanation.

For example, if m points to the manager, the user might do:


                myhist = m->histProf ( "Pairs", 100, 0.5, 1.5, 0., 9. );

                myhist.accumulate (x,y); 

                // and when finished -- 

                delete myhist;

A fresh HepHistProfArray:

HepFileManager:: histProfArray(

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

HepFileManager:: histProfArray(

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

The errorMethod argument here is the same as for HepHistProf and everything said there applies here as well. Either of these constructors will instantiate a collection of size HepHistProf objects, all with the same values for nBinsX, minX, maxX, minY 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 HepHistProf's. Note that this will "use up" size id's - one for each HepHistProf 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 HepHistProf & so that myhists[k] in the following example is a HepHistProf 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->histProfArray( 10, "X-Y pairs", 100, 0.5, 1.5, 0.0, 9.0 );

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

		
		}

		// and when finished -- 

		delete myhists;

Construct a HepHistProf or HepHistProfArray to access an existing HepHistProf:

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

It is the user's responsibility to supply correct values for size and prefix. As for retrieveHistProf, 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 HepHistProf or HepHistProfArray, including all accumulated data:

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

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

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

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

Create a fresh empty HepHistProf or HepHistProfArray with binning identical to that of this HepHistProf:

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

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

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

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

In both cases, the new HepHistProf or HepHistProfArray 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

Add to the bin corresponding to X, the (weighted) value Y:

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

If Y is not in the range that was specified when the HepHistProf was constructed, this point will be ignored.

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

void reset();

Top | Methods | Related Classes

Retrieving histogram data

The following methods, retrieve the basic statistics collected. The user may interpret those to form error estimates.

For any given bin in X, Various statistical properties of the Y distribution of points in that bin may be retrieved:

Total number of entries:

float entries() const;

Number of entries in X-bin:

float entries(const int binNumX) const;

Error for X-bin:

float binError(const int binNumX) const;

Sum of weight in all bins:

float weight() const;

Sum of squares of weights in all bins:

float weight2() const;

Sum of weight in X-bin:

float weight(const int binNumX) const;

(Weighted) sum of X values

float sumX() const;

(Weighted) sum of Y values

float sumY() const;

(Weighted) sum of Y**2 values

float sumY2() const;

(Weighted) sum of Y values in X-bin:

float sumY(const int binNumX) const;

(Weighted) sum of Y**2 values in X-bin:

float sumY2(const int binNumX) const;

Bin-by-bin sum of weights for all X bins

void getSumW( float * data ) const;

Bin-by-bin sum of weighted Y for all X bins

void getSumWY( float * data ) const;

Bin-by-bin sum of weighted Y*Y for all X bins

void getSumWY2( float * data ) const;

Various other statistical quantities all at one go

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

Retrieve over- and underflow counts

void getOverflows( float * numOver, float * numUnder ) const;

The following two methods are not implemented at this time but the corresponding quantities can all be calculated from other quantities for which accessors do exist.

Retrieve the (weighted) mean value of Y:

float mean(const int binNumX) const;

Retrieve the error or spread:

float uncertainty(const int binNumX) const;

(As calculated based on the errorMethod argument supplied at construction.)

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 HistProf objects, one can say
arrayProf[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 HepHistProf::typeId

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

int nBinsX() const;

float minX() const;

float maxX() const;

float minY() const;

float maxY() const;

The error calculation method selected:

(Not yet implemented)

char errorMethod() const;

Top | Methods | Related Classes

Histogram arithmetic

Add, bin-by-bin

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

Subtract, bin-by-bin

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

Multiply, bin-by-bin

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

Divide, bin-by-bin

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