NAME

USAGE

DESCRIPTION

The xaarfgen task is a script that runs the task xaxmaarfgen, which creates an ancillary response function (ARF) file for the XRISM Resolve or Xtend instruments (selected with the 'instrume' parameter). The xaarfgen task takes as input an exposure map file created by the xaexpmap task. The exposure map file contains information about the satellite attitude and variation in the telescope optical axis pointing, as well as spatial effective exposure time information. However, it is important to note that xaarfgen only needs the attitude histogram, and the exposure map itself is present for other tasks. A standard SAO region file input can be used to specify the region in RA/DEC or DET coordinates for which the output ARF file is created (see 'regmode' and 'regionfile' parameters). For Resolve, only region files in DET coordinates are allowed. For Xtend, if the region is in RA/DEC coordinates, the script then creates a number of selection regions in the DET coordinate system corresponding to discrete satellite attitude intervals (or histogram bins), that are contained in the exposure map file. The options for specifying the spatial distribution of the X-ray source are: (1) point source ('sourcetype=POINT'), (2) uniform emission from an extended circular region ('sourcetype=FLATCIRCLE') with a set radius (see 'flatradius' parameter), (3) beta model ('sourcetype=BETAMODEL'; see 'betapars' parameter), and (4) input image ('sourcetype=IMAGE'). The image option, useful for extended sources, uses an input image file to create a photon event list by using the simulator task heasim. This event list is subsequently used to generate input for the raytracing code, which is run internally by xaarfgen. The input RA/DEC image file could be made from data from a different mission, or from a model. The third and fourth numbers in the string for the input parameter 'erange' are the lower and upper energy bounds for the the input image respectively. For source types (1) to (3), the source position is input using the 'source_ra' and 'source_dec' parameters. For image mode, the RA and DEC values for each pixel are utilized by xaarfgen, but the parameters 'source_ra' and 'source_dec' should be set to either a position in the image for which most accurate coordinate transformations are required in linearized coordinates, or to the center of the input image. In image mode, xaarfgen also produces a file with the generic name heasim_events.fits. If this file is needed by the user for input to other tasks, such as xmatraceback, the file should be renamed, otherwise the next run of xaarfgen in image mode will over-write the existing heasim_events.fits file.

The ARF made with any of the extended-source choices for 'sourcetype' corresponds to the flux of the entire spatial extent of the input source (as it should). For image mode, this corresponds to the flux of the entire input image. However, spectral fitting a model using an extended-source ARF to a spectrum that is made from a smaller region than the size of the input source (which will almost always be the case), will not give the correct flux from that smaller region. The flux obtained from spectral fitting must be corrected in order to account for the size of the input source. The correction factor will not be trivial to calculate for a complex input image, but for Resolve, the task xmatraceback can be used to help. In the most naïve sense, the correction for an input source with uniform emission can be estimated to be the ratio of the area of the small region and the area of the whole input source.

The xaarfgen task runs the raytracing task xrtraytrace, using information about the source and region selection to simulate photon paths through the X-ray telescope. The photon paths, or events, along with the source and region information, are passed onto xaxmaarfgen in order to enable the net effective area to be calculated. Detector efficiencies are calculated in xaxmaarfgen, not in xaarfgen. The raytracing file is saved and can be used again to run xaarfgen without rerunning xrtraytrace. When xaarfgen is executed, if it finds that a raytracing file with the requested file name already exists, xaarfgen skips running the raytracing code again, and instead passes the existing event file onto xaxmaarfgen. Running the raytracing code is very time-intensive so this feature avoids unnecessarily long run times whenever possible. The event file from previous runs of the raytracing may be used if the ARF is recalculated using a different energy binning (the binning is defined by the RMF), a different region, a different gate valve setting, a different filter wheel choice, or a different choice about whether to use the auxiliary transmission file or not (see parameter 'auxtrans').

