NAME

addarf -- Add input ARF files with specified weights

USAGE

addarf infiles weights outfile

or

addarf @infile out_ARF=outfile

DESCRIPTION

ADDARF sums input ARF files with specified weights, and outputs a single ARF. This task may be used when combining several spectral files having different ARFs but an identical RMF. For example, when combining energy spectra taken at different pointing positions with the same detector, and adding spectral files taken simultaneously with plural detectors having different ARFs but the same RMF.

Note that use of this task in inappropriate circumstances (for example, if the underlying detector response is not the same for all the spectra, or if the weights are incorrect) will probably yield inaccurate results. In general analyzing spectra separately with appropriate, individual ARFs and RMFs is recommended (rather than combining weighted ARFs).

PARAMETERS

list [string]

ARF files to be added together. The input to this parameter can either be a list of ARF files, or can be the name of an ASCII file containing such a list of files (one per line) and weighting factors for the ARFs. The weighting factor should be given after each ARF file and should be a real number (with decimal point). If an ascii file is used, the name of the ASCII file should be preceeded by an "@" sign. For example

addarf list = "@file_list.lis"

instructs the task to open the ASCII file file_list.lis, and read the ARF filenames and weights from it. The number of ARF files cannot exceed 2500.

weights [string]

Relative weighting factors for the ARFs given via the list parameter. User is asked for this parameter when name of ARFs are given explicitly on the command line. The number of values and ordering MUST be the same as for the filenames specified by the list parameter. The input to this parameter is a string of real numbers separated by commas. The WEIGHTS parameter is not used if the input list is an ASCII file of ARFs and weights.

out_ARF [string]

The name of the ARF file to be created. The name of the output file CANNOT be the same as one of the input files unless CLOBBER=yes. The existing file can also be automatically removed, and the new file written if the output filename is preceeded by "!".

(clobber = F) [logical]

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.

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

EXAMPLES

A) Average gis2.arf and gis3.arf and output gis23.arf,

specifying everything on the command line.

addarf 'gis2.arf gis3.arf' '0.5 0.5' gis23.arf

or

addarf gis2.arf,gis3.arf 0.5,0.5 gis23.arf

B) Add the files listed in ASCII file arfs.ascii,

using the weighting factors listed in ASCII file weights.ascii, with the output overwriting an existing file called sum.arf

prompt> addarf

** addarf 1.2.8

List of i.p ARFs to be added[] @arfs.ascii

Name of output ARF to be created[] !sum.arf

LIMITATIONS

The inappropriate use of this task will most likely yield inaccurate results.

The number of ARF files cannot exceed 2500.

The summation is not carried out unless number of energy bins and all the ENERG_LO and ENERG_HI values are identical for all the input files.

The TELESCOP and INSTRUME values can be different for input files. In this case, values in the first file are written in the output ARF.

BUGS

None Known

SEE ALSO

mathpha, addrmf, marfrmf

LOG OF SIGNIFICANT CHANGES

Ken Ebisawa & Ian George (1.0.1:1995 Oct)

Beta Version

Banashree M Seifert (1.1.0:1996 Nov26)

changes made by Keith Arnaud and Ken Ebisawa

Banashree M Seifert (1.2.0:1997 March 11)

added option for input file list with contents like:
file1.arf 1.0
file2.arf 4.0

Ning Gan (1.2.2:1999 Oct 25)

Added dynamically allocated arrays of sum_arf, e_high, e_low.

Added a routine process_add_arf

Ning Gan (1.2.4:2000 Mar 01)

Find ARF extensions automatically

Ning Gan (1.2.5:2000 Mar 19)

Increase the size of filenames to 255.

Increase the total number of arf files from 100 to 2500.

Ning Gan (1.2.6:2000 May 11)

Fixed the write statements for output of error and warning strings.

Bryan Irby (1.2.8:2018 Nov 9)

Replaced udmget/udmfre calls with allocate/deallocate

PRIMARY CONTACT

Mike Corcoran

HEASARC