NAME

USAGE

DESCRIPTION

The xaxmaarfgen task creates an ARF for the Resolve or Xtend instruments on XRISM. In the most common usage, xaxmaarfgen is called by the task xaarfgen. The task xaxmaarfgen takes as input: an exposure map file, a set of region files in detector coordinates, and an event file containing raytracing events for simulated photons injected into the telescope. The exposure map file (specified by the parameter 'emapfile') is generated by the xaexpmap task and contains attitude histograms based on discrete satellite attitude pointing (the exposure map itself is not needed for making the ARF, but is used by other software). The region files are made by the script xaarfgen, which uses the attitude information in the exposure map file and a region file in RA/DEC coordinates to generate several region files in the detector (DET) coordinate system, one region file per attitude bin in the exposure map file. In the case of a single attitude bin, a region file that is already in DET coordinates can be input directly and does not have to be made by xaarfgen. The raytracing event file is also made by the script xaarfgen, which runs the raytracing code xrtraytrace based on information in the attitude histograms in the exposure map file. The event file from previous runs of the raytracing may be used if the ARF is to be recalculated using a different energy binning (the binning is defined by RMF) and/or different regions. The same raytracing event file can be also be used if the user wants to make a different choice regarding whether or not to use an auxiliary transmission, or whether the Resolve gate valve is open or closed, or which Resolve filter wheel setting to use (see below).

The ARF includes the telescope effective area (XMA-R or XMA-X for Resolve or Xtend respectively), quantum efficiency, extinction due to contaminants, filters, and in the case of Resolve, the gate valve if it is closed. The efficiencies are specified in calibration database (CalDB) files and of these, only the contaminants file is time-dependent. The Xtend detector has just one filter transmission, the contamination-blocking filter (CBF). The Resolve detector has an optical blocking filter (OBF) in addition to a filter wheel mechanism that places a selectable filter in the optical path, between the X-ray telescope and the focal plane. Aside from two open positions, the filter wheel may have one of four possible settings: Beryllium, Neutral Density, Polyimide, or an Fe 55 calibration source filter. If the user specifies CALDB for the filter wheel calibration file, xaxmaarfgen takes the value of the keyword FILTER in 'emapfile' and obtains the corresponding filter calibration file. If the user specifies CALDB for the gate valve calibration file, xaxmaarfgen takes the value of the keyword GATEVALV (which can have the value OPEN or CLOSED) from 'emapfile', and obtains the gate valve calibration file if the value of the GATEVALV keyword is equal to CLOSED.

The task also prints to the screen, and in the log file, the PSF fraction contained in the selected region and contained inside of the detector.

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

PARAMETERS

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.

emapfile [filename]

Name of the exposure map file (produced by the xaexpmap task) that contains histograms of satellite attitude and related quantities, as well as good time intervals (GTI) for the attitude bins. There is also an effective exposure time image in the primary extension of the exposure map, but it is not needed by xaxmaarfgen.

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

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

Name of the optical blocking filter file (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 file (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.

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 specified 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 specified instrument), pre-calculated on a coarse energy grid. If the parameter is set to CALDB, the file is read from the CalDB.

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

The 'polydeg' parameter defines the polynomial order for internal fitting of a function. The DEFAULT value instructs xaxmaarfgen to internally test more than one value for the polynomial order, and choose the value to use that gives the best fitting stability.

outfile [filename]

Name of the output ARF file.

regionfile [filename]

Names of standard SAO-formatted ASCII region files, or the name of a file containing a list of names of such files, preceded by the "@" symbol (e.g., 'regionfile=@xaarfgen_region.lis', where xaarfgen_region.lis is an ASCII file in which each row contains the name of a region file). The coordinates of these region files must be DET coordinates, and the region files specify the data extraction regions that correspond to the discrete satellite attitude intervals in the exposure map file ('emapfile') attitude histogram. Note that Resolve region files made by xamkregion should not be used as input to xaxmaarfgen. 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.

xrtevtfile [filename]

Name of the raytracing event/history file that was created by xaarfgen.

(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 of running raytracing within xaarfgen, 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.

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

(buffer = -1) [integer -1|0|N]

Rows to buffer (-1=auto, 0=none, N>0=number of rows).

(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. Make an ARF file for a point source observed by Resolve, given an exposure map file (src_expmap.fits) made by the xaexpmap task, and a set of region files in DET coordinates that are listed in the ASCII file xaarfgen_region.lis. In this example, the gate valve is open so there is no need to specify the gate valve file. Each region file, in DET coordinates, corresponds to an attitude histogram bin in the exposure map file. The raytracing event file that is required by the xaxmaarfgen task is made by a prior run of xaarfgen. Note: xaxmaarfgen does not need any explicit information about the spatial distribution of the X-ray source because that is already factored into the raytracing event file. Since xaxmaarfgen only uses the energy grid in 'rmffile' and not the actual matrix data, the particular RMF specified for 'rmffile' is not important. The ARF made by xaxmaarfgen is calculated on the exact energy grid in 'rmffile' that is on the "input" side of the response matrix.

xaxmaarfgen telescop=XRISM
          instrume=RESOLVE
          emapfile=src_exmpmap.fits
          qefile=CALDB
          obffile=CALDB
          fwfile=CALDB
          contamifile=CALDB
	  rmffile=rsl.rmf
          onaxiscfile=CALDB
          onaxisffile=CALDB
          outfile=src_1.arf
	  regionfile=@arfgen_region.lis
	  xrtevtfile=src_1_raytrace.fits

The example run produces the output file src_1.arf.

SEE ALSO

LAST MODIFIED