Last modified: 17 Feb 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/vtpdetect/

Running vtpdetect

CIAO 4.16 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:

Last Update: 17 Feb 2022 - Review for CIAO 4.14. Updated to use new obsid.


Contents


Getting Started

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

unix% chandra_repro 2254 2254/repro

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 ACIS-I array and restrict the energy range to 0.5 to 7.0 keV.

unix% dmcopy "acisf02254_000N003_fov1.fits[ccd_id=0:3]" acisf02254.fov
unix% dmcopy "acisf02254_repro_evt2.fits[ccd_id=0:3,energy=500:7000,sky=region(acisf02254.fov)]" acisf02254_evt2.fits

The event list may be viewed in ds9:

unix% ds9 acisf02254_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-acisf02254 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=acisf02254_evt2.fits
unix% pset vtpdetect outfile=acisf02254_src.fits
unix% vtpdetect
Input file name (acisf02254_evt2.fits): 
Exposure map file name (none): 
Source list output file name (acisf02254_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 (acisf02254_src.reg) and a FITS file (acisf02254_src.fits). Both formats are fully described in the Detect manual.

To display the data with source detections overlaid:

unix% ds9 acisf02254_evt2.fits &

Load the source list from the output file (Region → Load Regions... → acisf02254_src.fits). The detections are shown in Figure 2.

Figure 2: Simple chip acisf02254 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 acisf02254 detections

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

To better understand the seemingly spurious ellipses, the actual vtpdetect polygons can be dispalyed as shown in Figure 3

Figure 3: vtpdetect polygons

[Thumbnail image: Polygon regions used by vtpdetect]

[Version: full-size]

[Print media version: Polygon regions used by vtpdetect]

Figure 3: vtpdetect polygons

The output acisf02254_src.fits file contains extensions. The first, default extension is the typical elliptical regions as shown in Figure 2. The 2nd extension, the SRC_REGION extension, are the actual polygons that vtpdetect used to extract the source properties.

unix% ds9 acisf02254_evt2.fits -region "acisf02254_src.fits[src_region]"

Zooming into the large extended object, this figure shows that vtpdetect has detected filamentry structure around the source. There are small gaps between the filaments and the main object which leads to the multiple ellipses in the previous image.

The regions with a red slash going through them are excluded regions. vtpdetect does indeed detect sources that may contain holes in them. These regions can be ignored by filtering the region file:

unix% dmcopy "acisf02254_src.fits[src_region][shape=Polygon]" \
  acisf02254_src_include_only.fits

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.


Include Exposure Maps

For best results, users should use an exposure map. As vtpdetect is optimized to find low-surface brightness extended emission, failing to account for non-uniformity in the exposure map will cause spurious detections. The exposure map can be created with the fluximage tool.

unix% fluximage acisf02254_evt2.fits acisf02254 clob+ bin=2
Running fluximage
Version: 04 November 2021

Using CSC ACIS broad science energy band.
Aspect solution pcadf02254_000N001_asol1.fits found.
Bad-pixel file acisf02254_repro_bpix1.fits found.
Mask file acisf02254_000N004_msk1.fits found.

The output images will have 1367 by 1368 pixels, pixel size of 0.984 arcsec,
    and cover x=2786.5:5520.5:2,y=2760.5:5496.5:2.

Running tasks in parallel with 4 processors.
Creating 4 aspect histograms for obsid 2254
Creating 4 instrument maps for obsid 2254
Creating 4 exposure maps for obsid 2254
Combining 4 exposure maps for obsid 2254
Thresholding data for obsid 2254
Exposure-correcting image for obsid 2254

The following files were created:

 The clipped counts image is:
     acisf02254_broad_thresh.img

 The observation FOV is:
     acisf02254.fov

 The clipped exposure map is:
     acisf02254_broad_thresh.expmap

 The exposure-corrected image is:
     acisf02254_broad_flux.img

A binsize of 2 was used to provide sufficent detail in the exposure map.

[NOTE]
Exposure Map?

Unlike the other detect tools: celldetect and wavdetect, vtpdetect works from an event file, not an image. Therefore it is unquie in that while celldetect and wavdetect require the exposure map be the same image size as the input image, the exposure map input to vtpdetect can be an arbitrary size. The finer the resolution (larger the expsoure map) the better fidelity in the detections, but this gives users a bit more flexibility.

This exposure map can then be input to vtpdetect and the detection repeated.

unix% pset vtpdetect expfile=acisf02254_broad_thresh.expmap
unix% pset vtpdetect outfile=acisf02254_src_with_exp.fits
unix% vtpdetect
Input file name (acisf02254_evt2.fits): 
Exposure map file name (acisf02254_broad_thresh.expmap): 
Source list output file name (acisf02254_src_with_exp.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 results are show in Figure 4 and show that with the exposure map the gaps betwen the filaments gets filled in due to the exposure variations in their vicinity.

Figure 4: vtpdetect Detections Using An Exposure Map

[Thumbnail image: comparison with detcitons w/o exposure map]

[Version: full-size]

[Print media version: comparison with detcitons w/o exposure map]

Figure 4: vtpdetect Detections Using An Exposure Map

(Left) is the usual elliptical source regions. Compared to Figure 2, there are fewer seemingly suprious ellipses. (Right) are the actual polgyon regions vtpdetect found. It looks very similar to Figure 3; however, some of the disjoint regions have been merged into the main source.


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 = )                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-acisf02254 chip instead of a 512x512 region.
03 Dec 2012 Review for CIAO 4.5; added note about energy filter and exposure map.
13 Dec 2013 Review for CIAO 4.6. Added an energy filter the event file. Added section on using the exposure map. Added examples showing how to use the polygon regions to understand the origin of the seemingly suprious ellipses.
23 Dec 2014 Review for CIAO 4.7; no changes.
17 Feb 2022 Review for CIAO 4.14. Updated to use new obsid.