The number of photons injected into the raytracing code determines the statistical accuracy of the effective area. This number is controlled by the parameter 'numphoton', but it is not equal to the total number of photons. The total number of photons injected into the raytracing code is determined by an algorithm that takes into account the relative time intervals for each attitude bin as given in the first extension of the exposure map file. Each row in the first extension of the exposure map file corresponds to one attitude bin. The value of the parameter 'numphoton' corresponds roughly to the number of raytracing photons allocated to each attitude bin per energy grid point. The total number of photons is then equal to a weighted sum in which this algorithm determines the weighting for the sum over the attitude and energy bins. If any attitude bin has a time interval significantly larger than the average time interval, xaarfgen allocates additional raytracing photons to that attitude position. Note that raytracing is performed on a coarse energy grid for modeling the spatial distribution of photons, which has a weak energy dependence. The final effective area calculated by xaarfgen combines these coarse-grid results with some pre-calculated raytracing results that were obtained on a (non-uniform) fine energy grid that is designed to capture the relevant atomic physics at a level of detail that is better than the Resolve energy resolution.

As a rough guide, one should aim for a minimum total of 3 million photons over the whole energy range, and 'numphoton' can be estimated by numphoton~(total number of photons/number of attitude bins/X), where X~16 for Resolve or Xtend over the nominal energy range 0.3-12 keV. The run time for the raytracing code is approximately 1 minute per 100,000 photons. The energy range for which xaarfgen calculates the ARF file is selectable by the user, and ranges different to the nominal range may be specified. However, xaarfgen will generally fail to produce a usable ARF if the energy range includes any regime with vanishing effective area. Therefore, for Resolve, even though it is possible to go up to 30 keV, it is not recommended to go higher than 18 keV (the XMA is not calibrated above 17.5 keV), or below ~1.7 keV with the gate valve closed. For Xtend, the valid energy range is ~0.3 to 24 keV, but again the XMA is not calibrated above 17.5 keV. Additional caveats are discussed below, under 'erange'.

Note that Resolve region files made by xamkregion should not be used as input to xaarfgen (or xaxmaarfgen). This is because xamkregion creates DET coordinate regions for Resolve that have overlapping pixel regions.

PARAMETERS

xrtevtfile [filename]

Name of event/history file created by the raytracing program xrtraytrace, and used by xaarfgen. If 'xrtevtfile' does not exist, xaarfgen creates it by running xrtraytrace. If 'xrtevtfile' is the name of an existing file that was previously created by xaarfgen, this file is used instead of creating a new one.

source_ra = 150.0 [double]

Right ascension (RA, degrees) of the X-ray source for which the ARF is to be created. For 'sourcetype=FLATCIRCLE' or 'sourcetype=BETAMODEL', 'source_ra' is the RA of the center of the source. For 'sourcetype=IMAGE', the parameter 'source_ra' represents the RA position of the targeted source within the image. If there is no obvious source, 'source_ra' should be set to the RA position of the center of the image.

source_dec = 50.0 [double]

Declination (DEC, degrees) of the X-ray source for which the ARF is to be created. For 'sourcetype=FLATCIRCLE' or 'sourcetype=BETAMODEL', 'source_dec' is the DEC value of the center of the source. For 'sourcetype=IMAGE', the parameter 'source_dec' represents the DEC position of the targeted source within the image. If there is no obvious source in the image, 'source_dec' should be set to the DEC position of the center of the image.

(nompntpars = "43.0 65.0 130.0 43.0 65.0") [string]

This parameter is only used if no exposure map is input to xaarfgen ('emapfile=NONE'). The parameter consists of a string of five numbers as follows: (1) RA of satellite pointing direction, (2) DEC of satellite pointing direction, (3) roll angle of satellite, (4) RA of the telescope optical axis, and (5) DEC of the telescope optical axis. However, note that the option 'emapfile=NONE' is still experimental and not recommended.

telescop = XRISM [string]

Mission name (currently, XRISM is the only choice).

instrume = RESOLVE [string XTEND|RESOLVE]

Instrument for which the ARF is to be made.

