thistogram: Make a histogram of a column in a table.

Package: nttools

Usage

thistogram intable outtable column

Description

This task generates a histogram of the values in a column. The histogram may be written to STDOUT or to a table. If there is more than one table in the input list then a separate histogram is generated for each table. If there is more than one input table and the histogram of the values in all the tables combined is needed, then the tables should first be merged using the 'tmerge' task with the 'option' parameter set to "append".

If x1 and x2 are the lower and upper limits of a particular bin, a value X will be included in the bin if x1 <= X < x2. Note that this also applies to the upper limit ('highval') of the last bin.

There are six interrelated parameters having to do with the number of bins, bin width, and bin locations. Any number of these may be specified as long as the values are consistent. As a minimum, only one value is required, either 'nbins' or 'dx'. The task computes what it doesn't have based on the parameters that were specified, or based on the minimum and maximum data values in the table column if necessary. If the minimum (maximum) column data value is used, that value will normally be reduced (increased) a bit before being used as 'lowval' ('highval') to ensure that the value is included in the range. The relationships between the parameters is as follows:

dx = (highval - lowval) / nbins
dx = (chigh - clow) / (nbins - 1)
clow = lowval + dx / 2
chigh = highval - dx / 2

Parameters

intable [file name template]: A list of input tables. A histogram will be generated for one column in the table; the same column name is used for each table in the list. The name of the column is specified using the 'column' parameter,

outtable = STDOUT [file name template]: Output tables or STDOUT. If the value of this parameter is "STDOUT" then the histogram will be written to the standard output preceded by a header line (beginning with "#") that gives the number of rows included in the histogram and the name of the table. If 'outtable' is passed a file name, then the number of names must match the number of file names in 'intable', and the histogram of each input table will be written to an output table of the specified name.

column [string]: Column name in input tables that will be used to generate the histogram. Only the values in the column with this name will be used. The same column name is used for each input table.

(nbins = 100) [integer, min=1]: Number of bins in the histogram. Normally either 'nbins' or 'dx' (or both) must be given. You could also give both 'lowval' and 'clow', or both 'chigh' and 'highval', since the bin width can be computed from these.

(lowval = INDEF) [real]: Lower limit for histogram. Values below 'lowval' will not be used in generating the histogram. If 'lowval = INDEF', then the minimum value in the table column will be used.

(highval = INDEF) [real]: Upper limit for histogram. Values equal to or greater than 'highval' will not be used in generating the histogram. If 'highval = INDEF', then the maximum value in the table column will be used.

(dx = INDEF) [real]: Bin width.

(clow = INDEF) [real]: Value at the center of the first bin.

(chigh = INDEF) [real]: Value at the center of the last bin.

(rows = -) [string]: Range of rows to use for generating the histogram. The default "-" means that all rows are used. (Type "help xtools.ranges" for more information.)

(outcolx = value) [string]: Column name for bin centers. If the output is written to a table rather than to STDOUT, then 'outcolx' is the column name containing the bin centers. This column will be double precision.

(outcoly = counts) [string]: Column name for histogram values. If the output is written to a table then 'outcoly' is the column name containing the number of counts in the bin. This column will be of integer data type.

Examples

1. Generate a histogram of the values in the 'flux' column in every table whose name begins with "hr"; put all the histograms in the ASCII file 'hist.lis'.

tt> thistogram hr*.tab STDOUT flux > hist.lis

2. Generate the same histograms as in the previous example, but put the results in tables rather than displaying them on the terminal screen. One output file is produced for each input table; for example, the histogram for an input table 'hr465.tab' would be put in 'hr465h.tab'.

tt> thistogram hr*.tab hr*%%h%.tab flux

3. Plot the histogram of column 'V' in 'bs.tab':

tt> thistogram bs STDOUT V | sgraph (crvstyle="pseudohist")

4. Plot the same histogram as in the previous example, but set the spacing between bins to be 0.1.

tt> thistogram bs STDOUT V nbins=INDEF dx=0.1 | \\
>>>   sgraph (crvstyle="pseudohist")

Bugs

References

This task was written by Phil Hodge.