NAME

faint -- Convert faint mode fits data into bright data


USAGE

        faint infile outfile split dfefile maxgrade 

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.


PARAMETERS

infile [file name]
The FITS file and extension from which the faint PHA columns are to be read.

outfile [file name]
The new FITS file containing the bright mode data.

split [integer]
The split threshold level desired. Must be between 0 and 4095.

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.

maxgrade [integer]
The maximum value of the grade to output.

(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.

(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.)

(sis11echo = 1.1135E-2, sis12echo = 4.2187E-3, sis13echo = 2.0695E7) [real]
The current (9/15/95) recommended values for sis1[1,2,3].

(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.

(qfancy = no) [boolean]
Whether to apply the "fancy" correction algorithm. This parameter is only used for version 5.0 of the classification routine.

(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.

(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.

(phacol = pha) [string]
The name of the BRIGHT2 output PHA column.

(gradecol = grade) [string]
The name of the grade output column.

(abovecol = none) [string]
The name of the above output column. If the column name is 'none' (the default), no above column is written.

(timecol = 'TIME') [string]
The name of the input file time column.

(idcol = 'CCDID') [string]
The name of the input file CCD ID column.

(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.

(copyprime=no) [boolean]
Only copy the primary array when creating the output file. Ignored if copyall=yes.

(history=yes) [boolean]
Whether to output history keywords to the output file.


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"


BUGS


SEE ALSO

FAINTDFE

CATEGORY

Jun93 ftools.asca