Histograms

The Hist class gives a simple implementation of one-dimensional histograms, useful for quick-and-dirty testing, without the need to link to more sophisticated packages. For this reson it is used in many of the sample main programs found in the examples subdirectory.

A Histogram is declared by a

class Hist name( title, numberOfBins, xMin, xMax)
where
argument title : is a string with the title of the histogram at output,
argument numberOfBins : is the number of bin the x range will be subdivided into,
argument xMin : is the lower edge of the histogram,
argument xMax : is the upper edge of the histogram.

For instance

   Hist ZpT( "Z0 pT spectrum", 100, 0., 100.);

Alternatively you can first declare it and later define it:

   Hist ZpT;
   ZpT.book( "Z0 pT spectrum", 100, 0., 100.);

Once declared, its contents can be added by repeated calls to fill

method fill( xValue, weight)
where
argument xValue : is the x position where the filling should occur, and
argument weight (default = 1.) : is the amount of weight to be added at this x value.

For instance

   ZpT.fill( 22.7, 1.);

Since the weight defaults to 1 the last argument could have been omitted in this case.

A set of overloaded operators have been defined, so that histograms can be added, subtracted, divided or multiplied by each other. Then the contents are modified accordingly bin by bin. Thus the relative deviation between two histograms can be found as

  diff = (data - theory) / (data + theory);

assuming that diff, data and theory have been booked with the same number of bins and x range. That responsibility rests on the user; some checks are made for compatibility, but not enough to catch all possible mistakes.

Also overloaded operations with double real numbers are available. Again these four operations are defined bin by bin, i.e. the corresponding amount is added to, subtracted from, multiplied by or divided by each bin. The double number can come before or after the histograms, with obvious results. Thus the inverse of a histogram result is given by 1. / result. The two kind of operations can be combined, e.g.

  allpT = ZpT + 2. * WpT

Finally, also the +=, -+, *=, /= are overloaded, with the right-hand side being either a histogram or a real number.

A histogram can be printed by making use of the overloaded << operator, e.g.:

   cout << ZpT;

The printout format is inspired by the old HBOOK one. To understand how to read this format, consider the simplified example

                                    
        3.50*10^ 2  9                     
        3.00*10^ 2  X   7               
        2.50*10^ 2  X  1X               
        2.00*10^ 2  X6 XX                
        1.50*10^ 2  XX5XX                 
        1.00*10^ 2  XXXXX                
        0.50*10^ 2  XXXXX        

          Contents 
            *10^ 2  31122
            *10^ 1  47208
            *10^ 0  79373

          Low edge  -- 
            *10^ 1  10001 
            *10^ 0  05050

The key feature is that the Contents and Low edge have to be read vertically. For instance, the first bin has the contents 3 * 10^2 + 4 * 10^1 + 7 * 10^0 = 347. Correspondingly, the other bins have contents 179, 123, 207 and 283. The first bin stretches from -(1 * 10^1 + 0 * 10^0) = -10 to the beginning of the second bin, at -(0 * 10^1 + 5 * 10^0) = -5.

The visual representation above the contents give a simple impression of the shape. An X means that the contents are filled up to this level, a digit in the topmost row the fraction to which the last level is filled. So the 9 of the first column indicates this bin is filled 9/10 of the way from 3.00*10^2 = 300 to 3.50*10^2 = 350, i.e. somewhere close to 345, or more precisely in the range 342.5 to 347.5.

The printout also provides some other information, such as the number of entries, i.e. how many times the histogram has been filled, the total weight inside the histogram, the total weight in underflow and overflow, and the mean value and root-mean-square width (disregarding underflow and overflow). The mean and width assumes that all the contents is in the middle of the respective bin. This is especially relevant when you plot a integer quantity, such as a multiplicity. Then it makes sense to book with limits that are half-integers, e.g.

   Hist multMI( "number of multiple interactions", 20, -0.5, 19.5);

so that the bins are centered at 0, 1, 2, ..., respectively. This also avoids ambiguities which bin gets to be filled if entries are exactly at the border between two bins. Also note that the fill( xValue) method automatically performs a cast to double precision where necessary, i.e. xValue can be an integer.

Some further metods are:

getBinContent(iBin) returns the value in bin iBin, ranging from 1 through nBin, with 0 for underflow and nBin + 1 for overflow.
getEntries() returns the number of entries.
table(ostream& = cout) prints a two-column table, where the first gives the center of each bin and the second the corresponding bin contents. This may be useful for plotting e.g. with Gnuplot.
null() resets bin contents.
name( title) resets the title to the new string.
sameSize( Hist&) checks that the number of bins and upper and lower limits are the same as in the histogram in the argument.
takeLog(true) take 10-logarithm of contents bin by bin.
takeLog(false) take e-logarithm of contents bin by bin.