.help stw2pha Apr94 ftools.caltools 
.ih
NAME
stw2pha -- converts PHA dataset from stsdas/fitsio/stwfits to OGIP standard
.ih
USAGE
stw2pha infil sofil bofil phafil hduclas2
.ih
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).

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

.ih
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:
.ls 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. 
.le
.ls 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.
.le

.ih
PARAMETERS
.ls infil [character string]
 The name of the input file (from stwfits) to be converted to OGIP-standard 
 FITS format.
.le
.ls 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.
.le
.ls 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.
.le
.ls phafil [character string]
 The name of the OGIP-standard FITS PHA file to be created
.le 
.ls (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.
.le
.ls 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'). 
.le
.ls (origin = 'LOCAL') [character string]
 The name of the organization and/or author running the task.
 The default value is ORIGIN=UNKNOWN.
.le
.ls (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.
.le
.ls (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.
.le
.ls telescop  [chracter string]
 The user-supplied string for the telescope name, required if QOVERRIDE=Y
.le
.ls instrume [character string]
 The user-supplied string for the instrument name, required if QOVERRIDE=Y
.le
.ls 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.
.le
.ls 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.
.le
.ls (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.
.le
.ih
BUGS
None known

.ih
SEE ALSO
.br
.nj
OGIP/92-007 (Arnaud etal, 1992, Legacy, 2, 65)
.br
.nj
OGIP/92-007a containing changes to the Arnaud etal article
.ju

.ih
LOG OF SIGNIFICANT CHANGES

.ls v3.0.0 (1994 Feb)
    Botch for compatibility with PROSv2.3
.le
.ls v2.0.0 (1993 Aug)
    Added ROSAT HRI
.le
.ls v1.0.0 (1993 May)
    Public release version
.le

.ih
PRIMARY AUTHOR

.nj
Ian M George
.br
.nj
HEASARC
.br
.nj
NASA/GFSC
.br
.nj
ftoolshelp@athena.gsfc.nasa.gov
.br
.nj
(301) 286-6094
.ju



.endhelp
