NAME

acis_grade_prf - determine grade fraction profile

SYNOPSIS

acis_grade_prf [options] FITS event filename

DESCRIPTION

acis_grade_prf determines the fractional distribution of grades in an ACIS event list as a function of distance from a fiducial position in the image. It also determines a surface brightness profile, as well as the distribution of counts per ACIS frame.

The fiducial position is nominally the center of a point source. The center may be specified, or may be determined by a sigma-clipping centering algorithm. The initial position for that algorithm may be automatically determined.

The events are divided into annuli such that each annulus has a minimum number of events in it. The grade distribution and surface brightness is determined within each annulus.

Plots of the fractional grade distributions, the PSF, and the distribution of frame counts are written to a PGPLOT output device. An RDB table containing the derived data may also be output.

Determining the Object Center

If --force_ctr is specified, the source center is provided by the --xc and --yc options.

If --force_ctr is not specified, the location and scale of the object is determined by iteratively centering on the events. The initial center may be specified in one of the following methods:

--xc

--yc

--pixcent

If none of these methods is specified, the average event position is used.

An initial clip is performed about the initial center, with the clipping radius provided by the --clip parameter. Events outside of a clipping radius are discarded, and the average center is redetermined.

This step is repeated until either the center hasn't changed, or the absolute change in the center is less than the tolerance specified by the --dtol option. After the initial clip, the clipping radius is a multiple of the standard deviation of the events; the --nsigma option specifies the mutiplication factor.

The object, center, and the final clipping radius may be optionally displayed via ds9 by specifying --display.

OPTIONS

acis_grade_prf uses long-style options. Options which take values may be separated from the values by whitespace or the = character.

Input Options

--input=filename: The input event list. This may also be specified as the last argument on the command line.
--rfilter=row filter: An optional CFITSIO compatible filter expression to weed out unwanted rows. If rfilterc is also specified, rfilterc is used to filter data prior to centroiding, but rfilter is used to filter the data for all other uses.
--rfilterc=row filter: A an optional CFITSIO compatible filter expression to weed out unwanted rows prior to determining the centroid. It does not filter the data used for other analysis purposes; for that, use the rfilter option instead.

Output Options

--tag=string

This is a string used to prefix the output plot and rdb files.

--rdb

This indicates that an RDB table containing the fractional grade distribution and the PSF should be written. It will be written to a file with the template tag_gprf.rdb

--device=PGPLOT device

The PGPLOT device to which plots should be output. It defaults to /xs. Hardcopy PGPLOT devices are:

    /ps       landscape PostScript
    /vps      portrait PostScript
    /cps      landscape color PostScript
    /vcps     portrait color PostScript

--pltsplit

If this is specified, each plot is written to a separate window or file. Normally they are written to a single output device.

Clipping, Centering, and Binning Options

--clip=float: This specifies the radius for initial clipping of the data when acis_grade_prf is performing an iterative centroid.
--force_ctr: If true, the center specified by the --xc and --yc options will be used as the center. The --min and --max parameters must be specified in absolute units (rather than as a multiple of the image standard deviation, as this will not be determined).
--dtol=float: Absolute convergence tolerance for the centering algorithm.
--iter=integer: This specifies the number of iterations the centering routine should perform.
--nsigma=float: This specifies the clipping radius, in units of standard deviation, used during the iterative centering stage.
--xc=float: If set, this specifies an initial value (in scaled units) for the X coordinate of the center of the object. See --scale.
--yc=float: If set, this specifies an initial value (in scaled units) for the Y coordinate of the center of the object. See --scale.
--pixcent: If specified, choose the brightest pixel in the image as the initial center. This option optionally takes an integer argument specifying the image size in pixels (the image is square). This defaults to 256.
--nevts=integer: The number of events in each radial annulus. This defaults to 100.
--rmax=float: The radius of a circle enclosing the events to be analyzed. This is done after the center determination.
--hrmax=list: A comma separated list of radii within which to determine the distribution of counts per frame. These are not annuli!

Frame counting options

The number of frames is determined by summing the GTI intervals based on the start/stop columns of the GTI extension in the event list and dividing by the frame time (TIMEDEL) obtained from the event list headers. Optionally, the number of frames can be obtained using a stat1 file.

--stat1=string: An optional level 1 stat1 file to use to determine the number of frames. If a stat1 file is provided, the time column is read, uniq'd (to obtain only one time per frame), intersected with the event list GTI, and the number of elements (number of frames within the GTI) is obtained. This parameter defaults to ``''.

Normalization Options

--normgrade=string: This selects the type of normalization to be used for computing the grade fractions. The choices are 'good' or 'all'.

Plotting/Scaling Options

--axisxfrm=HASH: The hash keys specify the data to which the transformation is to be applied, and the hash value specifies the transformations to be applied to the data. The hash keys can be one of: ``psf'' (PSF profile plot), or ``badgood'' (ratio of bad grades to good grades). The hash value is one of: ``linlin'', ``linlog'', ``loglin'', ``loglog''.

Miscellaneous Options

--verbose: Output more statements thabn normal.
--version: Print the version and exit.
--help: Print a short help message and exit.
--usage: Print a longer help message and exit.

OUTPUT

The fractional grade distribution and PSF are written out as RDB tables.

The RDB table has the following columns

r: The outer radius of the annulus
psf: The surface brightness, in counts / unit^2, where unit is determined from the input file.
psf_err: The Poisson error in the surface brightness
f*: The fraction of total counts in this grade
f*_err: The Poisson error in the fraction.

AUTHOR

Diab Jerius ( djerius@cfa.harvard.edu )