xmatraceback is designed to facilitate extended source analysis of Hitomi SXS or XRISM Resolve data by quantifying spatial mixing due to the point-spread function (PSF). Using real data, it is impossible to trace back each photon that hits the detector and determine definitively where in the sky it originated. However, it is possible with simulated data, as the information about the photon's origination is stored in the simulation event files. The xmatraceback tool, taking into account PSF effects, plots RA/Dec images of simulated photons that hit the detector plane, showing which parts of the detector have contrbutions from which parts of the source. This facilitates quantifying PSF effects, spatial-spectral mixing (SSM) analysis, and is also useful for proposals.
The xmatraceback script uses raytracing and heasim event files, made using the tools aharfgen (Hitomi SXS) or xaarfgen (XRISM Resolve), in order to determine which photons from the RA/Dec image of the source impact particular regions on the detector. The tools aharfgen and xaarfgen should be run in "image mode", using images from other missions with higher spatial resolution as input, such as Chandra or XMM-Newton. It is important to note that xmatraceback is only designed to work with aharfgen/xaarfgen runs performed for one attitude bin only. It is the responsibility of the user to ensure that this condition is satisfied because the task does not check for this, and incorrect results will be obtained if the input files were made for more than one attitude bin.
Using xmatraceback, users can take the outputs of aharfgen/xaarfgen and generate 37 traceback images: one for each individual pixel and one for the full array. The traceback image of the full array does not include data from pixel 12. Individual pixel images can be added together to create traceback images for custom detector regions. By including photons that originate from both within and outside of the detector region, the user is able to determine which regions of the detector have contributions which regions of the source. Detector region files, in both RA/Dec and DET coordinates, are also output for each pixel and for the full array. The RA/Dec region files can be overlaid on the traceback images. The xmatraceback tool also produces an output FITS file that contains numerical results for the fractional contributions to each Resolve pixel from outside and inside that pixel.
In addition to the raytracing and heasim event files, xmatraceback has input parameters 'xcen' and 'ycen' (in DET coordinates), which specify the point on the detector to align with the origin of the raytracing coordinates. Numerical values can be entered, or the strings CENTER (this is the default), or CALDB. The CENTER option corresponds to the center of the detector (the official "aim point"), and CALDB corresponds to the ground-measured optical axis position. For software HEASoft 6.36 or later and for CalDB 12 or later, the CALDB option includes a small adjustment offset from the optical axis that is based on inflight calibration. The user can also specify the energies of the photons to include in the traceback images by inputting a minimum and maximum energy by means of the 'erange' parameter.
The xmatraceback tool produces 37 traceback FITS images and two sets of detector region files, one set in RA/Dec and one in DET coordinates. All output files have a root name that is set by the 'outroot' parameter string. The total size of the images can be very large, exceeding 1GB or more, but the total size can be reduced by a factor of a hundred or more by compression (due to relatively sparse populations of the contents of the images).
The full array traceback image will be named with the suffix '_sxs' (for Hitomi) or '_rsl' (for XRISM) appended to 'outroot', followed by appending '_allpix_srcimg.fits'. Similarly, the full-array detector region file will have the name {outroot}_{ins}_allpix_{coord}.reg', where 'coord' will be either 'det' or 'radec', depending on whether the region file is in DET or RA/Dec coordinates respectively.
The individual traceback images for each pixel have a more complex naming convention: {outroot}_{ins}_pix{NN}_x{n}y{m}_srcimg.fits where 'pix{NN}' gives the pixel ID ({NN} having values '00' to '35'), and {n} and {m} are integers between 1 and 6 giving the pixel DETX and DETY coordinates respectively. For example, pixel 18 will have 'pix18' and 'x3y4'. The region file name follows a similar convention: {outroot}_{ins}_pix{NN}_x{n}y{m}_{coord}.reg', where 'coord' again refers to the coordinate system used ('det' or 'radec').
The name of the output file containing the calculated photon fractions is {outroot}_photon_fractions.fits. The results are in the first extension, which has columns named Pixel (holding the pixel ID), PixFracExtern (the fraction of photons contributing to a pixel that originate from outside the pixel), and PixFracInpIMG (the fraction of the entire input image that contributes to a pixel). The value of the header keyword FREXTERN is the fraction of photons that contribute to the Resolve 35-pixel full array that originate from outside of the array. The value of the header keyword FRINPIMG is the fraction of photons from the original input image that contributes to the Resolve 35-pixel full array.
Generate traceback images -- FITS image files showing the distribution of simulated photons at the source that hit each Resolve pixel and the full detector array-- for the Hitomi SXS instrument, using existing raytracing and heasim event files ('perseus_raytrace.fits' and 'heasim_events_perseus.fits', respectively) from a previously run instance of aharfgen.
The 'xcen' and 'ycen' parameters are set to CENTER, centering the origin of the raytracing coordinates at (3.5,3.5) in DET coordinates. The energy range is set from 0.5 to 17.1 keV, inclusive. The root name of all output fits files will be 'traceback'.
xmatraceback xrtevtfile=perseus_raytrace.fits heasimevtfile=heasim_events_perseus.fits xcen=CENTER ycen=CENTER telescop=HITOMI instrume=SXS teldeffile=CALDB erange="0.5 17.1" outroot=traceback clobber=yes
This will output:
37 region files (one for each pixel and one for the full array sans pixel 12) in RA/Dec coordinates: Example: traceback_sxs_pix00_radec.reg 37 region files (one for each pixel and one for the full array sans pixel 12) in DET coordinates: Example: traceback_sxs_pix00_x4y3_det.reg 37 image files (one for each pixel and one for the full array): Example: traceback_sxs_pix00_x4y3_srcimg.fits 1 FITS table file containing numerical results for fractional photon contributions: traceback_photon_fractions.fits
Generate XRISM Resolve traceback images for the full detector array and for each individual pixel using an existing Chandra image of an extended source.
First, run xaarfgen in image mode, using the Chandra image as input, to create XRISM Resolve simulated events files for the source. xaarfgen runs the heasim simulation tool which outputs a heasim event file named 'heasim_events.fits.' The xaarfgen tool internally uses the heasim event list as input for the raytracing code and outputs the raytracing event file 'raytracing_centaurus_subimage_v1.fits'. In this case, the heasim event file is renamed to 'centaurus_heasim_events.fits.'
In this example, 'xcen' and 'ycen' are set to CALDB. This sets the X and Y positions on the detector with which to align with the origin of the raytracing coordinates. The energy range is set to a minimum of 2 keV and maximum of 8 keV (inclusive). The root name of all output files will be 'traceback_centaurus'.
xmatraceback xrtevtfile=raytracing_centaurus_subimage_v1.fits heasimevtfile=centaurus_heasim_events.fits xcen=CALDB ycen=CALDB telescop=XRISM instrume=RESOLVE teldeffile=CALDB erange="2.0 8.0" outroot=traceback_centaurus clobber=yes
This will output:
37 region files (one for each pixel and one for the full array sans
pixel 12) in RA/Dec coordinates:
Example: traceback_centaurus_rsl_pix00_radec.reg
37 region files (one for each pixel and one for the full array sans
pixel 12) in DET coordinates:
Example: traceback_centaurus_rsl_pix00_x4y3_det.reg
37 image files (one for each pixel and one for the full array):
Example: traceback_centaurus_rsl_pix00_x4y3_srcimg.fits
1 FITS table file containing numerical results for fractional photon contributions: traceback_centaurus_photon_fractions.fits