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

Running vtpdetect

CIAO 4.2 Science Threads



Overview

Last Update: 27 Jan 2010 - reviewed for CIAO 4.2: DS9 images updated with results

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.

Purpose:

To illustrate several ways to use the Detect tool vtpdetect.

Read this thread if:

if you want to detect sources in an ACIS or HRC observation. This tool finds faint, low surface brightness features, and extended sources found as single source in visually "correct" way, regardless of their actual shape.

Related Links:




Contents



Getting Started

Sample ObsID used: 578 (ACIS-S, 3C 295)

File types needed: evt2

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 the time vtpdetect takes to run increases with the number of events, first try the program on a low-density event list. Here we restrict the file to a 512x512 section of the S3 (ccd_id=7) chip:

unix% dmcopy "acisf00578N002_evt2.fits[EVENTS][ccd_id=7,x=3848:4360,y=3860:4372]" s3_evt2.fits

Don't limit the region area too much, since vtpdetect relies on the background information to make good source detections.

The event list may be viewed in ds9:

unix% ds9 s3_evt2.fits &

Figure 1 shows the filtered dataset.

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

[Version: full-size]

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

Figure 1: Filtered event file

The event file used in this thread is filtered to 512 square pixels.


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.

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

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



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/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

Return to Threads Page: Top | All | Imag

Where are the PDFs?
Last modified: 27 Jan 2010