ADDARF (Oct95)               ftools.caltools              ADDARF (Oct95)




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.
    
    Users  are  WARNED  that  the  use  of  this  task  in inappropriate
    circumstances  can  (and  most  likely  WILL)  lead   to   extremely 
    misleading results.
    
    
    
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  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.
        
    
    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.
        
    
    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.
        
    
    (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.0.1
            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 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.
    
    
    
BUGS
    
    None Known
    
    
    
SEE ALSO
    mathpha, addrmf, marfrmf
    
    
    
LOG OF SIGNIFICANT CHANGES
    
    
    v1.0.1 (1995 Oct)
            Beta-test version
    
    
    
PRIMARY CONTACT
    
    Ian M George
    HEASARC
    NASA/GFSC
    http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
    (301) 286-6094