HEADAS help file

NAME

aharfgen - Make an ancillary response function (ARF) file for the SXS or SXI, or a response matrix (RSP) file for the HXI

USAGE

aharfgen xrtevtfile source_ra source_dec instrume dattfile emapfile qefile contamifile gateevalvefile sampling rmffile erange onaxisffile onaxiscfile outfile regmode regionfile mirrorfile obstructfile frontreffile backreffile pcolreffile scatterfile numphoton sourcetype imgfile

DESCRIPTION

'aharfgen' is a script that runs the tools 'ahsxtarfgen' and 'hxirspeffimg'. When 'aharfgen' is used to run 'ahsxtarfgen', an ancillary response function (ARF) file for the SXS + SXT-S (parameter 'instrume=SXS') or the SXI + SXT-I ('instrume=SXI') combination is created. When 'aharfgen' is used to run 'hxirspeffimg', a spectral response matrix (.RSP file) for the HXI1 + HXT ('instrume=HXI1') or HXI2 + HXT ('instrume=HXI2') combination is created. 'aharfgen' takes as input an exposure map file created by the tool 'ahexpmap'. The exposure map file contains information about the satellite attitude and variation in the telescope optical axis pointing, as well as spatial effective exposure time information. A standard SAO region file input can be used to specify the region in RA/DEC or DET coordinates for which the output ARF or RSP files are created (see 'regmode' and 'regionfile' parameter). If the region is in RA/DEC coordinates, the script then creates a number of selection regions in the DET coordinate system corresponding to discrete satellite attitude intervals (or histogram bins) described in the exposure map file. The options for specifying the spatial distribution of the of X-ray source, are (1) point source ('sourcetype=point'), (2) uniform source ('sourcetype=flatcircle') with a set radius (see 'flatradius' parameter), (3) beta model ('sourcetype=betamodel'; see 'betapars' parameter), and (4) input image ('sourcetype='image'). The image option, useful for extended sources, uses an input image file to create a photon event list by the simulation tool 'heasim'. This event list is subsequently input into the raytracing code. The input image file could be made from data from a different mission, or from a model. The source position is input using the 'source_ra' and 'source_dec' parameters.

'aharfgen' runs the raytracing tool 'xrtraytrace', using information about the source and region selection to simulate photon paths through the X-ray telescope. The photon paths, or events, along with the source and region information, are passed onto 'ahsxtarfgen' or 'hxieffrspimg' in order to enable the telescope effective area to be calculated. Detector efficiencies are calculated in 'ahsxtarfgen' and 'hxieffrspimg', not in 'aharfgen'. The raytracing file is saved and can be used again to run either 'ahsxtarfgen' or 'hxieffrspimg' without running 'xrtraytrace'. When 'aharfgen' is run, and it finds that a raytracing file with the requested file name already exists, 'aharfgen' skips running the raytracing code again, and instead pass on the existing event file onto 'ahsxtarfgen' or 'hxirspeffimg'. Running the raytracing code is very time-intensive so this feature avoids unnecessarily long run times whenever possible. 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 number of photons injected into the raytracing code determines the statistical accuracy of the effective area and detector efficiencies. This number is controlled by the parameter 'numphoton'. The total number of photons injected into the raytracing code is determined by an algorithm that takes into account the relative time intervals for each attitude bin as given in the first extension of the exposure map file. Each row in the first extension of the exposure map file corresponds to one attitude bin. The value of the parameter 'numphoton' corresponds roughly to the number of raytracing photons allocated to each attitude bin per energy grid point. If any attitude bin has a time interval significantly larger than the average time interval, 'aharfgen' allocates additional raytracing photons to that attitude position. Note that the raytracing is performed on a coarse energy grid for modeling the spatial distribution of photons, which has a weak energy dependence. The final effective area calculated by 'aharfgen' combines these coarse-grid results with some pre-calculated raytracing results that were obtained on a fine energy grid that captures all of the atomic physics at a level of detail sufficient for the SXS.

As a rough guide, one should aim for a minimum total of 3 million photons over the whole energy range, and numphoton can be estimated by numphoton ~ (total number of photons/number of attitude bins/X), where X~16 for SXS or SXI over the energy range 0.4-15 keV, and X~270 for the HXI over the energy range 4-70 keV. The run time for the raytracing code is approximately 1 minute per 100,000 photons. The energy range for which 'aharfgen' calculates the ARF or RSP files is selectable by the user, and ranges wider than the nominal ranges just mentioned may be specified. For the SXS the energy range can span 0.03 to 30 keV; and, for the SXI, 0.03 to 24 keV. For the HXI the energy range can span 2 to 120 keV. However the calibration outside of the nominal energy ranges is not reliable, so it is not recommended to choose wider ranges the nominal ones, which would also result in a substantial increase in the runtime.

PARAMETERS

xrtevtfile [filename]: Name of event/history file created by the raytracing program 'xrtraytrace', and used by 'aharfgen'. If xrtevtfile does not exist 'aharfgen' creates it by running 'xrtraytrace'. If xrtevtfile is the name of an existing file that was previously created by 'aharfgen', this file is used instead of creating a new one.
source_ra [real]: Right ascension (RA, degrees) of the X-ray source for which the ARF is to be created. For 'sourcetype=flatcircle' or 'betamodel', it is the RA of the center of the source. For 'sourcetype=image', the parameter 'source_ra' represents the RA position of the source within the image. If there is no obvious source, it should be set to the RA position of the center of the image.
source_dec [real]: Declination (DEC, degrees) of the X-ray source for which the ARF is to be created. For 'sourcetype=flatcircle' or 'betamodel', it is the DEC value of the center of the source. For 'sourcetype=image', the parameter 'source_dec' represents the DEC position of the source within the image. If there is no obvious source in the image, it should be set to the DEC position of the center of the image.
(nompntpars) [string]: This parameter is only used if no exposure map is input to 'aharfgen' ('emapfile=NONE'). The parameter consists of a string of five numbers as follows: (1) RA of satellite pointing direction; (2) DEC of satellite pointing direction; (3) Roll angle of satellite; (4) RA of the telescope optical axis; (5) DEC of the telescope optical axis.
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, SXS, HXI1, or HXI2.
(teldeffile) [filename]: Name of the telescope definition file appropriate for the instrument for which the ARF is to be made. If the parameter is set to CALDB, the file is read from the calibration database.
dattfile [filename]: Name of the CAMS delta-attitude file describing the position of the optical axis in RAWX, RAWY, as a function of time. This parameter is only used if 'instrume = HXI1' or 'instrume = HXI2'. The columns used are RAWX_FLOAT, RAWY_FLOAT.
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'), containaing 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 to the value in contamifile.
(covfac = "1.0") [string]: Partial covering factors for contaminant materials. This number multiplies the partial covering factors of all of the contaminant materials in the calibration file
gatevalvefile [filename]: Name of the SXS gate valve calibration file. This file is only needed 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 gatevalve.
sampling [integer]: This parameter is only needed if 'instrume = HXI1' or 'instrume = HXI2'. It is the sampling factor for the HXI CAMS delta-attitude bins. if 'sampling = 1' then the original binning in the 'dattfile' is used. If 'sampling = N', then use the first bin, then the (N+1)th bin etc.
(baffle = "64.0 64.0 25.35 622.0 24.67 124.0") [string]: This parameter is only needed if 'instrume =HXI1' or 'instrume = HXI2'. It is a string list of six numbers that specify parameters of the HXI baffle model as follows: (1) Baffle center RAWX coordinate, (2) Baffle center RAWY coordinate, (3) Radius of top entrance of baffle (mm), (4) Height of baffle entrance hole above focal plane (mm), (5) Radius of bottom exit of baffle (mm), (6) Height of exit hole above focal plane (mm).
rmffile [filename]: Name of a response matrix file (RMF) valid for the instrument for which the arf is generated. For the SXI and SXS the rmffile is always a single file, generated either by 'sxsrmf' or 'sxsirmf,' from which the energy grid is read and used within aharfgen for the output energy grif of the ARF file. For the HXI instead the rmffile may be input as ascii file containing a list of the rmffiles, prefixed with "@" or as CALDB. The ascii file contains one RMF filename per line and to calculate the ARF the HXI requires 5 RMF one for each of the detector layers. If set to CALDB aharfgen automatically retrives the correct RMF.
erange [string]: A string containing four numbers. The first and second numbers correspond to the minimum and maximum energy, respectively, of the valid data in the output ARF or RSP file (points outside this range are filled with zeros). Restricting the energy range in this way may be used to shorten the run time, if a restricted energy range is sufficient for the application. The third and fourth numbers in the input parameter string are only relevant if 'sourcetype = image' (one of the extended source options), and are set to the lower and upper energy bound respectively, of the image data.
onaxisffile [filename]: Name of the file and extension that contains the on-axis telescope effective area, appropriate for the 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 the 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 or RSP file.
regmode [string RADEC|DET]: Type of coordinate system associated with the region file ('regionfile'), RADEC or DET.
regionfile [filename]: Name of the source region selection file, in RADEC (RA/DEC units) or DET coordinates. The format is that of a standard SAO region file.
mirrorfile [filename]: Name of the telescope description file (TDF) and the extension (e.g., MIRROR) that holds the geometrical description of primary and secondary mirror foils. It is assumed that the name of the pre-collimator extension is COLLIMATOR. If the parameter is set to CALDB, the file is read from the calibration database.
obstructfile [filename]: The name of the telescope description file (TDF) and the extension (e.g. OBSTRUCT) that holds the geometrical description of the telescope support structures. If the parameter is set to CALDB, the file is read from the calibration database.
frontreffile [filename]: The name of the reflectivity file and the extension for the front-side reflectivity of the mirror foils. The extension also includes the thin surface film transmission. The names of the reflectivity and transmission columns are linked to groups of mirror foils that they apply to, by means of a column called FREFLECT in the TDF. Note that the second extension in the reflectivity file contains mass-absorption coefficients that are used by the raytracing code 'xrtraytrace' to calculate transmission probabilities of the "thick" materials (as opposed to thin films) in the telescope.
backreffile [filename]: The name of the reflectivity file and the extension for the backside reflectivity of the mirror foils.
pcolreffile [filename]: The name of the reflectivity file and the extension for the reflectivity of the pre-collimator blades/foils. The pre-collimator reflectivity is the same for frontside and backside reflection.
scatterfile [filename]: The name of the file containing the scattering angle probability distributions for the direction of reflected rays relative to the specular direction. The file contains data for the frontside of mirror foils, the backside of mirror foils, and for the pre-collimator blades. In general, foils in different physical regions of the telescope can have different scattering distributions. The column names are referenced in the SCATTER column in the TDF.
numphoton [integer]: The value of the parameter 'numphoton' corresponds roughly to the number of raytracing photons allocated to each attitude histogram bin (in the exposure map file), per energy grid point. If any attitude bin has a time interval significantly larger than the average time interval, 'aharfgen' allocates additional raytracing photons to the that attitude position.
(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.
sourcetype [string]: Method for treatment of the spatial distribution of the X-ray source. (1) Point: Point source at infinity. Photons arrive at random points on the active region of the telescope aperture. (2) Flatcircle: Extended source at infinity that has a spatial distribution that has uniform flux over a circular region (zero outside of the circle). (3) Betamodel: Extended source at infinity that has a spatial distribution described by the "beta model" (see 'betapars' parameter). (4) Image: A FITS image file (in RA/DEC coordinates) is used to create a photon event list using the simulation code 'heasim'. This event list is subsequently input into the raytracing code by 'aharfgen'. The input image file could be made from data from a different mission, or from a model. The name of the image file is given by the parameter 'imgfile'.
(betapars = "0.50 0.60 5.0") [string]: Parameters of the beta model if 'sourcetype' is set to 'betamodel' as follows: (1) beta model core radius in arcmin, (2) the index "beta" of the beta model, (3) the maximum radius (in arcmin) of the source spatial distribution.
(flatradius = 10.0) [real]: The radius (in arcmin), of the extended source for the flat spatial distribution option, 'sourcetype=flatcircle'.
imgfile [filename]: Name of the input image file to be used for raytracing if the input parameter 'sourcetype=image'. The image should be in the primary extension and coordinate system should be SKY (RA/DEC units). The minimal mandatory keywords are the standard ones describing the "X" and "Y" grids: CRPIX1, CRVAL1, CDELT1, CUNIT1, CRPIX2, CRVAL2, CDELT2, CUNIT2.
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. This valid for HXI, SXI and SXS. By default is set to NONE. To apply the auxiliary transmission users has either to input a file or set to CALDB.
(rmfthresh = 1.0e-10) [real]: This parameter is only valid for the HXI not for the SXI or SXS. 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.
(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.
(seed = 29075) [integer]: Random number seed. If the value is zero then the code uses the system time to generate a random number.
(cleanup = no) [boolean]: Determines whether to delete temporary files (yes/[no]).
(clobber = no) [boolean]: Overwrites the existing output file if set to yes (yes/[no]).
(chatter = 1) [integer]: 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]: Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.
(debug = no) [boolean]: Diagnostic output is printed out on the screen if set to yes (yes/[no]).
(history = yes) [boolean]: Records tool parameters in HISTORY ([yes]/no).
(mode = ql) [string ql|hl|q]: Mode to query the parameter file. Acceptable values include: "ql (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).(Optional)

EXAMPLES

1. Make an ARF file for a point source in the SXI given the RA/DEC region selection file src_sky.reg, and an exposure map file src_expmap.fits made by the tool 'ahexpmap'. An example of the contents of the region file src_sky.reg is:

# Region file format: DS9 version 4.1 global color=green dashlist=8 3 width=1 font="helvetica 10 normal" select=1 high lite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1 wcs=wcs fk5 circle(140.0,35.0,150.0")

In this example the source RA and DEC coordinates are 140 and 35 degrees respectively, and the extraction region is a circle centered on the source, with a radius of 150 arcsec. The parameters 'source_ra' and 'source_dec' that should be entered are equal to the values of the corresponding source coordinates in the region file. For the SXS or SXI, 'ahsxtarfgen' (called by aharfgen) only uses the energy grid in 'rmffile' and not the actual matrix data, so 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'.

aharfgen  xrtevtfile=src_1_raytrace.fits 
	  source_ra=140.0
	  source_dec=35.0
	  telescop=HITOMI
	  instrume=SXI
	  teldeffile=CALDB (ah_sxi_teldef_20140101v001.fits)
	  emapfile=src_exmpmap.fits
	  qefile=CALDB (ah_sxi_quanteff_20140101v001.fits)
	  contamifile=CALDB (ah_sxi_contami_20140101v001.fits)
          rmffile=sxi.rmf
	  erange="0.4 15.0 0.4 15.0" 
	  onaxiscfile=CALDB (ah_sxi_telarea_20140101v001.fits[EFFAREACRS])
	  onaxisffile=CALDB (ah_sxi_telarea_20140101v001.fits[EFFAREAFNE])
	  outfile=src_1_arf.fits
	  regmode=RADEC
	  regionfile=src_sky.reg
	  mirrorfile=CALDB (ah_sxi_mirror_20140101v001.fits[MIRROR])
	  obstructfile=CALDB (ah_sxi_mirror_20140101v001.fits[OBSTRUCT])
	  frontreffile=CALDB (ah_sxi_reftrans_20140101v001.fits[AH_SXT_FRONT])
	  backreffile=CALDB  (ah_sxi_reftrans_20140101v001.fits[REFPROBBACK])
	  pcolreffile=CALDB  (ah_sxi_reftrans_20140101v001.fits[REFPROBPCOL])
	  scatterfile=CALDB  (ah_sxi_scatter_20140101v001.fits)
	  numphoton=10000
	  sourcetype=point

The example run produces the output following files: (1) src_1_arf.fits; (2) aharfgen_region.lis (contains the names of region files made in detector coordinates: src_1_arf.arfregion0.reg to src_1_arf.arfregionN.reg where N is the number of attitude histogram bins in the exposure map file, extension 1; (3) src_1_raytrace.fits.

KNOWN BUGS

If 'aharfgen' is run with 'sourcetye=image', the number of photons generated from the image in the initial event list should be equal to the input parameter 'numphoton', but this is not the case. A way to mitigate the effects of this bug is to run 'aharfgen' with the intended value of 'numphoton' and note in the screen output the number of actual source events generated by the tool 'heasim.' Then interrupt 'aharfgen' and run it again with a new value of 'numphoton' set to the original value squared divided by the actual number of events generated by heasim.

LAST MODIFIED

January 2016