NAME

USAGE

DESCRIPTION

The ahexpmap task creates either an exposure map (for HXI, SXI, and SXS), containing an integrated exposure time for each pixel (with 'outmaptype=EXPOSURE'), or a flat field image (for SXI and SXS), in which effects such as detector quantum efficiency, filter transmission, and telescope vignetting are included (with 'outmaptype=EFFICIENCY'). The 'outmaptype=EXPOSURE' output is an input to the aharfgen task, whereas the 'outmaptype=EFFICIENCY' output may be directly used for exposure correction in image analysis.

For both 'outmaptype' modes, the task requires an EHK file ('ehkfile') and a GTI file ('gtifile') as input. The EHK file contains orbital and attitude information. The GTI file is the same as that used to screen the event file (these GTI are typically in the second extension of the event data file). In addition, two files, the bad image file ('badimgfile') and the pixel GTI file ('pixgtifile') may be optionally input. The task reads the input EHK file and calculates a residual (off-axis) of the satellite attitude from the mean optical axis for each time stamp. Then, it determines a time interval for each off-axis wedge for which the size may be set by the parameters 'delta' and 'numphi'. When 'delta=A' and 'numphi=B' ("A" is a real number and "B" an integer), the off-axis wedges are populated as follows. First, the sky region is divided into a central circle and outer annuli with radii of A*(n-1) arcmin, where n=0 for the central circle, n=1,2,3.. for the subsequent annuli. Then, the innermost annulus (n=1) is divided into B wedges. Similarly, the n-th annulus is divided into B*n wedges.

If 'outmaptype=EXPOSURE' and 'instrume=SXI or SXS', the output file contains an exposure map image in the primary extension (where each pixel contains the net exposure time in seconds) and an off-axis histogram table in the first extension. This table contains information such as the average attitude and exposure time of each off-axis wedge. The following extensions (from the second to the last) contain pixel lists for each attitude histogram bin (or off-axis wedge), in which each pixel that had less than the full exposure time for that bin has its coordinates and fractional exposure time listed.

The output exposure map image may be in either DET, FOC, or SKY coordinates, set by the parameter 'stopsys'. If 'stopsys=SKY', the task uses the attitude information in the EHK file for the coordinate transformation. If 'outmaptype=EXPOSURE' and 'instrume=HXI1 or HXI2', the output file contains the off-axis histogram table in the first extension. Subsequent extensions have a GTI table in each extension, corresponding to each attitude histogram bin. No exposure map image is created in this case. The task hxirspeffimg needs to be run in order to generate an HXI flat field.

If 'outmaptype=EFFICIENCY', the output file contains a so-called flat field image in the primary extension, in which each pixel has a dimensionless efficiency value between 0 and 1. The image accounts for the smearing due to attitude variations, by means of the parameters 'delta' and 'numphi'. In this flat-field mode, the task reads CALDB files set by the parameters 'qefile', 'vigfile', 'contamifile', 'obffile', 'fwfile', and 'gvfile' (the last four are not needed for the HXI, and the last three are not needed for the SXI), and multiplies all the efficiencies at the energy or energy range specified by the parameters 'specmode' and 'energy' (see below) to calculate the flat field image. Each of the efficiency components may be turned off by setting the parameter to NONE (e.g., 'vigfile=NONE' means vignetting is not taken into account). There are two ways to set the energy or energy range for which the efficiencies are used. When 'specmode=MONO', the parameter 'energy' should be a single value and the efficiency at this energy is read from the CALDB files. When 'specmode=SPEC', a spectrum file is also required and 'energy' indicates the minimum and maximum of the desired energy range (two values separated by a comma, e.g., 'energy=1.0,5.0'). The name and format of the spectrum file must be specified by the parameters 'specfile' and 'specform', respectively.

The optional bad image file ('badimgfile') is a FITS image containing the following flag values for each pixel: 0: good pixels, 1: calibration source regions, 2: bad pixels and columns, and -1 (or NULL) indicates a position that is either out of the detector or in a region of area discrimination. For SXI, the bad image file is output from the sxiflagpix task. If 'badimgfile=NONE', the active pixel location is found from the input 'instmap' from CALDB. However, the CALDB file does not contain the bad/hot pixel or calibration source location, and distinguishes only between inside and outside of the detector.

The optional pixel GTI file ('pixgtifile') contains the pixel location in DET coordinates with START and STOP times for each dead time interval (e.g., the pixel is "bad" between START and STOP). This file is needed to account for the time-dependent bad pixels (e.g., flickering pixels for SXI).

In the default mode, the calibration source regions (for SXI) are masked out. However, these regions may be regarded as good pixels by setting 'maskcalsrc=no'.

PARAMETERS

ehkfile = ah_test.att [filename]

Name of input EHK file.

