Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: 29 Dec 2016

URL: http://cxc.harvard.edu/ciao/threads/celldetect/

Running celldetect

CIAO 4.9 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: 29 Dec 2016 - Reviewed for CIAO 4.9; no changes.


Contents


Getting Started

Download the sample data: 578 (ACIS-S, 3C 295); 1522 (ACIS-I, Trapezium Cluster)

unix% download_chandra_obsid 578,1522 

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.

ObsId 578 was taken very early in the Chandra mission. As is described in the Watch Out page, data from early in the mission was not included in the bulk Repro-4 reprocessing. Therefore, before this ObsId can be used with CIAO we need to update the headers manually.

unix% r4_header_update acisf00578N003_evt2.fits 
Missing keywords 'OCLKPAIR,ORC_MODE,SUM_2X2,FEP_CCD' from event file 'acisf00578N003_evt2.fits' header.
Missing keywords 'DY_AVG,DZ_AVG,DTH_AVG' from event file 'acisf00578N003_evt2.fits' header.
unix% dmkeypar acisf00578N003_evt2.fits FEP_CCD echo+
752386

The event file header has now been updated with the necessary keywords.

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_broad_thresh.img blocks
 
--------------------------------------------------------------------------------
Dataset: s3_broad_thresh.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_broad_thresh.img &

which produces Figure 1.


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_broad_thresh.img
unix% pset celldetect outfile=s3_src.fits
unix% pset celldetect regfile=s3_src.reg
unix% celldetect
Input file (s3_broad_thresh.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_broad_thresh.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.]

[Version: full-size]

[Print media version: The detections are overlaid on the event file as green ellipses.]

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_broad_thresh.img
unix% pset celldetect outfile=s3_expmap_src.fits
unix% pset celldetect regfile=s3_expmap_src.reg
unix% pset celldetect expstk=s3_broad_thresh.expmap
unix% pset celldetect expratio=0.9
unix% celldetect
Input file (s3_broad_thresh.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_broad_thresh.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.]

[Version: full-size]

[Print media version: Detections from both runs of celldetect are shown on the data as different-colored ellipses.]

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][energy=500:7000]"
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][energy=500:7000]): 
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.]

[Version: full-size]

[Print media version: The detections are overlaid on the event file as green ellipses.]

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][energy=500:7000]"
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][energy=500:7000]):
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.]

[Version: full-size]

[Print media version: The detections are overlaid on the event file as green ellipses.]

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

[Version: full-size]

[Print media version: Detections from both recursive blocking runs are shown on the data as different-colored ellipses.]

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_broad_thresh.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_broad_thresh.img Input file
       outfile = s3_expmap_src.fits Output source list
       (expstk = s3_broad_thresh.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
25 Feb 2013 Added bpix to download_chadra_obsid list
25 Nov 2013 Review for CIAO 4.6. Added step to run r4_header_update for obsid 578.
16 Dec 2014 Reviewed for CIAO 4.7. Minor edits to file names.
29 Dec 2016 Reviewed for CIAO 4.9; no changes.


Last modified: 29 Dec 2016
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.