|
|
|
|
|
SynopsisUse a "sliding cell" to search for sources Syntaxcelldetect infile outfile [kernel] [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. 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. NOTES:
Example 1celldetect pleiades.fits cell_output.fits Run celldetect on the primary image in pleiades.fits, putting output in cell_output.fits. Example 2celldetect "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 3celldetect pleiades.fits cell_output.fits fixedcell=9 Use a fixed-size detect cell of size 9 pixels square. Example 4celldetect 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 "Detecting Sources in Imaging Observations - Using celldetect". Parameters
Detailed Parameter DescriptionsParameter=infile (file required filetype=input)Input image file. If the input is a primary array of image data, recursive blocking is inoperative. If the input is an event file, the tool should find the EVENTS extension but it can be specified as "foo.fits[EVENTS]". 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. The files and the stack file are generated by a script currently under development. An 'at' sign must precede the filename, e.g. expstk="@expmap.lis". 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=kernel (string default=default)The datamodel will support more than one output format (eg: "fits", "iraf"). This parameter selects among them. Use "default" to set the output kernel to be the same as that for the input file. 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)If non-zero, celldetect will use a fixed size cell of the specified dimension over the entire field of view. Set this to 0 for automatic use of the Chandra variable cellsize option using `psftable' and `eenergy'. Units are pixels. Allowed values are 1 or an integer divisible by 3. If set, This effectively disables the eenergy, x/yoffset, and eband parameters. Value must be evenly divisible by three, or equal to one. Set to 0 for normal operation. 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. NB: a revised version was released in 2000Dec (Ciao2.0). This means that parameters such as net counts, s/n, etc will be different than in previous results. Prior to 2000Dec, the PSF tables employed were provisional. The revised tables are more accurate. Notwithstanding this, 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. 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. This method is much slower at present, and should really 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. BugsSee the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs. See Also
|
 |
The Chandra X-Ray
Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA. Email: cxcweb@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2004. All rights reserved. |
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}