NAME

arftable - Create an effective area file and an ancillary response function (ARF) file from the output events from the raytracing code xrtraytrace, not including any detector efficiencies

USAGE

arftable inxrtevtfile inrmffile outfileroot tgtOffaxis tgtAzimuth objecttype inimagefile objectheights objectradii imagerotangles xoffsets yoffsets regioncenter regionradius

DESCRIPTION

The 'arftable' script creates an effective area (EA) FITS file, and an ancillary response function (ARF) FITS file from input history event files that are created by the raytracing tool 'xrtraytrace'. 'arftable' allows simple region selection of events from the raytracing on the focal plane by specifying the center and radius of an event extraction circle. The script also allows one or more simple 2-D geometrical objects to be placed in the optical path between the bottom of the X-ray telescope and the focal plane. The objects may be in the form of planes with circular holes, or images. In this manner, objects such as the Hitmoi SXS gate valve, SXS filters, and HXI baffle may be modeled in a simple way. There is a possibility to write and event file to contain the events that are not stopped by the object between the telescope and focal plane (see parameter 'writeevtfile'). Note that if there are not objects between the telescope and the focal plane the event output file contains all the events of the input files.

The effective area in the EA and ARF files is due to the telescope only, and does not include any detector efficiencies. The only differences between the EA and ARF files are the energy grid and file format (see "OUTPUT" description below). The effective area values are identical in the two files. This script operates in two modes, depending on whether the value of the hidden parameter 'mergePtg' is set to 'yes' (default) or 'no'. If the value of 'mergePtg' is 'yes' (default) and there is only one input raytracing event file, the script merges events from all pointing directions in a single input raytracing event (or history) file (i.e. all values of off-axis and azimuthal angles relative to the telescope axial symmetry axis contribute to the effective area). If the value of 'mergePtg' is no the effective area is calculated by interpolating the results from raytracing runs performed at more than one pair of values of off-axis and azimuthal angle. This latter mode allows the effective area to be calculated quickly for X-ray source positions at different off-axis and azimuthal angles, without needing to run the 'xrtraytrace' tool repeatedly.

In the interpolation mode (if the value of 'mergePtg' is set to 'no', or if there is more than one input raytracing event file), the script creates an effective area 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 effective area 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 effective area for each. The script then calculates what the effective area should be for the desired angles. If the raytracing runs include an on-axis position (theta=0) the script can also calculate vignetting functions for every energy in the raytracing events (history) files (if the hidden parameter 'vignetting' is not equal to 'NONE'). However, note that if a vignetting file is created, the other files (EA and ARF) are not created.

INPUT

The input raytracing event file(s) must be in the same format as the 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. However, the same off-axis angle cannot be in multiple history files. Therefore the program is using at most two files: 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, and in this case the program would only be using one history file. In interpolation mode (if the value of 'mergePtg' is set to 'no'), 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, then 0, 5, 10, and 18 (for example) would be valid target values of theta. Target theta values of 21 or 50 would not be valid. In merging mode (if the value of 'mergePtg' is set to 'yes'), the values of the input parameters 'tgtOffaxis' and 'tgtAzimuth' are ignored. However, note that if more than one input raytracing event file is given, the value of the parameter 'mergePtg' is ignored and the script runs in interpolation mode (equivalent to 'mergePtg' set to 'no').

An RMF (response matrix function) is required if the requested output is an ARF file. This because an ARF file must have the same energy grid as the input energy grid in the RMF file that the ARF file is going to be used with. The RMF filename is specified in the parameter 'inrmffile'. If set to NONE, the ARF file is not output.

OUTPUT

The output effective area is written to two FITS files: an EA file and an ARF file. The EA file has an identical format to the output EA file from 'xrtraytrace' (one column of energy, called ENERGY, and one column of effective area, called EFFAREA). The ARF file, readable by XSPEC, has the standard format of lower and upper energy bound columns (ENERG_LO and ENERG_HI respectively), and an effective area column called SPECRESP. When a vignetting file is desired, neither the EA file nor the ARF is created; only the vignetting file is created. The vignetting file contains functions of off-axis to on-axis effective area ratio versus energy. Last if the writeevtfile=yes than an event file is written out as describe above.

PARAMETERS

inxrtevtfile [filename]
Name of the input photon history (or event) file (in the format created by the raytracing tool 'xrtraytrace'). Alternatively, the name of an ASCII file many be entered, preceded by an '@' character, where the file contains the list of input files, one per line.

inrmffile [filename]
Name of the input RMF file (or NONE). If an RMF file is provided, the input energy grid from the RMF file is used to create the ARF file. The RMF file may also be a multi-extension line-spread function (LSF) file. Regardless of the type of RMF file, the energy grid is always obtained from the first extension. If 'inrmffile' is set to NONE, no ARF file is created (only the EA file is created).

