Histograms

The GBOOK package was written in 1979, at a time when HBOOK [Bru87] was not available in Fortran 77. It has been used since as a small and simple histogramming program. For this version of PYTHIA the program has been updated to run together with PYTHIA in double precision. Only the one-dimensional histogram part has been retained, and subroutine names have been changed to fit PYTHIA conventions. These modified routines are now distributed together with PYTHIA. They would not be used for final graphics, but may be handy for simple checks, and are extensively used to provide free-standing examples of analysis programs, to be found on the PYTHIA web page.

There is a maximum of 1000 histograms at your disposal, numbered in the range 1 to 1000. Before a histogram can be filled, space must be reserved (booked) for it, and histogram information provided. Histogram contents are stored in a common block of dimension 20000, in the order they are booked. Each booked histogram requires NX+28 numbers, where NX is the number of x bins and the 28 include limits, under/overflow and the title. If you run out of space, the program can be recompiled with larger dimensions. The histograms can be manipulated with a few routines. Histogram output is `line printer' style, i.e. no graphics.

Purpose:

to book a one-dimensional histogram.

ID :

histogram number, integer between 1 and 1000.

TITLE :

histogram title, at most 60 characters.

NX :

number of bins in the histogram; integer between 1 and 100.

XL, XU :

lower and upper bound, respectively, on the $x$ range covered by the histogram.

Purpose:

to fill a one-dimensional histogram.

ID :

histogram number.

X :

$x$ coordinate of point.

W :

weight to be added in this point.

Purpose:

to rescale the contents of a histogram.

ID :

histogram number.

F :

rescaling factor, i.e. a factor that all bin contents (including overflow etc.) are multiplied by.

Remark:

a typical rescaling factor could be $f$ = 1/(bin size * number of events) = NX/(XU-XL) * 1/(number of events).

Purpose:

this is a general-purpose routine for editing one or several histograms, which all are assumed to have the same number of bins. Operations are carried out bin by bin, including overflow bins etc.

OPER:

gives the type of operation to be carried out, a one-character string or a CHARACTER*1 variable.

= '+', '-', '*', '/' :

add, subtract, multiply or divide the contents in ID1 and ID2 and put the result in ID3. F1 and F2, if not 1D0, give factors by which the ID1 and ID2 bin contents are multiplied before the indicated operation. (Division with vanishing bin content will give 0.)

= 'A', 'S', 'L' :

for 'S' the square root of the content in ID1 is taken (result 0 for negative bin contents) and for 'L' the 10-logarithm is taken (a nonpositive bin content is before that replaced by 0.8 times the smallest positive bin content). Thereafter, in all three cases, the content is multiplied by F1 and added with F2, and the result is placed in ID3. Thus ID2 is dummy in these cases.

= 'M' :

intended for statistical analysis, bin-by-bin mean and standard deviation of a variable, assuming that ID1 contains accumulated weights, ID2 accumulated weight*variable and ID3 accumulated weight*variable-squared. Afterwards ID2 will contain the mean values (= ID2/ID1) and ID3 the standard deviations ( $=\sqrt{\mathtt{ID3/ID1}-\mathtt{(ID2/ID1)}^2}$). In the end, F1 multiplies ID1 (for normalization purposes), while F2 is dummy.

ID1, ID2, ID3 :

histogram numbers, used as described above.

F1, F2 :

factors or offsets, used as described above.

Purpose:

to print all histograms that have been filled, and thereafter reset their bin contents to 0.

Purpose:

to print out a single histogram.

ID :

histogram to be printed.

Purpose:

to reset all bin contents, including overflow etc., to 0.

ID :

histogram to be reset.

Purpose:

to dump the contents of existing histograms on an external file, from which they could be read in to another program.

MDUMP :

the action to be taken.

= 1 :

dump histograms, each with the first line giving histogram number and title, the second the number of $x$ bins and lower and upper limit, the third the total number of entries and under-, inside- and overflow, and subsequent ones the bin contents grouped five per line. If NHI = 0 all existing histograms are dumped and IHI is dummy, else the NHI histograms with numbers IHI(1) through IHI(NHI) are dumped.

= 2 :

read in histograms dumped with MDUMP = 1 and book and fill histograms according to this information. (With modest modifications this option could instead be used to write the info to HBOOK/HPLOT format, or whatever.) NHI and IHI are dummy.

= 3 :

dump histogram contents in column style, where the first column contains the $x$ values (average of respective bin) of the first histogram, and subsequent columns the histogram contents. All histograms dumped this way must have the same number of $x$ bins, but it is not checked whether the $x$ range is also the same. If NHI = 0 all existing histograms are dumped and IHI is dummy, else the NHI histograms with numbers IHI(1) through IHI(NHI) are dumped. A file written this way can be read e.g. by GNUPLOT [Gnu99].

LFN :

the file number to which the contents should be written. You must see to it that this file is properly opened for write (since the definition of file names is platform dependent).

NHI :

number of histograms to be dumped; if 0 then all existing histograms are dumped.

IHI :

array containing histogram numbers in the first NHI positions for NHI nonzero.

Purpose:

to contain all information on histograms.

IHIST(1) :

(D = 1000) maximum allowed histogram number, i.e. dimension of the INDX array.

IHIST(2) :

(D = 20000) size of histogram storage, i.e. dimension of the BIN array.

IHIST(3) :

(D = 55) maximum number of lines per page assumed for printing histograms. 18 lines are reserved for title, bin contents and statistics, while the rest can be used for the histogram proper.

IHIST(4) :

internal counter for space usage in the BIN array.

INDX :

gives the initial address in BIN for each histogram. If this array is expanded, also IHIST(1) should be changed.

BIN :

gives bin contents and some further histogram information for the booked histograms. If this array is expanded, also IHIST(2) should be changed.