(teldeffile = CALDB) [filename CALDB|file name]

Name of the telescope definition (teldef) file appropriate for the instrument for which the ARF is to be made. If the parameter is set to CALDB, the file is read from the calibration database (CalDB).

emapfile = [filename]

Name of the exposure map file (created by the task xaexpmap) containing histograms of satellite attitude and related quantities, including partial pixel exposure information. There is also an effective exposure time image in the primary extension of the exposure map file, but it is not needed by xaarfgen.

qefile = CALDB [filename CALDB|NONE|file name]

Name of the file containing the quantum efficiency (QE) for the detector. If the parameter is set to CALDB, the file is read from the CalDB. For Xtend, the QE is combined with the optical blocking layer (OBL) transmission. The Xtend QE CalDB file also contains the transmission for the Contamination Blocking Filter (CBF). Spatial dependence of the QE is treated by xaarfgen for both the Resolve and Xtend instruments.

(obffile = CALDB) [filename CALDB|NONE|file name]

Name of the optical blocking filter file (needed for Resolve only). If the parameter is set to CALDB, the file is read from the CalDB.

(fwfile = CALDB) [filename CALDB|NONE|file name]

Name of the filter wheel filter file (needed for Resolve only). If the parameter is set to CALDB, the file is read from the CalDB, using the FILTER keyword in 'emapfile' to determine which CalDB filter file to retrieve. If the parameter is set to NONE, the filter wheel is effectively removed (this will never happen inflight, but the option is available for theoretical investigations and ground data analysis).

contamifile = CALDB [filename CALDB|NONE|file name]

Name of the file containing information to calculate the transmission due to contaminants on the detector as a function of time, energy, and detector position. If the parameter is set to CALDB, the file is read from the CalDB. This file for both Resolve and Xtend has so far had a column density of 0.0 for all contaminants since the launch of XRISM.

(abund = 1.0) [string]

Relative abundances of contaminants modifier. Either several values, or a single value can be specified in the string 'abund'. If there is more than one value, the number of values must be equal to the number of contaminant components in the contamination CalDB file, and each value of the abundance modifier multiplies the abundance of the corresponding component, in the order that the component columns appear in the contamination file. If there is only one numerical value in the string 'abund', then that single value multiplies the abundances of all of the contaminant materials in the calibration file.

(cols = 0.0) [string]

Additional column densities for contaminants [1E18 cm^{-2}]. The column densities of all of the contaminant materials in the calibration file are modified by adding values from this parameter to the value in contamifile. The number of numerical values in the parameter string must be the same as the number of values in the string for the 'abun' parameter. If there is only one value, that value is applied to all of the contaminant components.

(covfac = 1.0) [string]

Partial covering modifier for contaminant materials. The partial covering factors of all of the contaminant materials in the calibration file are modified by multiplying them by values from this parameter. The number of numerical values in the parameter string must be the same as the number of values in the string for the 'abun' parameter. If there is only one value, that value is applied to all of the contaminant components.

gatevalvefile = CALDB [filename CALDB|file name]

Name of the Resolve gate valve calibration file. This file is only necessary for Resolve observations that have the gate valve closed (for which the value of the GATEVALV keyword in 'emapfile' will be 'CLOSED'). The file accounts for the blocking and attenuation effects of the gate valve. If 'gatevalvefile=CALDB', the gate valve file in the CalDB is used.

rmffile [filename]

Name of a response matrix file ('RMF' or 'RSP') valid for the instrument for which the ARF is generated. The 'rmffile' is only used for its energy grid (not for its actual matrix), which must match the energy grid of the ARF. For Resolve or Xtend the 'rmffile' is generated either by rslmkrmf/rslmkrsp or xtdrmf respectively, from which the energy grid is read and used within xaarfgen for the output energy grid of the ARF file.

erange = "0.50 18.0 2.0 8.0" [string]

