HEADAS help file

NAME

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.

USAGE

ahsxtarfgen telescope instrume emapfile qefile contamifile gatevalvefile rmffile onaxisffile onaxiscfile outfile regionfile skyregfile xrtevtfile

DESCRIPTION

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

PARAMETERS

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

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

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

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

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

EXAMPLES

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

ahsxtarfgen telescop=HITOMI
          instrume=SXS
          emapfile=src_exmpmap.fits
          qefile=CALDB
          obffile=CALDB
          fwfile=CALDB
          contamifile=CALDB
	  rmffile=sxs.rmf
          onaxiscfile=CALDB
          onaxisffile=CALDB
          outfile=src_1_arf.fits
	  regionfile="@arfgen_region.lis"
	  skyregfile=src_sky.reg
	  xrtevtfile=src_1_raytrace.fits

The example run produces the output files:

src_1_arf.fits

LAST MODIFIED