outfileroot [string]
Root name for the output file EA and ARF files. If an ARF file is to be created, the file name is outfileroot.arf. The EA file name is outfileroot_ea.fits.

writeevtfile [boolean, (yes|no)]
Write or not an output event file. By default writeevtfile is set and the task does not write out any event file. Setting this paramater to yes the task writes an event file named using 'outfileroot' and adding '_evt.fits'. NOTE this is only useful if an object is placed bewteen the telescope and the focal plane to check which events are not stopped by the object and arrive to the focal plane.

(vignetting = NONE) [filename]
Name of the output vignetting file (or NONE). When a vignetting file is desired, the regular effective area files (EA and ARF) are not created; only the vignetting file is created. The file contains an extension with the ratio of the EA for each theta and azimuthal angle combination, to the EA at theta=0.
    EA(E, theta, roll)
  -----------------------
    EA(E, theta=0, roll)
  
Because of the dependence on theta=0, one of the input history files must have raytracing results for theta=0.

(mergePtg = yes) [boolean, (yes|no)]
If 'mergePtg' is set to 'yes', raytracing results for all off-axis and azimuthal angles from a single input history event file are combined into a single effective area. If more than one raytracing event file is specified, then the value of the parameter 'mergePtg' is ignored and the action of the script is to produce an interpolated effective area for a pair of desired off-axis and azimuthal angles, equivalent to 'mergePtg' set to 'no'.

tgtOffaxis [real]
Target off-axis angle [arcmin]. This is the off-axis angle at which the desired effective area should be calculated in interpolation mode (i.e. if 'mergePtg' is set to 'no'). It must be within the range of the off-axis angles in the input file(s). For example, 'tgtOffaxis' cannot be smaller than the smallest off-axis angle in the provided input file(s). If 'mergePtg' is set to 'yes', then the value of 'tgtOffaxis' has no effect.

tgtAzimuth [real]
Target azimuthal (roll) angle [deg]. This is the azimuthal angle at which the desired effective area should be calculated in interpolation mode (i.e. if 'mergePtg' is set to 'no'). It must be within the range of the azimuthal angles in the input file(s). For example, 'tgtAzimuth' cannot be smaller than the smallest azimuthal angle in the provided input file(s). If 'mergePtg' is set to 'yes', then this parameter has no effect.

objecttype [string, (NONE|CIRCLE|IMAGE)]
Type of object to place in the optical path between the bottom (exit) of the telescope and the focal plane. Select NONE for no object in the path, CIRCLE for one or more circles, or IMAGE for one or more images. The heights of the circles above the focal plane and the radii of the circles are specified by the parameters 'objectheights' and 'objectradii' respectively (the 'objecttradii' parameter is ignored when 'objecttype' is not CIRCLE). The region outside a circle is treated as opaque, and the region on or inside a circle is treated as transparent. If 'objecttype' is IMAGE, the names of one or more FITS image files can be specified for the parameter 'inimagefile'. The images must be in the primary extension of each file and the X and Y units must mm. Image pixels that have a value greater than zero are treated as opaque and pixels that have values of zero are treated as transparent. The entire region outside the image boundaries is treated as opaque.

inimagefile [filename]
Name of an input image file modeling an object in the optical path between the telescope ad focal plane. Alternatively, the name of an ASCII file many be entered, preceded by an '@' character, where the file contains the list of input files, one per line.

objectheights [string]
A string containing one or more numbers, each number corresponding to the height (in mm) of a simple 2-D object above the focal plane. The heights of the objects must be listed in descending order.

objectradii [string]
A string containing one or more numbers, each number corresponding to the radius (in mm) of the "hole" in an otherwise opaque plane placed at a height above the focal plane that is specified by the corresponding number in the string parameter 'objectheights'. The parameter 'objectradii' is ignored if the parameter 'objecttype' is not CIRCLE.

imagerotangles [string]
A string containing one or more numbers, each number corresponding to the rotation angle (in degrees) of an image object in the optical path between the telescope and the focal plane. The rotation angle is zero if the X-axis of the image is aligned with the X-axis of the telescope and the rotation angle is positive if the image is rotated counter-clockwise in 'look-down' coordinates. The parameter 'imagerotangles' is ignored if 'objecttype' is not IMAGE.

xoffsets [string]
A string containing one or more numbers, each number corresponding to the offset (in mm) along the telescope X-axis of the center of an object in the optical path between the telescope and the focal plane. Note that the telescope axial symmetry axis has a value of 0.0 for the X-axis offset. Each number in 'xoffsets' is associated with a corresponding height above the focal plane in the string of numbers in the parameter 'objectheights'.

