FAINT (Jun93)                  ftools.asca                 FAINT (Jun93)



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