Subsections


8. Running vtpdetect


8.1 Key vtpdetect Parameters

This section highlights some frequently used vtpdetect parameters. Similar parameters and their description have been grouped together. Chapter 10 has information on each vtpdetect parameter in alphabetical order.

  1. Input file name (infile )

    The input FITS file can an event list or an image. CIAO Data Manipulation (DM) syntax may be used in the input file specification, as explained in Chapter 1, Section 1.3.3.

    If the input file is an image, a pseudo event list is created; events are added with a multiplicity equal to the pixel amplitude. The FITS primary array may not be a floating point array; vtpdetect only knows how to convert an image that is an integer type: byte (BITPIX=8), short (BITPIX=16), or long (BITPIX=32).

  2. Source list output file name (outfile )

    The outfile parameter is used to provide a name for the output file. The kernel parameter controls the output format; the default is for the output file to have the same format as the input file.

  3. Threshold scale factor (scale )

    scale is actually a scale factor that refers to the intensity, not the spatial size. The algorithm figures out the threshold to distinguish between background and source events, based on the area of the Voronoi cell, then the scale parameter allows the user to scale that value. If scale is left to its default value of 1, the threshold remains as calculated by the code. Setting the scale value > 1 will tend to de-blend sources while losing faint sources. Setting it < 1 will tend to blend sources while picking out fainter sources. The recommended range for this parameter is between 0.8 and 3.

  4. Maximum probability of a false source (limit )

    This parameter indicates the number of false detections per event. The user may wish to change the limit , depending on the size and population of the field. The default value is 10$ ^{-6}$; if there are significantly less than a million events, limit may be increased accordingly.

  5. Name for ASCII output region files (regfile )
    Size of output source ellipses (ellsigma )

    In addition to the output source list (outfile ), the user may choose to have an ASCII source region file written by specifying a filename in regfile parameter. If autonaming is used (i.e. "regfile=."), then the source regions output file will be named "<infile_root>_reg".

    This region file is useful for subsequent input into ds9, particularly to overlay region markers over each detection; see Chapter 1, Section 1.4 for details.

    The size of the elliptical source regions in both of the source region files is controlled via the ellsigma parameter. This parameter is a multiplicative factor applied to sigma, the standard deviation of the distribution, to scale the major and minor axes of the ellipses for each source detection. This feature is included so that the graphics overlay may be made more visible; it is does not affect the detections themselves, only the display of the regions.

    By default the value for ellsigma is 3, but a larger value is often helpful.

  6. Exposure map file name (expfile )

    vtpdetect works in fluxes, and so needs to know about significant exposure deviations in order to work properly. The provided exposure map must be a 2-D image with WCS that matches the input file (infile ).

  7. Minimum number of events per source (coarse )

    The minimum number of events required in order for a detection to be considered a real source. The default value is 10.

  8. Maximum number of iterations to allow (maxiter )

    The maximum number of iterations to be allowed in estimating the background level (default is 10). vtpdetect may enter a state where the background estimate cycles between 2 or 3 values; setting the maxiter parameter to different values in this case will allow the user to control the exit level. Note that the tool may converge before reaching maxiter .

  9. How close to the field edge to reject events (edge )

    The Voronoi tessellation at the edges is unbounded. This parameter controls how deep into the field to ignore events; the default is 2 tessellation cells.

  10. Overwrite if file exists (clobber )
    Debug level (verbose )
    Debug file name (logfile )

    vtpdetect does not not overwrite existing outputs unless clobber is set to yes.

    The verbosity of log information ranges from 0 (none) to 5 (maximum output) and is sent to STDERR (usually the screen). However, if log is set to yes, then the log information will be written to the specified filename.


8.2 Examples Using Dataset A (Simulated ACIS Data)


8.2.1 Example 1: Running vtpdetect with the Default Parameters

This first example illustrates running vtpdetect using a simulated ACIS dataset as input; see Chapter 2, Section 2.1 for further information about this dataset.


8.2.1.1 Description of the Default Parameter Functionality

As required, the user specifies the following:

  1. Input file (infile = "data/datasetA_acis_img.fits") The input file is an image of simulated Chandra data named data/datasetA_acis_img.fits.

  2. Source list output file name (outfile = "example1_out.fits") The output file is to be named example1_out.fits.

None of the parameters are changed from their default values, so:

  1. Threshold scale factor (scale = 1) The default threshold scale factor (1) is used.

  2. Maximum probability of being a false source (limit = 1e-06)

    The maximum probability of a false source detection will be 1e-06.

  3. Minimum number of events per source (coarse = 10)

    The minimum number of events per source detection is 10.

  4. Maximum number of iterations to allow (maxiter = 10)

    The maximum number of iterations allowed is 10.

  5. How close to edge of field to reject events (edge = 2)

    The edge is 2 by default.

  6. Name for ASCII output region files (regfile = none),
    Size of output source ellipses (ellsigma = 3)

    No ASCII region file will be produced. The FITS source list will contain a 3-sigma ellipse for each detection.


8.2.1.2 Setting Required Parameters

The pset tool is used to supply the required parameter values (infile and outfile ):

