NAME

USAGE

DESCRIPTION

The ahsxtarfgen task creates an ancillary response file (ARF) for the SXS + SXT-S or SXI + SXT-I. 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 ahexpmap task 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 (DET) 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 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.

The ARF includes the telescope effective area (for SXS + SXT-S and SXI + SXT-I), 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 is time-dependent. The SXI has just one filter transmission, the contamination-blocking filter (CBF). The SXS has an optical blocking filter (OBF) in addition to 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 obtains the corresponding filter calibration file. 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 obtains the gate valve calibration file if the value of the GATEVALV is equal to CLOSED. However, due to the short life of Hitomi, the gate valve was never opened, so the SXS was operated with the gate valve closed for all observations.

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 SXS region files made by ahmkregion should not be used as input to ahsxtarfgen. This is because ahmkregion creates DET coordinate regions for SXS that have overlapping pixel regions.

PARAMETERS

telescop = HITOMI [string]

Mission name (value to write in header keyword TELESCOP for CALDB).

instrume = SXI [string SXI|SXS]

Instrument for which the ARF is to be made.

emapfile = expmap.fits [filename]

Name of the exposure map file (produced by the ahexpmap 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|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 calibration database (CalDB). For SXI, the QE is combined with the optical blocking layer (OBL) transmission.

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

Name of the optical blocking filter file (SXS only). If the parameter is set to CALDB, the file is read from the CalDB.

(fwfile = CALDB) [filename CALDB|file name]

Name of the filter wheel file (SXS only). If the parameter is set to CALDB, the file is read from the CalDB.

contamifile = CALDB [filename CALDB|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. The abundances of all of the contaminant materials in the calibration file are multiplied by this number.

(cols = 0.0) [string]

A comma-seperated string of numbers specifying additional column densities for contaminants [1E18 cm^{-2}]. The column density of each of the contaminant materials in the calibration file is modified by adding the appropriate value in the parameter string.

(covfac = 1.0) [string]

A comma-seperated string of numbers specifying partial covering factors for contaminant materials. The partial covering factors of each of the contaminant materials in the calibration file is multiplied by the appropriate value in the parameter string.

gatevalvefile = CALDB [filename CALDB|file name]

Name of the SXS gate valve calibration file. This file is only required for SXS 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.

rmffile = sxs.rmf [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.

outfile = sxs.arf [filename]

Name of the output ARF file.

regionfile = @aharfgen_region.lis [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=@aharfgen_region.lis', where aharfgen_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 SXS region files made by ahmkregion should not be used as input to ahsxtarfgen.

xrtevtfile = xrtraytrace_sxt_events.fits [filename]

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

(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 ahsxtarfgen to internally test more than one value for the polynomial order, and choose the value to use for based on fitting stability.

(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 in the SXS, given the RA/DEC region selection file src_sky.reg, an exposure map file (src_expmap.fits) made by the ahexpmap 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 aharfgen task, which should be run prior to running ahsxtarfgen. 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 aharfgen_region.lis. The raytracing event file that is required by the ahsxtarfgen task is made by the prior run of aharfgen. Note: 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 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
	  xrtevtfile=src_1_raytrace.fits

The example run produces the output file:

• src_1_arf.fits

SEE ALSO

LAST MODIFIED