NAME

USAGE

DESCRIPTION

The aharfgen task is a script that runs the tasks ahsxtarfgen or 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-1 ('instrume=HXI1') or HXI2 + HXT-2 ('instrume=HXI2') combination is created. The aharfgen task takes as input an exposure map file created by the ahexpmap task. 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' parameters). 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), that are contained in the exposure map file. The options for specifying the spatial distribution of the X-ray source are: (1) point source ('sourcetype=POINT'), (2) uniform emission from an extended circular region ('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 using the simulator task heasim. This event list is subsequently used to generate input for 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.

The aharfgen task runs the raytracing task 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 hxirspeffimg in order to enable the net effective area to be calculated. Detector efficiencies are calculated in ahsxtarfgen and hxirspeffimg, not in aharfgen. The raytracing file is saved and can be used again to run either ahsxtarfgen or hxirspeffimg without rerunning xrtraytrace. When aharfgen is executed, and it finds that a raytracing file with the requested file name already exists, aharfgen skips running the raytracing code again, and instead passes the existing event file onto ahsxtarfgen or hxirspeffimg. Running the raytracing code is very time-intensive, therefore 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 energy binning (the binning is defined by the RMF), a different region, or a different choice about whether to use the auxiliary transmission file or not (see parameter 'auxtrans').

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 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 is designed to capture 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 nominal energy range 0.4-15 keV, and X~270 for the HXI over the nominal 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 from 2 to 120 keV. However, the calibration outside of the nominal energy ranges quoted above is not reliable, so it is not recommended to choose wider ranges the nominal ones; this would also result in a substantial increase in the run time.

Note that SXS region files made by ahmkregion should not be used as input to aharfgen. This is because ahmkregion creates DET coordinate regions for SXS that have overlapping pixel regions.

PARAMETERS

