HEADAS help file

NAME

ftmathpha -- performs mathematical operations on spectrum files

USAGE

ftmathpha expression units outfile exposure areascal properr errmeth divzero auxfiles backfile backscal corrfile corrscal arffile rmffile comments chatter clobber

DESCRIPTION

This task performs mathematical operations on one or more spectrum files. The expression parameter can contain spectrum filenames (and optionally, an extension number), arithmetic operations (i.e. "+", "-", "*", "/"), integers, reals, and pairs of parentheses ("(" & ")"). The units parameter determines whether the algebra is performed in counts or counts/sec. Note that this is irrespective of whether the spectra themselves are stored in counts or counts/sec. The exposure and areascal parameters control what is written to the exposure and areascal keywords in the output file. These can be set to a specific value, read from a file, or for exposure calculated based on the exposure keywords in the files used in the expression. The statistical errors for the output spectrum can either be calculated based on the errors in the input spectra and the arithmetic expression (properr=yes) or calculated from the counts in the output spectrum (properr=no). In the latter case the error calculation method is controlled by the errmeth parameter. If an operation in the expression requires a divide by zero for any bin in the spectrum then the result can be set using the divzero parameter. Note that this is a moderately powerful tool and thus open to confusion and/or abuse. Make sure that you understand what your parameter choices mean. In particular, confusion can arise from the implied units for any numbers which form part of the expression, the details of error propagation (if selected), and the choice of the output exposure time.

RULES GOVERNING THE CONSTRUCTION OF THE INPUT EXPRESSION

The input expression is a character string which forms a mathematical expression consisting of:

