eSASS task: ERBACKMAP

Scope

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

Summary:

Create smooth background maps by masking source regions in input image and smoothing either by 2D spline fit or an adaptive smoothing algorithm. The task accepts source lists created by ERBOX orERMLDET as input.

Algorithms:

The task erbackmap creates the background images for the eROSITA source detection pipeline. The input data are one science image, an input source list (typically created by task erbox in local mode), an exposure map (from task expmap) and detection mask (from task ermask). In a first step circular regions around the input sources are calculated, where the surface brightness of the input sources exceed the threshold set by parameter scut . The radii of these circles depend on the source counts, the PSF, and the source extent parameter. A mask image where this regions are set to 0 can optionally (cheesemask_flag="Y") be written to the file specified by parameter cheesemask . The image data outside the masked out source regions are used to create a smoothed background map which is also interpolated to the positions of the input sources. The user can choose between a 2D spline fit (fitmethod="spline") and an adaptive smoothing algorithm (fitmethod="smooth") to perform the smoothing/interpolation.

The option "smooth" is recommended for all types of observations, the "spline" can be considered as obsolete. The spline fit can be controlled with the parameters nsplinenodes (number of spline nodes per dimension), degree , smoothflag , smoothval . If smoothflag =Y, a smoothing spline with smoothing factor smoothval is used. If smoothflag =N, a weighted least-squares spline is used. For the setting (fitmethod="smooth" an adaptive smoothing algorithm is used to create the background map. If an exposure map is read in (expima_flag="Y"), a count rate map is calculated by dividing the input science image with the exposure map. Source regions are masked out by multiplying the image with the source mask. The adaptive smoothing algorithm (fitmethod="smooth") then convolves the masked count image or count rate image with a set of up to 16 Gaussian kernels and calculates a signal-to-noise map for each kernel size. The size σ₁ of the smallest kernel is set by parameter smoothval, in units of image pixels, the largest kernels size is set by smoothmax. The sizes of the i=1 kernels are σ_i = σ₁ * (√2)ⁱ. Also the source masks are convolved with the same kernels and each smoothed image is divided by the smoothed mask in order to account for the masked out regions. Smoothed count rate images are multiplied with the exposure map. The background map is then calculated for each image pixel by finding the two kernel sizes σ_i, σ_i+1, whose signal-to-noise maps bracket the required SNR defined by parameter snr. The background value of the pixel is the interpolated from the 2 smoothed images i, i+1.

A user defined mask of type byte can be supplied (usermask_flag="Y", usermask=filename), which will be multiplied to the source mask generated from the input list. Regions where this mask is 0 are treated like sources and excised from the image.

The task ERBACKMAP can also be used to adaptively smooth an image without removing any source regions.

Parameters:

• image (string) REQUIRED
  • Input science image
• boxlist (string) REQUIRED
  • Input source list file name
• expima_flag (boolean) OPTIONAL [ e.g. Y]
  • Use exposure map (recommended)
• expima2_flag (boolean) OPTIONAL [ e.g. Y]
  • Use second exposure map (not yet supported)
• detmask_flag (boolean) OPTIONAL[ e.g. Y]
  • Use detection mask (recommended)
• usermask_flag (boolean) OPTIONAL[ e.g. Y]
  • Set this flag to read in user defined source mask
• cheesemask_flag (boolean) OPTIONAL[ e.g. Y]
  • Set this flag to write out map containing masked out source areas
• expimage (string) OPTIONAL/REQUIRED IF expima_flag=Y
  • Exposure map
• expimage2 (string) OPTIONAL/REQUIRED IF expima_flag2=Y
  • Second exposure map (currently not used)
• detmask (string array) OPTIONAL/REQUIRED IF detmask_flag=Y
  • Detection mask
• detmask (string array) OPTIONAL/REQUIRED IF detmask_flag=Y
  • Detection mask
• usermask (string) OPTIONAL
  • User defined mask image (type byte) defining regions to be masked out
• cheesemask (string) OPTIONAL
  • Output "swiss cheese" mask indicating masked out source areas
• idband (integer) OPTIONAL
  • Energy band index id_band in input list corresponding to input image
• emin (real) OPTIONAL [ e.g. 200.]
  • Lower energy boundary [eV] for the input image.
• emax (real) OPTIONAL [ e.g. 500.]
  • Upper energy boundary [eV] for the input image.
• scut (real) OPTIONAL [ e.g. 0.0001]
  • Surface brightness limit [cts/pix] for source masking
  • Determines the cutout radius depending on source count rate and PSF
• mlmin (real) OPTIONAL [ e.g 0.0]
  • Input likelihood threshold for source masking
• maxcut (real) OPTIONAL [ e.g 0.5]
  • Maximum fraction of masked out area
  • If this fraction is exceeded, the cutout radii are rescaled
• fitmethod (string) OPTIONAL [e.g. "smooth"]
  • Fit method [spline | smooth]
  • The recommended method is "smooth" (adaptive smoothing)
  • The "spline" option is obsolete
  • For >fitmethod="smooth", use paramter snr to set the required signal-to-noise ratio
  • For >fitmethod="smooth", use paramter smoothval to set the sigma of the smallest smoothing kernel
• snr (real) OPTIONAL [ e.g 30.0]
  • If fitmethod="smooth": required signal-to-noise ratio after smoothing
  • Increasing snr will result in larger smoothing scales
• smoothval (real) OPTIONAL [e.g. 15.]
  • If fitmethod="smooth", smoothflag="Y": Gaussian sigma of the smallest smoothing kernel [image pixel]
  • If fitmethod="spline", smoothflag="Y":Smoothing value for spline fit
• smoothmax (real) OPTIONAL [e.g. 360.]
  • If fitmethod="smooth", smoothflag="Y": Gaussian sigma of the largest smoothing kernel [image pixel]
• nfitrun (integer) OPTIONAL [e.g. 1]
  • If fitmethod="spline": Number of iterations for sigma clipping
• excesssigma (excesssigma) OPTIONAL [e.g. 1000.]
  • If fitmethod="spline" and nfitrun > 1: Sigma threshold to remove bins from next iteration of spline fit
• nsplinenodes (real) OPTIONAL [e.g. 36]
  • If fitmethod="spline": Number of spline nodes / spatial bins per dimension
• degree (integer) OPTIONAL [e.g. 2]
  • If fitmethod="spline": Degree of the spline used for fitting [1-5]
• smoothflag (boolean) OPTIONAL [e.g. Y]
  • If fitmethod="spline", smoothflag="Y": Calculate smoothing spline
  • If fitmethod="spline", smoothflag="N": Calculate weighted least-squares spline
• clobber (boolean) OPTIONAL [e.g. Y]
  • Overwrite output files ?

Input files:

• Input source list

  Source list with input positions. FITS binary table in the format as written by task ERBOX or ERMLDET. The file name is definbed by task parameter boxlist.

• Science image

  FITS files as generated by task EVTOOL. The primary FITS extension of each file contains a science image as an int32 array. The file name is defined by parameter image The task ERBACKMAP always works one one science image at a time.

• Exposure map

  FITS image ( real32) as created by task EXPMAP for the same instruments, energy bands, and WCS coordinate systems as the science images. The file name is defined by parameter expimage

• Detection mask

  FITS image ( int8) as created by task ERMASK with file name defined by parameter detmask. The image areas with value =1 are used for detection, areas with value =0 are masked out.

Output files:

• Background maps

  FITS image ( real32) containing the smoothed background map. The file name is defined by parameter bkgimage . The unit of the background map is counts/(image pixel).

• "Swiss cheese" mask FITS image ( int8) containing a map indicating the source areas which were masked out before smoothing the background map. Image pixels used for the background derminations have values =1, masked out pixels have values =0. Written if parameter cheesemask_flag="Y", the file name is defined by parameter cheesemask.

Examples:

• Calculate background map for image image_soft.fits covering the energy band 200-500 eV. Use adaptive smoothing with SNR=30 and a smallest smoothing scale of 15.0 image pixels:

      erbackmap image=image_soft.fits  \
                expimage=image_soft_exp.fits \
                boxlist=boxlist_local.fits \
                detmask=detmask.fits \
                idband=1 \
                emin=200. \
                emax=500. \
                bkgimage=image_soft_bkg.fits \
                cheesemask=image_soft_cheese.fits \
                scut=0.001 \
                mlmin=6 \
                maxcut=0.5 \
                fitmethod=smooth \
                snr=30.  \
                smoothval=15.0 \
                smoothmax=360 \
                cheesemask_flag='Y'
  

• Calculate adaptively smoothed image without removing sources (mlmin=10⁶), the smallest smoothing scale is 4.0 image pixels:

      erbackmap image=image_soft.fits  \
                expimage=image_soft_exp.fits \
                boxlist=boxlist_local.fits \
                detmask=detmask.fits \
                idband=1 \
                emin=200. \
                emax=500. \
                bkgimage=image_soft_bkg.fits \
                cheesemask=image_soft_cheese.fits \
                scut=0.001 \
                mlmin=1.0E6 \
                maxcut=0.5 \
                fitmethod=smooth \
                snr=30.  \
                smoothval=4.0 \
                cheesemask_flag='Y'