NAME

fhisto -- Bin column data into a histogram or spectrum

USAGE

     fhisto infile outfile column binsz

or

     fhisto infile[with binning specifier] outfile 

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".

PARAMETERS

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.

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.

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.

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.

(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.

(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.

(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.

(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.

(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.

(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.

(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.

(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.

(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.

(wcscol = yes) [boolean]

If true, a FITS column containing the bin center values in WCS format will be generated in the output file.

(outcolx = column name) [string]

The name of the FITS "x - data" column used to store the bin center (raw pixel format) values.

(outcoly = "Y") [string]

The name of the FITS "y - data" column used to store the histogram values.

(outcolz = "ERROR") [string]

The name of the FITS "z - data" column used to store the statistical error.

(outcolw = "X_WORLD") [string]

The name of the FITS "x - data" column used to store the bin center (WCS format) values.

(clobber = no) [boolean]

If true, an existing file with the same name as the requested output file will be overwritten.

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

     
          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

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.

BUGS

SEE ALSO

fcopy, flcol, fdump, fcurve, f2dhisto. fv, the interactive FITS file editor, can also be used to calculate histograms of table columns.

CATEGORY