NAME

hxirspeffimg - Creates a combined effective area 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

The hxirspeffimg task creates the following for the HXI1 + HXT1 or HXI2 + HXT2 combinations:

The hxirspeffimg task takes as input an exposure map file, a set of region files in detector (DET) 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 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 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 RSP file is recalculated using a different binning (the binning is defined by the RMF), a 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 hxirspeffimg must consider satellite attitude variations for many CAMS motion time intervals, the runtime of hxirspeffimg can be potentially impractical. The parameter 'sampling' allows a trade-off between runtime 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 = HITOMI [string]
Mission name (value to write in header keyword TELESCOP for CALDB).

instrume = HXI1 [string HXI1|HXI2]
Instrument for which the RSP file is to be made.

erange = 6 6 [string]
A string containing two numbers that correspond to the lowest and highest energies [keV] of the bandpass for calculating the flat field correction image.

dattfile = deltatt.fits [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 'dattfile' file is produced by running cams2att.

filtoffsetfile = filtoffset.fits [filename]
Name of the delta-attitude file describing the CAMS motion with columns DELTARAWX, DELTARAWY, SINANGLE, and COSANGLE, as a function of time. The 'filtoffsetfile' file is produced by running cams2att with 'filtoffset=filtoffsetfile'.

emapfile = expmap.fits [filename]
Name of the exposure map file (made by the ahexpmap task) that contains histograms of satellite attitude and related quantities, as well as good time intervals (GTI) for the attitude bins.

onaxisffile = onaxisfine_ea.fits [filename CALDB|file name]
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 = onaxiscoarse_ea.fits [filename CALDB|file name]
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 = @regionfilelist.txt [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 name of an ASCII file in which each row contains the name of a region file is preceded by an "@" symbol. 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, and not the flat field file.

xrtevtfile = xrtraytrace_hxt_events.fits [filename]
Name of the raytracing event file that was created by aharfgen.

outflatfile = hxi_flatfield_image.fits [filename]
Name of the output image file containing the flat field or efficiency image. If 'outflatfile' is set to NONE, then no flat field or efficiency image is created. The type of image created is determined by 'outmaptype'.

outmaptype = EXPOSURE [string EXPOSURE|EFFICIENCY]
Type of image output. When 'outmaptype=EXPOSURE', the image contains the exposure time [s] for each pixel. When 'outmaptype=EFFICIENCY', the image accounts for the vignetting and quantum efficiency, as well as the exposure times; the pixel values in this case are normalized as a fraction of the total, so they range between 0 and 1. The file name is specified by 'outflatfile'. If 'outflatfile=NONE', 'outmaptype' is ignored. Only one map may be created for each run.

outfile = hxi [filename NONE|file root name]
File name stem for the output RSP file and the output ancillary response file (ARF). The actual file names 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 = 4 [integer]
Sampling factor for the HXI CAMS delta-attitude bins. If 'sampling = 1', the task uses the original time binning in the input CAMS files ('dattfile' and 'filtoffsetfile'). If 'sampling=N', the task uses the first time bin, then the (N+1)th time 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', this matrix element is set 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 = CALDB [filename CALDB|file name]
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 vs. energy functions for each of 5 layers). If the parameter is set to CALDB, the file is read from the calibration database.

rmffile = CALDB [filename CALDB|file name]
Name of the line-spread-function (LSF) file that contains five response matrices (RMF). One matrix is required for each of the 5 layers of a single HXI detector. If the parameter is set to CALDB, the file is read from the calibration database. The energy grid of 'rmffile' is the same one that is used for final output 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. The 'rmffile' parameter is not necessary for creating the flat field file.

vigfile = CALDB [filename CALDB|file name]
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. The 'vigfile' parameter is not necessary for creating an RSP file.

auxtransfile = CALDB [filename CALDB|file name]
Name of the input auxiliary transmission file. This file is used to apply an additional transmission factor (which can be greater than 1.0), that is not accounted in the telescope calibration files used by xrtraytrace.

(stopsys = SKY) [string ACT|DET|FOC|SKY]
Name of the coordinate system for the flat field output.

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

(polydeg = DEFAULT) [string DEFAULT|1|2|3|4|5]
The 'polydeg' parameter defines the polynomial order for the fitting. For the HXI, the DEFAULT value of 'polydeg' is set to 5.

(buffer = -1) [integer -1|0|N]
Rows to buffer (-1=auto, 0=none, N>0=numrows).

(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 RSP, ARF, and flat field for a source in HXI1, given an exposure map file (src_expmap.fits) produced 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 hxirspeffimg. 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 detector coordinates are listed, one file per row, in the ASCII file aharfgen_region.lis. The raytracing event file that is required by the hxirspeffimg task is made by a 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

ahexpmap, aharfgen, ahsxtarfgen, xrtraytrace

LAST MODIFIED

November 30, 2018