.help f2dhisto Jul92 ftools.fimage
.ih
NAME
f2dhisto -- Compute a 2-dimensional histogram from 2 input columns which
give the x and y coordinates of a series of events.
.ih
USAGE
f2dhisto infile outfil xbinsz ybinsz xcol ycol xrange yrange
or 
f2dhisto infile(with outfil and binning)
.ih
DESCRIPTION
This task will create a two dimensional histogram in the primary array
of the output file from the data for a particular pair of columns in a
FITS file. 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 "xrange" and "yrange" values will be used to
set the xmin,xmax and ymin, ymax of the histogram. If xrange is input
as ",xmax" or "xmin," then the missing limits are automatically
computed (in the above case xmin and xmax respectively are computed).
The program will also recognize INDEF to indicate that it should
calculate the minimum or maximum.  For example, "INDEF,INDEF" will
cause the program to calculate both xmin and xmax.  The same is true
for "yrange".  Based on the values of the exposure hidden parameter,
the computed histogram will be either the counts, or the count rate.
The output file contains WCS keywords to transform the pixel coordinate
system back to the original data coordinate system.
.ih
PARAMETERS
.ls infile [filename]
The input FITS file name, extension name, rowfilter
and binning written as infile[extension][row filter][binning].
The extension, row filters, and binning are optional. 
The default extension is 1.
.le
.ls outfil [filename]
The output FITS file name.  The histogram will be in the primary array.
It will be ignored if the output file name is given in the infile name. 
In the pre.4.0 version, the corresponding parameter is outfil. 
.le
.ls xbinsz [real]
The size of the bins in the X dimension in data units.  If set to INDEF,
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.
It will be ignored if the binning is given in the infile name. 
.le
.ls ybinsz [real]
The size of the bins in the Y dimension in data units. If set to INDEF,
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.
It will be ignored if the binning is given in the infile name. 
.le
.ls xcol = 'X' [string]
The name of the column containing the X data.
It will be ignored if the binning is given in the infile name. 
.le
.ls ycol = 'Y' [string]
The name of the column containing the Y data.
It will be ignored if the binning is given in the infile name. 
.le
.ls xrange = 'INDEF,INDEF' [min/max string]
The lower and upper limits of X data to include in the histogram.  If only a ,
is specified (default) the program will include all data values.  Separate
lower or upper limits can be specified by requesting INDEF for the limit.  
Alternately, "xmin," will create a
histogram containing all values greater than xmin.
It will be ignored if the binning is given in the infile name. 
.le
.ls yrange = 'INDEF,INDEF' [min/max string]
The lower and upper limits of Y values to include in the histogram.  Separate
limits can be specified as described for xrange.
It will be ignored if the binning is given in the infile name. 
.le
.ls (pixel = 'j') [string]
The pixel size ot the histogram. The valid value is b(for byte), i(for 
short integer), j(for long integer), r(for floating point), or d(for
double precision floating points). The default value is j. However, 
if the expos parameter is set, the default will be d. 
It will be ignored if the binning is given in the infile name. 
.le
.ls (expos = ' ') [string]
The name of the exposure time keyword.  If left blank, the histogram returned
will have the units of counts.  If the exposure time is specified, the 
histogram
will return the count rate (in /sec).
It will be ignored if the binning is given in the infile name. 
.le
.ls (rows = '-') [rowrange]
The range rows to include in the histogram.  All rows are included by default.
It will be ignored if the rowfilter is given in the infile name. 
.le
.ls (clobber = no) [boolean]
If true, an existing file with the same name as the requested output
file will be overwritten.
.le
.ls (copyprime=yes) [boolean] (obsolete)
Whether to copy all additional keywords from the primary array of input
file to the primary array of the output file. This option is no longer supported.
.le
.ih
EXAMPLES 
To make a 2D histogram of the X and Y columns of the second extension
of the file psu0.fits, with 5 units per bin:

  ft>f2dhisto 'psu0.fits[2]' out.fits 5 5 X Y 'INDEF,INDEF' 'INDEF,INDEF'


To create an image from a file you know very little about (other than the fact that the EVENTS table is in the second extension)

  ft>f2dhisto 'psu0.fits[2]' out.fits INDEF INDEF X Y 'INDEF,INDEF' 'INDEF,INDEF'

(Note the quotes around the input file name.)

.ih
NOTES:
Due to the conflicts with the cfitsio library, the copyprime parameter 
are disabled. The user can use the tools cphead to copy the header of
the  primary array to the header of the histogram.

F2DHISTO 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.  If the upper limit of X and/or Y is not specified, the
program will automatically do this for you.

F2DHISTO uses dynamic memory allocation so that the entire array is in
memory at one time.  If too large an array is requested for the available
memory, an error will be reported.
.ih
BUGS
.ih
SEE ALSO
fhisto, fcopy, fcurve, fimgdmp, fim2lst, filenames, binfilter
.endhelp
