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. 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). 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. 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, and the corresponding energy interval must be greater than 0.0. (the interval for the default values is 0.0 and will result an error). For source types (1) to (3), 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.

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 xaxmaarfgen without rerunning xrtraytrace. When xaarfgen is executed, and 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, 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 attiude and energy bins. If any attitude bin has a time interval significantly larger than the average time interval, aharfgen 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 fine energy grid that is designed to capture the relevant atomic physics at a level of detail sufficient for Resolve.

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.4-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 wider than the nominal ranges just mentioned may be specified. For Resolve, the energy range can span 0.03 to 30 keV, and should not be extended beyond this, because there is no calibration outside of this energy range. For Xtend, the valid energy range is 0.03 to 24 keV.

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.

telescop = XRISM [string]

Mission name (and the value of header keyword TELESCOP to write in the output file, for CalDB).

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.

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. 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.

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.

(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 valie 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 factor 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, for which the value of the GATEVALV keyword is equal to 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) valid for the instrument for which the ARF is generated. For Resolve or Xtend the 'rmffile' is generated either by rslmkrmf 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.10 17.0 2.0 8.0" [string]

A string containing four numbers. 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 in this way may be used to shorten the run time if a restricted energy range is sufficient for the application. 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 image data.

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 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 effectve 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 energy grid point. If any attitude bin has a time interval significantly larger than the average time interval, aharfgen allocates additional raytracing photons to that attitude position.

(minphoton = 100) [integer]

The minimum number of 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, at least 5000 photons per energy (over the extraction region) are needed. The default value of minphoton is deliberately much less than this, in order that the ARF is available for diagnostic evaluation.

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. (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 to create a photon event list using the simulation code heasim. This event list is subsequently input into the raytracing code by aharfgen. The input image file may be made from data from a different mission, 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 coordinate system should be SKY (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.

(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, corresponding to effects of unknown origin that are not accounted for in the telescope calibration files used by the raytracing. If 'auxtransfile=CALDB', the file is read from the CalDB.

(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_sky.reg), and an exposure map file (src_expmap.fits) made by the xaexpmap task. An example of the contents of the region file src_sky.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=sxi.rmf
   	  erange="0.4 15.0 0.4 15.0"
   	  onaxiscfile=CALDB
   	  onaxisffile=CALDB
   	  outfile=src_1_arf.fits
   	  regmode=RADEC
   	  regionfile=src_sky.reg
   	  mirrorfile=CALDB
   	  obstructfile=CALDB
   	  frontreffile=CALDB
   	  backreffile=CALDB
   	  pcolreffile=CALDB
   	  scatterfile=CALDB
   	  numphoton=10000
   	  sourcetype=point
   

   This example run produces the following output files: (1) src_1_arf.fits, (2) aharfgen_region.lis (contains the names of region files made in detector coordinates: src_1_arf.arfregion0.reg to src_1_arf.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 aharfgen 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