XMM-Newton Science Analysis System


eboxdetect (eboxdetect-4.29) [xmmsas_20230412_1735-21.0.0]

Description

The task eboxdetect is used to perform source detection on individual images or on sets of images from different energy bands and/or different EPIC instruments. If source detection on multiple images is performed, the input images and corresponding exposure images, background images, and detection masks have to be supplied as lists of file names. All input images and accompanying exposure images, background images, and detection masks must have identical orientation and binning and must be supplied in a consistent order. The task is designed for a maximum of five energy bands and three EPIC instruments. It is technically possible to run eboxdetect for up to six energy bands, but users are encouraged not to use more than five because of the low count numbers in narrow-band images.

eboxdetect has two different modes of operation: (1) local detection and (2) map detection. eboxdetect is first run in local mode. The local-mode source lists serve as input for the task esplinemap which creates background maps (one per energy band for each EPIC instrument). They are then used to run eboxdetect in map mode. The boolean input parameter usemap controls whether the program operates in map mode or in local mode.

1. Local detection mode: The purpose of the local detection step is to provide an input list of source positions for the task esplinemap, which then constructs a background map from the non-source locations. Source counts are accumulated from a 3x3 or 5x5 pixel window (controlled by the parameter boxsize) and the background is determined from the surrounding 40 (7x7 pixel window minus 3x3) or 56 pixels (9x9 pixel window minus 5x5), respectively. Detection of moderately extended objects (up to several times the PSF size) is achieved by searching the image in up to three consecutive detection runs, each doubling the pixel size. The input image pixel size resampled from the original detector pixels is chosen such that the detection window corresponds to the size of the on-axis PSF. It is thus required that the PSF is at least moderately oversampled (which is the case for both pn and MOS CCD EPIC data). It is recommended to use a detection threshold of likemin=8 to provide a complete source list as input for esplinemap.

2. Map detection mode: Source counts are accumulated from a 3x3 or 5x5 pixels window with the option to use a position and energy dependent PSF weighted filter (matched filter; not yet implemented). Detection of extended objects is again achieved by doubling the pixel sizes in up to three consecutive detection runs. In map detection mode the background is taken from the background maps determined by esplinemap, resulting in an improved detection sensitivity as compared to the local detection step. If the map detection run is used as input for the task emldetect, it is recommended to use a somewhat lower detection threshold than for emldetect itself, e.g. mlmin=10 for emldetect and likemin=8 for eboxdetect.

In both modes, source searching is only performed in the area of the images which is marked by an optional detection mask created by task emask. Use of a detection mask is controlled by the boolean input parameter withdetmask. If true, one detection mask for each EPIC instrument must be supplied (parameter detmasksets). Parameter withexpimage controls the optional use of exposure maps as created by task eexpmap. The value of the exposure image at the location of each detected source is then used to calculate vignetting- and deadtime-corrected source count rates. If the parameter withexpimage is set to true, one exposure image for each energy band of each EPIC instrument must be supplied (parameter expimagesets). If no exposure images are supplied, raw count rates are calculated by deriving the exposure information from the good time intervals.

Background-subtracted source counts are calculated by applying correction factors to account for the respective fractions of source counts falling in each source and background area. The respective off-axis angle dependent correction factors are calculated using the medium-accuracy PSF. The following equations describe the PSF correction of source and background counts as implemented in the code of the task.

$n$ = detection box size

Enboxed energy fraction in source box:

$$\alpha = \sum_{n\times n } {\rm PSF}$$

Fraction of source counts in background counting area:

$$\beta = \sum_{(n+4) \times (n+4) }\!\!\! \!\!\!{\rm PSF} - \sum_{n\times n } {\rm PSF}$$

Raw box counts:

$$\index{Columns!BOX\_CTS}{\tt BOX\_CTS} = \sum_{n\times n } {\rm image}$$

Raw background map:

$$\index{Columns!BG\_RAW}{\tt BG\_RAW} = (\sum_{(n+4) \times (n+4)} \!\!\!\!\!\! {\rm image} - \sum_{n \times n } {\rm image})/((n+4)^2-n^2)$$

In local detection mode:

PSF corrected and background subtracted source counts:

$$\index{Columns!SCTS}{\tt SCTS} = \frac{\index{Columns!BOX\_CTS}{\... ...x{Columns!BG\_RAW}{\tt BG\_RAW}\cdot n^2}{\alpha-\beta\cdot n^2/((n+4)^2-n^2)}$$

PSF corrected background map:

$$\index{Columns!BG\_MAP}{\tt BG\_MAP} = \index{Columns!BG\_RAW}{\tt BG\_RAW} - \index{Columns!SCTS}{\tt SCTS}\cdot\beta/((n+4)^2-n^2)$$

$$err_{\rm bg} = \sqrt{ \index{Columns!BG\_RAW}{\tt BG\_RAW} \cdot ((n+4)^2-n^2)} / ((n+4)^2-n^2)$$

Error of source counts:

$$\index{Columns!SCTS\_ERR}{\tt SCTS\_ERR} = \frac{ \sqrt{ \index{C... ...\_CTS}{\tt BOX\_CTS} + (n^2* err_{\rm bg})^2} }{\alpha-\beta\cdot n^2/(n+4)^2}$$

In map detection mode:

$$\index{Columns!SCTS}{\tt SCTS} = (\index{Columns!BOX\_CTS}{\tt BOX\_CTS} - \index{Columns!BG\_MAP}{\tt BG\_MAP}\cdot n^2)/\alpha$$

The resulting output source table contains one row per input image for each detected source, plus a number of summary rows containing the broad band results for each EPIC telescope and the combined results for all EPIC telescopes taken together. The individual source rows are identified through the column entries ID_INST and ID_BAND in the output table where ID_INST refers to the EPIC instrument (1: PN, 2: MOS1, 3: MOS2, 0: summary row) and ID_BAND is the energy band number as defined by the ordering in which the energy bands are given on the command line. An ID_BAND value of 0 again refers to the summary information. No summary rows are output if the source detection is only performed on a single input image.

The source table lists statistical errors for both count rates and source positions. Count rate errors are calculated by assuming Poissonian statistics ( ${\rm error} = \sqrt{\rm counts}$) in both the source and background cells (if eboxdetect is run in local mode) and by applying standard error propagation. If run in map mode, the background taken from the spline background maps is assumed to be free of statistical errors. Positional errors are assumed to be equal to the standard deviation of the distribution of the counts in the detection cell. The errors of the derived parameters, such as count rates, fluxes, and source positions in celestial coordinates are derived from the count and image pixel positional errors, respectively.

Following the definition which was e.g. used by the ROSAT mission, detection likelihoods (per energy band and total) are given for each source in the form $L = - \ln p$ where $p$ is the probability of Poissonian random fluctuation of the counts in the detection cell which would have resulted in at least the observed number of source counts. The value of $p$ is calculated using the incomplete Gamma function $P(a,x)$ as a function of raw source counts and raw background counts in the detection box. See Press et al., Numerical Recipes, chapter 6.2 for the calculation of $P(a,x)$.

$$\index{Columns!LIKE}{\tt LIKE} = - {\rm ln} p(\index{Columns!BOX\_CTS}{\tt BOX\_CTS},\index{Columns!BG\_RAW}{\tt BG\_RAW}\cdot n^2)$$

In the case of simultaneous detection runs over several energy bands, the LIKE values from each individual energy band are added and transformed to equivalent single band detection likelihoods using the incomplete Gamma function:

$$L = P(n,\sum_{i=1}^n L_i)$$

where $n$ is the number of energy bands. A source is included in the output table if the equivalent single band detection likelihood exceeds the threshold given by the parameter likemin.

If detection over several energy bands is performed, up to three hardness ratios are calculated from the source counts in the individual bands. The hardness ratios are defined as follows:

$$HR_i = \frac{B_m - B_n}{B_m + B_n}$$

where $B$ denotes the count rates in energy bands $n$ and $m$, respectively. $n$ and $m$ are specified in the input parameter hrdef for each of the (up to) three hardness ratios. The default band assignment is given in the following table:

Table 1: Default band assignments of hardness ratios HR$_i$ for the EPIC instruments

$i$	$n$	$m$
1	1	2
2	2	3
3	3	4

The band numbers $n$ and $m$ (output table column ID_BAND) are assigned to the individual bands by numbering the corresponding input images in the order in which they are given on the command line. It is therefore important that the ordering of the input images is consistent with the contents of hrdef to obtain meaningful hardness ratios.

Input images. With version 4.24, the parameter obsmode has been introduced to distinguish between input data from pointing observations (obsmode=pointing) and from slew-mode observations (obsmode=slew). Input data in detector coordinates are accepted from version 4.25 on and identified by their header keywords CTYPE1/2=DETX/Y. Only one instrument is allowed in this case. The columns X_IMA, Y_IMA of the output source lists are given in the same coordinate system as the input data. Two additional columns DETX, DETY hold the detector coordinates of the detections. Position errors are not converted into detector coordinates. If required, users can derive them from the X_IMA_ERR, Y_IMA_ERR columns. No PSF correction is calculated for data in detector coordinates. Use of the defaults – pointing observation, X/Y coordinates – is recommended.