eSASS task: ermldet

Scope

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

Summary:

The task ERMLDET determines source parameters for a list of input sources from the file specified by parameter boxlist . The task uses a PSF fitting algorithm to fit a model of the source (either the PSF or a convolution of the PSF with an extent model) to the spatial distribution of counts taken from the images specified by parameter images . The primary set of fit parameters are x,y-position, count rates in each input image, and a source extent parameter. The fit parameters, derived quantities, and theit respective errors are written to the output source list specified by parameter mllist. Fitting of the source positions and source extent is optional and is controlled by the logical parameters fit_position and fit_extent . If shapelet_flag=no, the relevant PSF is read from the corresponding calibration image file, the relevant PSF calibration image is chosen using the header information in the science images and the energy interval given by emin and emax . In the case of shapelet_flag =yes, the SHAPELIB library routines are used to construct a source specific PSF, which is based on the positions and energies of the photons contributing to the respective source.

Algorithms:

The input source list is processed sequentially in descending order of likelihood from column LIKE . Neighbouring sources can also be fitted simultaneously as source clusters, the compilation of the source clusters is controlled by the parameters nmaxfit (maximum number of sources) and multrad (search radius). The task ERMLDET applies a PSF fitting algorithm to determine source parameters for a list of input positions. The source PSF can be generated using the following methods:

• from 2D PSF images stored in calibration files for a grid of photon energies and off-axis angles (pointed observations).
• from 2D images of the PSF averaged over the detector area and stored for a grid of photon energies.
• reconstruction of a source-specific PSF by averaging the PSFs of each source photon, the event-specific PSFs are stored in calibration files as sets of shapelet coefficients for a grid of energies and detector positions.
• calculation of event specific PSFs using the shapelet coefficients stored in calibration files ("photon mode").

A maximum likelihood fitting procedure is applied to the sources in the input list, starting with the most significant source and then working on the sources in the order of descending likelihood. Neighbouring sources can be combined for simultaneous fitting, and input positions can also be split up into multiple sources. The combination of the source clusters is controlled by the parameters nmaxfit (maximum number of sources) and multrad (search radius). The maximum number of splitted sources per input position is determined by the parameter nmulsou . The source models are generated using PSFs which are optionally (parameter fitext_flag=yes) folded with an extent model. Depending on parameter extent_model the extent model is either a Gaussian kernel or a beta model of the form

f(x,y)= [1 + ( (x-x₀)² + (y-y₀)²) / r_c² ]^-1.5

with the core radius r_c as a free fit parameter. The models are multiplied with the exposure map to account for instrumental effects and the background is added. The model parameters are:

• X, Y positions in image coordinates for each source
• extent radius for each source
• net source count rate for each source and input image

The source parameters are optimized by minimising the C-statistic (Cash 1979):

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

where e_i is the expected model value of pixel i, n_i is number of photon events in pixel i, and N the total number of image pixels used for the fit. Once the fit has converged at a set of best fitting parameters, the significance of each source is tested by calculating

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

where C_null is the C-statistic of the null hypothesis (i.e. model with zero net counts) and C_best is the value for the best fitting model. The fitting algorithm of ERMLDET can optionally obtain an individual PSF for each photon event depending on its energy and detector position (parameter photon_mode=yes). Where applicable, the event PSF is convolved with the extent model. In this mode the C-statistic is summed over the number of events rather than over the number of image pixels (unbinned likelihood).

The probability P that ΔC results from a chance fluctuation of the background is calculated using the regularised incomplete Gamma function P_Γ :

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

For each source the logarithmic detection likelihood L = -ln(P)) is obtained. In case of simultaneous multi-source fits, sources falling below the user defined likelihood threshold are removed and the fitting procedure is iteratively repeated. After each model fit to a source or source cluster, the model is added to the background map. The final background + model maps can be written to the fits files srcimages. For the significant sources, 68% parameter errors are calculated by varying the parameter of interest from its best value in both directions until C = C_best + 1.0 is reached. These boundaries are determined by an iterative procedure and the errors for both directions are averaged and written to the output table. In cases where for one direction the algorithm fails to converge after the given number of iterations, the errors determined for the other direction are adopted. In case no error margin can be determined in either direction, a zero is written to the output table. The positional errors are given in units of image pixels for both X and Y positions as well as an error radius (column RADEC_ERR) in units of arc seconds:

RADEC_ERR = pixelsize * √(X_IMA_ERR² + Y_IMA_ERR²).

For derived quantities as the sum of count rates in multi-band fits or the hardness ratios between energy bands the count rate errors are propagated treating them like Gaussian errors.

Input parameters:

• boxlist (string) REQUIRED
  • Input source list file name
• images (string array) REQUIRED
  • List of input images
• mllist (string) REQUIRED
  • Output source list
• expimages (string array) OPTIONAL/REQUIRED IF expima_flag=Y
  • Exposure map(s)
• detmasks (string array) OPTIONAL/REQUIRED IF detmask_flag=Y
  • Detection mask(s)
• bkgimages (string array) OPTIONAL
  • Background map(s)
• srcimages (string array) OPTIONAL/REQUIRED IF srcima_flag=Y
  • Output source model image(s)
• emin (real array) OPTIONAL [ e.g. 500.]
  • Lower energy boundary [eV] for each input image.
• emax (real array) OPTIONAL [ e.g. 2000.]
  • Upper energy boundary [eV] for each input image.
• ecf (real array) OPTIONAL [ e.g. 1.0 1.0 1.0]
  • Energy conversion factor for each image used to calulate flux column.
  • ML_FLUX(band) = ML_RATE(band) / ECF(band)
  • Unit: cm**2/ergs
• hrdef (integer array) OPTIONAL [ e.g. 1 2 2 3 3 4 ]
  • Energy bands used for hardness ratios.
  • Defines up to 3 pairs of energy bands between which the hardness ratios are calculated.
• likemin (real) OPTIONAL [ e.g. 8.0]
  • Detection likelihood threshold
• extlikemin (real) OPTIONAL [ e.g. 6.0]
  • Extent likelihood threshold
• extlike_slope (real array) OPTIONAL [ e.g. 0.0, 0.0]
  • Extent dependent likelihood threshold.
  • Only sources with L_ext ≥ extlike_slope(0)+extlike_slope(0)*ext are considered significantly extended.
• extmin (real) OPTIONAL [ e.g. 0.5]
  • Minimum extent likelihood in units of image pixels
• extmax (real) OPTIONAL [ e.g. 40.0]
  • Maximum extent likelihood in units of image pixels
• extentmodel (string) OPTIONAL [ e.g. "beta"]
  • Source extent model ["gaussian" | "beta" ]
• nmaxfit (integer) OPTIONAL [ e.g. 3]
  • Max. number of input sources to be combined for simultaneous fitting.
  • See also parameter multrad for the search radius.
• nmulsou (integer) OPTIONAL [ e.g. 1]
  • Maximum factor for source splitting. If > 1, input sources can be split into nmulsou sources.
• thresh_flag (boolean) OPTIONAL [ e.g. N]
  • Use threshold for source splitting.
  • If set, only for sources with input values thres_col ≥ thres_val source splitting is attempted.
  • See also parameters nmulsou, thres_col , thres_val
• thres_val (real) OPTIONAL [ e.g. 30.0]
  • Threshold value for source splitting
• thres_col (string) OPTIONAL [ e.g. "like"]
  • Column in input list to apply threshold ("LIKE"|"RATE"|"SCTS")
• multrad (real) OPTIONAL [ e.g. 25.0]
  • Search radius for multiple source fitting in units of image pixels.
  • See also paramter nmulsou for the maximum number of input sources to be combined.
• cutrad (real) OPTIONAL [ e.g. 20.0]
  • Cut radius for source fitting in units of image pixels.
  • The image pixels within this radius around the input position will be used for fitting
  • The radii cutrad and multrad should have similar values
