NAME

USAGE

DESCRIPTION

xmatraceback is designed to facilitate extended source analysis of Hitomi SXS or XRISM Resolve data. 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 are sensitive to which parts of the source. This facilitates spatial-spectral mixing (SSM) analysis and is also useful for proposals.

The xmatraceback script uses raytracing and heasim 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 whether 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 parts of the detector are sensitive to which parts 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.

In addition to the raytracing and heasim event files, xmatraceback takes the parameters 'xcen' and 'ycen' as input. The 'xcen' and 'ycen' parameters indicate which point on the detector to align with the origin of the raytracing coordinates. 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.

This 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 integeres 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').

PARAMETERS

xrtevtfile [filename]

Name of the raytracing event file output by aharfgen/xaarfgen.

heasimevtfile [filename]

Name of the heasim event file. This file should be an output from the same instance of aharfgen/xaarfgen that created the raytracing file specified by the 'xrtevtfile' parameter, and xmatraceback will output an error message if this is not the case.

xcen = NONE [double value|NONE|CALDB]

The X position, in DET coordinates, of the point on the detector to align with the origin of the raytracing coordinates. The default (xcen=NONE) is the DETX coordinate center of the detector, xcen=3.5. If XCEN is set to CALDB, the optical axis DETX coordinate stored in the calibration database (CalDB) is used (keyowrd OPTAXISX in the teldef file).

ycen = NONE [double value|NONE|CALDB]

The Y position, in DET coordinates, of the point on the detector to align with the origin of the raytracing coordinates. The default (ycen=NONE) is the DETY coordinate center of the detector, ycen=3.5. If ycen is set to CALDB, the optical axis DETY coordinate stored in the calibration database (CalDB) is used (keyword OPTAXISY in the teldef file).

telescop = XRISM [string XRISM|HITOMI]

Mission name. Only accepts HITOMI or XRISM. This should be the same as the mission name as was used in aharfgen/xaarfgen, and the tool will exit with a relevant error message if this is not the case.

instrume = RESOLVE [string RESOLVE|SXS]

Instrument name. Only accepts SXS or RESOLVE. This should be the same as the instrument that was input to aharfgen/xaarfgen, and the tool will exit with an error message if the instrument names do not match. The instrument name should also agree with the input mission name.

teldeffile = CALDB [filename file name|CALDB]

The telescope definition (teldef) file for the instrument of interest. If teldeffile=CALDB, the teldef file from the CalDB will be used.

erange = '0.5 17.0' [string]

A string of two numbers that defines the energy range of photons in the raytracing file that will be used to make a xmatraceback images. The first and second numbers correspond to the energy minimum and maximum, respectively (both limits are inclusive). If the user input for the energy range has no overlap with the energy range of the raytracing file, the tool will stop. If the user input minimum is a value smaller than the minimum energy in the raytracing file, the energy minimum used by the xmatraceback tool will revert to the minimum energy present in the raytracing file (and the tool will alert the user to this fact). Likewise, if the user input for the maximum energy exceeds the greatest energy present in the raytracing file, the latter will effectively be the maximum energy.

outroot = [string]

The root name prefix string which forms the basis of constructing the output file names.

clobber = yes [string yes|no]

If set to yes, existing output files with the same names will be overwritten.

EXAMPLES

1. Generate traceback images -- fits image files showing the distribution of simulated photons that hit the detector region-- 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 NONE, 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=NONE
   		ycen=NONE
   		telescop=HITOMI 
   		instrume=SXS 
   		teldeffile=ah_sxs_teldef_20140101v002.fits 
   		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
   

2. 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, use the image of an extended source taken using another mission as input to xaarfgen, to create simulated XRISM Resolve simulated events 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, this heasim event file is renamed to 'centaurus_heasim_events.fits.'

   In this example, xcen and ycen are set to 3.5 (DET coordinates), although setting xcen and ycen = NONE would accomplish the same thing. 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=3.5 
   		ycen=3.5 
   		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
   

KNOWN BUGS

SEE ALSO

LAST MODIFIED