NAME

USAGE

DESCRIPTION

The arftable script creates an effective area (EA) FITS file and an ARF FITS file from input history event files that are created by the raytracing task xrtraytrace. The arftable task allows simple region selection of events from raytracing on the focal plane by specifying the center and radius of an event extraction circle. This 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 an event file which contains the events that are not stopped by the object between the telescope and focal plane (see parameter 'writeevtfile'). Note: if there are no 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, 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 task repeatedly.

In the interpolation mode (if 'mergePtg=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 EA and ARF files are not created.

INPUT

The input raytracing event file(s) must be in the same format as the output from the xrtraytrace task, 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 uses, at most, two files: one for theta below the target theta, and one for the theta above the target theta. These two theta values could also be in the same file, and in this case the program would only use one event file. In interpolation mode (if 'mergePtg=no'), the task 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 event files are created using off-axis angles 0, 10, and 20, then 0, 5, 10, and 18 would be valid target values of theta; target theta values of 21 or 50 would not be valid. In merging mode (if 'mergePtg=yes'), the values of the input parameters 'tgtOffaxis' and 'tgtAzimuth' are ignored. Note: 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=no').

A response matrix file (RMF) is required if the requested output is an ARF file. This is because an ARF file must have the same energy grid as the input energy grid in the RMF. The RMF file name is specified in the parameter 'inrmffile'. If set to NONE, an output ARF file is not made.

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 vs. energy. Lastly, if 'writeevtfile=yes', then an event file is written out as described above.

PARAMETERS

inxrtevtfile [filename]

Name of the input photon history (or event) file (in the format created by the raytracing task 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 (or NONE). If an RMF is provided, the input energy grid from the RMF is used to create the ARF file. The RMF may also be a multi-extension line-spread function (LSF) file. Regardless of the type of RMF, 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 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 = no [boolean yes|no]

If set to yes, the task writes an event file named using 'outfileroot' and appending "_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 actually arrive at the focal plane.

(vignetting = NONE) [filename NONE|file name]

Name of the output vignetting file. 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. Note that the denominator (on-axis effective area) does not depend on the roll angle but raytracing results must exist for the all values of the roll angle used in the numerator.

(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, 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=no').

tgtOffaxis = 0.0 [double]

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=no' or if there is more than one input file). The 'tgtOffaxis' parameter value 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, the 'tgtOffaxis' parameter is ignored.

tgtAzimuth = 0.0 [double]

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=no'). The 'tgtAzimuth' parameter value 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', this parameter is ignored.

objecttype = NONE [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=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 coordinates must be in 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 = "622.0 124.0" [string]

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

objectradii = "25.35 24.67" [string]

A string containing one or more numbers, each number corresponding to the radius [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 = "0.0 0.0" [string]

A string containing one or more numbers, each number corresponding to the rotation angle [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. The rotation angle is positive if the image is rotated counterclockwise in look-down coordinates. The parameter 'imagerotangles' is ignored if 'objecttype' is not IMAGE.

xoffsets = "0.0 0.0" [string]

A string containing one or more numbers, each number corresponding to the offset [mm] along the telescope x-axis of the center of an object in the optical path between the telescope and the focal plane. Note: 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 = "0.0 0.0" [string]

A string containing one or more numbers, each number corresponding to the offset [mm] along the telescope y-axis of the center of an object in the optical path between the telescope and the focal plane. Note: 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 = "0.0 0.0" [string]

A string 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 [arcmin] and the second number is the y-coordinate [arcmin]. The parameter setting 'regioncenter="0.0 0.0"' 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: if 'mergePtg=no', or if there is more than one raytracing input event file, the parameters 'regioncenter' and 'regionradius' are ignored.

regionradius = 3.0 [double]

The radius [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: if 'mergePtg=no', or if there is more than one raytracing input event file, the parameters 'regioncenter' and 'regionradius' are ignored.

(cleanup = yes) [boolean yes|no]

Delete temporary files if 'cleanup=yes'.

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records tool parameters in HISTORY.

EXAMPLES

1. Create EA and ARF files from a raytracing photon event file (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. The output files created are src_ea.fits and src.arf.

   arftable.pl inxrtevtfile=rt_evt.fits inrmffile=src.rmf outfileroot=src mergePtg=yes objecttype=NONE regionradius=-1

2. Create EA and ARF files from an on-axis raytracing photon event file (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 Hitomi HXI1 baffle in the optical path between the telescope and the focal plane. The RMF file used is the 5-matrix 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. The output files created are src_ea.fits and src.arf.

   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 

3. Create an EA file by creating and interpolating the effective area from multiple input raytracing photon event 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 event files, with off-axis angles 0 and 30 arcmin, 40 and 50 arcmin, and 60 and 70 arcmin, respectively. Each event file uses the same azimuthal grid of 0, 45, and 90 deg, and same energy grid of 0.5, 2.0, 3.0 keV. The contents of the file list history_files.txt is:

      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 arcmin, 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 input raytracing photon event 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 angles. Since theta=0 is in the history file, only the azimuthal dependence would be interpolated.

SEE ALSO

LAST MODIFIED