yoffsets [string]
A string containing one or more numbers, each number corresponding to the offset (in mm) along the telescope Y-axis of the center of an object in the optical path between the telescope and the focal plane. Note that the telescope axial symmetry axis has a value of 0.0 for the Y-axis offset. Each number in 'yoffsets' is associated with a corresponding height above the focal plane in the string of numbers in the parameter 'objectheights'.

regioncenter [string]
A string containing containing two numbers specifying the center (on the focal plane) of a circular selection region for raytracing events. The first number is the X-coordinate (in arcmin) and the second number is the Y-coordinate (in arcmin). A value of "0.0 0.0" for 'regioncenter' corresponds to the intersection of the telescope axial symmetry axis with the focal plane. Only events from the input raytracing files (specified by the parameter 'inxrtevtfile') that fall on or inside the circular region contribute to the output effective area. Note that if 'mergePtg' is set to 'no', or if there is more than one raytracing input event file, then the parameters 'regioncenter' and 'regionradius' are ignored.

regionradius [real]
The radius (in arcmin) of a circular selection region (on the focal plane) for raytracing events. Only events from the input raytracing files (specified by the parameter 'inxrtevtfile') that fall on or inside the circular region contribute to the output effective area. If no region selecton is desired (i.e. if all events are to be included), any negative value for 'regionradius' should be specified. Note that if 'mergePtg' is set to 'no', or if there is more than one raytracing input event file, then the parameters 'regioncenter' and 'regionradius' are ignored.

(cleanup = yes) [boolean, (yes|no)]
Whether or not to delete temporary files.

(clobber = no) [boolean, (yes|no)]
Whether to overwrite existing output file.

(chatter = 1) [integer]
Chatter level for output.

(logfile = !DEFAULT) [string]
Set the name of the log file. Special values are DEFAULT and NONE for the default file name or no log file. The default is the name of the tool with a .log extension. For example, if running ahdemo, the default log file is named ahdemo.log. If the parameter is set to an empty string, an error is generated. If the parameter begins with an exclamation point (!), then any existing log file with the chosen name is overwritten.

(debug = no) [boolean, (yes|no)]
Whether to display debugging information. If turned on, this parameter causes error messages to print a stacktrace in addition to the usual error message.

(history = yes) [boolean, (yes|no)]
Whether to record tool parameters in history keywords in all output files.

(mode = ql) [string, (h|hl|q|ql)]
Sets how automatic parameters are specified. Legal values are h, hl, q, and ql. Hidden parameters (h) are not presented to the user and take the default value from the parameter file, but can be specified as command-line arguments. Queried parameters (q) are prompted for input from the user, but give the default value from the parameter file as a choice. Either type with learning enabled (e.g. ql) cause the default value to change to that given in the previous run.

EXAMPLES

  1. Create EA and ARF files from a raytracing photon history file named rt_evt.fits, with no objects in the optical path between the telescope and the focal plane, and no region selection, using an RMF file named src.rmf.
      arftable.pl inxrtevtfile=rt_evt.fits inrmffile=src.rmf outfileroot=src mergePtg=yes objecttype=NONE regionradius=-1
      
    The output files created is named src_ea.fits and src.arf.


  2. Create EA and ARF files from an on-axis raytracing photon history file named rt_hx1_evt.fits, for a circular extraction region of radius 3 arcmin centered on the telescope symmetry axis, and including a simple model of the HXI1 baffle in the optical path between the telescope and the focal plane. The RMF file used is the 5-matrix line-spread function (LSF) ah_hx1_lsf_20140101v001.fits, which can be found in data/hitomi/hxi/bcf/ under CALDB. The HXI baffle is modeled as two planes at different heights above the focal plane, with the higher plane having a hole representing the baffle entrance, and the lower plane having a hole representing the baffle exit.
      arftable.pl inxrtevtfile=rt_hx1_evt.fits inrmffile=ah_hx1_lsf_20140101v001.fits outfileroot=src mergePtg=yes objecttype=CIRCLE objectheights="622.0 124.0" objectradii="25.35 24.67" xoffsets="0.0 0.0" yoffsets="0.0 0.0" regioncenter="0.0 0.0" regionradius=3.0 
      
    The output files created is named src_ea.fits and src.arf.


  3. Create an EA file by creating and interpolating effective area from multiple photon history files.
            arftable.pl inxrtevtfile=@history_files.txt inrmffile=NONE outfileroot=eafile tgtOffaxis=35 tgtAzimuth=50 mergePtg=no
          
    The input file assigned to 'inxrtevtfile' 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 are 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.


  4. Create an EA file using angles from a single photon history file.
            arftable.pl inxrtevtfile=history_0_30.fits inrmffile=NONE outfileroot=eafile tgtOffaxis=0 tgtAzimuth=50 mergePtg=no
          
    Here, the input file assigned to inxrtevtfile is a raytracing 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.

SEE ALSO

LAST MODIFIED

December 2016