SISRMG (Apr97)                 ftools.asca                SISRMG (Apr97)



NAME
    sisrmg -- SIS Response Matrix Generator
    
    
USAGE
    sisrmg infile arfile rmfile
    
    
DESCRIPTION
    This task generates  the  SIS  response  matrix  appropriate  to  an
    instrument  parameter  regime  as  defined  by keywords found in the
    infile FITS header.  If an ancillary response  file  is  found,  its
    energy  space  information  will  be  used to construct the response
    matrix.  Otherwise, hidden parameters  are  used  to  construct  the
    energy space for the resulting response matrix file.
    
    
STANDARD USAGE
    It  is recommended that the user run SISRMG on XSELECT-generated PHA
    files to ensure that all information required  to  reliably  produce
    the proper matrix is present in the input PHA file.  For example:
    
      sisrmg s0c1.pha NONE s0c1.rmf
    
    Optional command line parameters are available to modify the matrix.
    
    
PARAMETERS
    
    infile [file name]
        The  name  of  the  PHA  file  for which a matrix is to be made.
        Alternate possibilities are described below.
    
    arfile [file name]
        The name of the  ancillary  response  file.   If  this  file  is
        missing  the  energy  domain  of  the matrix will be constructed
        from the emin, emax and ebin hidden parameters.
    
    rmfile [file name]
        The name of the output SIS response matrix file.
    
    
