NAME

analycent - plot diagnostics of image centroid motion

SYNOPSIS

analycent options [input file]

OPTIONS

analycent uses long options. Options may be abbreviated, and the "=" character shown below in the option templates is optional. A command line argument which begins with the @ character is taken to be the name of a file which contains white-space delimited options.

Input Data Specification

--input=file: The input events FITS file. The file may also be specified as the last argument on the command line.
--extname=string: The FITS extension name of the HDU to be read from the input file. It defaults to events
--filter=string: A CFITSIO compatible events filter
--xcol=string --ycol=string --tcol=string: The names of the event position and time columns to use. These default to x, y, and time, respectively.
--gti=file: A CFITSIO compatible file/HDU specification of a good time interval list to apply to the data.
--scale=float: A factor by which the input event positions will be multiplied (for units conversion). It defaults to 1.
--units=string: The position units (after scaling by --scale). For plotting purposes. Defaults to pixels.

Output Options

--tag=string

The prefix used for the output files. This option is not optional.

--device=PGPLOT device

The output plotting device. It defaults to /xs, which plots to the screen. Useful other ones are /cps and /vcps, which are, respectively, landscape and portrait color PostScript output.

Hardcopy will be left in files with extensions of .ps for PostScript, .png for PNG, etc.

--xsid

When plotting to the /xs device, multiple windows are used, one per plot. The starting PGPLOT window id may be specified with this option. It defaults to 5.

--title, --notitle

Do (don't) write a title on the plots. Default is to write the title.

--width=float

Specify the (approximate) width of the resultant plots, in inches.

--verbose, --verbose=level

Be noisy. A verbosity level > 1 will also output progress in reading the input file.

Image Centering Options

--force_ctr: If specified, the point specified by the --xc and --yc options will be used as the center, rather than being determined by an iterative sigma clipping method. The --clip_r option must be set if --force_ctr is used.
--dtol=float: Absolute convergence tolerance for the iterative centering algorithm. It defaults to 0.01.
--iclip=float: The initial centering clipping radius, in scaled position units. It defaults to 1000.
--iter=integer: The number of iterations the centering routine should perform. It defaults to 10.
--nsigma=float: The clipping radius, in units of the standard deviation of the event distribution about the center, used during the iterative centering. It defaults to 3.
--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.

Analysis Options

--nbins=integer: The number of time bins into which to divide the exposure. This defaults to 100. See also --binw.
--binw=float: The time bin width, in seconds. See also --nbins.
--clip_sigma=float: The radius of the circular region around the object used for the analysis, in units of the calculated standard deviation of the event distribution about the center. See also --clip_r. Defaults to 2.
--clip_r=float: The radius of the circular region around the object used for the analysis, in scaled units. See alsc --clip_sigma. This must be specified if --force_ctr is used.
--hist_d_width=float: The width of the bins used to generate the histogram of average distances to the center. By default 25 bins are created.
--hist_r_width=float: The width of the bins used to generate the RMS histogram. By default 25 bins are created.
--hist_p_width=float: The width of the bins used to generate the first - last quartile histogram. By default 25 bins are created.
--hist_d_lim=xmin,xmax,ymin,ymax: Plot limits for the distance histogram. Values not specified will be determined from the data.
--hist_r_lim=xmin,xmax,ymin,ymax: Plot limits for the RMS histogram. Values not specified will be determined from the data.
--hist_p_lim=xmin,xmax,ymin,ymax: Plot limits for the first - last quartile histogram. Values not specified will be determined from the data.

Miscellaneous Options

--help: Output abbreviated usage information and exit.
--usage: Output extensive usage information and exit.
--version: Output version information and exit.

DESCRIPTION

analycent produces some simple diagnostics of the motion of the centroid of a point source as a function of time. It divides an observation into a number of time bins and calculates the events statistics in each bin in a circular region centered about the center of the point source as determined in that bin. (Bins with outrageously large clipping regions (greater than 3 sigma from and iteratively determiend averaged) are not plotted, but are written to the output RDB table).

The input events must be in a binary table extension of a FITS file. CFITSIO is used to extract the data, so the CFITSIO extended filename syntax may be used to filter the data. The event positions may be scaled (to convert to seconds of arc, for example).

The center of the circular region may be specified by the user, via the --xc, --yc and --force_ctr options, or may be determined from the data by centering using a sigma clipping algorithm. In the latter case, an initial position may be specified using --xc and --yc. The options for the centering algorithm may be modified with the --dtol, --iclip, --iter, and --nsigma.

The radius of the analysis region is determined either from the standard deviation of the event distribution about the center, if analycent determined the center and --clip_sigma is specified, or may be given directly via the --clip_r option.

Output

Plots

In the following descriptions, .sfx refers to the filename suffix appropriate to the hard copy format (e.g, .ps, .png)

Event Positions

The X and Y event positions relative to the object's center are plotted. Hardcopy will be left in the file tag_events.sfx.

Time variation of image centroids

The average offset of events from the object's center are determined for each time slice in the circular region and are plotted as a function of time. Hardcopy will be left in a file tag_pts_dist.sfx.

A histogram of the offsets is also provided. Hardcopy will be left in the file tag_hist_dist.sfx

The 2D motion of the events relative to the image centroid is also plotted. Hardcopy will be left in the file tag_pts_motion.sfx.

Time variation of image width.

The RMS of events' positions is determined.

A scatter plot (position vs. time) is sent to tag_pts_rms.sfx. A histogram is sent to tag_hist_rms.sfx.
The difference between the first and last quartile positions is plotted against time in tag_pts_mq.sfx. A histogram is plotted to tag_hist_mq.sfx

Output data

An RDB table is written to tag_stats.rdb with the following columns, one per time bin:

tmin, tmax: The bin limits.
mask: True if the bin was not outrageously out of line, based on the radius of the clipping region used to select events in the time bin.
x_ave, y_ave: The average of the X and Y event positions.
x_cent, y_cent: The iteratively determined center of the positions in the bin
x_fq, y_fq, x_lq, y_lq: The first and last quartiles of the data
x_median, y_median: The median of the data
x_rms, y_rms: The RMS of the data

VERSION

$Revision$

AUTHOR

Diab Jerius (djerius@cfa.harvard.edu)