addspec HEADAS help file

NAME

addspec -- adds PHA spectra, bkgd files & combines response matrices

USAGE

        addspec infil outfil qaddrmf qsubback

DESCRIPTION

This task is essentially a FORTRAN wrapper for the tasks mathpha, ftmarfrmf and ftaddrmf. 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 input PHA datasets will be combined appropriately (see below). Thus the final output from this task is the summed PHA file, plus (if possible) an appropriate background PHA file and/or response matrix. Keywords in the output file are updated to specify the background PHA file and/or response matrix, enabling them to be automatically read into XSPEC when the output 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

A) to combine PHAs from different observations made by the same detector of a given source,

B) to combine PHAs made at the same time by different but "identical" detectors.

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.

Note that this tool implicitly assumes case A) in that it adds together the exposure times of the PHA files instead of the effective areas. This means that for case B) the count rate will be incorrect and the exposure time and effective areas should be adjusted after running the tool.

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.

Note that the similarly-named ASCA task addascaspec is more specialized than addspec. addascaspec was specifically written for the case of simultaneous observations by two essentially identical telescopes. For example, addascaspec would be appropriate for co-adding NuSTAR FPMA and FPMB for the same observation, whereas addspec is more appropriate for adding data from the same detector at different times.

PARAMETERS

infil [character string]

The name of an ASCII file listing the input 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. Note that any whitespace leading or trailing the PHA file name(s) may result in addspec failing to find the correct file(s). Also note that filenames containing the reserved arithmetical symbols for addition ("+"), subtraction ("-"), or multiplication ("*") - or containing parentheses ("(" or ")") - will likely be misinterpreted by mathpha as operators and cause the task to fail.

outfil [character string]

A character string giving the root of the names of the output 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.

(qaddpha=yes) [boolean]

This parameter is a place-holder, and currently should always be set to true.

(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 output 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 input 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.

qaddrmf [boolean]

A flag indicating whether the task should try to construct a detector response matrix appropriate for the output PHA dataset. This can only be performed if the input PHA datasets contain the necessary keywords (RESPFILE, ANCRFILE) specifying the paths and names of the relevant RMF, ARF or RSP files.

qsubback [boolean]

A flag indicating whether the task should try to construct a background PHA dataset appropriate for use with the output PHA dataset. This can only be performed if the input PHA datasets contain the necessary keyword (BACKFILE) specifying the path and name of the relevant background file for each.

(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 output background PHA dataset. The exposure time in the output 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).

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

(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:

ERRMETH = 'Gauss': whereby the errors are calculated using SQRT(N).
ERRMETH = 'POISS-0': (the default) whereby errors are not explicitly calculated and the POISSERR flag is set to T in the resulting spectrum.
ERRMETH = 'POISS-1': whereby the algorithm of Gehrels (1986 ApJ, 303, 336) eqn 7 (+ve error) is used.
ERRMETH = 'POISS-2': whereby the algorithm of Gehrels (1986 ApJ, 303, 336) eqn 11 (-ve error) is used.
ERRMETH = 'POISS-3': whereby 0.5 * (POISS-1 + POISS-2) is used

Caution is urged, particularly when using ERRMETH = 'Gauss', as unexpected and/or misleading results can be produced. See OGIP/95-008 for further details.

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

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

(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 output 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.

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.

LOG OF SIGNIFICANT CHANGES

v1.0.1 (1995 Aug): Public release version

PRIMARY AUTHOR

     Ian M George
     HEASARC
     NASA/GFSC
     http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp