analycent - plot diagnostics of image centroid motion
analycent options [input file]
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=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.
- --tag=string
-
The prefix used for the output files. This parameter is required.
- --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
-
Be noisy.
- --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.
- --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.
- --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. It defaults to
0.5.
- --hist_r_width=float
-
The width of the bins used to generate the RMS histogram.
It defaults to
0.5.
- --hist_p_width=float
-
The width of the bins used to generate the first - last quartile histogram.
It defaults to
0.5.
- --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.
- --help
-
Output abbreviated usage information and exit.
- --usage
-
Output extensive usage information and exit.
- --version
-
Output version information and exit.
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 parameters 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.
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
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
$Revision: 1.19 $
Diab Jerius (djerius@cfa.harvard.edu)