Subsections


14. wavdetect Parameters & Data Products Reference

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


14.1 Default Parameter File

unix% plist wavdetect

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

#
#   parameter file for wavdetect
#
#
#   input
#
        infile =                  Input file name
#
#   output
#
       outfile =                  Output source list file name
     scellfile =                  Output source cell image file name
     imagefile =                  Output reconstructed image file name
   defnbkgfile =                  Output normalized background file name
#
#   scales
#
        scales = 2.0 4.0          wavelet scales (pixels)
      (regfile = )                ASCII regions output file
#
#   output options
#
      (clobber = no)              Overwrite existing outputs?
       (kernel = default)         Output file format (fits|iraf|default)
     (ellsigma = 3.0)             Size of output source ellipses (in sigmas)
     (interdir = .)               Directory for intermediate outputs
#
#########################################################################
#
#   wtransform parameters
#
#
#   optional input
#
     (bkginput = )                Input background file name
  (bkgerrinput = no)              Use bkginput[2] for background error
#
#   output info
#
  (outputinfix = )                Output filename infix
#
#   output content options
#
    (sigthresh = 1e-06)           Threshold significance for output source pixel list
 (bkgsigthresh = 0.001)           Threshold significance when estimating bkgd only
#
#   exposure info
#
      (exptime = 0)               Exposure time (if zero, estimate from map itself
      (expfile = )                Exposure map file name (blank=none)
    (expthresh = 0.1)             Minimum relative exposure needed in pixel to analyze it
#
#   background
#
      (bkgtime = 0)               Exposure time for input background file
#
#   iteration info
#
      (maxiter = 2)               Maximum number of source-cleansing iterations
     (iterstop = 0.0001)          Min frac of pix that must be cleansed to continue
#
#   end of wtransform parameters
#
########################################################################
########################################################################
#
#   wrecon parameters
#
#
#   PSF size parameters
#
      (xoffset = INDEF)           Offset of x axis from optical axis
      (yoffset = INDEF)           Offset of y axis from optical axis
        (eband = 1.4967)          Energy band
      (eenergy = 0.393)           Encircled energy of PSF
     (psftable = ${ASCDS_CALIB}/psfsize20010416.fits -> /soft/ciao/data/psfsize20010416.fits) Table of PSF size data
#
#   end of wrecon parameters
#
########################################################################
#
#   run log verbosity and content
#
          (log = no)              Make a log file?
      (verbose = 0)               Log verbosity
#
#   mode  
#
         (mode = ql)


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


14.3 Data Product Descriptions

Source List File (outfile )

The primary output of wavdetect 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
DEC deg Source declination
RA_ERR deg Source right ascension error
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
NPIXSOU pixel Pixels in source region
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 background counts
NET_RATE   Source count rate (count/exposure map units)
NET_RATE_ERR   Source count rate error
BKG_RATE   Background count rate (count/exposure map unit)
BKG_RATE_ERR   Background count rate error
EXPTIME   Effective exposure map value (exposure map unit)
EXPTIME_ERR   Effective exposure map error
SRC_SIGNIFICANCE   Source significance
PSF_SIZE pixel Estimated size of PSF
MULTI_CORREL_MAX   1 if source contains 2+ correl maxima
SHAPE   Shape of source region
R[2]   Radii of source region
ROTANG deg Rotation angle of source region
PSFRATIO   The ratio of the equivalent sigma of the count distribution to the PSF_SIZE
COMPONENT   Source number

Source cells are arbitrarily shaped groups of pixels within which source properties are estimated. A given source's cell is constructed by: (1) estimating the PSF size; (2) choosing the source counts image created using a smoothing scale closest to that PSF size; and (3) going to the source's location in that image, where the image amplitude is positive, and determining the closest zero-amplitude contour around that point. (If there is a saddle point in the source counts distribution closer than the zero-point in a particular direction, then the saddle point is used to define the contour.) Pixels within that contour constitute the source cell.

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 11, Section 11.2.2:

unix% more example2_out.reg 
ellipse(251.973913,268.647826,14.517026,8.139225,102.509720)
ellipse(251.878641,309.131068,8.314850,7.646153,26.671946)
ellipse(251.925620,320.471074,8.546168,7.646372,90.888733)
.
.
.

Log File (logfile )

If log is set to yes, then the files wrecon.log and wtransform.log are created.

The log files from the example in Chapter 11, Section 11.2.2:

unix% more wrecon.log 
reading data image
Input image file: data/datasetA_acis_img.fits[123:630,109:614]
Input correlation maxima stack: ./wd_srclist_stk
.
.
.

unix% more wtransform.log
input file: data/datasetA_acis_img.fits[123:630,109:614]
exposure file: 
correlation maxima output stack: ./wd_srclist_stk
correlation image output stack: ./wd_correl_stk
.
.
.

Source Cell Image File (scellfile )

The source cell image shows which pixels are used in the computation of properties for each detected source. The value for each pixel is either 0 (not a source pixel) or an integer (corresponding to a particular numbered source in the source list, i.e. a pixel value "2" means that that pixel is associated with source #2). The extent of each source cell is determined by using the particular source counts image closest in size to the PSF size at the source location; see Chapter 13 for more details on /wavdetect/ theory.

Reconstructed Image File (imagefile )

The reconstructed source image is a noise-free reconstruction of the raw data using the correlation images output from wtransform . Note that the overall normalization of the source image differs from that of the raw data image, thus values in particular pixels should not be read as estimates of the number of counts in those pixels. Chapter 13 contains details on how this image is constructed.

Normalized Background File (defnbkgfile )

During its second stage, wavdetect makes one normalized background estimate from the stack of per-scale normalized backgrounds produced during the first stage. It writes this computed background to this file.

The normalized (or flat-field) background image shows the number of expected background counts in each detector pixel, if the exposure time in each pixel is constant and equal to the amount of time the field was observed.

Computationally, the normalized background is:

$\displaystyle B_{{\rm norm},i,j}~=~\frac{<NW{\ast}D'>_{i,j}}{<NW{\ast}E>_{i,j}} ,$ (14.1)

where $ NW$ represents the wavelet function with positive values reset to zero ("Negative Wavelet"), $ D'_{i,j}$ are the cleansed data in each pixel (the data with putative source counts removed), and $ E_{i,j}$ is the ratio of exposure time in each pixel to the overall observation time. $ <NW{\ast}D'>_{i,j}$ and $ <NW{\ast}E>_{i,j}$ are the correlation of the negative wavelet function with the cleansed data and exposure, respectively.

Because $ B_{{\rm norm},i,j}$ is a function of wavelet scale size, there is a distinct normalized background image output from wtransform at each chosen pair of scales ( $ \sigma_x,\sigma_y$).

cxchelp@head.cfa.harvard.edu