10. vtpdetect Parameters & Data Products Reference

This chapter lists all the vtpdetect parameters in alphabetical order for quick reference. In addition, a guide to the data products output by vtpdetect is provided.

10.1 Default Parameter File

unix% plist vtpdetect

Parameters for /soft/ciao/param/vtpdetect.par

#
# parameters for vtpdetect
#
#
# inputs -- can either be an image or table
#
        infile =                  Input file name
       expfile = none             Exposure map file name
#
# output
#
       outfile =                  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)

10.2 Parameter Descriptions

In the following parameter descriptions, "required=yes" indicates that the user must provide a value for the indicated parameter (e.g. infile) before the program will run. Also, the empty string (" ") is equivalent to the string none for filenames.

• clobber
  Overwrite if file exists
  type=boolean
  def=no
  

  Replace output file if it already exists?

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

• coarse
  Minimum number of events per source
  type=integer
  def=10
  min=1

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

  If the field is heavily populated, there will be more occurrences of statistical fluctuations for which a given number of events are close to each other. It is advisable to increase the value of coarse to suppress false detections for such fields. Conversely, for extremely sparse (i.e. low background) applications, coarse can be decreased.

• edge
  How close to edge of field to reject events
  type=integer
  def=2

  Specifies how deep into the field to ignore events.

  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.

• ellsigma
  Size of output source ellipses (in sigmas)
  type=real
  def=3.0

  The size, in sigmas, to make the elliptical source detection regions.

  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.

  The distribution is defined as the distribution of counts within the source cell (i.e. the observed counts), and is assumed to be Gaussian. Thus, if ellsigma is 1, then the elliptical source region will contain 39.3% of the source counts (i.e. the 1-sigma point for a 2-D Gaussian).

  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.

• expfile
  Exposure map file name
  type=string
  filetype=input
  def=none

  The name of an input exposure map file.

  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 ).

• fitstart
  Initial background fit starting scale factor
  type=real
  def=1.5
  min=0.9
  max=2.0

  The initial guess at Poisson fit.

  This value is used as the first guess at where to separate background from source events. It is the normalized inverse area; values larger than this "flux cutoff" are classified as source events and smaller values are considered to belong to the background distribution.

  The default value is adequate for most analyses.

• fittol
  Tolerance on Possion fit
  type=real
  def=1.0E-6

  The fit tolerance on Poisson fit.

  The default value is adequate for most analyses.

• infile
  Input file name
  type=string
  filetype=input
  required=yes

  The name of the input file.

  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).

• kernel
  Output format
  type=string
  def=default

  The format for the output file.

  The kernel parameter controls the output format (default, fits, or iraf); the default is for the output file to have the same format as the input file.

• limit
  Max. probability of being a false source
  type=real
  def=1.0E-6
  min=0.0
  max=1.0

  Maximum probability of a false source per number of background events.

  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.

• logfile
  Debug file name
  type=string
  filetype=output
  def=STDOUT

  The name of an output log file.

  The verbosity of log information 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.

• maxbkgflux
  Maximum normalized background flux to fit
  type=real
  def=0.8

  The maximum normalized background flux level to fit with the cumulative Poisson distribution.

  This parameter is one of several which limits the search for the inverse area (i.e. "flux") value for either the total background flux or the cutoff point where the cumulative distribution of inverse areas of the data departs from that expected of a Poisson distributed background.

  The default value is adequate for most analyses; in rare instances, the user might want to widen or lessen these intervals.

• maxcutoff
  Maximum total flux cutoff value
  type=real
  def=3

  The maximum absolute normalized flux level to find background cutoff.

  This parameter is one of several which limits the search for the inverse area (i.e. "flux") value for either the total background flux or the cutoff point where the cumulative distribution of inverse areas of the data departs from that expected of a Poisson distributed background.

  The default value is adequate for most analyses; in rare instances, the user might want to widen or lessen these intervals.

• maxiter
  Maximum number of iterations to allow
  type=integer
  def=10
  min=1

  The maximum number of iterations to be allowed in estimating the background level.

  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 .

• maxtotflux
  Maximum total flux fit range
  type=real
  def=2.6

  The maximum normalized total flux level to fit with a parabola.

  This parameter is one of several which limits the search for the inverse area (i.e. "flux") value for either the total background flux or the cutoff point where the cumulative distribution of inverse areas of the data departs from that expected of a Poisson distributed background.

  The default value is adequate for most analyses; in rare instances, the user might want to widen or lessen these intervals.

• mincutoff
  Minimum total flux cutoff value
  type=real
  def=1.2

  The minimum absolute normalized flux level to find background cutoff.

  This parameter is one of several which limits the search for the inverse area (i.e. "flux") value for either the total background flux or the cutoff point where the cumulative distribution of inverse areas of the data departs from that expected of a Poisson distributed background.

  The default value is adequate for most analyses; in rare instances, the user might want to widen or lessen these intervals.

• mintotflux
  Minimum total flux fit range
  type=real
  def=0.8

  The minimum normalized total flux level to fit with parabola.

  This parameter is one of several which limits the search for the inverse area (i.e. "flux") value for either the total background flux or the cutoff point where the cumulative distribution of inverse areas of the data departs from that expected of a Poisson distributed background.

  The default value is adequate for most analyses; in rare instances, the user might want to widen or lessen these intervals.

• mode
  def=ql

  The mode defines how to handle querying for parameters. For example, setting the mode to "h'' means that no prompting will occur; this is useful when running the tool from a script. See "ahelp parameter'' for more information and a list of all the available modes.

• outfile
  Source list output file name
  type=string
  filetype=output
  required=yes

  The name of the output file.

  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.

