NAME
ahexpmap - Generates an exposure map for HXI, SXI, and SXS,
or a flat field image for SXI and SXS
USAGE
ahexpmap ehkfile gtifile instrume badimgfile pixgtifile outfile outmaptype
delta numphi
DESCRIPTION
'ahexpmap' creates either an exposure map (for HXI, SXI, and SXS) containing an integrated exposure time
for each pixel (with the parameter setting 'outmaptype=EXPOSURE') or
a flatfield image (for SXI and SXS) where efficiencies, such as telescope vignetting and
detector quantum efficiency, are multiplied (with the parameter setting 'outmaptype'=EFFICIENCY').
The EXPOSURE output is an input to the 'aharfgen' task,
whereas the EFFICIENCY output may be directly used for exposure-correction in imaging analysis.
For the 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 used to screen the event file (typically the second extension of
the event data).
In addition, two files, bad image file ('badimgfile') and pixel GTI file ('pixgtifile')
might be input optionally.
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
of which 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 the radii of A arcmin.
Then, the innermost annulus (just out of the central circle) is divided into
B wedges. Similarly the 'n'-th annulus is divided into B*'n' wedges.
If 'outmaptype=EXPOSURE' and 'instrume=SXI or SXS', then the output file contains
an exposure map image in the primary extension (where each pixel contains net exposure
time in second) 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)
are GTI table for each off-axis.
The output exposure map may be in either DET, FOC, or SKY coordinate
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', then
the output file contains only the off-axis histogram table and GTI tables,
and no image is created. The task 'hxirspeffimg'
needs to be ran 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. In this mode, the task reads efficiency CALDB files set by
the parameters 'qefile', 'contamifile', 'vigfile', 'obffile', 'fwfile', and 'gvfile'
(the last three are for only SXS), 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., "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: good pixels (0), calibration source regions (1),
bad pixels and columns (2), and out of the detector or area discrimination (-1, null).
For the SXI, this is the output of the 'sxiflagpix' task.
If 'badimgfile=NONE', then the active pixel location is found from the input
'instmap' CALDB. However, the CALDB file does not contain the bad/hot pixel or calibration
source location, and distinguish only inside or outside of the detector.
The optional pixel GTI file ('pixgtifile') contains the pixel location in the DET coordinate
with START and STOP time 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 setting, the calibration source regions (for SXI) is masked out.
However, these regions may be regarded as good pixels by setting 'maskcalsrc=no'.
PARAMETERS
- ehkfile [filename]
- Name of input EHK file.
- gtifile [filename]
- Name of input GTI file.
- instrume [string]
- Name of the instrument (SXS, SXI, HXI1, or HXI2).
- badimgfile [filename]
- Name of input bad pixel image file. The file should contain
an image in the primary extension with the following flag values:
good pixels (0), calibration source region (1), bad pixels and columns (2),
and out of the detector or area discrimination (-1, null).
For the SXI, this is simply the output of the sxiflagpix routine ('outbadimg').
- pixgtifile [filename]
- Name of input pixel GTI list.
The file contains a bin table with columns of START, STOP, DETX, and DETY,
indicating the duration and location of each partial bad pixel.
- outfile [filename]
- Name of output file.
- outmaptype [string]
- Type of the output map (EXPOSURE or EFFICIENCY).
- delta [real]
- Size in arcmin of each off-axis annulus grid (and on-axis circle) in the output histogram.
- numphi [integer]
- Number of azimuth (phi) bins in the first off-axis annulus at (delta <= theta < 2 * delta).
A n-th off-axis annulus has azimuth bins of numphi * n.
- (stopsys = SKY) [string]
- Output coordinate system (DET, FOC, or SKY).
- (instmap = CALDB) [filename]
- Name of input instrument map file.
If the paramater is set to CALDB, the file is read from the calibration database.
This file is required for the task to run.
- (qefile = CALDB) [filename]
- Name of input quantum efficiency file.
If the paramater 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' is set to EXPOSURE.
- (contamifile = CALDB) [filename]
- Name of input contamination file.
If the paramater 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' is set to EXPOSURE.
- (vigfile = CALDB) [filename]
- Name of input vignetting coefficient file.
If the paramater 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' is set to EXPOSURE.
- (obffile = CALDB) [filename]
- Name of input optical blocking file for the SXS.
If the paramater 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' is set to EXPOSURE or 'instrume' is not SXS.
- (fwfile = CALDB) [filename]
- Name of input filter wheel file for the SXS.
If the paramater 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' is set to EXPOSURE or 'instrume' is not SXS.
- (gvfile = CALDB) [filename]
- Name of input gate valve file for the SXS.
If the paramater 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' is set to EXPOSURE or 'instrume' is not SXS.
- (maskcalsrc = yes) [boolean]
- 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' is set to NONE.
- (fwtype = OPEN) [string]
- Filter wheel type for the SXS (OPEN, FE55, BE, ND, or POLY)
This parameter is ignored when 'outmaptype' is set to EXPOSURE or 'instrume' is not SXS.
- (specmode = MONO) [string]
- Type of input energy: monochrome energy (MONO) or spectrum (SPEC).
- (specfile) [filename]
- Name of input spectrum file. This parameter is ignored if 'specmode' is set to MONO.
- (specform = FITS) [string]
- Format of the input spectrum file (FITS or ASCII).
This parameter is ignored if 'specmode' is set to MONO.
- (energy = 6.0) [string]
- An energy value 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., '6.0')
When 'specmode' is set to SPEC, this parameter should be two values separated by
a comma (e.g., '1.0,5.0') to specify the input energy range.
- (evperchan = DEFAULT) [string]
- Energy (in eV) per channel of the input spectrum file.
This parameter is ignored if 'specmode' is set to MONO.
If this parameter is set to DEFAULT (as default) and 'instrume' is set to SXI,
a 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 (as default) and 'instrume' is set to SXS,
a 0.5 eV/channel is assumed.
- (abund = "1.0") [string]
- Relative abundances of contaminants. The abundances of all of the contaminant mate
rials in the calibration file are multiplied by this number.
- (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 v
alue of this parameter.
- (covfac = "1.0") [string]
- Partial covering factors for contaminant materials. The partical covering factors
of all of the contaminant materials in the calibration file are multiplied by this num
ber.
- (buffer = -1) [integer]
- Rows to buffer (-1=auto, 0=none, >0=numrows).
- (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]
- 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).
EXAMPLES
1. Create exposure map for the SXS with off-axis bin size of 0.5 arcmin.
No pixel GTI file is input. Exclude calibration source as 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 efficiency map for the SXI with off-axis bin size of 1.0 arcmin.
Flickering pixel file is input as pixel GTI. Include calibration source regions
as good pixel.
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
February 2016