Running vtpdetect

Getting Started

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

[Version: full-size]

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

[Version: full-size]

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

[Version: full-size]

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.

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

[Version: full-size]

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.