OGIP Memo OGIP/95-008

The MATHPHA User's Guide

Ian M George
Code 668,
Greenbelt, MD20771

Version: 1995 Aug 23
MATHPHA v4.0.0


MATHPHA is a task within the HEASARC sub-package

of FTOOLS which allows users to perform mathematical operations on PHA datasets. Here we describe in detail the required user inputs, available commands & current limitations of the task. A number of examples are also provided for illustration.


Release Sections Changed Brief Notes
1995 Mar 30 Original Version
1995 Apr 14 All Update for MATHPHAv3.5.0
1995 Aug 23 3, 8 Update for MATHPHAv4.0.0


MATHPHA takes a user-defined input expression representing mathematical operations to be performed on (one or more) PHA datasets. The input expression is thus allowed to contain PHA filenames (and optionally, an extension number), a number of mathematical operators, integers, reals, and pairs of curved brackets ("(" & ")"). Assuming the expression is able to be parsed (and a number of other criteria are satisfied), the operations specified are performed on the PHA dataset, the errors propagated (see Section 3), and a new file containing the resultant PHA dataset is written.

The units in which the algebra is performed is controlled by a parameter (units; see Section 2), the default of which is COUNTS (as opposed to COUNTS PER SECOND). This is true IRRESPECTIVE of whether the original PHA data themselves are stored as counts or counts per second. The exposure time written for the new PHA dataset is controlled by a user-defined parameter (exposure; see Section 4). Users also have the option of specifying the values written to the o/p file of several other mandatory keywords (see Section 6).

Users should note that MATHPHA is a moderately powerful tool, and thus open to confusion/abuse. Users are strongly urged to read & attempt to fully understand the deatils of the task. In particular, users should understand the implied units for any integers/reals which form part of the input expression, the details of the error propagation, and options available to calculate the exposure time written to the o/p file. Both of these issues are discussed in detail below. Any remaining confusion/uncertainties/strange results should be reported to the author.

At the current time, only a modest number of mathematical operations are possible (as listed in Section 2.1), though it is anticipated that they will serve the vast majority of users' needs. These will be added to as dictated by demand. In addition, due to the relative crudeness of the expression parser, there are number of rules which users must conform to when constructing their input expression (Section 2). Violation of these rules will result in the task (hopefully) stopping, (possibly) crashing, or (maybe even) producing incorrect results.

Only the the OGIP recognised PHA file formats described in OGIP/92-007

(see also Arnaud etal 1992) and its appendix provided in OGIP memo OGIP/92-007a are supported for both the input and output files.


The input expression is a character string (currently with a maximum length of 1024 characters) which forms a mathematical expression consisting of:

Within the constraint of the total number of characters specified above, any number of spaces can be added to the input expression.

2.1  Currently Supported Mathematical Operations

The following mathematical operations are currently supported:

It should be noted that the parser will interpret all characters besides those listed above and the open/close curved brackets/parentheses characters (ie ( and )) as (parts of) input PHA filenames.


There several options open to users regarding the calculation or propagation of errors, controlled by the parameters errmeth and properr.

The (hidden) parameter errmeth controls which prescription is used to calculate errors, should the task need to do so. The value of this keyword is therefore important if the errors are to be propagated (ie properr='yes') and one or more of the i/p files contain the FITS keyword POISERR = T indicating Poissonian statistics should be used to calculate the statistical errors, or if errors are not to be propagated (ie properr='no') and the algebra is performed in counts/sec (ie units='Rate').

Currently, the following prescriptions are available (where N is the number of counts observed in a given PHA channel):

Caution is urged, particularly when using errmeth = 'Gauss', as unexpected and/or misleading results can be produced.

The following tables enables direct comparisons to be made between these approximations:

N true 1-sigma errors calcd using errors calcd
Poisson errors Gehrels approx using √{N}
0 +1.84 -0.00 +1.87 -0.00 +0.00 -0.00
1 +2.30 -0.83 +2.32 -0.67 +1.00 -1.00
2 +2.63 -1.92 +2.66 -1.33 +1.41 -1.41
3 +2.92 -1.63 +2.94 -1.66 +1.73 -1.73
4 +3.16 -1.91 +3.18 -1.94 +2.00 -2.00
5 +3.38 -2.16 +3.40 -2.18 +2.24 -2.24
10 +4.27 -3.11 +4.28 -3.12 +3.16 -3.16
50 +8.12 -7.05 +8.12 -7.05 +7.07 -7.07
100 +11.00 -9.98 +11.00 -9.99 +10.00 -10.00

The (hidden) parameter properr controls whether the errors are to be propagated during the algebra or (if properr='no') whether the errors are simply calculated from the resultant PHA dataset. In the former case, the errors are propagated in the normal manner (e3 = √{[e12 + e22]}). This is an approximation when in the Poissonian regime (ie for low N). Whilst it is true that the variances of the Poissonian distribution are combined in this normal way, confidence limit error bars are not simply related to the variance like they are for Gaussian statistics.

HOWEVER, these approximations work well for all but the smallest N, and is certainly superior to either assuming √{N} errors, or neglecting errors altogther:

Severely misleading and/or incorrect results are possible if the errors are not propagated (ie if properr=no). Turning off error propagation is only reccomended when one is adding non-background-subtracted datasets, and one fully understands the risks.


The value written as the exposure time in the o/p PHA dataset is indicated by a user-defined flag (exposure). This facility provides added flexibility to users, but with a risk of some confusion. It should be remembered however, that if desired, the exposure time given for a PHA dataset can always be reset using the chkey command within the ftools/heasarc task GRPPHA. The following options are currently available:


