Back to eSASS task descriptions

eSASS task: expmap

Updated documentation (30.10.2024), this update is not included in the eSASS4DR1 package (old version available here)

erosita/expmap-2.11.5+

Scope

This document provides a description of parameters and instructions for the correct usage of the EXPMAP task, which is part of eSASS (the eROSITA Science Analysis Software System).

Description

The eSASS task EXPMAP computes exposure maps, optionally in up to 50 energy bands. Output maps in each band may be either 'merged' from several telescope modules (TMs), and/or 'single' maps, i.e. one map per TM. The choice of either output depends on the boolean parameters withmergedmaps and withsinglemaps.

The exposure maps display the approximate exposure time at each sky location in units of seconds. In 'merged' maps, each pixel value is a weighted average of the individual TM exposure times at that pixel. See the 'algorithm' section for more detail of the weighting scheme. Energy dependent vignetting may be applied if desired (boolean parameter withvignetting). Bad pixels (boolean parameter withfilebadpix) and out-of-FOV pixels (boolean parameter withdetmaps) can be excluded; note however that you should take care in both cases to match the filtering that was applied to the event list. EXPMAP will issue a warning if it detects a mismatch between the filtering applied to the event list and the pixel exclusions you request, but ultimately it is up to the user to make the map match the list.

Of the inputs to EXPMAP, the event list(s) (inputdatasets) define the TMs to use, also the good time intervals (GTIs), attitude history and dead-time history for each TM, and the event filtering that was applied; the templateimage only defines the size and sky-position of the output exposure map(s). Note that the actual data in the EVENTS table of the event list is not used.

Note that as of version 2.6, EXPMAP can be run in parallel. This behaviour is activated by setting the appropriate value of the environment variable OMP_NUM_THREADS.

Input Parameters

Known Issues:

Input files

Two inputs are required, and a third is optional:
  1. A list of eventlist file names should be provided via the parameter inputdatasets, each file of which includes the standard set eSASS file extensions. These extensions have uses as follows:
    • EVENTS: the actual events data are not used by EXPMAP but the standard eSASS header keywords are required.
    • GTIn (or FLAREGTIn etc, see parameter gtitype): The sum of GTIs for telescope module (TM) n forms the starting value of the exposure map for that TM.
    • DEADCORn: this fractional exposure value is sampled at the time steps used internally by EXPMAP.
    • CORRATTn: these attitude samples are required to allow coordinate transformation from CCD to sky coordinates.
    • BADPIXn: carries information about which pixels of the nth CCD to exclude.
    • HK and other extensions: unused.
    The set of TMs for which EXPMAP should compute exposure maps is defined by the full set of GTIn extensions found in the set of event lists provided to the inputdatasets parameter. Note that it is not permitted that 2 or more of these eventlists include extensions for the same nth TM. For example, suppose you supplied 2 event lists, the first containing extensions GTI1, GTI3 and GTI4, the second with extensions GTI2 and GTI3: since the GTI extension for TM3 appears twice, the task would in this case fail with an error. It is thus easy to see that the maximum number of files that can be supplied to inputdatasets is 7.
  2. A FITS image to function as an image template should be provided via the parameter templateimage. The pixel dimensions of the output maps, their pixel sizes, and their location on the sky, are all set by this image. The image must be in the primary HDU of the FITS file.
  3. If withinputmaps=YES, the user can provide input exposure maps via the parameter inputmaps. Note that these must be TM- and band-specific maps; i.e., you must supply 1 per TM/band combination. (The order should be the same as singlemaps.) If these are supplied, the output exposure maps will contain cumulative totals of the input maps plus any new exposure. There at present NO CHECKS made of consistency with the template image, so if you supply inputmaps from a different projection, you will end up with a mess.

Output files

Algorithms

The task accumulates internally 1 exposure map per TM/band combination. The starting point for each is a CCD image, which is projected onto the sky at a succession of time samples within each GTI for that TM.

CCD images

  1. A starting image is first obtained from the DETMAP component of the cal DB. This currently has value unity over the CCD pixel grid.
  2. If the template image excluded out-of-FOV events, and if parameter withdetmaps is set, these are then excluded from the CCD image.
  3. If parameter withfilebadpix is set, bad pixels are excluded based on the choices of bad-pixel and pattern filtering used in making the template image.
  4. If parameter withvignetting was set, the CCD image is multiplied by a vignetting function. For each energy band, the vignetting function is calculated as follows:
    • The band is broken into N sub-bands, N being calculated as ceiling(width_band_eV/50).
    • A vignetting map is obtained at the mean energy of each sub-band.
    • A scalar weight is obtained at that mean energy from a power-law spectrum energyindex, the index being suppliable by the user via the plindex parameter.
    • The final vignetting map for the band and CCD is obtained from the weighted mean of the sub-band maps.

Accumulation over GTI

