Running celldetect
![[CXC Logo]](../../imgs/cxc-logo.gif){kind=logo}
CIAO 4.5 Science Threads
Overview
Synopsis:
celldetect uses a sliding square detect cell whose size is matched to the instrument PSF to search for statistically significant enhancements over the background. 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.
Purpose:
To illustrate several ways to use the Detect tool celldetect. This tool works well in simple fields with well-separated point sources.
Last Update: 3 Dec 2012 - Review for CIAO 4.5
Contents
- Getting Started
- Running celldetect
- Caveat: source detection and cosmic-ray afterglows
- Parameter files:
- History
-
Images
- Figure 1: Filtered event file (ObsID 578)
- Figure 2: Simple chip S3 detections (ObsID 578)
- Figure 3: Chip S3 (ObsID 578): detections with and without an exposure map
- Figure 4: ACIS-I detections from recursive blocking (ObsID 1522)
- Figure 5: ACIS-I detections from recursive blocking with an exposure map (ObsID 1522)
- Figure 6: Comparison of recursive blocking results with and without an exposure map (ObsID 1522)
Getting Started
Download the sample data: 578 (ACIS-S, 3C 295); 1522 (ACIS-I, Trapezium Cluster)
unix% download_chandra_obsid 578,1522 evt2,asol,fov
To run this thread, we want a source image and a congruent exposure map (for the "Running wavdetect with an exposure map" section). We chose to create both by running the fluximage script. The image and exposure map may also be created by following the Single-Chip ACIS Exposure Map thread.
For the first three thread examples, a full resolution image of the ACIS-S3 (ccd_id=7) is used:
unix% fluximage "acisf00578N003_evt2.fits[ccd_id=7,sky=region(acisf00578_000N003_fov1.fits[ccd_id=7])]"\
binsize=1 bands=broad outroot=s3
unix% dmlist s3_0.5-7.0_bin1.img blocks
--------------------------------------------------------------------------------
Dataset: s3_0.5-7.0_bin1.img
--------------------------------------------------------------------------------
Block Name Type Dimensions
--------------------------------------------------------------------------------
Block 1: EVENTS_IMAGE Image Int4(1390x1389)
Block 2: GTI7 Table 2 cols x 1 rows
If the input is larger than 2048x2048, the tool will operate in "recursive blocking" mode.
To view the file, load it into ds9:
unix% ds9 s3_0.5-7.0_bin1.img &
which produces Figure 1.
![[Thumbnail image: The filtered and binned event file is displayed in ds9.]](events.png)
[Version: full-size]
Figure 1: Filtered event file (ObsID 578)
Running celldetect
A Simple Example
To run celldetect with the basic parameters set, it is necessary to specify the infile and output file names only. Note that it is not required to create an ASCII version of the region file; if the regfile parameter is left blank, it will not be used.
unix% punlearn celldetect unix% pset celldetect infile=s3_0.5-7.0_bin1.img unix% pset celldetect outfile=s3_src.fits unix% pset celldetect regfile=s3_src.reg unix% celldetect Input file (s3_0.5-7.0_bin1.img): Output source list (s3_src.fits):
The contents of the parameter file may be checked using plist celldetect.
There are two source lists created, both containing the same sources: an ASCII file (s3_src.reg) and a FITS file (s3_src.fits). Both formats are fully described in the Detect manual.
To display the image with the source detections overlaid:
unix% ds9 s3_0.5-7.0_bin1.img &
Load the source list from either file (Region → Load Regions... → s3_src.fits OR s3_src.reg). The detections are shown in Figure 2.
![[Thumbnail image: The detections are overlaid on the event file as green ellipses.]](detections.png)
[Version: full-size]
Figure 2: Simple chip S3 detections (ObsID 578)
These source detections were determined with the default parameter values.
A key parameter that you may wish to vary is thresh, the detect cell signal-to-noise (S/N) threshold; it was left at the default value of 3 in the above example. Cells whose S/N exceeds this value are identified as containing possible source candidates. Note that not all such cells will result in detected sources; if the findpeaks parameter is set to "yes" (the default), adjacent cells whose ratios exceed thresh will be combined into a single detection. Simulations indicate that values of thresh as low as ~2 may be appropriate for short, on-axis observations, but it is recommended to start with a value of 3 or 4.
With An Exposure Map
False sources may be detected in the vicinity of significant exposure variations, such as detector edges or chip gaps. To mitigate this effect, run celldetect with an exposure map.
The exposure map was created in the Get Started section by running the fluximage script with the broad energy band definition. The exposure map may also be created by following the Single-Chip ACIS Exposure Map thread.
When running the tool with an exposure map, the expratio parameter must be set. This is the ratio of the average exposure of the background frame around the detect cell to that in the cell. Detections for sources whose ratio falls below the specified value are omitted from the source regions file (regfile); all detections are present in the output source list (outfile) and the column EXPO_RATIO is created.
unix% punlearn celldetect unix% pset celldetect infile=s3_0.5-7.0_bin1.img unix% pset celldetect outfile=s3_expmap_src.fits unix% pset celldetect regfile=s3_expmap_src.reg unix% pset celldetect expstk=s3_2.3_bin1.expmap unix% pset celldetect expratio=0.9 unix% celldetect Input file (s3_0.5-7.0_bin1.img): Output source list (s3_expmap_src.fits):
The contents of the parameter file may be checked using plist celldetect.
To display the image:
unix% ds9 s3_0.5-7.0_bin1.img &
Load the source list from the region file (Region → Load Regions... → s3_expmap_src.reg). Figure 3 shows the results from both runs; the red ellipses are the results of using an exposure map and the green ellipses are the additional sources picked up when running without an exposure map.
![[Thumbnail image: Detections from both runs of celldetect are shown on the data as different-colored ellipses.]](expmap.png)
[Version: full-size]
Figure 3: Chip S3 (ObsID 578): detections with and without an exposure map
The red, dashed-line ellipses are the sources detected in the run with the exposure map (s3_expmap_src.reg); the green ellipses are the additional sources detected when running without an exposure map (s3_src.reg).
In this case, the exposure map does not make a discernable difference in the detections.
Remember that only the results in the ASCII region file (regfile) are affected by the exposure map.
Using Recursive Blocking
As mentioned before, if the input is larger than 2048x2048, celldetect automatically uses a "recursive blocking scheme": the inner 2048x2048 pixel region of the dataset is searched for sources, then the inner 4096x4096 pixel region (excluding the part already analyzed) is blocked by 2 and searched for sources, then the inner 8192x8192 is blocked by 4, etc., until TLMIN, TLMAX is reached.
For each consecutive search, the portion of the data that has already been searched for sources is excluded from the analysis. Therefore, only one blocking factor is used for each region on the dataset. Since a source could be missed if it straddles the border between regions of different blocking factors, each pass actually extends a bit into the previously-analyzed region. Occasionally this leads to two detections of the same source, but such cases are automatically identified (see the output source list columns DOUBLE and DOUBLE_ID, discussed in the "celldetect Input Parameters & Data Products Reference Chapter" of the Detect manual).
For the recursive blocking scheme to operate, the fixedcell parameter must be set to zero and point-spread-function (PSF) information must be supplied via psftable (the tool will not examine a dataset past the radius for which PSF information is available). By default, both parameters are correctly set for recursive blocking of Chandra data.
For this example, we use the level=2 event file of ObsID 1522. The DETNAM keyword shows that the four ACIS-I chips (0-3) and two ACIS-S chips (6-7) were on for this observation:
unix% dmkeypar acisf01522N004_evt2.fits DETNAM echo+ ACIS-012367
A Data Model filter is added to the input datafile so that only the ACIS-I chips are used in the analysis:
unix% punlearn celldetect unix% pset celldetect infile="acisf01522N004_evt2.fits[ccd_id=0:3]" unix% pset celldetect outfile=acisi_block_src.fits unix% pset celldetect regfile=acisi_block_src.reg unix% celldetect Input file (acisf01522N004_evt2.fits[ccd_id=0:3]): Output source list (acisi_block_src.fits):
The contents of the parameter file may be checked using plist celldetect.
To display the event data with the source detections overlaid:
unix% ds9 acisf01522N004_evt2.fits &
Load the source list from either file (Region → Load Regions... → acisi_block_src.fits OR acisi_block_src.reg). The detections are shown in Figure 4.
![[Thumbnail image: The detections are overlaid on the event file as green ellipses.]](blocking.png)
[Version: full-size]
Figure 4: ACIS-I detections from recursive blocking (ObsID 1522)
Recursive blocking allows source detection over a larger area than the maximum image size (2048x2048).
To see what recursive blocking was used on the event file, examine the BLOCK column of the FITS output file. This dmlist command gives the position of each source and the the blocking factor used at that point:
unix% dmlist "acisi_block_src.fits[cols x,y,block]" data -------------------------------------------------------------------------------- Data for Table Block SRCLIST -------------------------------------------------------------------------------- ROW POS(X,Y) BLOCK 1 ( 3868.9213483146, 4056.2996254682) 1 2 ( 3871.16250, 4059.950) 1 3 ( 3871.3913043478, 4147.8260869565) 1 . . . 614 ( 5146.50, 3300.33750) 2 615 ( 5159.5655737705, 3298.9426229508) 2 616 ( 5269.0, 3215.8529411765) 2
Using Recursive Blocking and Exposure Maps
Here we repeat the recursive blocking example with the addition of exposure maps.
One exposure map is needed to match each blocking factor that celldetect will use. Create the exposure maps by running the fluximage script, as shown in the ACIS Exposure Map (Multiple Chips) thread.
Each exposure map must be made with the binning factor used in the recursive blocking scheme (typically 1, 2, 4). The exposure map must also match the spatial region that celldetect will search at each step of recursive blocking: the exposure map binned by a factor of 1 should cover the inner 2048x2048 pixels of the image, bin factor 2 should cover the inner 4096x4096 region, and so on.
The exposure maps are input to the expstk parameter; note the stack syntax (@) used with the list file.
unix% punlearn celldetect unix% pset celldetect infile="acisf01522N004_evt2.fits[ccd_id=0:3]" unix% pset celldetect outfile=acisi_block_expmap_src.fits unix% pset celldetect regfile=acisi_block_expmap_src.reg unix% pset celldetect expstk="@expmap.lis" unix% pset celldetect expratio=0.99 unix% celldetect Input file (acisf01522N004_evt2.fits[ccd_id=0:3]): Output source list (acisi_block_expmap_src.fits):
The contents of the parameter file may be checked using plist celldetect.
Display the event data with the source detections overlaid:
unix% ds9 acisf01522N004_evt2.fits &
Load the source list from either file (Region → Load Regions... → acisi_block_expmap_src.fits OR acisi_block_expmap_src.reg). The results are shown in Figure 5. Placing these results on top of those from the recursive blocking without an exposure map example (Figure 6) shows that using an exposure map helps to eliminate spurious detections along the chip edges.
![[Thumbnail image: The detections are overlaid on the event file as green ellipses.]](blockexpmap.png)
[Version: full-size]
Figure 5: ACIS-I detections from recursive blocking with an exposure map (ObsID 1522)
Including an exposure map with the recursive blocking reduces the number of false sources in the vicinity of significant exposure variations, such as detector edges or chip gaps.
![[Thumbnail image: Detections from both recursive blocking runs are shown on the data as different-colored ellipses.]](compare.png)
[Version: full-size]
Figure 6: Comparison of recursive blocking results with and without an exposure map (ObsID 1522)
The red ellipses are the sources detected in the run with the exposure map (acisi_block_expmap_src.reg); the green ellipses are the additional sources detected when running without an exposure map (acisi_block_src.reg).
Caveat: source detection and cosmic-ray afterglows
CIAO users who are trying to detect sources of about 10 counts or less should be aware of potential confusion with cosmic-ray afterglows that have not been removed from the data.
The Cosmic-Ray Afterglows why topic explains the current processing options and the limitations of the available tools used to detect afterglows.
Parameters for /home/username/cxcds_param/celldetect.par
(comment lines have been omitted)
infile = s3_0.5-7.0_bin1.img Input file
outfile = s3_src.fits Output source list
(expstk = ) list of exposure map files
(regfile = s3_src.reg) ASCII regions file
(clobber = no) Overwrite exiting outputs?
(thresh = 3) Source threshold
(findpeaks = yes) Find local peaks?
(centroid = yes) Compute source centroids?
(ellsigma = 3) Size of output source ellipses (in sigmas)
(expratio = 0) cutoff ratio for source cell exposure variation
(fixedcell = 0) Fixed cell size to use (0 for variable cell)
(xoffset = INDEF) Offset of x axis from data center
(yoffset = INDEF) Offset of y axis from data center
(eband = 1.4967) Energy band
(eenergy = 0.8) Encircled energy of PSF
(psftable = ${ASCDS_CALIB}/psfsize20010416.fits -> /soft/ciao-4.0/data/psfsize20010416.fits) Table of PSF size data
(cellfile = ) Output cell size image stack name
(bkgfile = ) Background file name
(bkgvalue = 0) Background count/pixel
(bkgerrvalue = 0) Background error
(convolve = no) Use convolution?
(snrfile = ) SNR output file name (for convolution only)
(verbose = 0) Log verbosity level
(log = no) Make a celldetect.log file?
(mode = ql)
Parameters for /home/username/cxcds_param/celldetect.par
(comment lines have been omitted)
infile = s3_0.5-7.0_bin1.img Input file
outfile = s3_expmap_src.fits Output source list
(expstk = s3_2.3_bin1.expmap) list of exposure map files
(regfile = s3_expmap_src.reg) ASCII regions file
(clobber = no) Overwrite exiting outputs?
(thresh = 3) Source threshold
(findpeaks = yes) Find local peaks?
(centroid = yes) Compute source centroids?
(ellsigma = 3) Size of output source ellipses (in sigmas)
(expratio = 0.9) cutoff ratio for source cell exposure variation
(fixedcell = 0) Fixed cell size to use (0 for variable cell)
(xoffset = INDEF) Offset of x axis from data center
(yoffset = INDEF) Offset of y axis from data center
(eband = 1.4967) Energy band
(eenergy = 0.8) Encircled energy of PSF
(psftable = ${ASCDS_CALIB}/psfsize20010416.fits -> /soft/ciao-4.4/data/psfsize20010416.fits) Table of PSF size data
(cellfile = ) Output cell size image stack name
(bkgfile = ) Background file name
(bkgvalue = 0) Background count/pixel
(bkgerrvalue = 0) Background error
(convolve = no) Use convolution?
(snrfile = ) SNR output file name (for convolution only)
(verbose = 0) Log verbosity level
(log = no) Make a celldetect.log file?
(mode = ql)
Parameters for /home/username/cxcds_param/celldetect.par
(comment lines have been omitted)
infile = acisf01522N002_evt2.fits[ccd_id=0:3] Input file
outfile = acisi_block_src.fits Output source list
(expstk = ) list of exposure map files
(regfile = acisi_block_src.reg) ASCII regions file
(clobber = no) Overwrite exiting outputs?
(thresh = 3) Source threshold
(findpeaks = yes) Find local peaks?
(centroid = yes) Compute source centroids?
(ellsigma = 3) Size of output source ellipses (in sigmas)
(expratio = 0) cutoff ratio for source cell exposure variation
(fixedcell = 0) Fixed cell size to use (0 for variable cell)
(xoffset = INDEF) Offset of x axis from data center
(yoffset = INDEF) Offset of y axis from data center
(eband = 1.4967) Energy band
(eenergy = 0.8) Encircled energy of PSF
(psftable = ${ASCDS_CALIB}/psfsize20010416.fits -> /soft/ciao-4.0/data/psfsize20010416.fits) Table of PSF size data
(cellfile = ) Output cell size image stack name
(bkgfile = ) Background file name
(bkgvalue = 0) Background count/pixel
(bkgerrvalue = 0) Background error
(convolve = no) Use convolution?
(snrfile = ) SNR output file name (for convolution only)
(verbose = 0) Log verbosity level
(log = no) Make a celldetect.log file?
(mode = ql)
Parameters for /home/username/cxcds_param/celldetect.par
(comment lines have been omitted)
infile = acisf01522N002_evt2.fits[ccd_id=0:3] Input file
outfile = acisi_block_expmap_src.fits Output source list
(expstk = @expmap.lis) list of exposure map files
(regfile = acisi_block_expmap_src.reg) ASCII regions file
(clobber = no) Overwrite exiting outputs?
(thresh = 3) Source threshold
(findpeaks = yes) Find local peaks?
(centroid = yes) Compute source centroids?
(ellsigma = 3) Size of output source ellipses (in sigmas)
(expratio = 0.99) cutoff ratio for source cell exposure variation
(fixedcell = 0) Fixed cell size to use (0 for variable cell)
(xoffset = INDEF) Offset of x axis from data center
(yoffset = INDEF) Offset of y axis from data center
(eband = 1.4967) Energy band
(eenergy = 0.8) Encircled energy of PSF
(psftable = ${ASCDS_CALIB}/psfsize20010416.fits -> /soft/ciao-4.0/data/psfsize20010416.fits) Table of PSF size data
(cellfile = ) Output cell size image stack name
(bkgfile = ) Background file name
(bkgvalue = 0) Background count/pixel
(bkgerrvalue = 0) Background error
(convolve = no) Use convolution?
(snrfile = ) SNR output file name (for convolution only)
(verbose = 0) Log verbosity level
(log = no) Make a celldetect.log file?
(mode = ql)
History
| 03 Jan 2005 | reviewed for CIAO 3.2: no changes |
| 03 Jun 2005 | updated links for CIAO 3.2 version of Detect manual |
| 19 Dec 2005 | updated for CIAO 3.3: the acis_expmap script has been updated to version 3.3 for the new asphist tool syntax; updated files in detect data tarfile |
| 05 Jan 2006 | update to acis_expmap usage message (script functionality is unchanged) |
| 01 Dec 2006 | reviewed for CIAO 3.4: no changes |
| 16 Jan 2008 | updated for CIAO 4.0: acis_expmap script removed from the CIAO scripts package (obsolete); ds9 now automatically looks for the "[SRCLIST]" extension in the region file, so it doesn't have to be specified; kernel parameter removed from celldetect; removed data tarfile |
| 16 Apr 2008 | added Source Detection and Cosmic-Ray Afterglows caveat |
| 13 Jan 2009 | updated for CIAO 4.1: images are inline |
| 29 Jan 2010 | reviewed for CIAO 4.2: images no changes |
| 12 Jan 2011 | reviewed for CIAO 4.3: no changes |
| 15 Dec 2011 | reviewed for CIAO 4.4: use fluximage to create the image and exposure map |
| 03 Dec 2012 | Review for CIAO 4.5 |