filenames: If the filename contains mathematical operators (such as / for the directory path) then the filename must be enclosed in quotes to prevent the parser interpreting the filename as a mathematical operation. A specific extension of the input file containing the spectrum to be operated on can be specified by including the integer extension number in square ("["extn#"]") brackets after the filename. If such a specification is not used, then the entire file will be searched and the first SPECTRUM extensions used. Very long expressions on the command line are limited by the parameter interface however this can be worked around by placing the expression in a text file and setting the expression as "@" followed by the file name.
Allowed mathematical operations: The mathematical operators currently allowed "+". "-", "*", and "/". Any character which is not in this list, and which cannot be interpreted as (part of) an integer or real, will be interpreted as a filename, or part thereof. Users should adhere to standard mathematical conventions when constructing the input expression to ensure that operations are carried out in the desired order. It should be noted that in the case of a 'sub-expression' consisting of a series of multiplication and/or division operations on filenames and/or numerical constants (ie where the sub-expression does not contain either "+", "-", "(" or ")" characters), these operations will be carried out working from left-to-right. Thus the sub-expression "4/2*6" will result in a value of "12".
Numerical constants (reals and/or integers): For internal purposes, the parser interprets all integers as reals, thus the inclusion/exclusion of the decimal point for whole numbers is of no consequence. If a number is given in scientific notation (e.g. 1.0e-5) or is negative then the number must be enclosed in quotes. Remember that the units of any numerical constants added to or subtracted from spectrum are assumed to be in the units specified by the parameter units", irrespective of whether the original spectra themselves are stored as counts or counts/sec.
Matching pairs of curved brackets (parentheses): Curved brackets should be used in the standard mathematical manner to denote the priority in which various calculations are performed. For safety, the task will stop if the number of open-brackets (() does not equal the number of close-brackets()). The only limitations currently in place are that neither the first nor last entry within a pair of brackets is a mathematical operator, in which case the task should stop.

Any number of spaces can be added to the input expression.

CALCULATION & PROPAGATION OF ERRORS

There are several options for calculating or propagating errors, controlled by the parameters errmeth and properr. The first decision to make is whether errors should be propagated (properr='yes') or calculated. If errors are propagated then the errors on the output file are calculated from the errors on the input files according to the input expression. This is straightforward for additions and subtractions of spectra but when multiplications or divisions are involved the results are approximations and should be interpreted with great caution. If errors are being propagated then any spectrum with Poisson errors will be treated as Gaussian with sigma of SQRT(N). If the errors are not propagated then the errors assigned to the output spectrum are specified by the errmeth parameter. If the input spectra all have Poisson errors and the spectra are only added or multiplied by a constant then errmeth=POISS-0 should be used set POISSERR=T in the output file. If spectra are subtracted this will not be valid because the difference of two Poisson distributions is not itself Poisson. Divisions or multiplications of files rend the resulting errors meaningless in this case. There are a number of other options for errmeth but they are not recommended and are listed below for historical interest. Assuming that N is the number of counts observed in a given channel:

ERRMETH = 'POISS-1': uses the algorithm of Gehrels (1986 ApJ, 303, 336) eqn 7 with S=1: error = 1.0 + SQRT(N + 0.75)
ERRMETH = 'POISS-2': uses the algorithm of Gehrels (1986 ApJ, 303, 336) eqn 11, with S=1: error = SQRT(N - 0.25)
ERRMETH = 'POISS-3': uses the mean of the errors given by POISS-1 and POISS-2 above.

Note that severely misleading and/or incorrect results are possible if the errors are not propagated (ie if properr=no). If data are not Poisson then error propagation should be turned on.

CALCULATION OF THE EXPOSURE TIME IN THE OUTPUT SPECTRUM

The value written as the exposure time in the output spectrum is controlled by the exposure parameter. The following options are currently available:

exposure = 'NULL': an exposure time of 1 second is used.
exposure = filename: the exposure time is read from the specified file.
exposure = real value: the exposure time is set to the specified value.
exposure = 'CALC': the exposure time is calculated from the input expression by sustituting each filename with its exposure time.

CALCULATION OF THE "AREA SCALING FACTOR" FOR THE OUTPUT SPECTRUM

The area scaling factor is a numerical constant stored in the mandatory FITS keyword (or vector) AREASCAL in the SPECTRUM extension of a spectrum 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 spectrum within XSPEC. As such the value of AREASCAL is often unity, but (particularly in the case of older response matrices) can have values of the order of the effective area (in cm^2) of the telescope/instrument. A vector AREASCAL can also be used in grating spectra to correct for a varying width extraction region. The parameter areascal determines the value written to AREASCAL in the output spectrum. The following options are currently available:

areascal = 'NULL'

an AREASCAL of 1.0 used.

areascal = filename

the AREASCAL is read from the specified file.

areascal = real value

the AREASCAL is set to the specified value.

areascal = %

the following logic is employed. If the values of AREASCAL in all the input files:

are the same within <1%: this value (actually the mean) will be used.
differ by >1%: an AREASCAL of 1.0 is written to the output file.

Essentially, if you don't see warning messages regarding AREASCAL during execution, don't worry about it. If you do, and the values in the various intput files vary dramatically and you don't understand why, then you should check whether the input expression was really that which you intended.

DETERMINATION OF THE AUXILIARY FILES FOR THE OUTPUT SPECTRUM

There are a number of mandatory keywords required in the header of the SPECTRUM extension in the output file. A number of these are crucial for the correct interpretation of the output spectrum. The prime example is the value of the EXPOSURE keyword, and as described above, ftmathpha has a parameter exposure' which controls how the value to be written to the ouput file is determined. Similarly ftmathpha compares the values of the AREASCAL keywords found in the input files, and attempts to determine the most appropriate value to be written to the output file. ftmathpha also checks the values of the TELESCOP, INSTRUME, DETNAM, FILTER & CHANTYPE keywords. If there are discrepancies with any of these keywords, ftmathpha will warn the user and write the appropriate null/default values to the output file. However, there are a number of mandatory keywords associated with associated files, for which ftmathpha is in general unable to set appropriate values (since it largely depends upon what the user is attempting to do via the input expression). These keywords are:

BACKFILE: - the name of the corresponding spectrum file containing the appropriate background spectrum (if any)
BACKSCAL: - the numerical scaling which should be applied to the background spectrum (as specified by the BACKFILE keyword) before background-subtraction (can be a vector)..
CORRFILE: - the name of the corresponding spectrum file containing the appropriate correction spectrum (if any). This is rare.
CORRSCAL: - the numerical scaling which should be applied to the correction spectrum (as specified by the CORRFILE keyword).
RESPFILE: - the name of the redistribution matrix file (aka RMF) to be used for the spectrum.
ANCRFILE: - the name of the ancillary response dataset (aka ARF) to be used in conjunction with the redistribution matrix given by the RESPFILE keyword.

(see also OGIP/92-007).

For convenience ftmathpha provides the opportunity to specify the values to be written to the output file via the hidden parameters auxfiles, backfile, backscal, corrfile, corrscal, arffile, and rmffile. The internal logic for ftmathpha regarding these parameters is as follows:

FIRST: If the auxfiles, backfile, backscal, corrfile, corrscal, arffile, and rmffile parameters all have their default value ('NONE'), then the null/default values of BACKFILE, BACKSCAL, CORRFILE, CORRSCAL, RESPFILE, and ANCRFILE will be written to the output file.
SECOND: If the auxfiles parameter is set to a filename, then the values of BACKFILE, BACKSCAL, CORRFILE, CORRSCAL, RESPFILE, and ANCRFILE written to the output file will be copied from the specified file (or set to their null/default values if there is a problem). Setting the auxfiles parameter overrides any values specified by the backfile, backscal, corrfile, corrscal, arffile, and rmffile parameters so any such values will be ignored.
FINALLY: If the auxfiles parameter is not set (has a value 'NONE'), then if any/all the parameters backfile, backscal, corrfile, corrscal, arffile, and rmffile are set to filenames in the expression, then the corresponding values will be copied from the specified file to the output file. If backscal or corrscal are set to real numbers then these will be used for the appropriate keyword in the output file. If any of backfile, corrfile, arffile, and rmffile are set to a filename which is not in the expression then this filename is used as the value for the corresponding keyword in the output file. If any of backfile, backscal, corrfile, corrscal, arffile, and rmffile are set to '%' then ftmathpha will check whether all the files in the expression have the same value of the appropriate keyword and if so use that otherwise set the keyword to its default ('NONE' or 1.0).

PARAMETERS expression [character string] The expression to be evaluated, or @filename.txt to refer to a file containing the expression. The expression must represent a series of mathematical operations to be performed on (one or more) spectra. The expression is allowed to contain filenames (and optionally, an extension number), the mathematical operators +, -, *, /, integers, reals, and pairs of curved brackets ("(" & ")"). Any filenames containing mathematical operators and numbers in scientific notations or preceeded by a minus sign must be enclosed in quotes. units [character string] A flag indicating the physical units in which the expression is to be evaluated (and the units in which the output file will be written). The allowed values are 'C' (ie 'COUNTS'), and 'R' (ie 'RATE'), implying that the algebra will be 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 spectra stored in counts/s will be converted to counts prior to any mathematical operations being performed). Similarly, this flag gives the implied units of any numerical constants within the input expression. A third option value is also allowed, units='F' (ie 'FILE') whereby the algebra is performed in which ever units most of the files are stored in ('COUNTS' in the event of a tie). Extreme caution is urged using this final option. outfile [character string] The name of the output file to be written containing the derived spectrum. For safety, the name of the output file cannot be the same as one of the output files unless clobber=yes parameter or the output filename is preceeded by !. exposure [character string] A flag determining how the exposure time in the output spectrum is calculated. The following options are currently available: 'NULL', 'CALC', a real number (giving the exposure in seconds), or a filename (see above). areascal [character string] A flag determing how the AREASCAL in output spectrum is set. The following options are currently available: 'NULL', '%', a real number, or a filename (see above). properr [character string] A flag whether the errors are to propagated during the algebra (if properr=yes), or whether the errors are simply calculated from the resultant spectrum. errmeth [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='POISS-0' the errors are calculated using SQRT(N). errmeth='POISS-1' the algorithm of Gehrels (1986 ApJ, 303, 336) eqn 7 (+ve error) is used. errmeth='POISS-2' the algorithm of Gehrels (1986 ApJ, 303, 336) eqn 11 (-ve error) is used. errmeth='POISS-3' 0.5 * (POISS-1 + POISS-2) is used divzero [real] A real to be written into the output spectrum for channels which suffer a divide-by-zero during the evaluation of the expression. auxfiles [character string] A flag indicating whether the values of ALL the auxiliary file keywords (BACKFILE, BACKSCAL, CORRFILE, CORRSCAL, RESPFILE & ANCRFILE) written to the output file are to be copied from a specified file. The default value ('NONE') indicates this is not the case, and will result in these keywords being written with their null/default values in the output file (see above). It should be remembered that setting the auxfiles parameter overrides any values specified via the backfile, backscal, corrfile, corrscal, arffile & rmffile parameters (below) such that any values will be ignored. backfile [character string] A flag determing how the BACKFILE keyword written in the output file is set. The following options are currently available: backfile='NONE' The default value ('NONE') for this keyword will be written in the output file. backfile='%' ftmathpha will check whether all the input spectra have the same values of BACKFILE. If this is the case, then that value will be written to the output file. Otherwise, the default value will be written to the output file. backfile=filename If the specified file is included in the expression then the value of BACKFILE from the specified file will be copied to the output file, otherwise the specified file will be used as the BACKFILE value in the output file. In the latter two cases, any problems will be reported by the task, and the default value written to the output file. backscal [character string] A flag determing how the BACKSCAL value written in the output file is set. The following options are currently available: backscal='NONE' The default value (1.0) will be written in the output file. backscal='%' ftmathpha will check whether all the input spectra have the same values of BACKSCAL. If this is the case, then that value will be written to the output file. Otherwise, the default value will be written to the output file. backscal=filename The value of BACKSCAL from the specified file will be copied to the output file. In the latter two cases, any problems will be reported by the task, and the default value written to the output file. corrfile [character string] A flag determing how the CORRFILE keyword written in the output file is set. The following options are currently available: corrfile='NONE' The default value ('NONE') for this keyword will be written in the output file. corrfile='%' ftmathpha will check whether all the input spectra have the same values of CORRFILE. If this is the case, then that value will be written to the output file. Otherwise, the default value will be written to the output file. corrfile=filename If the specified file is included in the expression then the value of CORRFILE from the specified file will be copied to the output file, otherwise the specified file will be used as the CORRFILE value in the output file. In the latter two cases, any problems will be reported by the task, and the default value written to the output file. corrscal [character string] A flag determing how the CORRSCAL value written in the output file is set. The following options are currently available: corrscal='NONE' The default value (1.0) will be written in the output file. corrscal='%' ftmathpha will check whether all the input spectra have the same values of CORRSCAL. If this is the case, then that value will be written to the output file. Otherwise, the default value will be written to the output file. corrscal=filename The value of CORRSCAL from the specified file will be copied to the output file. In the latter two cases, any problems will be reported by the task, and the default value written to the output file. arffile [character string] A flag determing how the ANCRFILE keyword written in the output file is set. The following options are currently available: arffile='NONE' The default value ('NONE') for this keyword will be written in the output file. arffile='%' ftmathpha will check whether all the input spectra have the same values of ANCRFILE. If this is the case, then that value will be written to the output file. Otherwise, the default value will be written to the output file. arffile=filename If the specified file is included in the expression then the value of ANCRFILE from the specified file will be copied to the output file, otherwise the specified file will be used as the ANCRFILE value in the output file. In the latter two cases, any problems will be reported by the task, and the default value written to the output file. rmffile [character string] A flag determing how the RESPFILE keyword written in the output file is set. The following options are currently available: rmffile='NONE' The default value ('NONE') for this keyword will be written in the output file. rmffile='%' ftmathpha will check whether all the input spectra have the same values of RESPFILE. If this is the case, then that value will be written to the output file. Otherwise, the default value will be written to the output file. rmffile=filename If the specified file is included in the expression then the value of RESPFILE from the specified file will be copied to the output file, otherwise the specified file will be used as the RESPFILE value in the output file. In the latter two cases, any problems will be reported by the task, and the default value written to the output file. comments [character string] The input parameters, including the expression, will be written as COMMENT keywords to the output file; the comments parameter allows additional comments to be added. Either a single comment can be given or a filename containing comments preceeded by the '@' symbol (e.g. @comments.txt). chatter [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. clobber [boolean] Flag specifying whether or not to overwrite a pre-existing file with the same name as the output file. Note that "!filename" syntax will overwrite an existing file irrespective of the value of the clobber parameter.