unix% punlearn vtpdetect
unix% pset vtpdetect infile = data/datasetA_acis_img.fits
unix% pset vtpdetect outfile = example1_out.fits

Notice that a path may be include with the filenames. Chapter 1, Section 1.3.1 has further information on manipulating parameters.


8.2.1.3 Listing Current Parameter Settings

If desired, the user may then list the current vtpdetect parameter settings with plist:

unix% plist vtpdetect

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

#
# parameters for vtpdetect
#
#
# inputs -- can either be an image or table
#
        infile = data/datasetA_acis_img.fits Input file name
       expfile = none             Exposure map file name
#
# output
#
       outfile = example1_out.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 = none)            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
       (kernel = default)         Output format
#
# mode
#
         (mode = ql)


8.2.1.4 Executing vtpdetect

To execute vtpdetect , type the name of the tool on the command line:

unix% vtpdetect
Input file name (data/datasetA_acis_img.fits): 
Exposure map file name (none): 
Source list output file name (example1_out.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): 
unix%

The parameter settings are shown in the prompt for each required parameter; these settings may be accepted by hitting the <RETURN> key or changed if desired.

Figure 8.1 shows the data with 3-sigma ellipses from the region file overlaid. Chapter 1, Section 1.4 has instructions on how to display the region file in ds9.

Figure 8.1: vtpdetect with default parameters. The ACIS-S simulated field with 3-sigma ellipses showing the vtpdetect results.
\begin{figure}\centering
\includegraphics{plots/vtp_run_dataA_ex1_fig1.ps}\end{figure}


8.2.1.5 Examining Results

The CIAO tool dmlist is used to for examine the contents of the output file. To see what blocks are in the file:

unix% dmlist example1_out.fits opt=blocks
--------------------------------------------------------------------------------
Dataset: example1_out.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SRCLIST                        Table        24 cols x 7        rows

In the SRCLIST block, there are 24 columns of information for each of the 7 detected sources (one row for each detected source). To list the names of these columns, along with brief column information:

unix% dmlist "example1_out.fits[SRCLIST]" opt=cols

--------------------------------------------------------------------------------
Columns for Table Block SRCLIST
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   RA                   deg          Real8          0:      360.0        
	Source Right Ascension
   2   RA_ERR               deg          Real8          -Inf:+Inf            
	Source Right Ascension error
   3   DEC                  deg          Real8          -90.0:       90.0    
	Source Declination
   4   DEC_ERR              deg          Real8          -Inf:+Inf            
	Source Declination error
   5   POS(X,Y)             pixel        Real8          -Inf:+Inf            
	physical coordinates
   6   X_ERR                pixel        Real8          -Inf:+Inf            
	Source X position error
   7   Y_ERR                pixel        Real8          -Inf:+Inf            
	Source Y position error
   8   SRC_AREA             pixel        Real4          -Inf:+Inf            
	Source region area
   9   NET_COUNTS           count        Real4          -Inf:+Inf            
	Net source counts
  10   NET_COUNTS_ERR       count        Real4          -Inf:+Inf            
	Error in net source counts
  11   BKG_COUNTS           count        Real4          -Inf:+Inf            
	Background counts (scaled to source cell)
  12   BKG_COUNTS_ERR       count        Real4          -Inf:+Inf            
	Error in BKG_COUNTS
  13   NET_RATE             count/s      Real4          -Inf:+Inf            
	Source count rate
  14   NET_RATE_ERR         count/s      Real4          -Inf:+Inf            
	Source count rate error
  15   BKG_RATE             count/s/pixel Real4          -Inf:+Inf            
	Background count rate
  16   BKG_RATE_ERR         count/s/pixel Real4          -Inf:+Inf            
	Background count rate error
  17   EXPTIME              s            Real4          -Inf:+Inf            
	Effective exposure time
  18   SRC_CUTOFF           count/s/pixel Real4          -Inf:+Inf            
	Source flux cutoff
  19   FSP                               Real4          0:        1.0        
	False source probability
  20   EDGE_OF_FIELD                     Int2           -                    
	Edge-of-field flag
  21   SHAPE                             String[10]                          
	Shape of source region
  22   R[2]                              Real4(2)       -Inf:+Inf            
	Radii of source region source
  23   ROTANG               deg          Real4          0:      180.0        
	Rotation angle of source region
  24   COMPONENT                         Int4           -                    
	Source Number

To further examine the contents of the output file, use dmlist to show the position and net counts of each source detection:

unix% dmlist "example1_out.fits[SRCLIST][cols X,Y, NET_COUNTS]" opt=data

--------------------------------------------------------------------------------
Data for Table Block SRCLIST
--------------------------------------------------------------------------------
 
ROW    POS(X,Y)                                 NET_COUNTS  
 
     1 (      370.7111511230,      272.2136535645)      9568.4208984375
     2 (      252.0195770264,      452.2350463867)       182.9890594482
     3 (      373.6678771973,      451.4666748047)        32.6915626526
     4 (      495.4709167480,      451.2944335938)        30.5647010803
     5 (      252.0762634277,      503.2118835449)      1037.4575195312
     6 (      374.0616760254,      502.9508361816)       172.6163940430
     7 (      495.9555969238,      504.1110839844)       146.7237854004

