Running vtpdetect

CIAO 4.5 Science Threads

Overview

Synopsis:

vtpdetect uses Voronoi Tessellation and Percolation (VTP) source detection to determine individual densities, or fluxes, for every occupied pixel. The tool then analyzes the distribution of densities for significant source enhancements.

This tool finds faint, low surface brightness features, and extended sources found as single source in visually "correct" way, regardless of their actual shape.

Purpose:

To illustrate several ways to use the Detect tool vtpdetect.

Related Links:

Analysis Guide: Extended Sources
Detect manual: other examples of using this tool are available in the "Running vtpdetect" chapter.

Last Update: 3 Dec 2012 - Review for CIAO 4.5; added note about energy filter and exposure map.

Getting Started
Running vtpdetect
Including Exposure Map
Caveat: source detection and cosmic-ray afterglows
Parameter files:
- vtpdetect
- vtpdetect
History
Images

Getting Started

Download the sample data: 578 (ACIS-S, 3C 295)

unix% download_chandra_obsid 578 evt2,fov

If vtpdetect is given an image as input, it automatically creates a simulated event list from the data. For this reason, the tool should be run directly on an event list whenever possible.

Since vtpdetect assumes that the background is uniform across the field, it is best run on a single chip at a time. Here we restrict the file to the S3 (ccd_id=7) chip:

unix% dmcopy "acisf00578N003_evt2.fits[ccd_id=7,,sky=region(acisf00578_000N003_fov1.fits[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.

Figure 1: Filtered event file

[Thumbnail image: The filtered and binned event file is displayed in ds9.]

[Version: full-size]

[Print media version: The filtered and binned event file is displayed in ds9.]

Figure 1: Filtered event file

A full resolution image of the ACIS-S3 chip.

Running vtpdetect

Now we are ready to run vtpdetect. 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 vtpdetect
unix% pset vtpdetect infile=s3_evt2.fits
unix% pset vtpdetect outfile=s3_src.fits
unix% pset vtpdetect regfile=s3_src.reg 
unix% vtpdetect
Input file name (s3_evt2.fits): 
Exposure map file name (none): 
Source list output file name (s3_src.fits): 
Threshold scale factor (0:) (1): 
Max. probability of being a false source (0:1) (1e-06): 
Minimum number of events per source (0:) (10): 
Maximum number of iterations to allow (0:100) (10):

The contents of the parameter file may be checked using plist vtpdetect.

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 data with 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.

Figure 2: Simple chip S3 detections

