Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2013

URL: http://cxc.harvard.edu/ciao/ahelp/celldetect.html
AHELP for CIAO 4.9

celldetect

Context: tools

Synopsis

Use a "sliding cell" to search for sources

Syntax

celldetect infile outfile [clobber] [thresh] [findpeaks] [centroid]
[fixedcell] [xoffset] [yoffset] [eband] [eenergy] [psftable] [cellfile]
[bkgfile] [bkgvalue] [bkgerrvalue] [expstk] [ellsigma] [regfile]
[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 (psftable), and the encircled energy percentage specified by the user (eenergy). 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 count 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.

Example 1

celldetect pleiades.fits cell_output.fits

Run celldetect on the primary image in pleiades.fits, putting output in cell_output.fits.

Example 2

celldetect "pleiades.fits[events]" cell_output.fits

Run celldetect on the EVENTS block in pleiades.fits, putting output in cell_output.fits. Note the quotes are needed when using the "[]" syntax.

Example 3

celldetect pleiades.fits cell_output.fits fixedcell=9

Use a fixed-size detect cell of size 9 pixels square.

Example 4

celldetect pleiades.fits cell_output.fits regfile=celldetect.reg

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

For other celldetect examples, please see the CIAO Science Thread "Running celldetect".

Parameters

name type ftype def min max units reqd stacks autoname
infile file input         yes    
expstk file input           yes  
outfile file output         yes   yes
regfile file   none           yes
clobber boolean   no            
thresh real   3            
findpeaks boolean   yes            
centroid boolean   yes            
ellsigma real   3            
expratio real   0            
fixedcell integer   0     pixels      
xoffset integer   INDEF     pixels      
yoffset integer   INDEF     pixels      
eband real   1.4967     keV      
eenergy real   0.8            
psftable file ARD              
cellfile file output             yes
bkgfile file input              
bkgvalue real   0            
bkgerrvalue real   0            
convolve boolean   no            
snrfile file output             yes
verbose integer   0 0 5        
log boolean   no            

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 2048x2048 (TLMIN/TLMAX values of the axes), the tool will operate in "recursive blocking" mode.

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=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=eband (real default=1.4967 units=keV)

Photon energy at which to calculate the PSF (keV).

Parameter=eenergy (real default=0.8)

Percentage of PSF energy to be encircled by the detect cell. Expressed as a fraction of 1.0. A good value to use is 0.8 with the revised PSF tables (Ciao2.0). This is a key parameter for detecting off-axis sources, and users are urged to experiment with other values.

Parameter=psftable (file filetype=ARD default=)

PSF calibration file provided with release.

Users are urged to experiment with values of eenergy other than the default value of 0.8 if they wish to determine the effects of altering the functionality of the variable sized cells. The user may not specify "CALDB" as a value for this parameter.

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 this is not the same as the "psftable" parameter used by the wavdetect tool. celldetect attempts to adjust the size of the detect cell off-axis by accessing the angular radius of a circle which contains the encircled energy of the total counts for an unresolved source. wavdetect, however, uses the PSF data only to choose the appropriate scales flux maps for estimating the source intensity; it is not used in the detection process itself.

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

Bugs

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

[New] (22 Dec 2016)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
create_bkg_map, roi, splitroi, tgdetect, tgidselectsrc, tgmatchsrc, vtpdetect, wavdetect, wrecon, wtransform

Last modified: December 2013
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.