NAME

ASCAARF -- Generates an ASCA ARF file for an input PHA file


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


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.


PARAMETERS

phafile [string]
The name of the input PHA file.

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.

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.

outfile [string]
The name of the output ARF file.

raytrace [bool]
If raytrace = yes then the source information will be read from the files listed in the file specified by the rayfile parameter.

point [bool]
If point = yes then the source is assumed to be point-like.

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

Xposition [real]
The X-axis position of the point source in detector coordinates (this is only prompted for if point = yes and simple = no).

Yposition [real]
The Y-axis position of the point source in detector coordinates (this is only prompted for if point = yes and simple = no).

fudge [bool]
If fudge = yes then the Gaussian fudge to the telescope effective areas will be applied.

arffil [bool]
If fudge = arffil then the correction to the ARF will be applied.

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.

clobber [bool]
If clobber = yes then overwrite the ARF file if a file of this name already exists.

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.

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.

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.

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.

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.


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


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.

CATEGORY

Dec98 ftools.asca