F2DHISTO (Jul92) ftools.fimage F2DHISTO (Jul92)
NAME
f2dhisto -- Compute a 2-dimensional histogram from 2 input columns
which give the x and y coordinates of a series of events.
USAGE
f2dhisto infile outfil xbinsz ybinsz xcol ycol xrange yrange or
f2dhisto infile(with outfil and binning)
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.
PARAMETERS
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.
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.
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.
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.
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.
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.
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.
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.
(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.
(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.
(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.
(clobber = no) [boolean]
If true, an existing file with the same name as the requested
output file will be overwritten.
(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.
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.)
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.
BUGS
SEE ALSO
fhisto, fcopy, fcurve, fimgdmp, fim2lst, filenames, binfilter