A string containing four numbers corresponding to two energy ranges in units of keV. The first and second numbers correspond to the minimum and maximum energy, respectively, of the valid data in the output ARF file (points outside this range are filled with zeros). Restricting the energy range to a narrower band may be used to shorten the run time if a restricted energy range is sufficient for the application (but note that the range should not be less than 4 keV or so). The third and fourth numbers in the input parameter string are only relevant if 'sourcetype=IMAGE' (one of the extended source options), and are set to the lower and upper energy bound, respectively, of the input image. Important note: due to the particular ways that xaarfgen works to calculate the effective area, the actual energy range of the output ARF may not always exactly match the request in the 'erange' parameter. This is a feature, not a bug. If the actual energy range of the ARF is not satisfactory, xaarfgen must be run again with new numbers in the first and second positions of the 'erange' parameter.

onaxisffile = CALDB [filename CALDB|file name and extension]

Name of the file and extension that contains the on-axis telescope effective area, appropriate for the instrument, pre-calculated on a fine energy grid. If the parameter is set to CALDB, the file is read from the CalDB.

onaxiscfile = CALDB [filename CALDB|file name and extension]

Name of file and extension that contains the on-axis telescope effective area, appropriate for the instrument, pre-calculated on a coarse energy grid. If the parameter is set to CALDB, the file is read from the CalDB.

outfile [filename]

Name of the output ARF file.

regmode = DET [string RADEC|DET]

Type of coordinate system associated with the region file ('regionfile').

regionfile [filename file name|NONE]

Name of the source region selection file, in RADEC (RA/DEC units) or DET coordinates. The format is that of a standard SAO region file. Note that RA/DEC region files are not the same as SKY region files. For Resolve, only regions in DET coordinates should be used because for spectra extracted in SKY coordinates, photons cannot be traced back to the individual pixels that they landed in due to the large size of the pixels compared to the size of the extraction region. Note that Resolve region files made by xamkregion should not be used as input to xaarfgen. If 'regionfile=NONE', the ARF is made for the entire detector.

rslgapreg = no [boolean yes|no]

This parameter pertains to the treatment of pixel gaps in Resolve, and is ignored if 'instrume=XTEND'. The parameter is also ignored if 'regionfile=NONE', in which case Resolve pixel gaps are accounted for by keywords in the header of the input file 'emapfile'. If 'rslgapreg=no', the input region file has no explicit gaps between pixels, and again, pixel gaps are accounted for by keywords in the header of the input file 'emapfile'. If 'rslgapreg=yes', the input region file explicitly excludes gaps between Resolve pixels, and no additional corrections are made for pixel gaps. Note that specifying a value for 'rslgapreg' that incorrectly characterizes the input region file will create an ARF with the wrong effective area.

doublesonly = no [boolean yes|no]

If 'doublesonly=yes', the ARF will contain the effective area only for photon paths through the telescope that contain a double reflection event (a primary mirror foil reflection immediately followed by a secondary mirror foil reflection). Double reflection events may include other interactions with the telescope. If 'doublesonly=no', all pathways through the telescope contribute to the effective area in the output ARF.

mirrorfile = CALDB [filename CALDB|file name and extension]

Name of the telescope description file (TDF) and the extension (e.g., MIRROR) that holds the geometrical description of primary and secondary mirror foils. It is assumed that the name of the pre-collimator extension is COLLIMATOR. If 'mirrorfile' is set to CALDB, the file is read from the CalDB.

obstructfile = CALDB [filename CALDB|file name and extension]

Name of the telescope description file (TDF) and the extension (e.g., OBSTRUCT) that holds the geometrical description of the telescope support structures. If the parameter is set to CALDB, the file is read from the CalDB.

frontreffile = CALDB [filename CALDB|file name and extension]

Name of the reflectivity file and the extension for the front-side reflectivity of the mirror foils. The extension also includes the thin surface film transmission. The names of the reflectivity and transmission columns are linked to groups of mirror foils that they apply to, by means of a column called FREFLECT in the TDF. Note that the second extension in the reflectivity file contains mass-absorption coefficients that are used by the raytracing code xrtraytrace, to calculate transmission probabilities of the "thick" materials (as opposed to thin films) in the telescope.

