HepHist1D

class HepHist1D

one-dimensional histogram

A HepHist1D one-dimensional histogram is a collection of bins corresponding to a set of X values. The assignment of a value X to a bin is based on a uniform partitioning of the specified range. Overflow and underflow bins are also tracked.

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

Methods

Generic Histogram

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 HepHist1D object. Instead, a reference (a HepHist1D & is obtained by calling the hist1D() method in the manager.

The following methods are not methods of HepHist1D but are documented here for convenience.

A fresh HepHist1D:

HepFileManager:: hist1D(

const string& title,
const int nBins, const float min, const float max,
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 HepHist1D.
For example, if m points to the manager, the user might do:


		myhist = m->hist1D( "Values of X", 1000, 0.5, 1.5 );

		myhist.accumulate(x); 

		// and when finished -- 

		delete myhist;

A fresh HepHist1D array:

HepFileManager:: hist1DArray(

const int size,
const string& prefix,
const int nBins, const float min, const float max,
const int id = 0);

This will instantiate a collection of size HepHist1D objects, all with the same values for nBins, min and max. 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 HepHist1D's. Note that this will "use up" size id's - one for each HepHist1D 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 HepHist1D & so that myhists[k] in the following example is a HepHist1D 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->hist1DArray( 10, "Values of X", 1000, 0.5, 1.5 );

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

		
		}

		// and when finished -- 

		delete myhists;

A HepHist1D refering to one existing in the manager (for retrieval and/or update access):

HepFileManager:: retrieveHist1D( 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.)

A HepHist1DArray refering to one existing in the manager (for retrieval and/or update access):

HepFileManager:: retrieveHist1DArray( 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 retrieveHist1D, the method name starts with retrieve to indicate that memory has been allocated and that release() should be invoked when the histograms are no longer needed.

Copying and Cloning

Clone this HepHist1D or HepHist1DArray, including all accumulated data:

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

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

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

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

Create a fresh empty HepHist1D or HepHist1DArray with binning identical to that of this HepHist1D:

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

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

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

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

In both cases, the new HepHist1D or HepHist1DArray 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 by a given weight:

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

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

void reset();

Top | Methods | Related Classes

Retrieving histogram data

Retrieve the value of the n-th bin.

float bin(int binNum) const;

Retrieve the error for the n-th bin.

float binError(int binNum) const;

Total Number of entries:

float entries() const;

Sum of weight in all bins:

float weight() const;

Sum of squares of weight in all bins:

float weight2() const;

(Weighted) sum of X values

float sum() const;

(Weighted) sum of X**2 values

float sum2() const;

Sample mean of the in-range values

float mean() const;

Sample variance of the in-range values ( sum2()/2-mean()*mean() )

float variance() const;

Upper and lower-end overflows

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

Fill array with contents of all bins

void getContents (float * values) const;

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

void putContents (float * values) const;

Fill array with errors of all bins

void getErrors (float * errors) const;

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

void putErrors (float * errors) const;

Various statistics all at once

void getStatistics (int& numEntries, float& sumW, float& sumw2, double& sumWX, double& sumWX2) 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 Hist1D objects, one can say
array1D[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 number of in-range bins and low and high ranges

int nBins() const;

float min() const;

float max() const;

Top | Methods | Related Classes

Histogram arithmetic

Add, bin-by-bin

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

Subtract, bin-by-bin

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

Multiply, bin-by-bin

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

Divide, bin-by-bin

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