ftstat HEADAS help file

NAME

ftstat - computes statistics for 2D images and columns in tables.

USAGE

ftstat infile [outfile] [centroid] [clip] [nsigma] [maxiter]

DESCRIPTION

ftstat computes numerical statistics of the input HDU, sending the output to STDOUT or to the optional outfile. If the specified input HDU is a table, then ftstat computes the minimum, maximum, mean, median, mode, standard deviation, sum, and the number of good and null values for each numeric column. If a mode is defined, the number of modes and intensity are also reported. In the event that there is more than one mode, the minimum is reported. If sigma clipping is performed then an indication of whether the clipping converged or not will be printed too. Non-numeric columns are ignored (i.e., columns with TFORMn = A, X, L, C, or M).

If the specified input HDU is a 1-D or 2-D image, then ftstat computes min and max pixel values, the locations of min and max pixel value (in both pixel and world coordinate), mean, median, standard deviation, sum, and the number of good and null pixels. If centroid = YES, then it computes the centroid and sigma centroid of the image as well. If centroid = NO and clip = YES, then an iterative sigma-clipping algorithm is applied to reject outlying pixels before computing the statistics. The clipping iterations are not performed if centroid = YES.

All the statistics are written to output task parameters (e.g. min, max, mean, median, mode, etc.) for use in scripting applications. Use 'plist ftstat' to see the values of all these parameters.

Note that for vector columns, the behavior of ftstat differs from the older utility 'fstatistic': ftstat will compute statistics for the total number of elements, in all of the rows of each column (whereas fstatistic computes on the *sum* of the vector elements in each row, i.e. it reports a mean value which is the mean of all the individual sums in each row).

Currently ftstat does not compute statistics for variable-length vector columns, columns with zero elements, or columns with data types TBIT, TLOGICAL or TSTRING.

PARAMETERS

infile [filename]: Input file name and optional extension name or number enclosed in square brackets of the HDU to be calculated (e.g., 'file.fits[2]' or file.fits[events]'). If no extension is specified, then the first table HDU, or the first non-null image HDU, will be used.
(outfile = STDOUT) [filename]: Optional output text file name for the statistical report. By default the report will be displayed on STDOUT. Precede output file name with an exclamation point, !, (or \! on the Unix command line), to overwrite a pre-existing file with the same name (or set the clobber parameter to YES)
(centroid = YES) [boolean]: Whether to compute the image centroid. (Ignored for table HDUs).
(clip = NO ) [boolean]: Whether to iteratively reject N*sigma outliers and recompute the statistics. Clipping is only performed on IMAGE HDUs if centroid = NO.
(nsigma): If clip = YES, then this is the sigma rejection factor.
(maxiter): If clip = YES, then this is the maximum number of iterations.
(clobber = NO) [boolean]: If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.
(chatter = 1) [integer, 0 - 5]: Controls the amount of informative text written to standard output. Setting chatter = 5 will produce additional diagnostic output.

EXAMPLES

1. Compute the statistics for an input image file file.img.

    ftstat file.img

2. Compute the statistics for a rectangular subset of a FITS image bounded by pixels 200 through 210 in the X dimension, and pixels 300 through 310 in the Y dimension.

    ftstat 'ngc1316o.fits[200:210,300:310]'

3. Compute the statistics for all column in the 'events' table in the input FITS file named 'myfile.fits':

    ftstat 'myfile.fits[events]'

4. Compute the statistics only for the 'X and Y' columns in the 'events' table; The listed column names are separated by semicolons.

    ftstat 'rate.fits[events][col X;Y]'

LAST MODIFIED