backreffile = CALDB [filename CALDB|file name and extension]

Name of the reflectivity file and the extension for the backside reflectivity of the mirror foils.

pcolreffile = CALDB [filename CALDB|file name and extension]

Name of the reflectivity file and the extension for the reflectivity of the pre-collimator blades/foils. The pre-collimator reflectivity is the same for front-side and back-side reflection.

scatterfile = CALDB [filename CALDB|file name and extension]

Name of the file containing the scattering angle probability distributions for the direction of reflected rays relative to regular (incident angle = reflected angle) specular reflection. The file contains data for the frontside of mirror foils, the backside of mirror foils, and for the pre-collimator blades. In general, foils in different physical regions of the telescope can have different scattering distributions. The column names are referenced in the SCATTER column in the TDF.

numphoton = 20000 [integer]

The value of the parameter 'numphoton' corresponds roughly to the number of raytracing photons allocated to each attitude histogram bin (in the exposure map file), per grid point in the internal energy grid used for raytracing. If any attitude bin has a time interval significantly larger than the average time interval, xaarfgen allocates additional raytracing photons to that attitude position.

(minphoton = 100) [integer]

The minimum number of raytracing photons that successfully reach the focal plane, per raytracing energy grid point, that is acceptable to make an ARF. The number of focal plane photons that contribute to the ARF must exceed 'minphoton' for every energy, otherwise the program aborts. Note that even if minphoton is exceeded at all energies, this does not guarantee that the resulting ARF is robust and sufficiently accurate. In general, about 5000 or more photons per energy (over the extraction region) give good results, but the actual minimum number varies case-by-case, and fewer may be sufficient in some cases. The default value of minphoton is deliberately very small, in order that the ARF is made and available for diagnostic evaluation. In general, it is not recommended to set 'minphoton' to a high value in the first place, because it is not possible to reliably estimate what 'numphoton' should be in advance, in order for that value of 'minphoton' to be satisfied for all energies, which could result in repeated failures after very long run times. It could also run into memory problems and/or a raytracing file size that is unmanageable.

sourcetype = POINT [string POINT|FLATCIRCLE|BETAMODEL|IMAGE]

Method for treatment of the spatial distribution of the X-ray source. (1) POINT: Point source at infinity. Photons arrive at random points on the active region of the telescope aperture from a single direction. (2) FLATCIRCLE: Extended source at infinity that has a spatial distribution with uniform flux over a circular region (zero outside of the circle). (3) BETAMODEL: Extended source at infinity that has a spatial distribution described by the "beta model" (see 'betapars' parameter). (4) IMAGE: A FITS image file (in RADEC coordinates) is used by xaarfgen to create a photon event list using the simulation code heasim. This event list is subsequently input into the raytracing code by xaarfgen. The input image file may be made from data from a different mission (with better spatial resolution than XRISM), or from a model. The name of the image file is given by the parameter 'imgfile'.

(betapars = "0.50 0.60 5.0") [string]

Parameters of the beta model if 'sourcetype=BETAMODEL' as follows: (1) beta model core radius [arcmin], (2) the index beta of the beta model, and (3) the maximum radius [arcmin] of the source spatial distribution.

(flatradius = 10.0) [double]

The radius [arcmin] of the extended source for the flat spatial distribution option 'sourcetype=FLATCIRCLE'.

imgfile [filename]

Name of the input image file to be used for raytracing if the input parameter 'sourcetype=IMAGE'. The image should be in the primary extension and the coordinate system should be RADEC (in RA/DEC units). The minimal mandatory keywords required are the standard ones describing the X and Y grids: CRPIX1, CRVAL1, CDELT1, CUNIT1, CRPIX2, CRVAL2, CDELT2, and CUNIT2. The units of the pixel contents in the image do not matter because xaarfgen creates a normalized probability distribution from the image.

