NAME

USAGE

DESCRIPTION

The xaxmaarfgen task creates an ARF for the Resolve or Xtend instruments on XRISM. It 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 is generated by the xaexpmap task and contains histograms based on discrete satellite attitude pointing. 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. 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 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 the Resolve filter wheel setting (see below).

The ARF includes the telescope effective area (XMAR or XMAX 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 the exposure map file 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), 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 (also value to write to the output file for header keyword TELESCOP). Currently, XRISM is the only choice for this parameter.

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.

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.

(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. 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 has a column density of 0.0 for all contaminants, at launch.

(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 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 required for Resolve observations, and only for those observations that have the value of the GATEVALV keyword equal to CLOSED. The file accounts for the blocking and attenuation effects of the gate valve.

rmffile [filename]

Name of the RMF. It is only used to extract the energy grid that is used for the output 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 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.

xrtevtfile [filename]

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

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

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

Name of the input auxiliary transmission file. This file is used to apply an additional transmission modifier (a multiplicative factor that could be greater than 1), that is not accounted for in the telescope calibration files used by the raytracing code, xrtraytrace. To apply the auxiliary transmission, the user has to either input a file or set the parameter to CALDB.

(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 the RA/DEC region selection file src_sky.reg, an exposure map file (src_expmap.fits) made by the xaexpmap task, and a set of region files in DET coordinates that are derived from src_sky.reg, using the exposure map src_expmap.fits and the xaarfgen task, which should be run prior to running xaxmaarfgen. 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. In this example, the names of the region files in DET coordinates are listed, one file per row, in the ASCII file xaarfgen_region.lis. The raytracing event file that is required by the xaxmaarfgen task is made by the 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'.

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.fits
	  regionfile=@arfgen_region.lis
	  xrtevtfile=src_1_raytrace.fits

The example run produces the output file:

• src_1_arf.fits

SEE ALSO

LAST MODIFIED