ahsxtarfgen - Creates an ancillary response file (ARF) for the SXS + SXT-S or SXI + SXT-I,
accounting for the telescope effective area and detector efficiencies.
ahsxtarfgen telescope instrume emapfile qefile contamifile gatevalvefile rmffile onaxisffile
onaxiscfile outfile regionfile skyregfile xrtevtfile
'ahsxtarfgen' creates an ancillary response file (ARF) for the SXS + SXT-S or SXI + SXT-I. It takes as
input an exposure map file ('ahexpmap'), 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 tool 'ahexpmap' and contains histograms based on discrete satellite attitude pointing.
The region files are made by the script 'aharfgen' 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
coordinate system, one region file per attitude bin in the exposure map file. The raytracing event file
is also made by the script 'aharfgen', 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 recalculated using a different binning (the binning is defined by rmf),
different region and whether or not the auxiliary transmission file is used.
The ARF includes the telescope effective area (for SXT-S in the case of the SXS, and SXT-I in the case
of the SXI), quantum efficiency, extinction due to contaminants, filters, and in the case of the SXS,
the gate valve if it is closed. The efficiencies are specified in CALDB files, and of these only the
contaminants file has a time dependence. The SXI has just one filter transmission, and that is the
contamination-blocking filter (CBF). The SXS has an optical blocking filter (OBF) but in addition also
has a filter wheel mechanism that places a selectable filter in the X-ray telescope path at 921 mm above
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, 'ahsxtarfgen' takes the value of the keyword FILTER in the exposure
map file and get the correct filter calibration file. In early observations of the mission, the SXS was
operated with the gate valve closed. If the user specifies CALDB for the gate valve calibration file,
'ahsxtarfgen' takes the value of the keyword GATEVALV (which can have the value OPEN or CLOSED), and
obtain the gate valve calibration file if the value of the keyword is equal to CLOSED.
The task also write on the screen and in the log file the PSF fraction contained in the selected region
and contained inside of the detector.
- telescop [string]
- Mission name (value to write in header keyword TELESCOP for CALDB).
- instrume [string]
- Instrument for which the ARF is to be made: SXI or SXS.
- emapfile [filename]
- Name of the exposure map file (made by the tool 'ahexpmap'), that contains histograms of satellite
attitude and related quantities, as well as "good time intervals" (GTI) for the attitude bins. In the case
of the SXI or SXS there is also an effective exposure time image in the primary extension of the exposure
- (qefile) [filename]
- 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 calibration database. For the SXI the QE is combined with the optical
blocking layer (OBL) transmission.
- (obffile) [filename]
- Name of the optical blocking filter file (needed for SXS only). If the parameter is set to CALDB,
the file is read from the calibration database.
- (fwfile) [filename]
- Name of the filter wheel filter file (needed for SXS only). If the parameter is set to CALDB, the
file is read from the calibration database.
- contamifile [filename]
- 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 calibration database.
- (abund = "1.0") [string]
- Relative abundances of contaminants. This number 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 the value of this parameter.
- (covfac = "1.0") [string]
- Partial covering factors for contaminant materials. The partial covering factors of all of the
contaminant materials in the calibration file are multiplied by this number.
- gatevalvefile [filename]
- Name of the SXS gate valve calibration file. This file is only needed for SXS observations for which
the value of the FILTER keyword is equal to CLOSED. The file accounts for the blocking and attenuation
effects of the gate valve.
- rmffile [file]
- A response matrix file (RMF). For the SXS and SXI, it is only used to extract the energy grid that
is used for the output ARF file.
- onaxisffile [filename]
- Name of the file and extension that contains the on-axis telescope effective area (appropriate for
instrument), pre-calculated on a fine energy grid. If the parameter is set to CALDB, the file is read
from the calibration database.
- onaxiscfile [filename]
- Name of file and extension that contains the on-axis telescope effective area (appropriate for instrument),
pre-calculated on a coarse energy grid. If the parameter is set to CALDB, the file is read from the
- outfile [filename]
- Name of the output ARF filename
- regionfile [filename]
- Names of standard SAO ascii region files, or the name of a file containing a list of names of such
files. In the latter case, the format is "@aharfgen_regions.lis", where aharfgen_regions.lis is an ascii
file in which each row contains the name of a region file. The coordinates of these region files are
detector 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.
- skyregfile [filename]
- Name of the source region selection file, in RA/DEC coordinates. The format is that of a standard
SAO region file. This file must be the same one that was used in 'aharfgen'. Also, the image in the
primary extension of the exposure map and 'skyregfile' must be self-consistent.
- xrtevtfile [file]
- Name of the raytracing event/history file that was created by 'aharfgen'.
- (minphoton = 100) [integer]
- The minimum number of photons that successfully reach the focal-plane, per raytracing energy grid point,
that is acceptable to make a viable ARF. The number of focal-plane photons that contribute to the ARF must
exceed minphoton for every energy, otherwise the program aborts.
- auxtransfile [filename]
- Name of the input auxiliary transmission file.
This file is used to apply additional transmission that is not accounted in the telescope
calibration files used by the raytracing. By default is set to NONE. To apply the auxiliary
transmission users has either to input a file or set to CALDB.
- (polydeg = "DEFAULT") [string]
- Polydeg defines the polynomial order for the fitting. The allowed values are: DEFAULT and
1 to 5 for the HXI and 1 to 10 for the SXS and SXI. For the HXI the DEFAULT value of polydeg is
set to 5. For the SXI and SXS, the DEFAULT value is set to the order tested internally for
- (clobber = no) [boolean, (yes|no)]
- Whether to overwrite any existing output file.
- (chatter = 1) [integer]
- Chatter level to designate desired amount output. Valid numbers are integers between 0 and 3.
All output is sent to the log file regardless of chatter level.
- 0 - nothing written to screen
- 1 - only output and errors
- 2 - output, errors, and high-priority information and warnings
- 3 - output, errors, and all information and warnings
- (logfile = !DEFAULT) [string]
- Set the name of the log file. Special values are DEFAULT and NONE for the default file name or no log
file. The default is the name of the tool with a .log extension. For example, if running ahdemo, the default
log file is named ahdemo.log. If the parameter is set to an empty string, an error is generated.
If the parameter begins with an exclamation point (!), then any existing log file with the chosen name is
- (debug = no) [boolean, (yes|no)]
- Whether or not to display debugging information. If set to yes, this paramater causes the error messages
to print a stacktrace in addition to the usual error message.
- (history = yes) [boolean, (yes|no)]
- Whether or not to record tool parameters in history keywords in all output files.
- (mode = ql) [string, (h|hl|q|ql)]
- Sets how automatic parameters are specified. Legal values are h, hl, q, and ql. Hidden parameters (h)
are not presented to the user and take the default value from the parameter file, but can be specified as
command-line arguments. Queried parameters (q) are prompted for input from the user, but give the default
value from the parameter file as a choice. Either type with learning enabled (e.g. ql) cause the default
value to change to that given in the previous run.
1. Make an ARF file for a point source in the SXS given the R.A./DEC region selection file src_sky.reg, an exposure map file src_expmap.fits made by the tool 'ahexpmap', and a set of region files in detector coordinates that are derived from src_sky.reg using the exposure map src_expmap.fits and the tool 'aharfgen', which should be run prior to running 'ahsxtarfgen'. In the example, the gate valve is open so there is no need to specify the gate valve file. Each region file in detector coordinates corresponds to an attitude histogram bin in the exposure map file. In this example, the names of the region files in detector coordinates are listed, one file per row, in the ascii file aharfgen_region.lis. The raytracing event file that is required by the tool 'ahsxtarfgen' is made by the prior run of 'aharfgen'. Note that 'ahsxtarfgen' 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 'ahsxtarfgen' only uses the energy grid in 'rmffile' and not the actual matrix data, the particular response matrix (RMF) specified for 'rmffile' is not important. The ARF made by 'ahsxtarfgen' is calculated on the exact energy grid in 'rmffile'.
The example run produces the output files: