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

CATEGORY