.help faint Jun93 ftools.asca
.ih
NAME
faint -- Convert faint mode fits data into bright data
.ih
USAGE
faint infile outfile split dfefile maxgrade 
.ih
DESCRIPTION
This task is written specifically to process data from the ASCA X-ray
satellite.
This task will read a vector column with 9 elements or 9 columns of 
faint mode PHA data, convert it to bright
mode data, and writes that column into a new file.  The conversion is done
using the CLASSIFY routine originally developed by K. Yoshida.  Three versions
of this routine are currently available:  5.0 written 6/10/93 by K. Arnaud,
4.0 written 12/1/92 by T. Dotani
or 3.1 written 5/1/91 by K. Yoshida.  The most recent version is the default, 
and includes proper handling of normal and fast mode data, echo removal and 
a "fancy" correction algorithm.
All other columns in 
the converted extension are copied to the new file, as are any additional
extensions and all header information.
Input from FAINTDFE can be used to correct for dark frame error for 
BRIGHT2 mode.  The on-board BRIGHT mode data was changed in include up to
grade 6 events on November 30, 1993 at 7:30 UT.  The BRIGHT mode emulation
in FAINT corrects for this based on the MJD-OBS keyword in the primary
header.

Starting FAINT version 3.5, a new parameter 'zerodef' is read from the
dfefile produced by new FAINTDFE.
The ZERODEF parameter allows the usage of the dfefile not only for
'bright = no' condition, but also for 'bright = yes and zerodef = 2' condition.
.ih
PARAMETERS
.ls infile [file name]
The FITS file and extension from which the faint PHA columns are to be read.
.le                                                                 
.ls outfile [file name]
The new FITS file containing the bright mode data.
.le
.ls split [integer]
The split threshold level desired.  Must be between 0 and 4095.
.le
.ls dfefile [string]
The name of the dark frame error correction file generated by faintdfe. 
If blank, or '-', no dark frame error correction is performed.
DFE values can also be entered by hand.  4 values will be assigned
to chips 0-3 respectively, or a single value will be used for all chips.
The values must be space delimited.  The format of the DFE file is 5
real values, TIME in seconds from MJDREF in the original FITS file
followed by 4 DFE values for chips 0 to 3 respectively.  The DFE value
is valid from TIME until the TIME in the next row.
.le
.ls maxgrade [integer]
The maximum value of the grade to output.
.le
.ls (echo= -99) [real]
The echo fraction to remove.  This parameter is only used for version 5.0
of the classification routine.  A negative value indicates to use the
current recommended values for echo removal as stored in the sis0[1,2,3]echo
and sis1[1,2,3]echo parameters.  Echo=0 performs no removal.
.le
.ls (sis01echo = 1.8401E-2, sis02echo = 8.1934E-3, sis03echo = 1.1954E7) [real]
The current (9/15/95) recommended values for sis0[1,2,3].
avrgt = (TSTART + TSTOP)/2
echo = sis01echo - sis02echo * exp(-avrgt/sis03echo)
(Similar equation applies for sis1[1,2,3]echo parameters.)
.le
.ls (sis11echo = 1.1135E-2, sis12echo = 4.2187E-3, sis13echo = 2.0695E7) [real]
The current (9/15/95) recommended values for sis1[1,2,3].
.le
.ls (version = 5.0) [string]
The version of the classify routine to use in the conversion.  Currently,
versions 5.0, 4.0 and 3.1 are available.  Version 5.0 has optional echo
removal and "fancy" correction algorithm.  Version 4.0 and above has 
different routines for normal and fast mode data.
.le
.ls (qfancy = no) [boolean]
Whether to apply the "fancy" correction algorithm.  This parameter is only used for version 5.0
of the classification routine.
.le
.ls (bright = no) [boolean]
Whether to mimic the ASCA onboard FAINT to BRIGHT conversion.  This uses 
echo=0, maxgrade=4 and qfancy=no (user inputs are ignored for these
parameters), and maps the 0-4096 PHA values to 0-2048 appropriately.
The DATAMODE keyword is set to BRIGHT, but the comment indicates that it was
written by FAINT.
.le
.ls (columns = pha) [string]
The names of the single vector column or the 9 input faint mode pha columns.  
If blank, the value of
'pha0 pha1 pha2 pha3 pha4 pha5 pha6 pha7 pha8' is used.
.le
.ls (phacol = pha) [string]
The name of the BRIGHT2 output PHA column.
.le
.ls (gradecol = grade) [string]
The name of the grade output column.
.le
.ls (abovecol = none) [string]
The name of the above output column.  If the column name is 'none' (the
default), no above column is written.
.le
.ls (timecol = 'TIME') [string]
The name of the input file time column.
.le
.ls (idcol = 'CCDID') [string]
The name of the input file CCD ID column.
.le
.ls (copyall=yes) [boolean]
If yes, the primary array and all other extensions are copied to the
output file.  If no, the extension acted upon will be the first extension
and the extra keywords in the primary array and the the requested
extension will be copied to the output file.
.le
.ls (copyprime=no) [boolean]
Only copy the primary array when creating the output file.  Ignored if
copyall=yes.
.le
.ls (history=yes) [boolean]
Whether to output history keywords to the output file.
.le
.ih
EXAMPLES
1. Calculate the BRIGHT2 mode values using a split threshold of 0, no echo
   removal, with no dark frame error correction, and output grades <= 4.

ft> faint infile.fits outfile.fits 0 '-'  4  echo=0.

2. Calculate the BRIGHT2 mode values as above, and include the above column 
   in the output, and the dark frame error output from faintdfe and standard
   echo correction.

ft> faint infile.fits outfile.fits 0 faintdfe.out  4 abovecol="above"
.ih
BUGS
.ih
SEE ALSO
FAINTDFE
.endhelp