GTIs are read for each TM from the supplied inputdatasets. For each TM for which a GTIn extension was found, the task loops through the list of its GTIs, accumulating the TM-specific exposure maps accordingly.

Attitude sampling

The CCD image must be projected onto the sky – to be precise, onto the same sky projection plane as used in the template image. This projection depends on the instantaneous attitude, which in general is continuously varying. The unattainable ideal of continuous coverage is approximated by projecting the image at a series of attitude samples.

In order to reduce the overhead from computation of coordinate transforms, the projection is broken into four parts as follows.

  1. At coarse attitude sampling (currently performed at a cadence of once per 20 CCD frames, i.e. once per second), the CCD map is projected to the image plane and stored. A new map is not calculated at each attitude sample, but only if the change in attitude is greater than a certain amount – roughly so much as to cause offsets at the size of an image pixel.
  2. At fine attitude sampling (at the same cadence as the CCD frames, i.e. 20 per second), the projected image is shifted in X and/or Y. A new shifted image is only calculated if (i) a new projected image was calculated at step 1, or (ii) the attitude has changed enough to shift by of order one image pixel.
  3. The shifted image is multiplied by the frame duration times the dead time fraction (sampled at the same coarse cadence as the attitude in step 1). A new multiplication is only performed if (i) a new shifted image was calculated at step 2, or (ii) the exposure has changed by more than 0.1%.
  4. The projected, shifted, exposure-corrected image is accumulated onto the TM- and band-specific exposure map.

Projection onto the sky

In practice, the algorithm calculates the coordinate transform in reverse: i.e. it takes the desired grid of sky-plane pixels and projects them, for a given instantaneous attitude, onto the CCD. This is because we want, for each image pixel and instant in time, to ask, what part of the CCD is this illuminating, at what vignetting factor, and is there a dead pixel there? However it is notionally easier to behave as if the CCD grid were projected to the sky.

The projection is a SIN rather than a TAN one. The original expmap implemented a TAN projection, which is most of the reason for the previous noticeably poor fit between images and exposure maps at significant off-axis angles (of order a degree or more). To retain backward-compatibility with older maps, this projection algorithm has been retained, for choice 'original' of parameter accuracy. The full-accuracy SIN projection is obtained for choice 'exact'; a linear approximation of it is performed for choice 'approximate'.

Final weighting for TM-merged maps

If TM-merged maps are desired (parameter withmergedmaps), these are summed at the final stage, for each energy band, from weighted TM- and band-specific maps. If parameter withweights is set 'true', the weight factors are calculated as follows. For each TM, the SPECRESP component from the cal DB comprises a list of SPECRESP and CONTRIB values at a series of energies. The weight for a given energy band and TM is calculated as a fraction for which the numerator is the sum of SPECRESP x CONTRIB x band_width across the band and the denominator the sum of SPECRESP x band_width. The weight can therefore be thought of as an area-weighted mean of the CONTRIB value across the band.

If parameter withweights is not set, all the weights are set equal to 1/num_TMs. The merged maps are thus in a sense averages, not sums, of the TM-specific maps.

Example calls

expmap inputdatasets="events.fits" \
       templateimage="image.fits" \
       mergedmaps="expmap.fits" \
       emin=0.5 emax=2.0
This minimalistic call creates a merged, vignetted exposure map for the telescopes included in event file events.fits in the energy band from 0.5 to 2.0 keV. GTIs are sought by default from the GTIn extensions. (Note that withmergedmaps can be omitted here because it defaults to 'true'.)

expmap inputdatasets="events1.fits events2.fits" \
       templateimage="image.fits" \
       mergedmaps="expmap_b1.fits expmap_b2.fits expmap_b3.fits expmap_b4.fits" \
       emin="0.2 0.5 1.0 2.0" \
       emax="0.5 1.0 2.0 10.0" \
       gtitype="FLAREGTI"
Merged, vignetted exposure maps for the telescopes included in event file events.fits are created for each of the energy bands 0.2 to 0.5, 0.5 to 1.0, 1.0 to 2.0 and 2.0 to 10.0 keV. GTIs are sought from the FLAREGTIn extensions. (Note that withmergedmaps can be omitted here because it defaults to 'true'.) 
expmap inputdatasets="events1.fits events2.fits" \
       templateimage="image.fits" \
       withsinglemaps="yes" \
       withmergedmaps="no" \
       singlemaps="expmap_b1t2.fits expmap_b2t2.fits expmap_b1t5.fits expmap_b2t5.fits" \
       emin="0.2 0.5" \
       emax="0.5 1.0" \
       gtitype="FLAREGTI"
Here the user has rather required per-TM (i.e. 'single') maps rather than the all-telescope 'merged' maps. The number of singlemaps must equal the number of TMs for which appropriate GTI extensions were found (here =2), times the number of energy bands (here also =2).