• fitext_flag (boolean) OPTIONAL [ e.g. Y]
  • Fit source extent?
  • If =no, only PSF fits without extent model will be performed.
• twostage_flag (boolean) OPTIONAL [ e.g. Y]
  • Split sources in two stages.
  • For a first fit no source splitting will be performed. If the source is significantly extended, a fit with nmulsou sources will be run ./li>
• fitpos_flag (boolean) OPTIONAL
  • Fit source positions?
  • Setting fitext_flag=N and fitpos_flag=N enables a "forced photometry" mode, where only count rates are measured for each input position.
• compress_flag (boolean) OPTIONAL[ e.g. N]
  • Use memory saving image handling (obsolete)
• srcima_flag (boolean) OPTIONAL [ e.g. Y]
  • Write source model maps
  • One soure map per input images, file names are determinde by paramter srcimages.
• expima_flag (boolean) OPTIONAL [ e.g. Y]
  • Use exposure maps (recommended)
• detmask_flag (boolean) OPTIONAL[ e.g. Y]
  • Use detection mask (recommended)
• shapelet_flag (boolean) OPTIONAL [ e.g. N]
  • Use shapelet PSF model
• photon_flag (boolean) OPTIONAL [ e.g. N]
  • Perform fitting in photon mode using unbinned likelihoods. This requires parameter shapelet_flag=yes.
• sixte_flag (boolean) OPTIONAL [ e.g. N]
  • Are we working on SIXTE simulated data? If yes, extra smoothing of the PSF is applied in order to match the slightly wider PSF of SIXTE simulations wrt. in orbit data.

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

  One or more FITS files as generated by task EVTOOL. The primary FITS extension of each file contains a science image as an int32 array. The file names are defined by task parameter images. In case task parameter shapelet_flag = yes is set, also the EVENTS and CORRATT extensions need to be present in the input files. Typically, the images of all active eROSITA telescope modules are added into one image and multiple images correspond to a set of non-overlapping energy bands. However, supplying images from multiple instruments is possible. The WCS coordinate systems of all input images have to be identical.

• 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

• Background maps

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

• 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.

Output files:

• Source list

  The source list is written to a FITS binary table extension, the file name is determined by the task parameter mllist. The table format is described in the following table:

  Columns	Type	Unit	Description
  ID_SRC	int		Source ID
  BOX_ID_SRC	int32		Input source ID
  ID_INST	int32		Instrument ID
  ID_BAND	int32		Index of energy band
  ID_CLUSTER	int32		Group ID of simultaneously fitted sources
  ML_CTS	real32	counts	Total source counts aperture corrected
  ML_CTS_ERR	real32	counts	Total source counts aperture corrected
  X_IMA	real32	pixel	Source position, image pixels
  X_IMA_ERR	real32	pixel	Position error, image pixels
  Y_IMA	real32	pixel	Source position, image pixels
  Y_IMA_ERR	real32	pixel	Position error, image pixels
  EXT	real32	arcsec	Extent value (core radius / sigma)
  EXT_ERR	real32	arcsec	Extent value, error
  DET_LIKE	real32		Log-likelihood, detection
  EXT_LIKE	real32		Log-likelihood, extent probability
  ML_BKG	real32	counts/arcmin**2	Background at source position
  ML_EXP	real32	s	Exposure at source position
  ML_FLUX	real32	erg /cm**2 /s	Source flux in energy band
  ML_FLUX_ERR	real32	erg /cm**2 /s	Source flux error in energy band
  ML_RATE	real32	counts/s	Source count rate, aperture corrected
  ML_RATE_ERR	real32	counts/s	Source count rate error, aperture corrected
  RA	real64	deg	RA position
  DEC	real64	deg	Dec position
  RADEC_ERR	arcsec	deg	Combined RA,DEC position error
  LII	real64	deg	Gal. longitude
  BII	real64	deg	Gal. latitude
  RAWX	int32	det. pixel	Source position on detector
  RAWY	int32	det. pixel	Source position on detector
  OFFAX	real32	arcmin	Source off axis angle on detector
  TM_NR	int32		Telescope module number
  HR1	real32		Hardness ratio 1
  HR1_ERR	real32		Hardness ratio error 1
  HR2	real32		Hardness ratio 2
  HR2_ERR	real32		Hardness ratio error 2
  HR3	real32		Hardness ratio 3
  HR3_ERR	real32		Hardness ratio error 3
  ML_RADIUS	real32	arcsec	Radius of sub image for fitting
  MASKFRAC	real32		Fraction of good pixels in ML_RADIUS
  ML_EEF	real32		Encircled energy fraction in ML_RADIUS
  VIGNET	real32		Source vignetting factor
  ONTIME	real32	s	Source exposure elapsed time
  DIST_NN	real32		Distance from nearest neighbour
  OWNER	int8		Data ownership flag

