.help addspec Aug95 ftools.heasarc
.ih
NAME
addspec -- adds PHA spectra, bkgd files & combines response matrices
.ih
USAGE
addspec infil outfil qaddrmf qsubback
.ih
DESCRIPTION

  This task is essentially a FORTRAN wrapper for the tasks mathpha, marfrmf
and addrmf. The input is an ASCII file containing a list of PHA datasets to be
added together. The task performs this operation via a call to mathpha, with
several parameters able to be specified by the user. In addition, should the
user so-wish, any background PHA datasets and/or detector redistribution &
ancillary response datasets specified via keywords in the i/p PHA datasets
will be combined appropriately (see below). Thus the final o/p from this task
is the summed PHA file, plus (if possible) an appropriate background PHA file
and/or response matrix. Keywords in the o/p file are updated to specify the
background PHA file and/or response matrix, enabling them to be automatically
read into XSPEC when the o/p PHA is read in.

  Users are WARNED that the addition of different PHA datasets is a dangerous 
exercise, and give rise to very misleading results from subsequent analysis.
The two occasions where the addition of PHA datasets *may* be valid is
.br
.nj
A) to combine PHAs from different observations made by the same detector
of a given source,
.br
.nj
B) to combine PHAs made at the same time by different but "identical" 
detectors.
.br
.ju
In case A), incorrect or misleading results will most likely be produced if
the source exhibits variability (especially spectral variability), and could
easily be produced if the response of the detector changes dramatically
between the epochs of the observation. In case B), incorrect or misleading
results could be produced if the detectors are not actually "identical", and
their reponses differ significantly. In both cases, errors could also be
introduced by the datasets having significantly different backgrounds (rates
or spectra). Users are STRONGLY urged to consider these facts before 
using the task.

  Only the the OGIP-recognised PHA file formats described in Arnaud etal 1992
(Legacy, 2, 65) and its appendix provided in OGIP memo OGIP/92-007a are
supported for both the input and output PHA datasets, and only the
OGIP-recognised RMF & ARF file formats described in George etal 1992 (Legacy,
2, 51) and its appendix provided in OGIP Calibration memo CAL/GEN/92-002a are
supported for both the input and output RMF, ARF & RMF datasets.



.ih
PARAMETERS
.ls infil [character string]
 The name of an ASCII file listing the i/p PHA files to be added. This
ASCII file should be in a format whereby there is one file per line, and
should include the path to each file if it is not in the current working 
directory.
.le
.ls outfil [character string]
 A character string giving the root of the names of the o/p files to be 
created. The task will append a ".pha" to this root in order to construct 
the name of the summed PHA file created, and (if applicable) ".bak"
and/or ".rsp" for the names of the background PHA dataset and/or 
detector response matrice.
.le 
.ls (qaddpha=yes) [boolean]
 This parameter is a place-holder, and currently should always be set to true.
.le
.ls (units=C) [character string]
 This parameter is for the spawns to mathpha. Generally it should be left
with its default value unless you have been instructed otherwise by GOF
personel, or really understand what you are doing. Essentially, it gives the
physical units in which the algebraic expression is to be evaluated (and the
units in which the o/p file will be written). A value of 'C' (ie 'COUNTS' -
the default), or 'R' (ie 'RATE') result in the algebra bing performed in
'COUNTS' and 'COUNTS PER SECOND' space respectively. The algebra will be
performed in this space irrespective of whether the input files contain data
stored in counts or in counts per second (ie, if units='C', then i/p PHA
histograms stored in counts/s will be converted to counts prior to any
mathematical operations being performed). There are a number of alternative
values for this parameter (see the mathpha Users' Gude), but these are
reserved for expert-use only.
.le
.ls qaddrmf [boolean]
 A flag indicating whether the task should try and construct a detector 
response matrix appropriate for the o/p PHA dataset. This can only be 
performed if the i/p PHA datasets contain the necessary paths and names 
of the relevant RMF, ARF or RSP files.
.le
.ls qsubback [boolean]
 A flag indicating whether the task should try and construct a background
PHA dataset appropriate for use with the o/p PHA dataset. This can only be 
performed if the i/p PHA datasets contain the necessary paths and names 
of the relevant background files.
.le
.ls (bexpscale = 1000) [real]
 A scaling factor to be used to avoid "rounding errors" in the background PHA
dataset. This factor is only important when qsubback=yes, units=C, and the
background datasets contain low count rates. In such cases, then this
parameter is a numerical factor by which the background counts (and
statistical errors) are multiplied by, prior to rescaling and addition to
create the o/p background PHA dataset. The exposure time in the o/p background
PHA dataset is also multiplied by this value in order to "correct" for this
procedure. It is recommended that this parameter has a value of at least the
default (bexpscale = 1000).
.le
.ls (properr='no') [character string]
 A flag whether the errors are to propagated during the algebra, or 
(if properr='no') whether the errors are simply calculated from the
resultant PHA dataset. 
.le
.ls (errmeth='POISS-0') [character string]
 A flag indicating what error presciption is to be used should errors need to
calculated by the task at any stage. The following values are currently allowed:
.ls ERRMETH = 'Gauss'
whereby the errors are calculated using SQRT(N).
.le
.ls ERRMETH = 'POISS-0'
(the default) whereby errors are not explicitly calculated and the POISSERR
flag is set to T in the resulting spectrum.
.le
.ls ERRMETH = 'POISS-1'
whereby the algorithm of Gehrels (1986 ApJ, 303, 336) eqn 7
(+ve error) is used.
.le
.ls ERRMETH = 'POISS-2'
whereby the algorithm of Gehrels (1986 ApJ, 303, 336) eqn 11 (-ve error) is
used.
.le
.ls ERRMETH = 'POISS-3'
whereby 0.5  * (POISS-1 + POISS-2) is used
.le
Caution is urged, particularly when using ERRMETH = 'Gauss', as unexpected
and/or misleading results can be produced. See OGIP/95-008 for further details.
.le
.ls (chatter = 9) [integer]
 Flag to indicate how chatty the task is at execution. A value of 9 is the
 default, with lower/higher values producing quieter/verbose output 
 respectively.
.le
.ls (schatter = 5) [integer]
Integer flag to indicate how chatty the spawned tasks will be during their
execution. A value of 5 is the default, with lower/higher values producing
quieter/verbose output respectively.
.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. This 
 parameter is required to be present by the FTOOLS group and NASA/GSFC and 
 provides the same functionality as that described above whereby the o/p 
 filename can be preceeded by "!" at the outfil. It should be noted that
 "!filename" syntax will overwrite any existing files irrespective of the 
 value of the clobber parameter.
.le


.ih
BUGS
This task should still be considered as a BETA test version. Please perform
spot checks and report all potential bugs via http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp.

.ih
SEE ALSO
.br
.nj
OGIP/95-008: The MATHPHA User's Guide
.br
.nj
CAL/GEN/92-002 (George etal 1992 Legacy, 2, 51),
.br
.nj
CAL/GEN/92-002a
.br
.nj
OGIP/92-007 (Arnaud etal 1992 Legacy, 2, 65),
.br
.nj
OGIP/92-007a
.ju

.ih
LOG OF SIGNIFICANT CHANGES

.le
.ls v1.0.1 (1995 Aug)
    Public release version
.le

.ih
PRIMARY AUTHOR

.nj
Ian M George
.br
.nj
HEASARC
.br
.nj
NASA/GFSC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.br
.nj
(301) 286-6094
.ju



.endhelp