(auxtransfile = NONE) [filename NONE|CALDB|file name]

Name of the input auxiliary transmission file. This file is used to apply an additional transmission modifier to the output ARF. This could correspond to modeling effects of unknown origin that are not accounted for in the telescope calibration files used by the raytracing, or it could be a function generated by the tool dustyarfmod that converts a point-source ARF to one that is appropriate for a point-source surrounded by a specified model of a dust scattering halo. If 'auxtransfile=CALDB', the file is read from the CalDB. However, the functions in these CalDB files for both instruments are simply unity for all energies, and there is currently no plan to change that for XRISM.

(polydeg = DEFAULT) [string DEFAULT|1|2|3|4|5|6|7|8|9|10]

The parameter 'polydeg' defines the polynomial order for the fitting of an internal function. The allowed values are 1 to 10. If 'polydeg=DEFAULT', the order is set to a value obtained internally by testing for fitting stability.

(seed = 29075) [integer]

Random number generator seed; uses system time for 'seed=0'.

(cleanup = no) [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 task parameters in HISTORY.

EXAMPLES

1. Make an ARF file for a point source in Xtend, given an RA/DEC region selection file (src_radec.reg), and an exposure map file (src_expmap.fits) made by the xaexpmap task. An example of the contents of the region file src_radec.reg is:
   
   

   # Region file format: DS9 version 4.1
   global color=green dashlist=8 3 width=1 font="helvetica 10 normal" select=1 high
   lite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1 wcs=wcs
   fk5 circle(140.0,35.0,150.0")

   In this example, the source RA and DEC coordinates are 140 and 35 degrees respectively, and the extraction region is a circle centered on the source, with a radius of 150 arcsec. The parameters 'source_ra' and 'source_dec' that should be entered are equal to the values of the corresponding source coordinates in the region file. The task xaxmaarfgen (called by xaarfgen) only uses the energy grid in 'rmffile' and not the actual matrix data so the particular RMF specified for 'rmffile' is not important. The ARF made by xaxmaarfgen is calculated on the exact energy grid in 'rmffile'.

   xaarfgen  xrtevtfile=src_1_raytrace.fits 
   	  source_ra=140.0
   	  source_dec=35.0
   	  telescop=XRISM
   	  instrume=XTEND
   	  teldeffile=CALDB
   	  emapfile=src_exmpmap.fits
   	  qefile=CALDB
   	  contamifile=CALDB
             rmffile=xtd.rmf
   	  erange="0.4 15.0 0.4 15.0"
   	  onaxiscfile=CALDB
   	  onaxisffile=CALDB
   	  outfile=src_1.arf
   	  regmode=RADEC
   	  regionfile=src_radec.reg
   	  mirrorfile=CALDB
   	  obstructfile=CALDB
   	  frontreffile=CALDB
   	  backreffile=CALDB
   	  pcolreffile=CALDB
   	  scatterfile=CALDB
   	  numphoton=300000
   	  sourcetype=point
   

   This example run produces the following output files: (1) src_1.arf (2) xaarfgen_region.lis (contains the names of region files made in detector coordinates: src_1.arfregion0.reg to src_1.arfregionN.reg, where N is the number of attitude histogram bins in the exposure map file, extension 1), and (3) src_1_raytrace.fits.

KNOWN BUGS

If xaarfgen is run with 'sourcetype=IMAGE', the number of photons generated from the image in the initial event list should be equal to the input parameter 'numphoton', but this is not the case, although the two numbers match approximately. For most applications, no mitigation is necessary because the exact number of photons would not be sufficiently different. The user can always specify a larger number of photons to begin with. Another mitigation method is to run xaarfgen with the intended value of 'numphoton' and note in the screen output the number of actual source events generated by the task heasim. Then, interrupt xaarfgen and run it again with a new value of 'numphoton' set to the original value squared, divided by the actual number of events generated by heasim.

SEE ALSO

LAST MODIFIED