Synopsis
Generate a Chandra imaging exposure map (effective area vs. sky position)
Syntax
mkexpmap asphistfile outfile instmapfile xygrid [normalize] [useavgaspect] [geompar] [verbose] [clobber]
Description
`mkexpmap' generates an exposure map which may be used to convert a counts image of a source to an image in flux units. An image in sky-coordinates, the exposure map is essentially an image of the effective area associated with each sky position as a result of the aspect motion of the telescope over the course of an observation. It accounts for the effects of dither motion which are especially important near the edges of the detector and also near bad pixels and bad columns.
The default units of the exposure map (M) are
M = [cm**(2)*counts/photon]
and are the same units as the effective area (ARF). Optionally, the exposure time factor (t) may be included, yielding a map
M' = M*t = [sec*cm**(2)*counts/photon].
To include the exposure time factor in the output map, set normalize="no".
To compute an image in photon flux units, divide the counts image (N) [counts/pixel] by the product of the exposure map (M) and the exposure time (t):
photon flux [photons/cm**2/s/pixel] = N / (M*t) = N / M'
Dmimgcalc may be used to carry out this division.
As input, 'mkexpmap' requires an aspect histogram file (computed by asphist) and an instrument map file (computed by mkinstmap). The output exposure map is generated for a specified sky-coordinate grid.
The input aspect histogram gives the total dwell time for each sky pointing direction accumulated by the telescope over the course of the observation.
The input instrument map is an image in detector coordinates which, for a given incident spectrum, is essentially the product of the mirror effective area projected onto the detector surface with the QE of the detector. It also incorporates bad pixels and ACIS windows (if any) by setting the efficiency to zero at the appropriate locations on the detector.
The exposure map is a dwell-time-weighted sum of overlapping instrument maps, with one term in the sum for each pointing orientation specified in the aspect histogram. Because this repeated shifting and adding of instrument map images can require an extremely large number of floating-point operations, the exposure map calculation may take a long time. The running time scales roughly as the product of the number of aspect histogram records and the number of sky pixels. In cases where computation speed is more important than a detailed treatment of the pointing motion, one can greatly speed up the computations by computing an exposure map for the average pointing direction; to select this option, set useavgaspect=yes.
For a detailed, quantitative definition of the exposure map, see Davis, John E. 2001, ApJ, 548, 1010. See also http://space.mit.edu/CXC/docs/expmap_intro.ps.gz .
Example
mkexpmap asphistfile=asphist.fits outfile=expmap.fits instmapfile=instmap.fits xygrid="3094.5:5050.3:#256,2042.0:5320.0:#512"
Computes an exposure map of size 256x512 for the sky region with 3094.5<=X<5050.3 and 2042.0<=Y<5320.0 and writes it to expmap.fits. The units of the output map are [cm**(2) counts/photon]
Parameters
| name | type | ftype | def | reqd |
|---|---|---|---|---|
| asphistfile | file | input | yes | |
| outfile | file | output | yes | |
| instmapfile | file | input | yes | |
| xygrid | string | yes | ||
| normalize | boolean | yes | ||
| useavgaspect | boolean | no | ||
| geompar | string | geom | ||
| verbose | integer | 0 | ||
| clobber | boolean | no |
Detailed Parameter Descriptions
Parameter=asphistfile (file required filetype=input)
The name of the input aspect histogram file. This file may be computed using the `asphist' program; it consists of a binary table with the following columns:
X_OFFSET:
The x aspect offset [pixels] for the tangent plane coordinate system appropriate to the detector.
Y_OFFSET:
The y aspect offset [pixels] for the tangent plane coordinate system appropriate to the detector.
ROLL_OFFSET:
The roll offset in degrees.
DURATION:
The number of seconds for this aspect offset bin.
In addition, the RA_NOM, DEC_NOM keywords from this file supply the sky coordinates of the reference pixel that defines the tangent plane pixel system, i.e., the RA and Dec values that correspond to X_OFFSET=0 and Y_OFFSET=0.
Parameter=outfile (file required filetype=output)
The name of the output exposure map file.
Parameter=instmapfile (file required filetype=input)
The name of the input instrument map file. This file may be produced by the `mkinstmap' program.
Parameter=xygrid (string required)
This string specifies a region in sky (X,Y) coordinates and the resolution of the output exposure map image. The recommended format is "x0:x1:#nx,y0:y1:#ny", where x0, x1, y0, & y1 are real valued numbers and nx & ny are positive integers. These numbers specify a region in sky coordinates satisfying the conditions x0<=X<x1 and y0<=Y<y1, and indicate that the region is to be regridded to nx by ny pixels in the output image.
For example, to compute a 256x512 exposure map for a sky region satisfying 3094.5<=X<5050.3 and 2042.0<=Y<5320.0, use "3094.5:5050.3:#256,2042.0:5320.0:#512".
Note that for floating point ranges, the syntax a:b should always be read as " a <= x < b".
Parameter=normalize (boolean default=yes)
This parameter selects the physical units of the output exposure map. If set to "no", the resulting exposure map has units of (time) * (effective area) [sec * cm**(2) counts/photon]. If set to "yes" [the default], the result has units of effective area [cm**(2) counts/photon].
Parameter=useavgaspect (boolean default=no)
If set to "yes", only the average aspect pointing will be used to derive the exposure map; otherwise all points in the aspect histogram will be used. Set this to "yes" only when computation speed is more important than accuracy.
The time required to compute the exposure map is proportional to the number of bins in the aspect histogram. If the aspect histogram contains 100 bins, then the use of this option should reduce the run time by a factor of 100.
Parameter=geompar (string default=geom)
The name of the Pixlib Geometry parameter file.
Parameter=verbose (integer default=0)
The verbosity level for messages.
Parameter=clobber (boolean default=no)
If set to yes, existing output files will be overwritten.
Tool Version
The command "mkexpmap --version" prints the version of mkexpmap and the associated libraries. This is useful when reporting problems with the tool.
Bugs
Caveats
-
*** Warning: CYCLE not found or invalid in /tmp/imap_3.fits --- assuming 'P'
-
The CIAO response tools will issue this warning if the CYCLE keyword is missing from the file header. The CYCLE keyword is needed in alternating mode observations (also referred to as interleaved mode) to indicate which frame time was used in the file. If you are not working with interleaved data, you can ignore the warning.
The What is the CYCLE keyword? FAQ explains further about this keyword.
See Also
- calibration
- ardlib
- psf
- psf
- tools
- acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, addresp, aprates, asphist, combine_grating_spectra, combine_spectra, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, readout_bkg, rmfimg, sky2tdet, specextract