eSASS task: erbox

Scope

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

Description:

The task ERBOX is based on a sliding box algorithm to detect peaks in the input science images. The task can be run in two modes:

local mode (bkgima_flag=no) , which estimates the background from a region surrounding the source box
map mode (bkgima_flag=yes), which uses the background maps generated by ERBACKMAP at the position of the source.

In local mode the background is measured in a 2 pixel wide frame around the source box, in map mode the background is taken from the background maps supplied in the files bkgimages and averaged over the source box. If the (recommended) parameter boxsize=4 (9x9 pixel detection box) is set, the image is first smoothed using a kernel of the form

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

with r_c=3.75 pixels (15 arcsec for the standard 4 arcsec bin size). For other values of boxsize the image is folded with the box profile. The smoothed image is searched for peaks, creating a preliminary source list. The significance of the peaks is measured by comparing the number of box counts n_i with the expected background counts b_i in each input image i using the (logarithmic) likelihood

L_i = - ln P_Γ (n_i, b_i)

where P_Γ is the regularised incomplete Gamma function

$P_{Γ} (a, x) = \frac{\int_{0}^{x} e^{- t} t^{a - 1} d t}{\int_{0}^{\infty} e^{- t} t^{a - 1} d t}$

This peak search can be repeated several times after rebinning the input images by a factor of 2x2, effectively doubling the box size. In the case of multiple input images (e.g., in different energy bands), a combined likelihood is computed using Fisher's method: the probability values P_i from n independent tests of the same null hypothesis are combined into a global likelihood value

$L' = - 2 \sum_{i = 1}^{n} \ln P_{i}$ ,

which follows a χ² distribution with 2n degrees of freedom. The combined detection likelihood of a source can therefore be calculated as

$L_{d e t} = - \ln (1 - P_{Γ} (n, \sum_{i = 1}^{n} L_{i}))$

The source list is filtered using a threshold on the combined likelihood. For the significant sources the following parameters are calculated for each input image and for the combined data set:

raw box counts
PSF-corrected box counts with errors
PSF-corrected count rates with errors
source fluxes with errors
background counts
detection likelihood values
source exposure values (for each input image only)
center of mass positions in image and equatorial coordinates (combined values only) with errors
the image rebinning step in which the source is most significant
hardness ratios of the form HR₁₂ = (cr₂-cr₁)/ (cr₂+cr₁) with errors

Input parameters:

images (string array) REQUIRED
- List of input images
boxlist (string) REQUIRED
- Output source list file name
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 maps(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 4 ]
- Energy bands used for hardness ratios.
- Defines up to 3 pairs of energy bands beween which the ahardness rations are calculated.
nruns (integer) OPTIONAL [ e.g. 3]
- Number of (2x2) image rebinning steps
likemin (real) OPTIONAL [ e.g. 8.0]
- Detection likelihood threshold
boxsize (integer) OPTIONAL [ e.g. 4]
- Detection box size (half width - 0.5) in units of images pixels
compress_flag (boolean) OPTIONAL[ e.g. N]
- Use memory saving image handling (obsolete)

Input files:

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. 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 boxlist. The table format is described in the following table:

Columns	Type	Unit	Description
ID_SRC	int		Source ID
ID_INST	int32		Instrument ID
ID_BAND	int32		Index of energy band
SCTS	real32	counts	Box counts aperture corrected
SCTS_ERR	real32	counts	Error of aperture corrected counts
BOX_CTS	real32	counts	Raw Box counts
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
LIKE	real32		Log-likelihood of detection
BG_MAP	real32	counts/pixel	Background at source position
BG_RAW	real32	counts/pixel	Background at source position
EXP_MAP	real32	s	Exposure at source position
FLUX	real32	erg /cm**2 /s	Source flux in energy band
FLUX_ERR	real32	erg /cm**2 /s	Source flux error in energy band
RATE	real32	counts/s	Source count rate, aperture corrected
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, currently not used
BII	real64	deg	Gal. latitude, currently not used
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
VIGNET	real32		Source vignetting factor, currently not used
BOX_SIZE	int32		Image rebinning factor for the most significant detection
EEF	real32		Enboxed energy fraction
DIST_NN	real32		Distance from nearest neighbour, currently not used

Examples:

Simultaneous detection on 2 input images in local mode:

  erbox images="image_soft.fits  image_hard.fits" \
        boxlist="boxlist_local.fits" \
        expimages="image_soft_exp.fits image_hard_exp.fits" \
        detmasks="detmask.fits" \
        emin="500 2000" \
        emax="2000 5000" \
        hrdef="1 2" \
        ecf="2.0E12 1.0E12" \
        nruns=3 \
        likemin=6. \
        boxsize=4 \
        compress_flag="N" \
        bkgima_flag="N" \
        expima_flag="Y" \
        detmask_flag="Y"

Simultaneous detection on 2 input images in map mode:

  erbox images="image_soft.fits  image_hard.fits" \
        boxlist="boxlist_map.fits" \
        expimages="image_soft_exp.fits image_hard_exp.fits" \
        bkgimages="image_soft_bkg.fits image_hard_bkg.fits" \
        detmasks="detmask.fits" \
        emin="500 2000" \
        emax="2000 5000" \
        hrdef="1 2" \
        ecf="2.0E12 1.0E12" \
        nruns=3 \
        likemin=6. \
        boxsize=4 \
        compress_flag="N" \
        bkgima_flag="Y" \
        expima_flag="Y" \
        detmask_flag="Y"

Back to eSASS task descriptions