CIAO 4.14 Science Threads
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.
To illustrate several ways to use the Detect tool vtpdetect.
- Analysis Guide: Extended Sources
Detect manual: other examples of using this tool are available in the "Running vtpdetect" chapter.
Last Update: 17 Feb 2022 - Review for CIAO 4.14. Updated to use new obsid.
- Getting Started
- Running vtpdetect
- Include Exposure Maps
- Caveat: source detection and cosmic-ray afterglows
- Parameter files:
Download the sample data: 2254 (ACIS-S, 3C 295)
unix% download_chandra_obsid 2254
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
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
To better understand the seemingly spurious ellipses, the actual vtpdetect polygons can be dispalyed as shown in Figure 3
Figure 3: vtpdetect polygons
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.
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
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)
|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.|