[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

The core sources are detected as a large single region when the default parameter values are used.

Key parameters that you may wish to vary are scale and limit; each affects the detection of faint sources in different ways.

The scale affects the flux threshold used to determine whether individual events should be assigned to source photon distributions. Increasing this threshold may remove fainter sources, but will also reduce the size of detected sources. Useful values for the scale parameter range from 0.8 to 2.5. Values less than 1 will detect more faint sources at the expense of blending nearby sources into a single source; values greater than 1 tend to de-blend complex extended sources into multiple sources at the expense of detecting faint sources.

The limit parameter affects the allowed probability of false source detection based on the distribution of densities above the flux threshold. Reducing this probability may remove faint, possibly false sources, but shouldn't affect the detection of stronger sources. The default value of 10^-6 corresponds to one spurious source in a 1000x1000 pixel map.

For the sake of comparison, the results of running vtpdetect on the same event file with limit=1e-07 - a higher detection threshold/fewer possibly false sources - are shown in Figure 3 with the detection results from the first run. The red, dashed ellipses are the sources detected in the run with the higher threshold limit (s3_limit_src.reg); the green ellipses are the additional sources detected with the lower threshold (s3_src.reg). The parameter file used for this run is given here.

Figure 3: Chip S3 detections: comparing threshold limits

[Thumbnail image: Detections from both runs of vtpdetect are shown on the data as different-colored ellipses.]

[Version: full-size]

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

Figure 3: Chip S3 detections: comparing threshold limits

The red, dashed ellipses are the sources detected in the run with the higher threshold limit (s3_limit_src.reg); the green ellipses are the additional sources detected with the lower threshold (s3_src.reg).

Including Exposure Map

[New] For best results, the input event file should be filtered on energy

unix% pset vtpdetect infile="s3_evt2.fits[energy=300:7000]"

An an exposure map should be supplied. The fluximage tool can be used to create the exposure map. Unlike the other detect tools, the size of the exposure map does not need to match the size of the image, as vtpdetect does not natively use images. Therefore we recommend making an exposure map at single pixel resoluiton.

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/vtpdetect.par


#
# parameters for vtpdetect
#
#
# inputs -- can either be an image or table
#
        infile = s3_evt2.fits     Input file name
       expfile = none             Exposure map file name
#
# output
#
       outfile = s3_src.fits      Source list output file name
#
# processing parameters
#
         scale = 1                Threshold scale factor
         limit = 1e-06            Max. probability of being a false source
        coarse = 10               Minimum number of events per source
       maxiter = 10               Maximum number of iterations to allow
#
# SAOImage regions
# 
      (regfile = s3_src.reg)      name for ASCII output region files
     (ellsigma = 3)               Size of output source ellipses (in sigmas)
         (edge = 2)               How close to edge of field to reject events
      (superdo = no)              Perform Super Voronoi Cell procedure
#
# probably use defaults for these...
#
   (maxbkgflux = 0.8)             Maximum normalized background flux to fit
   (mintotflux = 0.8)             Minimum total flux fit range
   (maxtotflux = 2.6)             Maximum total flux fit range
    (mincutoff = 1.2)             Minimum total flux cutoff value
    (maxcutoff = 3)               Maximum total flux cutoff value
       (fittol = 1e-06)           Tolerance on Possion fit
     (fitstart = 1.5)             Initial background fit starting scale factor
#
# user setable parameters 
#
      (clobber = no)              Overwrite if file exists
      (verbose = 0)               Debug level
      (logfile = stderr)          Debug file name
#
# mode
#
         (mode = ql)


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


#
# parameters for vtpdetect
#
#
# inputs -- can either be an image or table
#
        infile = s3_evt2.fits     Input file name
       expfile = none             Exposure map file name
#
# output
#
       outfile = s3_limit_src.fits Source list output file name
#
# processing parameters
#
         scale = 1                Threshold scale factor
         limit = 1e-07            Max. probability of being a false source
        coarse = 10               Minimum number of events per source
       maxiter = 10               Maximum number of iterations to allow
#
# SAOImage regions
# 
      (regfile = s3_limit_src.reg) name for ASCII output region files
     (ellsigma = 3)               Size of output source ellipses (in sigmas)
         (edge = 2)               How close to edge of field to reject events
      (superdo = no)              Perform Super Voronoi Cell procedure
#
# probably use defaults for these...
#
   (maxbkgflux = 0.8)             Maximum normalized background flux to fit
   (mintotflux = 0.8)             Minimum total flux fit range
   (maxtotflux = 2.6)             Maximum total flux fit range
    (mincutoff = 1.2)             Minimum total flux cutoff value
    (maxcutoff = 3)               Maximum total flux cutoff value
       (fittol = 1e-06)           Tolerance on Possion fit
     (fitstart = 1.5)             Initial background fit starting scale factor
#
# user setable parameters 
#
      (clobber = no)              Overwrite if file exists
      (verbose = 0)               Debug level
      (logfile = stderr)          Debug file name
#
# mode
#
         (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
12 Dec 2005	updated for CIAO 3.3: updated files in detect data tarfile
01 Dec 2006	reviewed for CIAO 3.4: no changes
16 Jan 2008	updated for CIAO 4.0: ds9 now automatically looks for the "`[SRCLIST]`" extension in the region file, so it doesn't have to be specified; `kernel` parameter removed from `vtpdetect`; removed data tarfile
16 Apr 2008	added Source Detection and Cosmic-Ray Afterglows caveat
12 Jan 2009	updated for CIAO 4.1: images are inline
27 Jan 2010	reviewed for CIAO 4.2: DS9 images updated with results
12 Jan 2011	reviewed for CIAO 4.3: no changes
09 Jan 2012	reviewed for CIAO 4.4: updated to use the full ACIS-S3 chip instead of a 512x512 region.
03 Dec 2012	Review for CIAO 4.5; added note about energy filter and exposure map.