eSASS task: expmap

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 EXPMAP eSASS task computes exposure maps for all-sky survey or pointed observations of one or several eROSITA telescopes energy bands.

Exposure maps will be created for all telescopes for which a full set of standard eSASS file extensions is provided in the input datasets. The output exposure maps will be binned according to the WCS keywords provided in the input template image. Depending on the command line parammeter setting, both single telescope and/or merged all-telescope exposure maps are created.

The exposure maps will contain the exposure time at each sky location in units of seconds. Energy dependent vignetting and/or area correction factors may be applied if desired. Bad pixels found either in the bad pixel extensions of the supplied event files or calibrated bad pixels only will be screened depending on the flag setting of the supplied event files, if requested.

Input Parameters

• inputdatasets (string array) REQUIRED
  • This can be either one or several eROSITA calibrated event lists or images with a full set of eSASS standard file extensions.
• templateimage (string) REQUIRED
  • The output exposure maps will be binned as specified in the WCS keywords of the template image.
• emin (real) REQUIRED
  • Lower bound of exposure map energy bands (unit: keV); up to six values in ascending order.
• emax (real) REQUIRED
  • Upper bound of exposure map energy bands (unit: keV); up to six values in ascending order.
• withsinglemaps (boolean) OPTIONAL [default value: NO]
  • Specifies whether single telescope exposure maps shall be created.
• withmergedmaps (boolean) OPTIONAL [default value: YES]
  • Specifies whether a merged all-telescope exposure maps shall be created.
• singlemaps (string array) OPTIONAL
  • Names of the output single telescope exposure maps. Enter one name per telescope and per energy band in ascending order, starting with the energy bands of the first telescope. The number of entries must match the number of telescopes provided in the input event files and the number of energy bands specified .
• mergedmaps (string array) OPTIONAL
  • Names of the merged all-telescope output exposure maps (one name per telescope in ascending order of telescope number)
• gtitype (string) OPTIONAL [default value: GTI]
  • Specifies the type of GTI to be used for exposure map creation. Allowed values: GTI, QUALGIT, FLAREGTI (GTI: time intervals included in the eventfile, where the telescope was on; QUALGTI: subset of GTI, time intervals where all housekeeping parameters are in their nominal range; FLAREGTI: subset of QUALGTI, low background time intervals as determined by task FLAREGTI).
  • Note: you will probably want to specify the same type of GTI that was used to filter your event list.
• withvignetting (boolean) OPTIONAL [default value: yes]
  • The exposure maps will be corrected for vignetting if set to YES. Exposure times will be normalized to the on-axis exposure. Vignetting correction factors are area weighted.
• withdetmaps (boolean) OPTIONAL [default value: no]
  • This governs whether exposure maps are cropped at the edge of the field of view for each TM. Note that this option only has effect if the FLAGSEL keyword of the respective input event file indicates that out-of-FOV pixels were screened from the event file.
• withweights (boolean) OPTIONAL [default value: YES]
  • If set to yes, exposure maps will be corrected for the fraction of the area supplied by each telescope with respect to the nominal all-telescope area, where the nominal area corresponds to the case where all filter wheels are in "FILTER" position. Single telescope exposure maps will thus only contain approximately one seventh of the actual exposure if this option is set. This option is mainly intended for use with the eSASS detection tasks (erbox, ermldet) where it allows the calculation of nominal all-telescope eROSITA count rates, fluxes and hardness ratios, independently of whether all telescopes were operational at all times. Similarly, exposure corrected, nominal count rates images may be created, independently of how many telescopes were operational at each time.
• withfilebadpix (boolean) OPTIONAL [default value: yes]
  • Bad pixels found in the bad pixel extension of the supplied event files will be screened from the exposure maps if set to yes. This option only has any effect if the FLAGSEL keyword of the respective input event file indicates that the bad pixels where screened from the event file.
• withcalbadpix (boolean) OPTIONAL [default value: yes]
  • Calibrated bad pixels will be screened from the exposure maps if set to yes. This option only has any effect if the FLAGSEL keyword of the input event files indicates that the bad pixels where screened from the event file.
• withinputmaps (boolean) OPTIONAL [default value: NO]
  • If set to yes, cumulative exposure maps will be created. The exposure corresponding to the GTI intervals provided in the input datasets will be added to the exposure maps provided with the expmap command line parameter. Times already included in the input exposure maps will be ignored. This option is mainly intended for the pipeline processing of all-sky survey data.

Input files

• Input datasets: eSASS event files or images with a full set of eSASS standard file extensions.
• Template image: the output exposure maps will be binned as specified in the WCS keywords of the template image.
• If withinputmaps=YES: input exposure maps

Output files

• One exposure map per energy band and per telescope (if parameter withsinglemaps is set to yes) or one all-telescope exposure per energy band (if parameter withmergedmaps is set to yes).

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.

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 are created.

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"

Known Issues:

• If the user has filtered events to remove invalid patterns but not to remove events on bad pixels, no pixels which are neighbours to bad pixels will be excluded from the exposure map. This is incorrect.
• Contrariwise, if bad pixels have been excluded from the event list, all neighbour pixels are excluded from the map (not just the orthogonal ones, as is correct).
• A too-narrow energy range may result in a zero-valued map.
• Optic axis is taken from the wrong columns of the 'instpar' cal file, which leads to a 1/2 CCD pixel error on some TMs.
• The task assumes that event images are made with a TAN projection of RA and Dec, whereas the true projection is SIN. This misprojection can lead to maps which are misaligned with event images by up to 1 or 2 CCD pixels.
• Some variables are not correctly initialized.
• If several energy bands are supplied, the output exposure maps all have keywords EMIN1 and EMAX1 which are set respectively to the lowest and highest values of the whole set of bands.
• The exposure maps are expected to be affected by the double counting of the chopper setting, if it is not 1 in the input dataset (see the FAQ). The exposure values in spectra and lightcurves will be scaled by 1/N of the chopper value. This has not yet been confirmed. A possible remedy would be to multiply the exposure map with the chopper factor N using e.g. the HEASOFT tool farith.