.help fhisto May92 ftools.futils
.ih
NAME
fhisto -- Bin column data into a histogram or spectrum
.ih
USAGE
fhisto infile outfile column binsz

or

fhisto infile[with binning specifier] outfile 
.ih
DESCRIPTION
This task creates a histogram or spectrum of the values in a specified
column.  The tool accepts two interfaces, either the FITS extended file
name or the original parameter interface.  The syntax of the FITS
extended file name can be found in the CFITSIO User's Guide or by
reading the 'filenames' and 'binfilter' ftools help files.  For the
parameter interface, the histogram is based on the input binsize and
requested low and high values.  The default values of low of high is
determined by TLMIN and TLMAX keywords.  If these keywords do not
exist, then they will be calculated from the data.  The default bin
size is the value of TDBINx keywords.  If this keyword does not exist,
then it will be calculated to result in at least 10 histogram bins.
The histogram is written out to a FITS binary table extension.  This
extension will be appended at the end of an existing FITS file or at
the extension 1 for a new FITS file.  This extension contains four
columns: the bin center values in raw pixel format, (default name
column name), the histogram value (default name Y), an error column
(default name Error) containing the statistical error, and the bin
center values in WCS format.  The fourth column may be omitted by
setting the hidden parameter "wcscol" to the value "no".
.le
.ih
PARAMETERS
.ls infile [filename]
The name of the FITS file, extension number/name, rowfilter and 
binning written as infile[ext][rowfilter][binning]. 
The rowfilter and binning are optional. The default extension 
is 1.
.le
.ls outfile [filename]
The name of the output FITS file containing the bin values.  If the first
character is a !, an existing file of the same name will be overwritten.
.le
.ls column [string]
The name of the column in the FITS file to be binned. This option will 
be ignored if the binning is given in the infile name.
.le
.ls binsz  [double]
The size of the bins to use in histogram.  If INDEF is specified, 
the values of the TDBINn keywords will be used. If the TDBINn keywords
do not exist, the default binsize will be set to 1, or (max - min) / 10., 
whichever is smaller.
This option will be ignored if the binning is given in the infile name.
.le
.ls (copyprime=yes) [boolean] (obsolete)
If true, all of the primary header keywords, the primary array (if any)
and all of the extension keywords of the input file are copied to 
the output file.  If false, only minimal headers are created. 
This option is no longer supported.
.le
.ls (copyall=no) [boolean] (obsolete)
If true, all of the additional extensions are copied to the output file.
The primary header and array are also copied.  If copyall is true, the
value of copyprime is ignored. This option is no longer supported.
.le
.ls (minkw = " ") [string]
The name of the FITS minimum keyword to be used in assignment of
lower bin values.  If blank or "-", no assignment is performed.
This option will be ignored if the binning is given in the infile name.
.le
.ls (maxkw = " ") [string]
The name of the FITS maximum keyword to be used in assignment of
upper bin values.  If blank or "-", no assignment is performed.
This option will be ignored if the binning is given in the infile name.
.le
.ls (lowval=INDEF) [double]
The lower limit for the histogram.  If the value is INDEF, the program will
determine the minimum from the data.
This option will be ignored if the binning is given in the infile name.
.le
.ls (highval=INDEF) [double]
The upper limit for the histogram.  If the value is INDEF, the program will
determine the maximum from the data.
This option will be ignored if the binning is given in the infile name.
.le
.ls (extname = " ") [string]
The name of the FITS extname keyword to be placed in the output FITS
file containing the histogram data. The default name is "1dhisto". 
If the outfile exists, and are not required to be overwritten, 
then this extension will be appended at the end of the outfile.  
Otherwise, it will be the first extension.
.le
.ls (exposure = " ") [string]
The name of the FITS exposure keyword to be used in normalization of
bin values.  If blank, no normalization is performed.
This option will be ignored if the binning is given in the infile name.
.le
.ls (rows = "-") [string]
The range of rows to be histogrammed.  The default of - means do all rows.
The first ten rows could be specified as ROWS=1-10 or just ROWS=-10.
To do the first ten rows and all rows from 900 through the last
(inclusive), use ROWS=-10,900-.  ROWS=1,3,7,23 will do only
those four rows.  It is not an error to specify rows larger than the
largest row number; they will simply be ignored.
This option will be ignored if the rowfilter is given in the infile
name.
.le
.ls (wcscol = yes) [boolean]
If true, a FITS column containing the bin center values in WCS format will be
generated in the output file.
.le
.ls (outcolx = column name) [string]
The name of the FITS "x - data" column used to store the bin center (raw
pixel format) values. 
.le
.ls (outcoly = "Y") [string]
The name of the FITS "y - data" column used to store the histogram values. 
.le
.ls (outcolz = "ERROR") [string]
The name of the FITS "z - data" column used to store the statistical error. 
.le
.ls (outcolw = "X_WORLD") [string]
The name of the FITS "x - data" column used to store the bin center (WCS
format) values. 
.le
.ls (clobber = no) [boolean]
If true, an existing file with the same name as the requested output file
will be overwritten.
.le
.ih
EXAMPLES
1.  Bin the data in the Label4 column of the third extension of the file
'data.fits' to hist.fits into bins 10 units wide ranging from 10 to 500
.nf

     ft> fhisto data.fits[3] hist.fits Label4 10 lowval=10 highval=500 
or 
     ft> fhisto data.fits[3][bin Label4=10:500:10] hist.fits

2.  As above, but with little knowledge of the values

     ft> fhisto data.fits[3] hist.fits Label4 INDEF
or 
     ft> fhisto data.fits[3][bin Label4] hist.fits

.fi
.ih
NOTES:
FHISTO bins the parameters as real values.  Included in each bin are values
greater than and equal to the lower limit of the bin and less than the upper
limit.  When binning integers, to have values exactly equal to the 
upper limit included, specify an upper limit one bin size greater than the
desired upper limit.

Due to the conflicts with the cfitsio library, the  copyall and 
copyprime are disabled. The user can use the tools fappend to copy 
the extensions from the original input file. Copying  keywords 
from primary arrray or other extensions of the original input file can 
be done by using cphead.
 
.ih
BUGS
.ih
SEE ALSO
fcopy, flcol, fdump, fcurve, f2dhisto.  fv,  the interactive FITS file
editor, can also be used to calculate histograms of table columns.

.endhelp
