HepHistProf
class HepHistProf
twodimensional 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 Xslice
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 2D points.
Assuming the Y values for a given X are gaussiandistributed samples
based on some singlevalued 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 scatterplot."
Typical uses of this class
#include "HepTuple/HepHistProf.h"
// and possibly
#include "HepTuple/HepHistProfArray.h"
Methods
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.
' '
 <(Default)> Spread normalized by
1/sqrt(N)
'S'
 Spread, not normalized.
'I'
 Spread, normalized, and
if spread is 0, assume Y values represent uniform data
rounded to the nearest integer.
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;
Both the title and the id must be unique within a directory.
If the id is 0 (default), the manager assigns a new
unique id to the HepHistProf.
 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, "XY 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;
Both the prefix and the id must be unique within a directory.
If the id is 0 (default), the manager assigns a new
unique id to the HepHistProf.

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 Xbin:
 float entries(const int binNumX) const;
 Error for Xbin:
 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 Xbin:
 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 Xbin:
 float sumY(const int binNumX) const;
 (Weighted) sum of Y**2 values in Xbin:
 float sumY2(const int binNumX) const;
 Binbybin sum of weights for all X bins
 void getSumW( float * data ) const;
 Binbybin sum of weighted Y for all X bins
 void getSumWY( float * data ) const;
 Binbybin 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 inrange 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:
 char errorMethod() const;
Top
 Methods
 Related Classes
Histogram arithmetic
 Add, binbybin
 HepHistProf & operator += ( const HepHistProf & h);
 Subtract, binbybin
 HepHistProf & operator = ( const HepHistProf & h);
 Multiply, binbybin
 HepHistProf & operator *= ( const HepHistProf & h);
 Divide, binbybin
 HepHistProf & operator /= ( const HepHistProf & h);
Related Classes
Top
 Methods
 Examples
 Related Classes
Return to Zoom Histograms Package Documentation
Jason Luther,
Walter Brown
and
Mark Fischler
Last modified: Thu Sep 4 14:35:23 CDT 1997