• Source map files:

  When the task parameter srcima_flag is set to Y, source maps are written to the FITS image files specified by parameter srcimages. The primary extension of each file (one for each input image) contains an image with the source model added to the input background map.

Examples:

1. Run ERMLDET on 2 images, allow simultaneous fitting of up to 3 input sources, use PSF from calibration images:

ermldet mllist=mllist.fits \
        boxlist=mboxlist.fits \
        images="image_soft.fits image_hard.fits" \
        expimages="image_soft_exp.fits image_hard_exp.fits" \
        detmasks="detmask.fits" \
        bkgimages="image_soft_bkg.fits image_hard_bkg.fits" \
        emin="500 2000"\
        emax="2000 5000" \
        hrdef="1 2" \
        ecf="2.0E12 1.0E12" \
        likemin=8. \
        extlikemin=10. \
        cutrad=15. \
        multrad=15. \
        extmin=1.5 \
        extmax=30.0 \
        expima_flag="Y" \
        detmask_flag="Y" \
        extentmodel="beta" \
        thres_flag="N" \
        nmaxfit=3 \
        nmulsou=1 \
        fitext_flag=yes \
        srcima_flag=yes \
        srcimages="image_soft_src.fits image_hard_src.fits" \
        expima_flag=yes \
        detmask_flag=yes \
        shapelet_flag=no \
        photon_flag=no \
        sixte_flag=no

2. Set srcima_flag=y and photon_flag=y to run ERMLDET using unbinned likelihoods:

ermldet mllist=mllist_photon.fits \
        boxlist=mboxlist.fits \
        images="image_soft.fits image_hard.fits" \
        expimages="image_soft_exp.fits image_hard_exp.fits" \
        detmasks="detmask.fits" \
        bkgimages="image_soft_bkg.fits image_hard_bkg.fits" \
        emin="500 2000"\
        emax="2000 5000" \
        hrdef="1 2" \
        ecf="2.0E12 1.0E12" \
        likemin=8. \
        extlikemin=10. \
        cutrad=15. \
        multrad=15. \
        extmin=1.5 \
        extmax=30.0 \
        expima_flag="Y" \
        detmask_flag="Y" \
        extentmodel="beta" \
        thres_flag="N" \
        nmaxfit=3 \
        nmulsou=1 \
        fitext_flag=yes \
        srcima_flag=yes \
        srcimages="image_soft_src_phot.fits image_hard_src_phot.fits" \
        expima_flag=yes \
        detmask_flag=yes \
        shapelet_flag=yes \
        photon_flag=yes \
        sixte_flag=no

Known issues:

• The detection tasks make use of the exposure maps created by task expmap which are affected by the double accounting of the chopper setting. For observations with chopper setting > 1, please follow the instructions in the expmap task description to correct the exposure maps (see also FAQ).
• In the the event based PSF mode ( photon_flag=Y) in some cases the model fit does not properly converge, in particular for bright sources (> 1000 counts). Therefore observations containing many bright sources or observations in pointed mode (where the event based PSF does not have any advantage), should be processed using photon_flag=N .