celldetect

Synopsis

Use a "sliding cell" to search for sources

celldetect  infile [psffile] [expstk] outfile [regfile] [clobber]
[thresh] [snr_diminution] [findpeaks] [centroid] [ellsigma] [expratio]
[fixedcell] [xoffset] [yoffset] [cellfile] [maxlogicalwindow] [bkgfile]
[bkgvalue] [bkgerrvalue] [convolve] [snrfile] [verbose] [log]

Description

`celldetect' searches for sources by summing counts in square cells ("detect" cells) in the dataset and comparing the counts to those of "background" cells. At each point where a cell is placed, a signal-to-noise ratio of source counts to background counts is computed. If this ratio is above the detection threshold, a candidate source is recorded.

Strengths

• Good for faint point sources, outside crowded fields.
• Long heritage (EINSTEIN, Rosat); well understood.

Weaknesses

• Requires fine-tuning of parameters for extended sources.
• Divides extended sources into multiple point sources.
• Has difficulty separating closely-spaced point sources.

For Chandra observations, at any given position (if `fixedcell'=0), the size of the detect cell is determined by the size of the PSF at that point using the input psffile. In the center of the field, the cells are small. As you go off-axis, the cells become larger. (celldetect does have a "fixed cell size" option, where the detect cell size is kept constant for the entire data set.)

There are three options for computing the background counts for a detect cell. (1) Usually, it will be estimated from a background cell which surrounds the detect cell. This is essentially the ROSAT LDETECT procedure. Alternatively, (2) the user may specify the background as an input image file, or (3) as a fixed value of counts/pixel. For options 2 and 3, the background cell is the same as the detect cell. In all of these cases, the data set is "tiled" with overlapping detect cells, and candidate sources are identified.

To minimize spurious detections along detector edges, one or more suitably binned exposure maps supplied by the user may be used in conjunction with the parameter `expratio' (try values between 0.9 and 0.99). By suitable choice of this parameter, it is possible to suppress entries in the region file (`regfile') although all detections will still be listed in the standard output file.

For a more complete description of the theory and operation of celldetect, please see the celldetect sections of the CIAO Detect Manual.

Examples

Example 1

celldetect pleiades.fits cell_output.fits psffile=psf.map

Run celldetect on the primary image in pleiades.fits, putting output in cell_output.fits. The PSF size information is provided using the psf.map input file.

Example 2

celldetect "pleiades.fits[events]" cell_output.fits psffile=psf.map

Run celldetect on the EVENTS block in pleiades.fits, putting output in cell_output.fits.

Example 3

celldetect pleiades.fits cell_output.fits fixedcell=9

Use a fixed-size detect cell of size 9 pixels square. When using a fixed detect cell size, the psffile is not used.

Example 4

celldetect pleiades.fits cell_output.fits regfile=celldetect.reg
psffile=psf.map

Create an output "regions" file, named celldetect.reg.

Example 5

celldetect acis_evt.fits src.fits psffile=@psfmap.lis

If the size of the input image is larger than the maxlogicalwindow size, then celldetect will recursively bin the image. When this happens users have to supply the correct PSF for each bin size celldetect uses. These are supplied using standard CIAO stack syntax.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input image or event file. If the input is an event file, the tool should find the EVENTS extension, but it can be specified as "foo.fits[EVENTS]".

If the input is larger than the maxlogicalwindow value along either axis (TLMIN/TLMAX values of the axes), the tool will operate in "recursive blocking" mode.

Parameter=psffile (file filetype=input default= stacks=yes)

Image of the PSF size

The PSF map is used to adjust the detect cell size for each pixel in the input image. The units of the PSF map are used to convert the pixel values to match the logical pixel size.

When the input image size is greater than maxlogicalwindow pixels, the image will be repeated rebinned. In that case, the user must supply a psffile for each of the bin sizes celldetect uses.

Parameter=expstk (file filetype=input default= stacks=yes)

Exposure map stack/file. This is a list of filenames where each file is an exposure map with appropriate binning to match celldetect's recursive blocking. NB: Exposure maps do not work with predetermined background inputs, or with the convolution option.

Parameter=outfile (file required filetype=output autoname=yes)

Output source list file. Some columns contain only zeros.

If auto-naming is used (outfile=.), the output file will have the suffix "_src"

Parameter=regfile (file default=none autoname=yes)

File for ascii region output. If an exposure map has been used, and 'expratio' is non-zero, there may be fewer entries in 'regfile' than in 'outfile'.

If auto-naming is used (regfile=.), the output file will have the suffix "_reg"

Parameter=clobber (boolean default=no)