The area scaling factor is a numerical constant stored in the OGIP-mandatory FITS keyword AREASCAL in the SPECTRUM extension of a PHA file. Details of its use (and misuse) are too varied and complex to be fully described here, but most often it is used to renormalize the response matrix associated with that PHA file within XSPEC. As such the value of the AREASCAL keyword is often unity, but (particularly in the case of older response matrices) can have values of the order of the effective area (in cm2) of the telescope/instrument.

The value written as the AREASCAL keyword in the o/p PHA dataset is determined by a hidden parameter, areascal. The following options are currently available:


There are a number of mandatory keywords required to be present in the header of extension containing the resultant PHA dataset in the o/p file. A number of these are crucial for the correct interpretation of the o/p dataset. The prime example is the value of the EXPOSURE keyword, and as described in Section 4, MATHPHA has a parameter exposure which controls how the value to be written to the o/p file is determined. Similarly MATHPHA compares the values of the AREASCAL keywords found in the i/p files, and attempts to determine the most appropriate value to be written to the o/p file (Section 5). MATHPHA also checks the values of the TELESCOP, INSTRUME, DETNAM, FILTER & CHANTYPE keywords. If there are discrepancies with any of these keywords, MATHPHA will warn the user and writes the appropriate null/default value to the o/p file.

However, there are a number of mandatory keywords associated with 'auxiliary' files, for which MATHPHA is in general unable to calculate 'appropriate' values (since it largely depends upon what the user is attempting to do via the input expression). These keywords are:

(see also OGIP/92-007).

However, for convenience MATHPHA does provide users some opportunity to specify the values to be written to the o/p file via the hidden parameters auxfiles, backfile, backscal, corrfile, corrscal, arfile and rmfile (see also Section 8). The internal logic for MATHPHA regarding these parameters is as follows:

  1. If the auxfiles, backfile, backscal, corrfile, corrscal, arfile & rmfile parameters all have their default value ('NONE'), then the null/default values of the BACKFILE, BACKSCAL, CORRFILE, CORRSCAL, RESPFILE and ANCRFILE keywords will be written to the o/p file. The o/p file will thus have the same values for these keywords as obtained using versions of MATHPHA earlier than v3.5.0.

  2. If the auxfiles parameter is set to one of the files in the i/p expression, then values of the BACKFILE, BACKSCAL, CORRFILE, CORRSCAL, RESPFILE and ANCRFILE keywords written to the o/p file will be taken (ie copied) from the specified i/p file (or set to their null/default values if there is a problem). It should be noted that setting the auxfiles parameter overrides any values specified via the backfile, backscal, corrfile, corrscal, arfile & rmfile parameters such that any values will be ignored.

  3. If the auxfiles parameter is not set (has a value 'NONE'), then if any/all the parmeters backfile, backscal, corrfile, corrscal, arfile & rmfile are set to any of the files in the i/p expression, then values of the corresponding keyword(s) written to the o/p file will be taken (ie COPIED) from the specified i/p file (or set to their null/default values if there is a problem). At the current time, unfortuantely one CANNOT specify the name of (say) the response matrix to be written as the value of the RESPFILE keyword via the parameter rmfile - one can only specify the i/p PHA from which the RESPFILE is to copied to the o/p file.


The parser is written in FORTRAN (!), and converts the user-supplied expression to ÏMG" Reverse Polish (a little-known dialect thought to be understood by but one person on the planet). The parser attempts to identify the various elements of the input expression, and order the mathematical operations and the reading of PHA datasets appropriately. The parser attempts to work out from the last-entered (innermost) bracket-pair. The mathematical expression contained therewithin is evaluated and the answer stored. The parser then moves to the 2nd-to-last bracket-pair. The mathematical expression contained therewithin is evaluated (including the results already calculated, if appropriate), and the answer again stored. This process thus continues until the full expression has been evaluated, and this is the result which is finally written as the output PHA dataset.

7.1  Common Mistakes/Limitations

Users should keep in mind the following constraints/behaviour:

The task will STOP (hopefully with an appropriate error message) if:

Users who encounter/suspect problems with the task are urged to contact the author, but also to experiment with the input expression (by increasing/moving pairs of brackets, and/or performing the required calculation with two or more passes through MATHPHA).

The author, USRA, the OGIP & NASA assume no responsibility for errors resulting from either bugs, or the misuse of this task. However, please report any comments/problems or bugs to Ian M George (george@lheavx.gsfc.nasa.gov).



Unfortunately, the following bugs are known to exist in the current version of the task:


Section incomplete


Information regarding on-line versions of any of the following references with an OGIP Memo number (ie documents starting OGIP/.. or CAL/..) can most easily be found via the WorldWide Web by following the links from the URL:

Most OGIP Calibration Memos of general community interest will eventually appear as articles in Legacy, but are also available on request from The Office of Guest Investigator Programs, Code 668, NASA/GSFC, Greenbelt, MD 20771, USA.

Arnaud, K.A., George, I.M., Tennant, A.F., 1992, Legacy, 2, 65.
(early, published version of OGIP/92-007)

George, I.M., Arnaud, K.A. 1992.

addendum to OGIP/92-007)

Gehrels, N., 1986, ApJ, 303, 336


The following useful links are available (in the HTML version of this document only):

File translated from TEX by TTH, version 3.13.
On 4 May 2004, 12:37.