'arftable' is a script that creates an ancilliary response function (ARF) FITS file from an output history event file from the raytracing tool 'xrtraytrace'. The effective area (EA) in the ARF file is due to the telescope only, and does not include any detector efficiencies. This script allows the user to create EA functions for X-ray source positions at different off-axis and azimuthal angles, without needing to run the 'xrtraytrace' tool repeatedly.
The script creates an EA for a targeted off-axis (theta) and azimuthal (roll) angle. These angles need not correspond to exact angles in any of the original raytracing runs since arftable interpolates the EA for off-grid points. The script works by finding the off-axis and azimuthal angles immediately above and below the desired values, and creating an EA for each. The script then calculates what the EA should be for the desired angles.
The input file(s) must be in the same format as output from the tool 'xrtraytrace', containing information about the event history of every raytraced photon and details of its path. The aperture, telescope description file (TDF), azimuthal angle grid, and energy grid must be consistent across each file. Each file may contain multiple off-axis angles, and may contain multiple roll angles. The same off-axis angle cannot be in multiple history files. Note that this means that the most number of files the program will actually use is two: one for the theta below the target theta, and one for the theta above it. These two theta values could also be in the same file, in which case the program will only be using one history file. The tool handles the cases where the target theta and target azimuthal angles may be on the grid of input angles, or between the angles. But they cannot be outside of the grid of angles. For example, if the input history files are created using off-axis angles 0, 10, and 20, valid target thetas would be 0, 5, 10, and 18. Target theta values of 21 or 50 would not be valid.
The output is a FITS EA file, in similar format to the output EA file from 'xrtraytrace'. Note that the file format is different to that of a standard ARF file that can be read by XSPEC and is therefore incompatible with XSPEC. There is a single extension with the EA at the desired off-axis and azimuthal angles. When a vignetting file is desired, a regular EA file is not created; only the vignetting file is created.
EA(E, theta, roll)
-----------------------
EA(E, theta=0, roll)
Because of the dependence on theta=0, one of the input history files must have theta=0.
arftable.pl @history_files.txt arf.fits tgtOffaxis=35 tgtAzimuth=50
Where the input file is an ascii file listing three history files, with off-axis angles 0 and 30 arcmin, 40 and 50 arcmin, and 60 and 70 arcmin respectively. Each history file uses the same azimuthal grid of 0, 45, and 90 deg, and same energy grid of 0.5, 2.0, 3.0 keV.
history_0_30.fits
history_40_50.fits
history_60_70.fits
Note that since the target off-axis is 35 arcmin, only the first two history files will be used. If the target off-axis were 25, then only the first file would be used.
The output EA file would be the effective area calculated at the target off-axis and azimuth, interpolated from the values in the input files.
arftable.pl history_0_30.fits arf.fits tgtOffaxis=0 tgtAzimuth=50
Where the input file is a history file with off-axis angles 0 and 30 arcmin, azimuthal angles of 0, 45, and 90 deg, and energy values of 0.5, 2.0, 3.0 keV.
The output EA file would be the effective area calculated at the target off-axis and azimuth. Since theta=0 is in the history file, only the azimuthal dependence would be interpolated.