.help sispi Feb96 ftools.asca
.ih
NAME
sispi -- Fill PI column of ASCA SIS BRIGHT or BRIGHT2 mode data
.ih
USAGE
.ls    sispi datafile calfile
.le
.ih
DESCRIPTION
This task is written specifically to process data from the ASCA
X-ray satellite and requires SIS BRIGHT or BRIGHT2 mode science
file(s) as input.  The Pulse Invariant (PI) column, which exists
in these files but not necessarily populated, will be filled,
or updated, by this task using a SIS gain/CTI history file;
PH to PI conversion formula, the history file format and the actual
values have been/are to be supplied by the ASCA SIS team.

.ih
PARAMETERS
.ls datafile [file name]
The ASCA science FITS file and extension to be processed.  Multiple
files can be processed if given the name of a file containing a list
of file names, preceded by an '@' symbol (e.g., @list).
.le
.ls calfile [file name]
The SIS gain/CTI history file name.  If the site and the user process
has the calibration database set-up, entering 'CALDB' here will ensure
the latest version will be used: this is the preferred access method.
'FTOOLS' is a valid anwer for now, and will use the pre-specified
file name in the refdata area.  'DEFAULT' means the value of
the defSISfile keyword (compatibility with ascalin), or the filename
can be specified explicitly here.  The 'AUTO' option, for use in scripts,
will try CALDB then FTOOLS then defSISfile until it succeeds.
.le
.ls rawxcol [string] (hidden parameters)
The name of the RAWX column.
.le
.ls rawycol [string] (hidden parameters)
The name of the RAWY column.
.le
.ls phacol [string] (hidden parameters)
The name of the PHA column.
.le
.ls gradecol [string] (hidden parameters)
The name of the GRADE column.
.le
.ls idcol [string] (hidden parameters)
The name of the CCD ID column.
.le
.ls picol [string] (hidden parameters)
The name of the PI column.
.le
.ls gainnom [real] (hidden parameters)
The nominal gain value to be used for the PI; negative value
is default, in which case the value found in the gain history file
will be used.  Positive values will be taken as eV/channel and
will supercede the history file value.
.le
.ls offset [real] (hidden parameters)
This parameter allows users to specify an offset (in keV) in the
channel-energy relashipnship.
.le
.ls launch [boolean] (hidden parameters)
Whether to use the time dependent gain/CTI values from the
calibration file (no) or simply use the nominal values at
launch (yes)
.le
.ls verbose [logical] (hidden parameters)
The verbose flag: run time information updates.
.le
.ls history [logical] (hidden parameters)
The history flag - currently this parameter does nothing, as there
are no optional history keywords that SISPI adds.
.le
.ls defSISfile [string] (hidden parameters)
An alternative method of specifying the calfile, used when DEFAULT
was used as calfile name.
.le
.ih
EXAMPLES
.ls sispi s0_clean.evt /ftools/DEC/release/refdata/sisph2pi.fits

To fill the PI column of previously processed SIS BRIGHT science file,
where "s0_clean.evt" is the science file.
.le
.ls sispi gainnom=3.68 offset=-0.024 verbose=yes

These optional keywords allow the user to incorporate results of
gain/offset fitting in XSPEC.  This is a powerful procedure,
and can be dangerous; please use with caution.
The energy vs channel calibration incorporated in sispi is imperfect,
and a slight adjustment in gain and offset may produce an improved
fit.  Since gain command in XSPEC is an approximation, it is
adviseable to feed the results back to the spectrum file, by using
sispi.  To do this, use these keywords with a gainnom value of
3.65 * xspec_gain, and an offset as derived by XSPEC.
.le
.fi
.ih
BUGS
.ls Refdata access routine used in the AUTO option will send an error
message to stderr, if the expected file is not found, which will terminate
XSELECT and ascascreen (and probably other scripts).
.le
.ls The content of the XFORMTYP keyword is not currently checked.
.ih
SEE ALSO
.ls ASCALIN, FAINT
.ih
AUTHOR
.ls Koji Mukai, ASCA GOF, NASA/GSFC.
.endhelp
