hxirspeffimg - Creates a combined effective are and spectral response matrix ("RSP" file)
and/or a flat-field correction image, for the HXI1 + HXT1 or HXI2 + HXT2 combinations,
accounting for the telescope effective area, detector efficiencies, and CAMS motion.
hxirspeffimg telescop instrume erange dattfile filtoffsetfile emapfile qefile rmffile
onaxisffile onaxiscfile vigfile outflatfile outfile regionfile xrtevtfile sampling
'hxirspeffimg' creates, for the HXI1 + HXT1 or HXI2 + HXT2 combinations:
'hxirspeffimg' 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 tool 'ahexpmap' and contains histograms based on discrete
satellite attitude pointings. The region files are made by the script 'aharfgen' which uses the
attitude information in the exposure map file and the information in a region file in R.A./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.
- A combined effective area and spectral response file (or RSP file) and/or
- A flat-field correction image.
The RSP file and flat-field corrections include the effects
of the telescope effective area, detector quantum efficiency, satellite attitude variations, and
the CAMS motion of the optical bench with respect to the telescope. Note that, since 'hxirspeffing'
must consider satellite attitude variations for many CAMS motion time intervals, the run time of
'hxirspeffimg' can be potentially impractical. The parameter 'sampling' allows a trade-off between
run time and the accuracy of the final RSP and/or flat-field file, by not considering every time
bin in the CAMS input files (see description for parameter 'sampling').
- telescop [string]
- Mission name (value to write in header keyword TELESCOP for CALDB).
- instrume [string]
- Instrument for which the response matrix (RSP) file is to be made: HXI1 or HXI2.
- erange [string]
- A string containing two numbers that correspond to the lower and upper energy (in keV) of the
bandpass for calculating the flat-field correction image.
- dattfile [filename]
- Name of the file containing the RAWX, RAWY coordinates of the optical axis as a function of time
(the optical axis RAWX, RAWY position moves due to the CAMS motion). The file is made by running
- filtoffsetfile [filename]
- Name of the delta-attitude file describing the CAMS motion with columns DELTARAWX, DELTARAWY,
SINANGLE, COSANGLE, as a function of time. The file is made by running cams2att with
- 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
- onaxisffile [filename]
- Name of a file and extension that contains the on-axis telescope effective area (appropriate for
instrument), pre-calculated on a fine energy grid. This file must also have, in the primary extension,
an image that allows 'hxirspeffimg' to correct for the shadowing effects of HXI baffle structure in
the flat-field calculations. If the parameter is set to CALDB, the file is read from the calibration
- onaxiscfile [filename]
- Name of a 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.
- 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 coordinate system 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.
The region files are only needed for creating the RSP file (response matrix), and not the flat-field
- xrtevtfile [filename]
- Name of the raytracing event file that was created by 'aharfgen'.
- outflatfile [filename]
- Name of the output image file containing the flat-field efficiency image. If outflatfile is set to
NONE, the flat-field calculations are not performed, and no flat-field file is made.
- outmaptype [string]
- Type of map output. The possibke type are EXPOSURE or EFFICIENCY. The first contains just the
time in each pixel given in seconds. The second contains the quantum efficiency and exposure effect normalized by the
total therefore each oixel value ranges betaeen 0 and 1. The name of the map is given in outflatfile.
The EXPOSURE and/or EFFICIENCY may be written out when the task is either run to create an rsp or a flat field.
Only one map may be created for each run.
- outfile [filename]
- Filename stem for the output response matrix (RSP) file and the output
ancillary response file (ARF). The actual filenames are formed by
concatenating the stem with extensions '.rsp' and '.arf', respectively.
If outfile is set to NONE, the response matrix calculations are not performed,
and the RSP file and ARF are not written.
- sampling [integer]
- Sampling factor for the HXI CAMS delta-attitude bins. 'sampling = 1" uses the original time binning
in the input CAMS files ('dattfile' and 'filtoffsetfile'). 'sampling=N' uses the first time bin, and
then the (N+1)th bin etc.
- (rmfthresh = 1.0e-10) [real]
Define the lower threshold for writing non-zero matrix elements in the HXI output RSP file. If the
matrix elements value is less than the value of rmfthresh then that matrix element is et to 0.
It is not recommended to increase the value rmfthresh above the default value as it may reduce
the compressibility of the output, making the matrix too large for the software to handle.
- qefile [filename]
- Name of the file containing the quantum efficiency (QE) for the detector, a function of energy
for each pixel (i.e. a 128x128 image of QE versus energy functions for each of 5 layers). If the
parameter is set to CALDB, the file is read from the calibration database.
- rmffile [filename]
- Name of the line-spread-function (LSF) file that contains five response matrices (RMFs). One matrix
is required for each of the 5 layers of one HXI detector. If the parameter is set to CALDB, the file
is read from the calibration database. The energy grid 'rmffile' is the one that is used for final
output response matrix (RSP) file. A single output RSP file is created that contains the correct
weighting for the responses separated by layer, and includes the telescope effective area, as well
as the effects of the CAMS motion. 'rmffile' is not needed for creating the flat-field file.
- vigfile [filename]
- Name of the calibration file containing coefficients that are used in analytic functions to
calculate the telescope vignetting functions, used in the flat-field calculations. If the parameter is
set to CALDB, the file is read from the calibration database. 'vigile' is not needed for creating an
RSP file (response matrix).
- 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.
- (stopsys = SKY) [string]
- Name of the coordinate system for the flatfield output. By default is SKY pixels.
Other coordintes are ACT, DET or FOC.
- (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 response matrix (RSP) file. The number of focal-plane
raytraced photons that contribute to the effective area of the telescope must exceed minphoton for
every energy, otherwise the program aborts.
- (baffle = "64.0 64.0 25.35 622.0 24.67 124.0") [string]
- A string list of six numbers that specify parameters of the HXI baffle model as follows:
1st value = Baffle center RAWX coordinate
2nd value = Baffle center RAWY coordinate
3rd value = Radius of top entrance of baffle (mm)
4th value = Height of baffle entrance hole above focal plane (mm)
5th value = Radius of bottom exit of baffle (mm)
6th value = Height of baffle exit hole above focal plane (mm)
- (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
- (buffer = -1) [integer]
- Rows to buffer (-1=auto, 0=none, >0=numrows)
- (clobber = no) [boolean, (yes|no)]
- Whether or not 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 parameter causes 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
1. Make a response matrix (RSP file), ARF, and flat field for a source in HXI1, given 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 'hxiespeffimg'. 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 'hxirspeffimg' is made by the prior run of 'aharfgen'. Note that 'hxirspeffimg' 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. In this example, the energy range selected for the flat field image is 8 to 25 keV. The two CAMS files ('dattfile' and 'filtoffsetfile') are made by running 'cams2att' (with 'filtoffset=filtoffsetfile'), prior to running 'hxirspeffimg'.
The example run produces the output files: