.help addarf Oct95  ftools.caltools
.ih
NAME
addarf -- Add input ARF files with specified weights
.ih
USAGE
   addarf infiles weights outfile 

or,

   addarf @infile out_ARF=outfile

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

Users are WARNED that the use of this task in inappropriate circumstances 
can (and most likely WILL) lead to extremely misleading results. 
.ih
PARAMETERS
.ls 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 factors should be followed by a blank after each ARF file
and should be real.  In case of, an ascii file is used, 
the name of the ASCII file should be preceeded by a, '@' (eg @file_list 
instructs the task to open the ASCII file file_list, and read the ARF 
filenames from it). The number of ARF files cannot exceed 2500.

.le
.ls 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 and not
the ascii file.
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 list of reals.

.le
.ls out_ARF [string]
The  name  of  the ARF file to be created. For safety, the name
of the o/p  file CANNOT be the same as one  of  the  i/p  files,
and  the task will stop  if this is the case. Under unix/ultrix,
an o/p filename identical to a  file  which  already  exists  on
disk  is  also  considered  illegal,  and  the   task will stop.
However, the existing file can be  automatically  removed,   and
the  new file written if the o/p filename is preceeded by "!" at
the out_ARF prompt.

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

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

.ih
EXAMPLES

A) Average gis2.arf and gis3.arf and output gis23.arf, 
	specifying everything on the command line.

.nf
   addarf 'gis2.arf gis3.arf' '0.5 0.5' gis23.arf
.fi
or
.nf
   addarf gis2.arf,gis3.arf 0.5,0.5 gis23.arf
.fi
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
.nf
prompt> addarf
** addarf 1.0.1
List of i.p ARFs to be added[] @arfs.ascii
Name of output ARF to be created[] !sum.arf
.fi

.ih
LIMITATIONS
The inappropriate use of this task will most likely give rise 
to extremely misleading results. Care should be exercised.

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.

.ih
BUGS
None Known
.ih
SEE ALSO
mathpha, addrmf, marfrmf
.ih
PRIMARY CONTACT
.nf
Ian M George
HEASARC
NASA/GFSC
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.fi
.endhelp


