STW2PHA (Apr94)              ftools.caltools             STW2PHA (Apr94)

NAME
    stw2pha  --  converts PHA dataset from stsdas/fitsio/stwfits to OGIP
    standard
    
    
USAGE
    stw2pha infil sofil bofil phafil hduclas2
    
    
DESCRIPTION
    
      This task reads i/p data from a  FITS  file  produced  by  stwfits
    (within  the stsdas/fitsio sub-package of IRAF) assumed to contain a
    1-dimensional PHA histogram, and writes an o/p  FITS  data  file  in
    OGIP  standard format for such a dataset. This involves writing both
    general & instrument-specific information into  the  FITS  file.  If
    desired,  users  may  also include the 'off-axis' histograms for the
    source and/or background regions selected (see below). The o/p  file
    is compatible with all versions of XSPEC higher than 8.2.
    
      THIS  IS  A  BETA-TEST  VERSION  which  has  NOT been exhaustively
    tested  using  files  produced  by  PROS  v2.3.  Instrument-specific 
    information  can  only  be  written for the ROSAT Position Sensitive
    Proportional Counters (PSPCs), High  Resolution  Imager  (HRI);  and
    for  the Einstein Observatory Imaging Proportional Counter (IPC) and
    HRI. Unfortunately the version of the task has  a  somewhat  reduced
    functionality  compared  to  previous  versions when used with files
    produced using PROSv2.3 (see below).
    
      For   further   information   regarding   this    task,    current  
    plans/schedule,  comments  or  bug  reports,  please  contact  Ian M
    George (ftoolshelp@athena.gsfc.nasa.gov).
    
    
    
WARNINGS ON USAGE
    
     A  number  of  changes  were  introduced  into  the  STSDAS  tables 
    produced  by  PROS  v2.3 which are reflected in changes to the files
    produced by stwfits (ie the i/p files to this task).  These  changes
    are  numerous,  but in most cases relatively minor. Unfortunately we
    have not been able to perform exhaustive tests  on  the  task  using
    PROS  v2.3 prior to release. Users who encounter any problems should
    contact the author. (Most effort has been extended to testing  ROSAT
    PSPC  &  HRI  datasets).  We believe full compatibility with earlier
    versions of PROS has been maintained.
    
    
    
CHANGES & KNOWN PROBLEMS ASSOCIATED WITH O/P FROM PROSv2.3
    
    As stated above, a number of the changes  introduced  by  PROS  v2.3
    has  resulted  in  changes to the i/p files to this task. These have
    resulted in changes & problems to this version of the  stw2pha  task
    as follows:
    
    The information concerning the source & background off-axis histrograms 
        are  no  longer  written  as FITS keywords when a PHA dataset is
        exported using stwfits. Instead  separate  source  &  background
        STSDAS  tables  are  constructed.   In  order  to  include  this 
        information within the o/p file from stw2pha, these tables  must
        now  also  be  individually  dumped  to  FITS  using stwfits and
        specified by the new sofil & bofil parameters to stw2pha.
    
    The information concerning the BAL histogram for the Einstein IPC is 
        no longer written  as  FITS  keywords  when  a  PHA  dataset  is
        exported   using  stwfits.  Instead  separate  STSDAS  table  is 
        constructed.  There  is  presently  no  way  to   include   this 
        information in the o/p file from stw2pha.
    
    
    
PARAMETERS
    
    infil [character string]
         The  name  of  the input file (from stwfits) to be converted to
        OGIP-standard  FITS format.
    
    sofil [character string]
         This is an optional parameter for the name of  the  file  (from
        stwfits)  containing  the  off-axis histogram (off-axis angle vs
        fraction of time) of the SOURCE region. If such a  histogram  is
        not  available  or  not  required  to  be present in the o/p PHA
        file, sofil = 'NONE' or ' ' should be entered.
    
    bofil [character string]
         This is an optional parameter for the name of  the  file  (from
        stwfits)  containing  the  off-axis histogram (off-axis angle vs
        fraction of time) of the BACKGROUND region. If such a  histogram
        is  not  available  or not required to be present in the o/p PHA
        file, bofil = 'NONE' or ' ' should be entered.
    
    phafil [character string]
         The name of the OGIP-standard FITS PHA file to be created
    
    (phaversn='1.1.0') [character string]
         The OGIP FITS format version for PHA files  in  which  the  o/p
        FITS   is  to  be   written.  The  default  is  PHAVERSN='1.1.0' 
        (previously known as '1992a'), and is  currently to only  format
        allowed.
    
    hduclas2 [character string]
         A  string  indicating  whether the PHA dataset is a spectrum of
        the source only  ('NET'), background  only  ('BKG'),  or  source
        plus background ('TOTAL').
    
    (origin = 'LOCAL') [character string]
         The  name  of  the organization and/or author running the task.
         The default value is ORIGIN=UNKNOWN.
    
    (chatter = 10) [integer]
         Flag to indicate how chatty the task is at execution.  A  value
        of  10  is  the   default,  with  lower/higher  values producing
        quieter/verbose output  respectively.
    
    (qoverride = NO) [boolean]
         Logical indicating whether the  user  wishes  to  override  the
        deconvolution   of  the  mission  and instrument strings derived
        from the corresponding  string supplied in the SF file. This  is
        often  necessary  since  the  task  only performs a rather crude
        deconvolution itself and since  the  RSP   file  often  contains
        non-OGIP-standard strings, and/or insufficient information.
    
    telescop  [chracter string]
         The  user-supplied  string  for the telescope name, required if
        QOVERRIDE=Y
    
    instrume [character string]
         The user-supplied string for the instrument name,  required  if
        QOVERRIDE=Y
    
    filter [character string]
         The  user-supplied  string  for the name of any moveable filter
        in use,  required if QOVERRIDE=Y.   FILTER=NONE should  be  used
        if on such moveable filter is in use.
    
    detnam  [character string]
         The  user-supplied string for the sub-instrument name, required
        if  QOVERRIDE=Y.     DETNAM=NONE   should   be   used   if   the 
        specification of a sub-instrument is  unneccessary.
    
    (clobber = false) [boolean]
         Flag  specifying  whether  or  not a pre-existing file with the
        same name as that  requested as the output file from  this  task
        will be overwritten.
    
    
BUGS
    None known
    
    
    
SEE ALSO
    OGIP/92-007 (Arnaud etal, 1992, Legacy, 2, 65)
    OGIP/92-007a containing changes to the Arnaud etal article
    
    
    
LOG OF SIGNIFICANT CHANGES
    
    
    v3.0.0 (1994 Feb)
            Botch for compatibility with PROSv2.3
    
    v2.0.0 (1993 Aug)
            Added ROSAT HRI
    
    v1.0.0 (1993 May)
            Public release version
    
    
    
PRIMARY AUTHOR
    
    Ian M George
    HEASARC
    NASA/GFSC
    ftoolshelp@athena.gsfc.nasa.gov
    (301) 286-6094