The graphical user interface of the CIAO tool Prism is an alternative to the command-line interface of dmlist:

unix% prism example1_out.fits &


8.2.2 Example 2: Running vtpdetect to Create Additional Output

This next example illustrates running vtpdetect using as input the same Chandra dataset from the first example (see Section 4.2.1), but with a few parameters changed from their defaults. This will cause additional output files to be produced:

In addition, the ellsigma parameter is increased to make the display of detected regions easier to see when displayed.


8.2.2.1 Setting Parameters

The input file is the same image used in the first example, and the output file is to be named example2_out.fits. We begin by setting all the parameters mentioned:

unix% punlearn vtpdetect
unix% pset vtpdetect infile = "data/datasetA_acis_img.fits"
unix% pset vtpdetect outfile = example2_out.fits
unix% pset vtpdetect regfile = example2_out.reg
unix% pset vtpdetect ellsigma = 5
unix% pset vtpdetect verbose = 3
unix% pset vtpdetect log = vtpdetect.log

A region file named example2_out.reg will be produced, and the size of the output source ellipses is increased to 5-sigma. The verbosity of log information is changed to 3 and will be recorded in vtpdetect.log.


8.2.2.2 Executing vtpdetect

unix% vtpdetect
Input file name (data/datasetA_acis_img.fits): 
Exposure map file name (none): 
Source list output file name (example2_out.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): 
unix%

The results are shown in Figure 8.2. Each detection has a 5-sigma ellipse overlay, since ellsigma was set to 5.

Figure 8.2: vtpdetect results with ellsigma=5. The ACIS-S simulated field with ellipses showing the vtpdetect results. The size of the ellipses has been increased from the default, which improves their visibility.
\begin{figure}\centering
\includegraphics*{plots/vtp_run_dataA_ex2_fig1.ps}
\end{figure}


8.2.2.3 Examining Results


8.3 Examples Using Dataset B (3C 295 on ACIS-S)


8.3.1 Example 1: Detecting Extended Emission

This first example illustrates running vtpdetect using a Chandra ACIS dataset of 3C 295 as input; see Chapter 2, Section 2.2 for further information about this dataset.

All parameters are kept at defaults, except for:


8.3.1.1 Setting Parameters

Set the parameters:

unix% punlearn vtpdetect
unix% pset vtpdetect infile = "data/acisf00578N002_evt2.fits[EVENTS][ccd_id=7][cols x,y]"
unix% pset vtpdetect outfile = example1_out.fits
unix% pset vtpdetect regfile = example1_out.reg
unix% pset vtpdetect ellsigma = 5

DM syntax is used to specify only the chip of interest for input (i.e. [ccd_id=7]); see Chapter 1, Section 1.3.3 for further information about DM syntax usage with celldetect . Note that for a FITS event list, the filter [cols x,y] must also be specified for vtpdetect .


8.3.1.2 Executing vtpdetect

unix% vtpdetect
Input file name (data/acisf00578N002_evt2.fits[EVENTS][ccd_id=7][cols x,y]): 
Exposure map file name (none): 
Source list output file name (example1_out.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): 
unix%

The results are shown in Figure 8.3.

Figure 8.3: vtpdetect on extended emission. Chip S3 (ccd_id=7) of the ACIS-S dataset of 3C 295, displayed with binning = 2; the ellipses show the celldetect results. While it appears that some detections occur within regions of the other detections, it is just a display feature caused by choosing ellsigma greater than 1. Comparing these results with those obtained using celldetect (Figure 4.4) shows that vtpdetect successfully detects regions of extended emission which celldetect misses.
\begin{figure}\centering
\includegraphics*{plots/vtp_run_dataB_ex1_fig1.ps}
\end{figure}


8.4 Examples Using Dataset C (3C 273 on HRC-I)


8.4.1 Example 1: Detecting Close Extended Sources

This example illustrates running vtpdetect using a Chandra HRC-I dataset of 3C 273 as input; see Chapter 2, Section 2.3 for further information about this dataset.


8.4.1.1 Setting Parameters

Set the usual parameters:

unix% punlearn vtpdetect
unix% pset vtpdetect infile = "data/hrcf00461N003_evt2_img.fits"
unix% pset vtpdetect outfile = example1_out.fits
unix% pset vtpdetect regfile = example1_out.reg
unix% pset vtpdetect ellsigma = 5


8.4.1.2 Executing vtpdetect

unix% vtpdetect
Input file name (data/hrcf00461N003_evt2_img.fits): 
Exposure map file name (none): 
Source list output file name (example1_out.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): 
unix%

The results are shown in Figure 8.4.

Figure 8.4: Detecting close extended sources with vtpdetect. The HRC-I dataset of 3C 273, with ellipses showing the vtpdetect results.
\begin{figure}\centering
\includegraphics*{plots/vtp_run_dataC_ex1_fig1.ps}\end{figure}

cxchelp@head.cfa.harvard.edu