xrtevtfile = xrtraytrace_sxt_events.fits [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 = 150.0 [double]

Right ascension (RA, degrees) of the X-ray source for which the ARF is to be created. For 'sourcetype=FLATCIRCLE' or 'sourcetype=BETAMODEL', 'source_ra' is the RA of the center of the source. For 'sourcetype=IMAGE', the parameter 'source_ra' represents the RA position of the targeted source within the image. If there is no obvious source, 'source_ra' should be set to the RA position of the center of the image.

source_dec = 50.0 [double]

Declination (DEC, degrees) of the X-ray source for which the ARF is to be created. For 'sourcetype=FLATCIRCLE' or 'sourcetype=BETAMODEL', 'source_dec' is the DEC value of the center of the source. For 'sourcetype=IMAGE', the parameter 'source_dec' represents the DEC position of the targeted source within the image. If there is no obvious source in the image, 'source_dec' should be set to the DEC position of the center of the image.

(nompntpars = 43.0 65.0 130.0 43.0 65.0) [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, and (5) DEC of the telescope optical axis.

telescop = HITOMI [string]

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

instrume = SXI [string SXS|SXI|HXI1|HXI2]

Instrument for which the ARF is to be made.

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

Name of the telescope definition (teldef) 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 (CalDB).

dattfile = deltatt.fits [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 and RAWY_FLOAT.

filtoffsetfile = filtoffset.fits [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 = expmap.fits [filename]

Name of the exposure map file (created by the task ahexpmap) containaing histograms of satellite attitude and related quantities, as well as good time intervals (GTI) for the attitude bins. In the case of SXI or SXS, 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 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 (needed for 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 filter file (needed for 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 modifier. This number multiplies the abundances of all of the contaminant materials in the CalDB.

(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 modifier for contaminant materials. This number multiplies the partial covering factors of all of the contaminant materials in the calibration file.

gatevalvefile = CALDB [filename CALDB|file name]

Name of the SXS gate valve calibration file. This file is only necessary 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. If 'gatevalvefile=CALDB', the gate valve file in the CalDB is used.

sampling = 4 [integer]

This parameter is only necessary if 'instrume=HXI1' or 'instrume=HXI2'. It is the sampling factor for the HXI CAMS delta-attitude bins. If 'sampling=1', the original binning in the 'dattfile' is used. If 'sampling=N', 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 necessary 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 [mm] of top entrance of baffle, (4) height [mm]of baffle entrance hole above focal plane, (5) radius [mm] of bottom exit of baffle, and (6) height [mm] of exit hole above focal plane.

rmffile = sxi.rmf [filename CALDB|file name]

Name of a response matrix file (RMF) valid for the instrument for which the ARF is generated. For SXI and SXS, the 'rmffile' is always a single file, generated either by sxirmf or sxsrmf (respectively), from which the energy grid is read and used within aharfgen for the output energy grid of the ARF file. For HXI, instead the 'rmffile' may be input as an ASCII file containing a list for 'rmffile', prefixed with "@", or as CALDB. The ASCII file contains one RMF file name per line and in order to calculate the ARF, HXI requires 5 RMF, one for each of the detector layers. If set to CALDB, the aharfgen task automatically retrives the correct RMF from the CalDB.

erange = 0.10 17.0 2.0 8.0 [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 = CALDB [filename CALDB|file name and extension]

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 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 instrument, pre-calculated on a coarse energy grid. If the parameter is set to CALDB, the file is read from the CalDB.

outfile = sxi.arf [filename]

Name of the output ARF or RSP file.

regmode = DET [string RADEC|DET]

Type of coordinate system associated with the region file ('regionfile'). For SXS you can only use 'regmode=DET'.

regionfile = extract.reg [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. However, SXS region files made by ahmkregion should not be used as input to aharfgen, and the region file must be in DET coordinates.

mirrorfile = CALDB [filename CALDB|file name and extension]

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 'mirrorfile' is set to CALDB, the file is read from the CalDB.

obstructfile = CALDB [filename CALDB|file name and extension]

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

frontreffile = CALDB [filename CALDB|file name and extension]

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 = CALDB [filename CALDB|file name and extension]

Name of the reflectivity file and the extension for the backside reflectivity of the mirror foils.

pcolreffile = CALDB [filename CALDB|file name and extension]

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 front-side and back-side reflection.

scatterfile = CALDB [filename CALDB|file name and extension]

Name of the file containing the scattering angle probability distributions for the direction of reflected rays relative to regular (incident angle = reflected angle) specular reflection. 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 = 20000 [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 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 = POINT [string POINT|FLATCIRCLE|BETAMODEL|IMAGE]

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 with 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 RADEC 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 may 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=BETAMODEL' as follows: (1) beta model core radius [arcmin], (2) the index beta of the beta model, and (3) the maximum radius [arcmin] of the source spatial distribution.

(flatradius = 10.0) [double]

The radius [arcmin] of the extended source for the flat spatial distribution option 'sourcetype=FLATCIRCLE'.

imgfile = image.fits [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 (in RA/DEC units). The minimal mandatory keywords required are the standard ones describing the X and Y grids: CRPIX1, CRVAL1, CDELT1, CUNIT1, CRPIX2, CRVAL2, CDELT2, and CUNIT2.

(auxtransfile = NONE) [filename NONE|CALDB|file name]

Name of the input auxiliary transmission file. This file is used to apply an additional transmission modifier to the output ARF, corresponding to effects of unknown origin that are not accounted for in the telescope calibration files used by the raytracing. The options are valid for HXI, SXI, and SXS. If 'auxtransfile=CALDB', the file is read from the CalDB.

(rmfthresh = 1.0e-10) [double]

This parameter is only valid for HXI, not for SXI or SXS. The 'rmfthresh' parameter defines the lower threshold for writing non-zero matrix elements in the HXI output RSP file. If the matrix element's value is less than the value of 'rmfthresh', the 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.

(polydeg = DEFAULT) [string DEFAULT|1|2|3|4|5|6|7|8|9|10]

The parameter 'polydeg' defines the polynomial order for the fitting of an internal function. The allowed values are 1 to 5 for HXI, and 1 to 10 for SXS and SXI. For HXI, the default value of 'polydeg' is set to 5. For SXI and SXS, the default value is set to a value obtained internally by testing for fitting stability.

(seed = 29075) [integer]

Random number generator seed; uses system time for 'seed=0'.

(cleanup = no) [boolean yes|no]

Delete temporary files.

(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 task parameters in HISTORY.

EXAMPLES

1. Make an ARF file for a point source in the SXI, given an RA/DEC region selection file (src_sky.reg), and an exposure map file (src_expmap.fits) made by the ahexpmap task. 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 SXS or SXI, ahsxtarfgen (called by aharfgen) only uses the energy grid in 'rmffile' and not the actual matrix data, therefore the particular 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
   	  emapfile=src_exmpmap.fits
   	  qefile=CALDB
   	  contamifile=CALDB
             rmffile=sxi.rmf
   	  erange="0.4 15.0 0.4 15.0"
   	  onaxiscfile=CALDB
   	  onaxisffile=CALDB
   	  outfile=src_1_arf.fits
   	  regmode=RADEC
   	  regionfile=src_sky.reg
   	  mirrorfile=CALDB
   	  obstructfile=CALDB
   	  frontreffile=CALDB
   	  backreffile=CALDB
   	  pcolreffile=CALDB
   	  scatterfile=CALDB
   	  numphoton=10000
   	  sourcetype=point
   

   This example run produces the following output 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), and (3) src_1_raytrace.fits.

2. This example is essentially the same as above, with the exception that every parameter that was set to CALDB above, is now replaced by a file name in order to illustrate the types of files and extensions that can be input for the various file parameters.

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

KNOWN BUGS

If aharfgen is run with 'sourcetype=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 (although the two numbers match approximately). 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 task 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.

SEE ALSO

LAST MODIFIED