.help ascaarf Dec98 ftools.asca
.ih
NAME
ASCAARF -- Generates an ASCA ARF file for an input PHA file
.ih
USAGE
ascaarf [<phafile> [<rmffile> [<chipno> [<outfile> [<raytrace> [<point> 
        [<simple> [<Xposition> [<Yposition> [<fudge> [<arffil> [bkgfile 
        [<clobber> [<bethick> [<grid> [<xrtrsp> [<xrtpsf> [<rayfile>
        ]]]]]]]]]]]]]]]]]

ascaarf <phafile> [rmffile=<rmffile>] [chipno=<chipno>] [outfile=<outfile>] 
        [raytrace=<raytrace>] [point=<point>] [simple=<simple>] 
        [Xposition=<Xposition>] [Yposition=<Yposition>] [fudge=<fudge>] 
        [arffil=<arffil>] [bkgfile=<bkgfile>] [clobber=<clobber>] 
        [bethick=<bethick>] [grid=<grid>] [xrtrsp=<xrtrsp>] [xrtpsf=<xrtpsf>]
        [rayfile=<rayfile>]

.ih
DESCRIPTION
ASCAARF generates an ASCA ARF file suitable for input into XSPEC for the
input PHA and RMF files. The energy bins for which the ARF is created are
read from the RMF file. ASCAARF operates in one of several modes, depending
on the input parameters.

1) An extended source (point='no'). The ARF is calculated by summing the
   ARFs for each bin in the image of the selected region stored in the
   primary header of the spectral file. The sum is weighted by the number
   of counts in the image bin.

2) A point source (point='yes') where the data selection was done using
   a region with the source at the center (simple='yes'). The ARF is 
   calculated by summing the contributions to the image point response 
   function modified by the detector efficiency. Only image bins with > 0 
   counts are included in the sum.

3) A point source (point='yes') where the data selection was not done as
   per method 2 (simple='no'). ASCAARF proceeds as per method 2 except that
   the user must give the source position (Xposition,Yposition) in detector
   coordinates.

4) A raytraced source (raytrace='yes'). The ARF is calculated by summing
   ray-traced output files over the selected region. One ray-traced image
   should be available for each energy and the units of the image should
   be cm^2.

This task expects that the PHA file and the RMF file conform to OGIP format 
standards. It also assumes that the detector pixels are squares.

The fudge parameter is used to specify whether the Gaussian fudge to the
telescope effective area is to be used. This is a hidden parameter whose
default option is to perform the fudge. The arffil parameter is used to
specify whether the ARF filter correction is performed. This is a hidden
parameter whose default option is to perform the correction.

Should the RMF file contain energy data which does not lie in the range 
0 < energy <= 12.0 keV, ASCAARF will write 0.0 to the SPECRESP column of the 
ARF file. For every bin outside this range, the user will be warned, and a 
COMMENT keyword will be written to the header of the ARF file.

If the spectrum is from the GIS and less than two rise time bits were used
then the ARF is modified from the standard version to take into account
the different efficiency due to the rise time background rejection not 
operating.

If a background file is specified then the image in this file will be
subtracted from the image in the spectrum file. This will not make any
difference in point source mode but should give a slightly more accurate
result when using extended source mode with faint sources. The background
image should be extracted using the same region filter as the spectrum.
One good way of doing this is to extract a spectrum from a background field
in exactly the same way that the source spectrum was extracted. This 
background spectrum can then be used as the background file.

.ih
PARAMETERS
.ls phafile [string]
The name of the input PHA file.
.le
.ls rmffile [string]
The name of the input RMF file. If this is set to CALDB then ascaarf will
look in the calibration database for an appropriate RMF file. Note that 
the RMF file is only used to set the energy ranges on which the effective
area is calculated.
.le
.ls chipno [int]
This parameter is only required if the RMF file is given as CALDB and
the spectrum is from one of the SIS cameras. It is used to choose which
RMF to use.
.le
.ls outfile [string]
The name of the output ARF file.
.le
.ls raytrace [bool]
If raytrace = yes then the source information will be read from the files
listed in the file specified by the rayfile parameter.
.le
.le
.ls point [bool]
If point = yes then the source is assumed to be point-like.
.le
.ls simple [bool]
If simple = yes then the point source is assumed to lie at the center of
the selected region (simple is only prompted for if point = yes).
.le
.ls Xposition [real]
The X-axis position of the point source in detector coordinates (this is
only prompted for if point = yes and simple = no).
.le
.ls Yposition [real]
The Y-axis position of the point source in detector coordinates (this is
only prompted for if point = yes and simple = no).
.le
.ls fudge [bool]
If fudge = yes then the Gaussian fudge to the telescope effective areas
will be applied.
.le
.ls arffil [bool]
If fudge = arffil then the correction to the ARF will be applied.
.le
.ls bkgfile [string]
The filename whose primary array is to be used as a background map to subtract
from the primary array in the spectrum file.
.le
.ls clobber [bool]
If clobber = yes then overwrite the ARF file if a file of this name already
exists.
.le
.ls bethick [string]
The filename for the GIS Be thickness detector map. This is probably called
s2bev1.fits or s3bev1.fits and can be found in the calibration database. If
this parameter is set to CALDB then the calibration database will be searched
for the file. If the parameter is set to AUTO then the calibration database
will be searched and if this fails then the ftools/refdata area is searched.
.le
.ls grid [string]
The filename for the GIS grid detector map. This is probably called 
s2gridv3.fits or s3gridv3.fits and can be found in the calibration database.
If this parameter is set to CALDB then the calibration database will be 
searched for the file. If the parameter is set to AUTO then the calibration 
database will be searched and if this fails then the ftools/refdata area is 
searched.
.le
.ls xrtrsp [string]
The XRT effective area file. The XRT team software reads this file and 
interpolates for the requested energy and detector position. The file is
probably called xrt_ea_v2_0.fits and can be found in the calibration database.
If this parameter is set to CALDB then the calibration database will be 
searched for the file. If the parameter is set to AUTO then the calibration 
database will be searched and if this fails then the ftools/refdata area is 
searched.
.le
.ls xrtpsf [string]
The XRT PSF file. The XRT team software reads this file and interpolates for 
the requested energy and detector position. The file is probably called 
xrt_psf_v2_0.fits and can be found in the calibration database. If this 
parameter is set to CALDB then the calibration database will be searched for 
the file. If the parameter is set to AUTO then the calibration database will 
be searched and if this fails then the ftools/refdata area is searched.
.le
.ls rayfile [string]
An ascii file listing the files containing the ray-trace output. Each line
of rayfile should consist of an energy (in keV) and a filename.
.le
.ih
EXAMPLES
1) Produce an ARF file called arf.fits from the PHA file pha.fits and the RMF 
file rmf.fits for an extended source.

     ca> ascaarf pha.fits rmf.fits arf.fits no

2) Produce an ARF file called arf.fits for a point source.

     ca> ascaarf pha.fits rmffile=rmf.fits outfile=arf.fits point=yes
         simple=yes

3) Produce an ARF file for a point source and turn off the fudges to the
effective area.

     ca> ascaarf pha.fits rmffile=rmf.fits outfile=arf.fits point=yes
         simple=yes fudge=no arffil=no

.fi
.ih
BUGS
If there is significant aspect variation during an observation ASCAARF
will not give the correct result.

It would be nice if a region file could be given as an additional option.

.ih


.endhelp




