.help sqaplot May93 ftools.asca
.ih
NAME
sqaplot -- SIS quick analysis ftool.
.ih
USAGE
sqaplot infile device
.ih
DESCRIPTION
Produce quick plot of image, pha spectrum, light curve
and diagnostic information for SIS science files.
.ih
PARAMETERS
.ls infile [file name]
The name of the science input file.  Currently only Faint and Bright
mode data are supported.
.le 
.ls device [string]
The name of a PGPLOT device name (e.g., /xw for xwindow, /xt for xterm,
/ps for PostScript, or /null to skip the plot altogether).
.le
.ls (outfile) [file name]
The name of the file in which to place some commentary on the infile.
This file includes ascii listings of the PHA Spectrum, Light Curve
and Flickering Pixel Distribution.
Special cases are "STDOUT", which produces an abbreviated commentary to
the standard output, "NONE", " ", or "/dev/null" which skip it altogether,
and DEFAULT, which will generate a file name from the input file name,
replacing the ".fits" extension with ".evt".  Note that the current version
doesn't copy the GTI extension to this new events file, nor does it use or
modify the GTI information from the input science file.
.le
.ls (eventfile) [file name]
The name of a file in which to copy valid events, i.e., events which
are not considered to be flickering pixels, which are not from telemetry
saturated frames, and with grades less than maxgrade.  In the case of
Faint science files, grading and ph summation will have been performed.
Thus, sqaplot with plotting device /null can be used to filter event files.
.le
.ls (flicker) [string]
A comma-delimited list of flickering pixel thresholds for each of the
four SIS chips:  only pixels with less than this number of events will
be included in the various plots.  The default, "0,0,0,0" invites the
program to make its own estimate of an appropriate choice per chip.
.le
.ls (range) [real]
Pixels with this fraction of the maximum number of counts will receive
the foreground color in the SIS image plot.
Typically, this should be less than one, since
most pixels have few counts.
.le
.ls (contours) [int]
This gives the number of contours to apply to a smoothed version of
the image histogram.
Unless there are a large number of counts, it's probably best to stick
with the default, 0, meaning no contours.
.le
.ls (smooth) [int]
This sets the number of times the image is smoothed before contouring.
Obviously, this is only needed if the image is to be contoured.
.le
.ls (split) [int]
Split threshold to be applied when grading Faint mode events.
.le
.ls (echos) [string]
A comma-delimited list of echo corrections to apply for each instrument.
.le
.ls (style) [int]
The number of pixels to be echo-corrected; typically one.
.le
.ls (maxgrade) [int]
The maximum grade of interest.  For this Quick Analysis application,
only events exceeding this grade are discarded.
.le
.ls (telemetry) [boolean]
Determines whether events from saturated telemetry frames are to be
discarded.  Typically, if the telemetry frame is holding near the maximum
possible number of events, most are background, light leak, or flickering
pixel events.
.le
.ls (maxcounts) [int]
If the above telemetry saturation flag is in effect, a maximum counts per
second threshold can be imposed to further restrict the number of allowed
events beyond what is allowed from telemetry considerations.
.le
.ls (pichip) [real]
Controls PHA to PI processing of events.  If this value is set to a valid
instrument.chip combination (0.0, 0.1, 0.2, 0.3, 1.0, 1.1, 1.2, 1.3) then
the plotted (and outfile) spectra will have been converted to a PI scale
corresponding to that chip.  Otherwise (1.4) the actual ADU values will
be used in the plots and output.  Note that the PI scale is merely a
useful heuristic, and not well calibrated.
.le
.ls (phtopi) [string]
Name of calibration file containing PH to PI transformation information.
If the file exists, this will supersede the effect of the pichip parameter.
.le
.ls (echohist) [string]
Name of calibration file containing the secular echo corrections.
If the file exists, it supersedes the effect of the echos parameter.
.le
.ls (rawdisplay) [boolean]
Controls the orientation of the image corresponding to raw ccd coordinates
(i.e. looking down on the detector) or detector coordinates (i.e. looking
through the detector at the sky) for "yes" and "no", respectively.  In
either case, the plot is constructed from the RAWX and RAWY addresses in
the science file.
.le
.ls (mode) [string]
The usual.
.le
.ih
EXAMPLES
.nf

  sqaplot ft930329_1109_1109S100101M.fits /xw
  sqaplot ft930329_1109_1109S100101M.fits /ps range=0.2
  sqaplot ft930329_1109_1109S100101M.fits /null flicker="3,3,3,3" \
	outfile=DEFAULT eventfile=DEFAULT

.fi
will successively produce an Xwindow summary of the data in this file,
a PostScript file (with the grayscale tweaked) suitable for printing
on a grayscale device, and event and output files
ft930329_1109_1109S100101M.evt and
ft930329_1109_1109S100101M.out with a restrictive flickering pixel
threshold of 3 applied to each chip.
.ih
BUGS
Under development; contact Geoffrey Crew (gbc@space.mit.edu) for details.
For some purposes it may be useful to run the program several times to
get the flickering thresholds and image parameters correct.  In particular,
if the flickering pixel distribution is atypical, all bets are off for
the automatic selection of thresholds.
.ih
SEE ALSO
gqaplot
.endhelp
