NAME

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.

USAGE

hxirspeffimg telescop instrume erange dattfile filtoffsetfile emapfile qefile rmffile onaxisffile onaxiscfile vigfile outflatfile outfile regionfile xrtevtfile sampling

DESCRIPTION

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

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

PARAMETERS

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

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 'filtoffset=filtoffsetfile'.

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.

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

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

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

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

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

EXAMPLES

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

    hxirspeffimg telescop=HITOMI
          instrume=HXI1
	  erange="8.0 25.0"
	  dattfile=hxi1_cams_dattfile.fits
	  filtoffsetfile=hxi1_cams_filtoffset.fits
          emapfile=src_exmpmap.fits
          qefile=CALDB
          rmffile=CALDB
          onaxiscfile=CALDB
          onaxisffile=CALDB
	  vigfile=CALDB
	  outflatfile=hxi1_1_flatfield.fits
          outfile=hxi1_1
          regionfile="@arfgen_region.lis"
          xrtevtfile=src_1_raytrace.fits
	  sampling=4.0

The example run produces the output files:

SEE ALSO

LAST MODIFIED

January 2016