• regfile
  Name for ASCII output region files
  type=string

  The name of an ASCII source region output file.

  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 contains the location and size of the principal axes, for each detected source elliptical region. The elliptical region size is such that the region contains some fraction of the source counts. The parameter ellsigma specifies the desired source count fraction.

  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.

• scale
  Threshold scale factor
  type=real
  def=1.0
  min=0

  The background flux cutoff 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.

• superdo
  Perform Super Voronoi Cell procedure
  type=boolean
  def=no

  Whether to perform the super Voronoi cell update algorithm at the end of the program.

  Since this is a time-consuming and uncalibrated routine, this is optional.

  After the final iteration, the Voronoi tessellation is computed from just the set of source pixel locations and the edge pixel locations (to constrain the tessellation). To better account for flux in the wings of a source profile, the total flux is taken to be the total flux contained in these "super" Voronoi cells around each source. Then the background is estimated from this larger source area.

  This option is currently implemented, but is not well-tested. The output is printed only to STDOUT, appearing between the lines that have "BEFORE" and "AFTER" comments.

• verbose
  Debug level
  type=integer
  def=0
  min=0
  max=5

  The verbosity of log output.

  The verbosity of log information ranges from 0 (none) to 5 (maximum output).

  Setting verbose to 4 or 5 can produce hundreds of pages of output; use these values only if necessary to diagnose a problem during the percolation.

10.3 Data Product Descriptions

Source List File (outfile )

The primary output of vtpdetect is the FITS file of source detections. The following properties are recorded in the output file:

Data item	Unit	Description
RA	deg	Source Right Ascension
RA_ERR	deg	Source Right Ascension error
DEC	deg	Source Declination
DEC_ERR	deg	Source Declination error
POS(X,Y)	pixel	Physical coordinates
X_ERR	pixel	Source X position error
Y_ERR	pixel	Source Y position error
SRC_AREA	pixel	Source region area
NET_COUNTS	count	Net source counts
NET_COUNTS_ERR	count	Error in net source counts
BKG_COUNTS	count	Background counts (scaled to source cell)
BKG_COUNTS_ERR	count	Error in BKG_COUNTS
NET_RATE	count/s	Source count rate
NET_RATE_ERR	count/s	Source count rate error
BKG_RATE	count/s/pixel	Background count rate
BKG_RATE_ERR	count/s/pixel	Background count rate error
EXPTIME	s	Effective exposure time
SRC_CUTOFF	count/s/pixel	Source flux cutoff
FSP		False source probability
EDGE_OF_FIELD		Edge-of-field flag
SHAPE		Shape of source region
R[2]		Radii of source region
ROTANG	deg	Rotation angle of source region
COMPONENT		Source number

• RA, DEC:
  Right ascension and declination coordinates, corresponding to X and Y. Calculated only if WCS keywords are present in the data, otherwise filled with zeros.

• RA_ERR, DEC_ERR:
  RA and DEC errors, corresponding to X_ERR and Y_ERR.

• POS(X,Y):
  Location of the source detection.

• X_ERR, Y_ERR:
  Uncertainties on source detection location.

• SRC_AREA:
  The geometric area of the sum of the Voronoi cells that comprise the source, in units of image pixels.

• NET_COUNTS:
  Net source counts.

• NET_COUNTS_ERR:
  Net source counts corresponding error.

• BKG_COUNTS:
  Background counts.

• BKG_COUNTS_ERR:
  Background counts corresponding error.

• NET_RATE:
  Source count rate: the NET_COUNTS divided by EXPTIME.

• NET_RATE_ERR:
  Source count rate corresponding error: the NET_COUNTS_ERR divided by EXPTIME.

• BKG_RATE:
  Background count rate: the BKG_COUNTS divided by EXPTIME.

• BKG_RATE_ERR:
  Background count rate corresponding error: the BKG_COUNTS_ERR divided by EXPTIME.

• EXPTIME:
  Effective exposure time, taken from the exposure map.

• SRC_CUTOFF:
  The flux cutoff determined for the source.

• FSP:
  False source probability, i.e. the probability that the detection is not a real source.

• EDGE_OF_FIELD:
  Indicates whether any of the the Voronoi cells were at the edge of the field; in this case, it is possible that flux was lost.

• SHAPE:
  The shape of region output to the ASCII source region file; ellipse by default.

• R[2]:
  The estimated semi-major and semi-minor axis lengths (i.e. the x and y radius lengths in pixels, before rotation). For SHAPE = ellipse, this is ellsigma times the axis lengths.

• ROTANG:
  The counterclockwise angle between the semi-minor axis (see R) and the y-axis of the image, in degrees.

• COMPONENT:
  The number assigned to the detected source. Its primary use is for filtering of the source list by CIAO tools (e.g. "component=1:10", "component=1,2,5").

ASCII Source Region File (regfile )

In addition to the source list file (outfile ), the user may also select to have a source region file (regfile ) output.

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 source region file from the example in Chapter 8, Section 8.2.2:

unix% more example2_out.reg
physical
ellipse(370.711151,272.213654,519.869385,173.405792,0.867785)
ellipse(252.019577,452.235046,18.365868,15.496613,115.604019)
ellipse(373.667877,451.466675,11.422175,5.275846,167.176056)
.
.
.

Log File (logfile )

If log is set to yes, then the log information will be written to the file indicated (vtpdetect.log in this example).

The log file from the example in Chapter 8, Section 8.2.2:

unix% more vtpdetect.log 
DEBUG: Version information -
DEBUG:     vtpdetect: 0.5.1
DEBUG:     datamodel : 1.99
DEBUG:     ascfit    : 2.2
.
.
.