OPTIONAL PARAMETERS
    
    
MATRIX CONSTRUCTION OPTIONS
    
    (vers) [real]
        The response version  to  use.   The  current  version  is  1.1;
        however,  versions  0.8  and  0.9  are  available  for  backward 
        compatibility.
    
    (datadir) [dir name]
        Directory  containing  the  various  SISRMG  calibration  files. 
        Ignored for files specified as "CALDB".
    
    (ecdata) [file name or "CALDB"]
        ECD  FITS  calibration  file:  separate  files are used for each
        detector, chip and split  threshold  combination.   If  "CALDB",
        use  the  ECD  files  from the Calibration Database.  Otherwise,
        look for the named file in datadir.
    
    (phtopi) [file name or "CALDB"]
        CTI FITS calibration file: contains the gain history  and  other
        CTI  related  data.   If  "CALDB",  use  the  CTI  file from the
        Calibration Database.  Otherwise, look for  the  named  file  in
        datadir.
    
    (echosh) [file name or "CALDB"]
        ECHO  FITS  calibration  file:  contains  the  echo history.  If
        "CALDB", use  the  ECHO  file  from  the  Calibration  Database.
        Otherwise, look for the named file in datadir.
    
    (rddhis) [file name or "CALDB"]
        RDD   FITS   calibration   file:   contains  the  residual  dark 
        distribution history.  If "CALDB", use the  RDD  file  from  the
        Calibration  Database.   Otherwise,  look  for the named file in
        datadir.
    
    (phmin) [integer]
        The minimum pulse height for which response is to be generated.
    
    (phmax) [integer]
        The maximum pulse height for which response is to be  generated.
        Note  that the phmin and phmax parameters refer to the intrinsic
        SIS ADU scale before any compression for telemetry  (BRIGHT  and
        FAST  modes) and any rebinning.  Thus these values are typically
        0 and 4095.
    
    (sisde) [boolean]
        Determines whether the SIS detector efficiency  is  included  in
        the matrix.  The default (yes) is to include it.
    
    (sispi) [boolean]
        Determines  whether  the  output  response  matrix is to be used
        with PI channels.  The default (no) is  generate  a  matrix  for
        the  actual  instrument  PHA.   This  parameter  is ignored if a
        valid PHA/PI file is used.
    
    (gains) [integer]
        A parameter which controls the smoothness of the  energy  to  PH
        mapping  in  the  EBOUNDS  extension.   A  value  of  zero  (the 
        default)  gives  a  piecewise  linear  function   tracking   the 
        energy-ph   peak  in  the  response;  the  values  1-12  provide 
        increasing smoothness of this function; the values  -1  gives  a
        linear  function between the endpoints; and the value -2 gives a
        linear function of the mean slope.
    
    (first) [integer]
        The naming  convention  for  the  pulse  height  channels.   The
        intrinsic  SIS pulse height numbering (ADU's) starts with 0, but
        earlier versions of XSPEC and RBNPHA favored a  value  of  1  as
        the   first   channel.    Either   convention   works,  provided 
        consistent information is passed via  the  TLMIN/TLMAX  keywords
        in the PHA and RMF files.
    
    
ENERGY SPACE OPTIONS
    
    (ebin) [integer]
        If  no  ARF  is provided, SISRMG will generate a simple ARF with
        unit effective area based on the values of ebin, emin and  emax.
        If ebin is positive, the energy range is partitioned in a linear
        fashion; if it is  negative,  logarithmically  spaced  bins  are
        used.   If  ebin  is  zero,  these  values  are  taken  from the
        telescope ascii file, if available.   Such  a  file  contains  a
        list   of   triplets:  energy,  telescopy  effective  area,  and 
        tranmission  factor.   By  setting  the   effective   area   and 
        transmission  to  unity, you can construct an RMF with virtually
        any energy domain.
    
    (emin) [real]
        The minimum of the energy range for which response is desired.
    
    (emax) [real]
        The maximum of the energy range for which response is desired.
    
    
PHA FILE OPTIONS
    
    (epch) [real]
        The epoch (time  in  ASCA  seconds)  of  the  observation.   The
        optional  parameters  in  this  section  supply information that
        should be obtained from the PHA file.  Use 0.0 if unknown.
    
    (cmode) [integer]
        CCD clocking mode:  use 1, 2 or 4 for 1CCD, 2CCD or  4CCD  mode,
        and use 0 for FAST mode.  Use 3 if unknown.
    
    (detr) [integer]
        The detector:  0 for SIS0 and 1 for SIS1.  Use 2 for unknown.
    
    (chip) [integer]
        The chip:  0, 1, 2 or 3.  Use 4 if unknown.
    
    (xcen) [real]
        The mean RAWX coordinate of the photons.  Use 0 if unknown.
    
    (ycen) [real]
        The mean RAWY coordinate of the photons.  Use 0 if unknown.
    
    (xwid) [real]
        The  width  (in  RAWX)  of  the  region  of  interest.  Use 0 if
        unknown.
    
    (ywid) [real]
        The width (in RAWY)  of  the  region  of  interest.   Use  0  if
        unknown.
    
    (evth) [integer]
        The event threshold, usually at least 100.  Use 0 if unknown.
    
    (spth) [integer]
        The  split  threshold,  usually  40.   A split threshold on echo
        corrected FAINT data is also supported.  Use 0 if unknown.
    
    (grades) [string]
        A list of the digits 0..7 signifying the grades present  in  the
        spectrum, or UNKNOWN.  (Cf. gmask.)
    
    (rebin) [string]
        A  string  describing  the  degree  and type of rebinning of the
        channels: 1,2,4,8  correspond  to  4096,  2048,  1024,  and  512
        channel  linear  spectra;  1b,  2b,  4b,  8b correspond to 2048,
        1024, 512 and 256 channel trilinear (BRIGHT mode) spectra.   Use
        UNKNOWN if not known.  (Cf. gmask.)
    
    (dmode) [string]
        The  datamode:   one  of BRIGHT, BRIGHT2, FAST or UNKNOWN.  (Cf.
        gmask.)
    
    (gmask) [string]
        The information of the parameters grades, rebin, and  dmode  may
        be  coded  in the single parameter gmask as follows.  Gmask is a
        hexadecimal union of flags which  specifies  which  event  types
        are  present,  and  in  which  fashion  the  PH data is has been
        encoded, including any rebinning.  The flags are:
        
                Faint PH encoding               0x0001  ( 0 < PH < 4095 )
                Faint/Bright Singles            0x0002  ( Grade 0 )
                Faint/Bright Single+Corner      0x0004  ( Grade 1 )
                Faint/Bright Vertical Split     0x0008  ( Grade 2 )
                Faint/Bright Left Hor. Split    0x0010  ( Grade 3 )
                Faint/Bright Right Hor. Split   0x0020  ( Grade 4 )
                Faint/Bright Split+Corner       0x0040  ( Grade 5 )
                Faint/Bright L & Square         0x0080  ( Grade 6 )
                Faint/Bright Others             0x0100  ( Grade 7 )
                Fast/Bright PH encoding         0x0200  ( 0 < PH < 2047 )
                Fast Singles                    0x0400  ( Grade 0 )
                Fast Others                     0x0800  ( Grade 1 )
                Log2 of Rebin Factor            0xR000  (R == 0,1,2,... )
        
        Sample choices:
        
                Faint Singles        (1024ch)   0x2003
                Faint Grades 0,2-4    (512ch)   0x303b
                Faint Grades 0,2-4,6 (4096ch)   0x00bb
                Bright Singles       (1024ch)   0x1202
                Bright Grades 0,2-4   (512ch)   0x223a
                Fast Singles         (1024ch)   0x1600
        
    
    (rddcorv) [integer]
        The version of  RDD  correction  code  applied:   0  implies  no
        correction  was made before the spectral file was created (hence
        corrections are applied in making the matrix), a positive  value
        is  the  version  number  of the correcting code, and a negative
        value implies the version should be determined  from  the  input
        PHA  file.   This parameter is ignored with a valid PHA/PI input
        file.
    
    (zerodef) [integer]
        The mode of dark frame correction employed by FAINTDFE:   0  for
        the  old  FAINTDFE  behavior,  1  for  the  new  behavior, 2 for
        emulation of onboard BRIGHT  mode,  and  3  for  unknown.   This
        parameter is ignored with a valid PHA/PI input file.
    
    (echo) [real]
        Echo  factor, if known.  (A nonzero value signifies echo-corrupt
        data; the correct value is obtained from the secular history.  A
        zero  value  indicated  echo-corrected data.)  The extreme value
        1.0 signifies unknown.
    
    (dark) [real]
        Average dark frame error.  FAINT mode data should  be  corrected
        with  FAINTDFE.   In  the  case  of  BRIGHT  mode, or FAINT data
        requiring further correction, this  parameter  may  be  used  to
        introduce  an  offset  to  the  PH scale in the response matrix.
        The extreme value 100. signifies unknown.
    
    (leak) [real]
        The effects of a true light leak (an  additional  broadening  of
        the  response  features)  may  be emulated by positive value for
        this parameter.  The extreme value 100. signifies unknown.
    
    (clobber) [boolean]
        This parameter makes it possible to overwrite the  output  file,
        should it exist.
    
    (chatr) [string]
        SISRMG  can  produce  copious  output  describing  the  response 
        generation progress.  You can control the amount of output  with
        this  parameter:  no  output  (no),  some  output (yes), copious
        output (lots), or output on  specific  aspects  of  the  process
        using a hexadecimal union of flags:
        
                What                            flag    no      yes     lots
                Echo inputs to terminal         0x0001                  *
                Calibration info echoed         0x0002                  *
                Response Calculation echoed     0x0004          *       *
                Ebounds Calculation echoed      0x0008          *       *
                Put RMF in FITS Primary (+)     0x0010                  *
                Put Inputs in FITS Primary      0x0020          *       *
                Echo XRT EA information         0x0040
                Echo RQT info in FITS Primary   0x0080          *       *
                Factor ARF into RMF             0x0100
                Calibration commentary          0x0200          *       *
        
        (+)  A  FITS  image of the matrix is produced in addition to the
        normal binary table extensions.
    
    
    
USAGE WITHOUT A PHA FILE
    SISRMG may be used without an input PHA file in one  of  two  modes.
    It  is  recommended to use a small number of energy bins to minimize
    the turn-around time while experimenting with these options.
    
    In the first mode, you may supply all the  information  that  should
    have been found in the PHA file with parameters on the command line:
    
      sisrmg NONE NONE s0c1.rmf ...
    
    In  the second mode, you may use any input FITS file that contains a
    suitable set of RQ* keywords.  These keywords are  typically  copied
    to  the  primary  header of matrices generated by SISRMG, so you can
    actually  use  an  existing  matrix  as  the  input  for  subsequent 
    invocations of SISRMG.
    
    Note  that  SISRMG reads its parameter interface first, then the PHA
    file, and then  looks  for  RQ*  keywords  only  if  there  is  some
    problem.   If  these  keywords  are found, they override other input
    (i.e. the parameter interface).
    
    
    The RQ* keywords are:
    
      RQVERS  calibration version--the current version is VERSION.
      RQEPCH  the time of observation in ASCA seconds.  This is used
              to correct gain, echo and RDD secular effects.
      RQEVTH  the event threshold for identifying events
      RQSPTH  the split threshold used in classifying events
      RQXCEN/RQYCEN mean RAWX/Y coordinate for CTI gain correction
      RQXWID/RQYWID width about mean (currently ignored)
      RQTEMP  focal plane temperature (currently ignored)
      RQEVPF  events per frame (currently ignored)
      RQIMHI  image clock hi (currently ignored)
      RQIMLO  image clock lo (currently ignored)
      RQECHO  the amount of echo corruption present in the data.  If nonzero,
              then the appropriate echo value will be obtained from the
              secular file named by RQEHIS.  If this keyword is not present,
              or if the named file does not exist, then the value given in
              RQECHO is used.
      RQLEAK  allows for the inclusion of an average light leak in the
              response.  This produces both a gain shift as well as a
              broadening of certain spectral features.
      RQDARK  used to indicate whether FAINTDFE was applied to clean up faint
              mode data.  If zero, then it is assumed FAINTDFE was applied;
              however, there are known problems with the calibration in this
              case.  If RQDARK is nonzero, then SISRMG will consult the
              file named by RQRDDH for RDD data.  If this keyword is missing,
              or if the named file does not exist, then internal heuristics
              are used.  The actual nonzero RQDARK value is ignored.
      RQDETR  0 or 1 for SIS0 or SIS1.
      RQCHIP  0-3 for chips 0, 1, 2 or 3.
      RQMODE  F, 1, 2, 4 for Fast, 1-CCD, 2-CCD or 4-CCD mode data.
      RQPMIN  minimum intrinsic PH [ADU] in the response
      RQPMAX  minimum intrinsic PH [ADU] in the response
      RQMASK  mask of response features to include (Cf. gmask)
      RQCHTR  level of chattiness during execution
      RQEBIN  number of energy bins in response domain
      RQEMIN  minimum input energy for response domain
      RQEMAX  maximum input energy for response domain
      RQFRST  conventional first output PH channel; should be 1
      RQGANS  controls smoothing of data in EBOUNDS extension.
      RQDEFF  forces inclusion of detector efficiency when nonzero
      RQDOPI  forces generation of PI matrices when nonzero.  Note:
              although the PI gain is time-independent, the resolution
              and other characteristics of the response are secular.
      RQRDCV  External RDD Correction Version: <0,0,>0 == Unknown,None,Applied
      RQDFEZ  FaintDFE style 0,1,2 == Old,New,Bright
      RQFIL0  ascii ARF file
      RQFIL1  ECD gaussian data files
      RQFIL2  high ph tail files
      RQFIL3  grade branching adjustment files
      RQDIR0  root directory of SIS data files
      RQGECD  ECD FITS data file
      RQPHPI  CTI gain transformation file
      RQEHIS  Echo secular history file
      RQRDDH  Residual Dark Distribution history file
    
    
    
    
BUGS
    A complete, new interface has been introduced for SISRMG v1.0.   All
    known bugs were fixed for v1.1.
    
    Please  forward  comments,  feedback,  etc.  to  the  author  of the
    software, Geoffrey Crew, gbc@space.mit.edu.
    
    
SEE ALSO
    Documentation for XSPEC, various OGIP documents, the  other  Ftools,
    http://heasarc.gsfc.nasa.gov/docs/asca,   http://space.mit.edu/~gbc,  
    etc.
