Skip to the navigation links
Last modified: 29 Jan 2010
Where are the PDFs?

Running celldetect

CIAO 4.2 Science Threads



Overview

Last Update: 29 Jan 2010 - reviewed for CIAO 4.1: images no changes

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.

Read this thread if:

if you want to detect sources in an ACIS or HRC observation. This tool works well in simple fields with well-separated point sources.

Related Links:




Contents



Getting Started

Sample ObsIDs used: 578 (ACIS-S, 3C 295); 1522 (ACIS-I, Trapezium Cluster)

File types needed: evt2; asol1

For the first three examples, we are interested only in data on the S3 (ccd_id=7) chip of ObsID 578:

unix% dmcopy "acisf00578N002_evt2.fits[EVENTS][ccd_id=7]" s3_evt2.fits

The event list may be viewed in ds9:

unix% ds9 s3_evt2.fits &

Figure 1 shows the filtered dataset.

[Thumbnail image: The S3 chip from the event file for ObsID 578 is displayed in ds9.]

[Version: full-size]

[Print media version: The S3 chip from the event file for ObsID 578 is displayed in ds9.]

Figure 1: Filtered event file (ObsID 578)

The event file is displayed at a blocking factor of 2.

Note that the current maximum size allowed for an image is 2048x2048, but an event list may occupy a larger spatial region. See the Using Recursive Blocking section for more information.



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_evt2.fits
unix% pset celldetect outfile=s3_src.fits
unix% pset celldetect regfile=s3_src.reg
unix% celldetect
Input file (s3_evt2.fits): 
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_evt2.fits &

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 sources 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 used in this example was created by following the ACIS Exposure Map (Single Chip) thread. For the purpose of illustration, we used a monochromatic instrument map of 0.71 keV. When creating your own exposure map, be sure that the exposure map and input image are congruent (i.e. same size, image center, and binning factor).

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.

First, create an image to use as the input file:

unix% dmcopy \
      "acisf00578N002_evt2.fits[ccd_id=7][bin x=3500:4900:1,y=3650:5100:1]" \
      s3_image.fits

then, run the tool:

unix% punlearn celldetect
unix% pset celldetect infile=s3_image.fits
unix% pset celldetect outfile=s3_expmap_src.fits
unix% pset celldetect regfile=s3_expmap_src.reg
unix% pset celldetect expstk=s3_0.71keV_expmap.fits
unix% pset celldetect expratio=0.9
unix% celldetect
Input file (s3_image.fits): 
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_image.fits &

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

Remember that only the results in the ASCII region file (regfile) are affected by the exposure map.


Using Recursive Blocking

As mentioned before, an event list may occupy a larger spatial region than the maximum image size (2048x2048). In such a case, 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.

Here 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 acisf01522N003_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="acisf01522N003_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 (acisf01522N003_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 acisf01522N003_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 following the Compute Multiple Chip ACIS Exposure Map and Fluxed Image Step-by-Step thread. The thread will need to be repeated for each blocking factor (typically 1, 2, and 4).

Once you have created the exposure maps, run celldetect on the ACIS-I chips:

unix% punlearn celldetect
unix% pset celldetect infile="acisf01522N003_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 (acisf01522N003_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.

DM syntax was once again used to specify only the chips of interest. The exposure maps are input to the expstk parameter; note the stack syntax (@) used with the list file.

The purpose of the expratio parameter is explained in the With an Exposure Map section.

Display the event data with the source detections overlaid:

unix% ds9 acisf01522N003_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 limitations of the current tools and describes analysis tips to help eliminate more of the afterglows.




Parameters for /home/username/cxcds_param/celldetect.par


(comment lines have been omitted)

        infile = s3_evt2.fits     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_image.fits    Input file
       outfile = s3_expmap_src.fits Output source list
       (expstk = s3_0.71keV_expmap.fits) 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.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_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.1: images no changes

Return to Threads Page: Top | All | Imag

Where are the PDFs?
Last modified: 29 Jan 2010