gtifile = gt1.fits [filename]

Name of input GTI file.

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

Name of the instrument.

badimgfile = badpiximage.fits [filename NONE|file name]

Name of input bad pixel image file. This file should contain an image in the primary extension with the following flag values: 0: good pixels, 1: calibration source regions, 2: bad pixels and columns, and -1 (or NULL), which indicates a position that is either out of the detector or in a region of area discrimination.

pixgtifile = flickpix.fits [filename]

Name of input pixel GTI list. This file contains a binary table with columns of START, STOP, DETX, and DETY values, indicating the duration and location of each partial bad pixel.

outfile = expmap.fits [filename]

Name of output file.

outmaptype = EXPOSURE [string EXPOSURE|EFFICIENCY]

Type of the output map.

delta = 0.5 [real]

Radial increment [arcmin] for the annular grid for which the attitude histogram will be calculated, centered on the center of the region. This parameter is ignored if 'regmode=DET'.

numphi = 4 [integer]

Number of azimuth (phi) bins in the second annular region over which attitude histogram bins will calculated (i.e., this annular region lies between 'delta' and 2*'delta' arcmin from the center of the region). The first annular region is a full circle of radius 'delta', and the nth annular region has an outer radius of (n+1)*'delta', and numphi*n azimuthal bins.

(stopsys = SKY) [string DET|FOC|SKY]

Output coordinate system for the exposure map image (not needed for HXI).

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

Name of input instrument map file. If the parameter is set to CALDB, the file is read from the calibration database. This file is required to execute the task.

-->

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

Name of input quantum efficiency file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE'.

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

Name of input contamination file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE'.

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

Name of input vignetting coefficient file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE'.

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

Name of input optical blocking file for SXS. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE' or 'instrume' is not SXS.

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

Name of input filter wheel file for SXS. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE' or 'instrume' is not SXS.

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

Name of input gate valve file for SXS. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE' or 'instrume' is not SXS.

(maskcalsrc = yes) [boolean yes|no]

If this parameter is set to yes, calibration source regions are regarded as bad pixels and excluded from the output exposure map. This parameter is ignored when 'badimgfile=NONE'.

(fwtype = OPEN) [string OPEN|FE55|BE|ND|POLY]

Filter wheel type for SXS. This parameter is ignored when 'outmaptype=EXPOSURE' or 'instrume' is not SXS.

(specmode = MONO) [string MONO|SPEC]

Distribution of input energies: monochromatic energy (MONO), or a range of energies weighted by the spectrum in 'specfile'.

(specfile = spec.fits) [filename]

Name of input spectrum file. This parameter is ignored if 'specmode=MONO'.

(specform = FITS) [string FITS|ASCII]

Format of the input spectrum file. This parameter is ignored if 'specmode=MONO'.

(energy = 6.0) [string]

An energy value [keV] or an energy range for the spectrum from which a flux-weighted efficiency is calculated. When 'specmode' is set to MONO, this parameter should be a single value (e.g., 'energy=6.0'). When 'specmode' is set to SPEC, this parameter should be two values separated by a comma (e.g., 'energy=1.0,5.0') to specify the input energy range.

(evperchan = DEFAULT) [string]

Energy [eV] per channel of the input spectrum file. This parameter is ignored if 'specmode=MONO'. If this parameter is set to DEFAULT and 'instrume=SXI', a value of 6.0 eV/channel is assumed so that the value matches a standard PHA file of SXI. Similarly, if this parameter is set to DEFAULT and 'instrume=SXS', a value of 0.5 eV/channel is assumed.

(abund = 1) [string]

Relative abundances of contaminants. The abundances of all of the contaminant materials in the calibration file are multiplied by this number.

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

(covfac = 1) [string]

Partial covering factors for contaminant materials. The partial covering factors of all of the contaminant materials in the calibration file are multiplied by this number.

(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. Create an exposure map for the Hitomi SXI with an off-axis bin size of 0.5 arcmin. No pixel GTI file is input; exclude calibration source as a bad pixel.

   ahexpmap ehkfile=ah.ehk gtifile=gti.fits instrume=SXS badimgfile=NONE pixgtifile=NONE outfile=outexpmap.fits \
      outmaptype=EXPOSURE delta=0.5 numphi=4 maskcalsrc=yes

2. Create an efficiency map for SXI with an off-axis bin size of 1.0 arcmin. A flickering pixel file is input as a pixel GTI. Include calibration source regions as good pixels.

   ahexpmap ehkfile=ah.ehk gtifile=gti.fits instrume=SXI badimgfile=badpiximage.fits pixgtifile=flickpix.fits \
      outfile=outflatfield.fits outmaptype=EFFICIENCY delta=1.0 numphi=4 maskcalsrc=no

SEE ALSO

aharfgen

LAST MODIFIED