Histogram: A Program for Making Histograms

Andrew D. Lewis andrew@mast.queensu.ca

17 March 1998

1 What does Histogram do?

This documentation is for the program Histogram which will read in a file of numbers and produce a histogram representing that data. I wrote the program mainly to be used with my grading program so I could get histograms for the exams, etc.

You should have three directories and one file in the base directory when you untar the tar file for Histogram:

  1. The files 00readme.txt, histogram.script, histogram.man, Makefile,

and some copyright files.

2. The directory demo which contains files to run a demonstration of the program,

3. The directory doc which contains the TEX source for what you are now reading.

Make sure these are all present upon untarring.

2 Installing and Testing Histogram^{1}

To install Histogram, modify the Makefile so that the BINDIR and MANDIR directories are properly named. Also set PERL to the location of Perl on your system, and DOCDIR so the name of the L^{A}TEX documentation file (with full path). Then type make to set up the files, make install to install the executable in BINDIR. Typing make man will also install a copy of the man page in MANDIR.

If you do not have sed you will have to make the changes to the files yourself.

First copy histogram.script to histogram and histogram.man to histogram.

Then look through these two new files for the string %% as this marks spots where replacing needs to be done. Hopefully it will be obvious what changes need to be made.

1This set up procedure has been performed with SunOS 5.4 and is not guaranteed to work on any other operating system.

You will also need the standard L^{A}TEX graphics package available from CTAN.

To test Histogram to see what it can do, go to the demo directory and type

    histogram data[.dat].

Histogram will read in the file data.dat. Then Histogram will check to see if the file filename.inp is present. If it is, the input data will be read from this file. If this file is not present, the presence of the file hist.inp will be checked. If this file is present, the input data will be read from it. If is it not, data should be entered by hand. However, data.inp is present so Histogram will read from it. If everything works properly, a file histogram.tex will be created. It is ready to have L^{A}TEX applied to it. After this is done, have a look at the dvi file and see what you think. You should get a histogram as in Figure 1. In this histogram the y-axis label is displayed horizontally. When you produce your own histograms, this label will be displayed vertically (at least in PostScript form). Also, documents made with histogram can be written in landscape mode. We will discuss this more later.

3 How to use Histogram

To use Histogram type

    histogram filename(.dat)

where filename.dat is the file containing the numbers you will read in. If this argument is omitted, the data will be read from standard input and output will go to standard output. If the argument is present, the file filename.dat should contain a column of numbers which will be your data. If you are reading from a file (and not standard input), Histogram will check for the file hist.dat to read input parameters from. If this file is not present, the input data will be read from filename.dat. If this file is not present, the data will be read from standard input. If you have read the data from standard input, the input parameters will also have to be entered from standard input. Here are the input parameters:

1. The first thing to enter is the minimum value the data will take. This will be a floating point number which which represents the minimum attainable value for your data. It will also be the lower limit on your plot.

2. The next thing to enter is the maximum value the data will take. This is naturally analogous to the minimum value.

3. The next thing you will enter is the number of different data values you wish to consider. This is also the number of bars in your histogram. It is an integer.

0.0  ^{5.0}  ^{10.0}  ^{15.0}  ^{20.0}^{0}^{1}^{2}^{3}^{4}^{5}^{6}^{7}  Histogram Title X-axis label Y-axis label  Mean = 15.0 Standard Deviation = 2.5

Figure 1: Histogram from demo directory.

4. Next is the minimum value for the y-axis. This does not have to be zero. If is is not zero, then any bars on the histogram lower than this minimum value will not appear. Histogram will warn you of this.

5. The next thing is the maximum value for the y-axis. This is an integer which should reflect the highest bar (plus whatever you want for appearance of the plot).

6. Now you need to enter the tick spacing for the x-axis. A short tick will always be placed in the middle of each bar. What you are entering here is the spacing between the ticks you want to be numbered. This does not have to be an integer divisor of the length of the horizontal scale. It is a floating point number.

7. Next is the vertical tick spacing. It is the same idea as the horizontal tick spacing.

8. Next you enter a title.

9. Next you enter the x-axis label.

10. Now the y-axis label.

11. Next you enter the coordinates of the top left corner of the box containing the statistical information which Histogram computes. Use graph coordinates and enter the pair as x, y.

12. The final entry is either l or p, depending on whether you want the histogram displayed in landscape or portrait format. Generally landscape looks better.

Perhaps the best way to see what the entries in the input file mean is to compare the file data.inp with the histogram it produces in Figure 1.

Histogram will now produce a file histogram.tex. This may be run through L^{A}TEX. The L^{A}TEX package graphics will be requested, so you’d better have this.

4 Usage Notes

Histogram is not very robust and will crash or malfunction with the slightest provocation. So try to not provoke it and follow the below guidelines.

1. The file filename.inp (or hist.inp, if you use it) must have its entries on separate lines.

2. The entries in filename.dat need not take their values in a discrete set. Histogram will produce bars that cover a range of data centred at the specified point. Points halfway between centres go to the rightmost bar. Note, however, that statistics are computed for the histogram and so may differ somewhat from the statistics for the data.

Please send any comments and errors to: andrew@mast.queensu.ca.