eSASS task: ersensmap

Scope

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

Summary:

Calculate eROSITA sensitivity maps

Description:

The task ERSENSMAP uses eSASS exposure maps (expimages) and background maps (bkgimages) to calculate the expected detection sensitivity for point sources or extended sources. The task can be operated in two main modes, determined by the parameter method:

• 1. method"APER": this mode calculates the sensitivy of aperture methods as employed by task ERBOX. Using the exposure and background values for each pixel and along the lines of the ERBOX algorithm ERSENSMAP calculates the flux required to reach the detection likelihood

  L = - ln P_Γ (n, b)

  where n is the number of counts in the given aperture and b is the number of background counts in the aperture. For more than one input image the same calculation of combined likelihoods as for task ERBOX is applied.

• 2. method="fit" : in this mode the sensitivity of the PSF fitting employed by the task ERMLDET is estimated. Along the lines of the ERMLDET algorithm the limiting flux is obtained as follows:

  A spatial source model (the PSF optionally folded with an extent model) is calculated for each position of the sky region definded by the input images. The source model is scaled using the flux, the ecf values, and the local exposure map. The limiting flux is the obtained iteratively by calculating the statistic

  $C=2{\sum }_{i=1}^N(e_i-n_i\ln e_i)$

  and

  $\Delta C=C_{null}-C_{best}$

  where e_i=n_i is the expected pixel value for the model + background for the calculation of C_best or the background value only in the case of C_null. The flux values are varied until the corresponding log-likelihood L = -ln(P)) with

  P=1 - P_Γ(ν/2 , ΔC/2)

  and

  $\Delta C=C_{null}-C_{best}$

  for ν degrees of freedom reaches the likelihood threshold given by parameter likemin.

The simultaneous detection on several input images can be modelled by providing more than one exposure map and background map. The spectral properties of the sources can be specified by providing an energy conversion factor for each input image (parameter ecf). When using method="FIT", extended sources can be modelled (parameters ext_flag, ext, extmodel). As optional output a FITS table containing the cumulative sky area as a function of detectable flux can be written (parameters area_flag, area_table). The sky area is calculated as the sum of the pixel areas having limiting fluxes less than or equal the table row flux value.

Parameters:

• sensimage (string) REQUIRED
  • Output sensitivity map
• expimages (string array) OPTIONAL/REQUIRED IF expima_flag=Y
  • Exposure map(s)
• bkgimages (string array) OPTIONAL
  • Background map(s)
• detmask_flag (boolean) OPTIONAL[ e.g. "Y"]
  • Use detection mask
• area_flag (boolean) OPTIONAL [e.g. "N" ]
  • Write area table ?
• detmasks (string array) OPTIONAL/REQUIRED IF detmask_flag=Y
  • Detection mask(s)
• area_table (string) OPTIONAL/REQUIRED IF area_flag=Y
  • Optional output table containing cumulative sky area as function of flux
• emin (real) OPTIONAL [e.g. 500. ]
  • Lower energy boundary for flux calculation [eV]
• emax (real) OPTIONAL [e.g. 2000. ]
  • Lower energy boundary for flux calculation [eV]
• ecf (real) OPTIONAL [e.g. "1.22045e+12" ]
  • Energy conversion factor to convert fluxes to count rates for each input image
• method (string) OPTIONAL [e.g. APER ]
  • Detection method, for which sensitivity is calculated (APER | FIT).
• aper_type (string) OPTIONAL [e.g. "BOX" ]
  • Shape of aperture (BOX | CIRCLE)
• aper_size (real) OPTIONAL [e.g. 4.5]
  • Aperture size (radius / box half width).
  • aper_size >=1 : absolute size [image pix]
  • aper_size <1 : given as encircled energy fraction.
• likemin (real) OPTIONAL [e.g. 8.0 ]
  • Detection likelihood threshold
• ext (real) OPTIONAL [e.g. 6.0]
  • Extent parameter for extended sources [image pixels].
• extentmodel (string) OPTIONAL [e.g. "beta" ]
  • Extent model type ("beta"|"gaussian").
  • Extent models as used in task ERMLDET
• ext_flag (boolean) OPTIONAL [e.g. "N" ]
  • Model extended sources? (only for parameter method="FIT")
• extlikemin (real) OPTIONAL [e.g. 6.0 ]
  • Likelihood threshold for extent detection (not yet supported).
• shapelet_flag[="Y"] (boolean) OPTIONAL [e.g. "N" ]
  • Use shapelet PSF (not yet supported)
• photon_flag (boolean) OPTIONAL [e.g. "N" ]
  • Calculate sensitivity for photon mode detection (not yet supported)

Input files:

• Exposure maps

  FITS images ( real32) as created by task EXPMAP for the same instruments, energy bands, and WCS coordinate systems as the science images. File names are defined by parameter expimages

• Detection masks

  FITS images ( int8) as created by task ERMASK with file names defined by parameter detmasks. The image areas with value =1 are used for detection, areas with value =0 are masked out. For multiple images from the same instrument, but for different energy bands, only one detection mask is required.

• Background maps

  FITS images ( real32) as created by task ERBACKMAP for each input science image. File names are defined by parameter bkgimages

Output files:

• Sensitivity map FITS image ( real32) containing the sensitivity map. The pixel values correspond to the flux of a source, which is expected to be to be detected with the detection likelihood likemin.

• area_table
Table containing cumulative sky area vs. limiting flux

Examples:

Calculate sensitivity map and area table for 9x9 pixel box apertures:

ersensmap expimages="expmap.fits" \
          bkgimages="bkgmap.fits" \
          detmasks="detmask.fits" \
          sensimage="sensmap_box.fits" \
          emin="500." \
          emax="2000." \
          ecf="1.22246e+12" \
          method="APER" \
          aper_type="BOX" \
          aper_size=4.5 \
          likemin=8. \
          detmask_flag="Y" \
          shapelet_flag="N" \
          photon_flag="N" \
          area_table="surveyarea_box.fits" \
          area_flag="Y"

Calculate sensitivity map for the detection of extended sources with beta-model (core radius = 5 pix):

ersensmap expimages="expmap.fits" \
          bkgimages="bkgmap.fits" \
          detmasks="detmask.fits" \
          sensimage="sensmap_fit_ext.fits" \
          emin="500." \
          emax="2000." \
          ecf="1.22246e+12" \
          method="FIT" \
          aper_type="BOX" \
          aper_size=4.5 \
          likemin=8. \
          detmask_flag="Y" \
          shapelet_flag="N" \
          photon_flag="N" \
          area_table="surveyarea_fit.fits" \
          area_flag="Y" \
          ext_flag="Y" \
          extentmodel="beta" \
          ext=5.0 

Known issues:

Version 1.8 can only handle PSF calibration files containing the survey averaged PSF and therefore only works correctly for input files with the observing modes indicated by the keywords OBS_MODE="SURVEY" or OBS_MODE="SLEW".