Next: 9. vtpdetect Theory Up: The Detect Reference Manual Previous: 7. celldetect Parameters & Contents
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.
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).
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.
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.
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
; if
there are significantly less than a million events,
limit may be increased accordingly.
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.
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 ).
The minimum number of events required in order for a detection to be considered a real source. The default value is 10.
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 .
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.
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.
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.
As required, the user specifies the following:
None of the parameters are changed from their default values, so:
The maximum probability of a false source detection will be 1e-06.
The minimum number of events per source detection is 10.
The maximum number of iterations allowed is 10.
The edge is 2 by default.
No ASCII region file will be produced. The FITS source list will contain a 3-sigma ellipse for each detection.
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.
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)
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.
 |
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 &
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.
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.
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.
 |
unix% dmlist example2_out.fits opt=blocks
--------------------------------------------------------------------------------
Dataset: example2_out.fits
--------------------------------------------------------------------------------
Block Name Type Dimensions
--------------------------------------------------------------------------------
Block 1: PRIMARY Null
Block 2: SRCLIST Table 24 cols x 7 rows
The SRCLIST block looks the same as Example 8.2.1: 24 columns of information for each of the 7 detected sources.
unix% more vtpdetect.log DEBUG: Version information - DEBUG: vtpdetect: 0.5.1 DEBUG: datamodel : 1.99 DEBUG: ascfit : 2.2 DEBUG: DEBUG: Parameters - DEBUG: For input - DEBUG: infile = data/datasetA_acis_img.fits DEBUG: expmap = none DEBUG: DEBUG: For output - DEBUG: outfile = example2_out.fits DEBUG: (clobber = no) DEBUG: (kernel = default) . .
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:
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 .
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.
 |
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.
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
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.
 |