If "yes", overwrite existing outputs.

Parameter=thresh (real default=3)

Signal to noise threshold for source detection. A good value to use is 3 to 4.

Parameter=snr_diminution (real default=1 min=0 max=1)

Evaluate detect cells with diminished SNR on finer grid.

If a detect cell is found to have a SNR = snr_diminution*thresh, then celldetect will recompute the SNR by recentering the detect cell on a finer grid. If the recentered cell is found to have a SNR above the threshold then it will be added to the source list.

Parameter=findpeaks (boolean default=yes)

Find the local maxima of contiguous detections? (yes|no)

Without this option enabled, single sources are usually identified multiple times. Normally set to "yes".

Parameter=centroid (boolean default=yes)

Compute source centroid positions? (yes|no). If `no', the center pixel of a source's detect cell is reported as the location of the source.

Parameter=ellsigma (real default=3)

Size, in sigmas, to make the elliptical source regions.

ellsigma is a multiplicative factor applied to sigma, the standard deviation of the distribution, to scale the major and minor axes of the ellipses for each source. ellsigma affects both the outfile and the ASCII region file (regfile). This feature is included so that the graphics overlay will be more visible and under the user's control. Often a value greater than 3 is helpful.

Parameter=expratio (real default=0)

Suppresses ascii source regions for sources whose EXPO_RATIO falls below this value.

This ratio is the average exposure of the background frame, divided by the average exposure in the detect cell. All detections will be present in 'outfile'; it is only the region file that may have some detections filtered out.

This option was devised to minimize the problem of spurious detections along chip edges; it is based on the option for 'local background', the frame around the detect cell. If this parameter is non-zero, a user supplied exposure map must be specified via the parameter 'expstk'. The column 'EXPO_RATIO' of the outfile will be filled. Values of 'expratio' in the range 0.9 to 0.99 have been found to function.

Parameter=fixedcell (integer default=0 units=pixels)

A fixed size for the detect cell over the complete field of view.

If a fixed cell size is set, the detect cell size is kept constant for the entire dataset. Allowed values are 1 or an integer divisible by 3. Setting this parameter effectively disables the parameters related to celldetect's variable cell size functionality: psftable, eenergy, eband, xoffset, and yoffset.

The default value of 0 indicates that a variable cell size will be used. Only detectors having a psftable supplied allow the use of the variable PSF option. Data from other instruments must be analyzed with a fixed cell size [fixedcell=(1 or an integer divisible by 3)].

Note that even though the PSF info isn't used to compute the cell sizes when fixedcell is non-zero, it still does populate the "psfratio" column in the output src list.

Parameter=xoffset (integer default=INDEF units=pixels)

Offsets of x- and y-axis for the calculation of the off-axis angle.

Offsets of x- and y-axis for the calculation of the off-axis angle. By default (when both offsets are set to INDEF), celldetect calculates the off-axis angle using the nominal pointing of the data file as the origin. Users may change this behavior by setting offsets to any numerical values; the offsets provide the location of the optical axis with respect to the center of the data file.

A typical scenario in which the users may select to use offsets is when their data file is a sum of two or more observations, with different pointings. The nominal pointing in such data file is usually poorly defined and the off-axis angle could be calculated from an undesired origin, leading to suboptimal selection of the detect cell size. The ability to set the origin explicitly with x/yoffset solves this problem.

Parameter=yoffset (integer default=INDEF units=pixels)

See "xoffset".

Parameter=cellfile (file filetype=output default= autoname=yes)

Name of stack for file names of cell size images.

The images show the detect cell size at each pixel location. If auto-naming is used, the output stack file will have the suffix "_cell".

Parameter=maxlogicalwindow (integer default=8192 min=0)

Maximum axis length before data are internally rebinned.

If either axis of the input dataset exceeds this value, the tool will operate on the central maxlogicalwindow by maxlogicalwindow part of the image. It will then bin the image by 2 and perform detection on the outer box-annulus.

The original intent of the parameter (internally set to 2048) was to limit memory usage; however, given modern computing standards, a larger limit is now reasonable.

For compatibility with older versions of CIAO, users can set this value to 2048.

Parameter=bkgfile (file filetype=input default=)

A predetermined background image for the dataset. Ignored if bkgvalue is nonzero.

Parameter=bkgvalue (real default=0)

Fixed value (events/pixels) to use for the background.

A non-zero value will override the normal background estimation option and the background file option. WARNING: If this value is too low, spurious sources will be detected on the periphery of the dataset.

Parameter=bkgerrvalue (real default=0)

Error in background map or value. If unknown, set to 0.

Parameter=convolve (boolean default=no)

If "yes" detection is done using the convolution library instead of sliding cells.

The "convolution" option is slow and does not work with recursive blocking. It should be used only if outputting the signal-to-noise map is needed.

Parameter=snrfile (file filetype=output default= autoname=yes)

The convolve option produces pixel-by-pixel map of the signal to noise ratio in the input. It is output to this file (only set this parameter when convolve is "yes").

If auto-naming is used, the output file will have the suffix "_snr".

Parameter=verbose (integer default=0 min=0 max=5)

verbosity of log output: 0-5

(0 - no log output, 5 -a lot of it).

Parameter=log (boolean default=no)

If set to "no", log information will go to stderr. If set to "yes", file "celldetect.log" will be created.

Changes in CIAO 4.15

The spatial columns in the output table will now contain WCS transformation. This may mean that these virtual column names may be different from those created with previous versions of CIAO: rather than starting with EQSRC they will use the names of the WCS transformation in the input file.

Changes in CIAO 4.11

psffile parameter

celldetect now obtains information about the size of the PSF at each pixel from the user supplied psffile input image. This image, also known as a PSF map, must be the same size (dimensions) as the input image. The pixel values represent the size of the PSF at each point in the input image. The units of the image are used to scale the PSF map pixel values to the cell-size. This updates allows celldetect to use PSF information from any arbitrary telescope.

For Chandra datasets, users can use the mkpsfmap tool to create the psffile. To approximate the old celldetect PSF information, users should use an energy of 1.4967 with a fraction of 80%, for example:

mkpsfmap infile=acis.img outfile=acis.psfmap energy=1.4967 ecf=0.8

If the celldetect input image is larger than the maxlogicalwindow parameter, then celldetect will repeatedly rebin the input image and search the central part of the image. In this case, users must supply a separate psffile for each binsize. A simple way to determine the correct binning scheme is to run with a fixed cell size with verbose=2 to see the grids that are used. The PSF files are then input using a CIAO stack.

One side effect to this update is to the PSFRATIO values in the output source list. Previously the PSFRAIO was hard coded to use the 39.3% PSF information at 1.0keV. The new PSFRATIO values are obtained directly from the PSF map.

New snr_diminution parameter

For efficiency, celldetect operates by sliding the detect cell in steps of one-third of the cell size. So with a cell-size of 3, it steps 1 pixel at a time. With a cell-size of 6, it steps 2 pixels at a time, and so on. This optimization can split some sources resulting in the SNR falling below the input threshold limit and lead to missing some sources.

The snr_diminution parameter temporarily reduces the threshold. If a detect cell meets the lower threshold, then the image around the cell is re-evaluted on a finer grid. A source may then be detected if the regridded detect cell meets the original SNR criteria.

Typical values for the snr_diminution are in the 0.8-1.0 range. The algorithm will tend to detect more sources near the threshold value; but can cause the tool to run slower and may increase the number of duplicate/double detections. The default is 1.0 which disables this additional search.

Bugs

Incorrect results using PSF map, psffile, in physical pixel units.

celldetect only knows how to convert a PSF map in arcsec units to logical pixel size to match the input image. All other units are ignored and the PSF map is treated as having logical pixel size values.

If the PSF map was created with physical pixel size values, and the image was binned by any value other than 1, then the PSF map values will not be correctly converted to match the input image. This may result in a different set of source detections and|or may result in the properties of those sources, including the radii, being wrong.

Users can check the units of the PSF map pixel values using dmlist, such as

unix% dmlist mypsfmap.fits cols
--------------------------------------------------------------------------------
Columns for Image Block broad.psfmap
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   mypsfmap.fits[2613,3222] logical      Real4(2613x3222) -Inf:+Inf            
...

This example shows a PSF map with units of logical pixel size.

Autonaming of ASCII region files uses the .fits extension instead of .reg as would be expected.

In general, autonaming only works for simple cases.

Caveats

RA_ERR and DEC_ERR values near poles

The RA_ERR and DEC_ERR values are approximations and become increasing inaccurate the closer to the poles, DEC=+/-90.

Users may also see incorrect values for these errors for RA values very near 0|360 such that the error bar crosses the boundary and wraps around.

Workaround:

The X_ERR and Y_ERR values in physical pixels is correct. Users can use these together with the known plate scale to compute their own error estimates.

See Also

tools::background

create_bkg_map

tools::detect

vtpdetect, wavdetect, wrecon, wtransform

tools::gratings

tgdetect, tgidselectsrc, tgmatchsrc

tools::region

rank_roi, regphystocel, roi, splitroi