Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/wrecon.html
AHELP for CIAO 4.2

wrecon

Context: tools

Synopsis

Combine wavelet transform coefficients into sources

Syntax

wrecon infile sourcefile scellfile imagefile correl nbkg srclist
defnbkgfile fluxfile [clobber] [regfile] [ellsigma] [outputinfix]
[xscales] [yscales] [fluxscales] [bkginput] [bkgerrinput] [exptime]
[bkgtime] [expfile] [expthresh] [xoffset] [yoffset] [eband] [eenergy]
[psftable] [stall] [log] [verbose]

Description

`wrecon' generates a source list from the information output by wtransform at each wavelet scale [correlation maxima tables, normalized (flat-field) background images (with errors), and correlation images]. Each correlation maximum is tested to see if it represents an independent, new, source, or a source seen at other scales. For each source, a cell is computed that contains the majority of the source flux, and within that cell, source properties (location, count flux, etc.) are computed.

Note: As a stand-alone tool, `wrecon' is only intended for use by those with a thorough understanding of the wavelet detection process. Most users should use the `wavdetect' script. Running `wtransform' followed by `wrecon' provides for more flexibility (e.g. different sized Mexican Hats in the x and y directions); running `wrecon' multiple times on the same output files of `wtransfom' permits experimentation with the choice of flux scales and other parameters without redoing `wtransform'.

For a more complete description of the theory and operation of wavdetect, please see the wavdetect sections of the CIAO Detect Manual.

Example

wrecon pleiades.fits pleiades_sources.fits pleiades_scell.fits
pleiades_img.fits correl=pleiades_correl_stk.lis
nbkg=pleiades_nbkg_stk.lis srclist=pleiades_src_stk.lis
defnbkgfile=pleiades_nbkg.fits fluxfile=pleiades_flux_stk.lis
xscales="1 2 4 8 16" yscales="1 2 4 8 16" fluxscales="1 3 5"

Read a primary image from "pleiades.fits", a list of candidate source files from "pleiades_sources.lis", a list of correlation images from "pleiades_correl_stk.lis", and list of normalized background images from "pleiades_nbkg_stk.lis". All these must have come from a previous run of wtransform. Generate a source list "pleiades_sources.fits", a source cell image "source_cell.fits" a source image "image.fits", a normalized background image "background.fits", and a set of flux image files, which will be listed in "pleiades_flux_stk.lis". Fluxes will only be generated for the first, thrid, and fifth x/y scale pairs. Note that the quotes around the x/y scale lists and the flux scale list are required.

For other wavdetect examples, please see the CIAO Science Thread "Running wavdetect".

Parameters

name type ftype def min max units reqd autoname
infile file input         yes  
sourcefile file output         yes yes
scellfile file output         yes yes
imagefile file output         yes yes
regfile file             yes
clobber boolean   no          
ellsigma real   3.0          
srclist file input         yes  
correl file input         yes  
nbkg file input         yes  
bkginput file input         no  
bkgerrinput boolean   no       no  
defnbkgfile file           yes yes
fluxfile file           yes  
outputinfix file           no  
xscales string              
yscales string              
fluxscales string           no  
expfile file input         no  
exptime real   0     seconds    
expthresh float   0.1          
bkgtime real   0     seconds    
xoffset integer   INDEF          
yoffset integer   INDEF          
eband float   1.4967          
eenergy real   0.393          
psftable file ARD         yes  
stall boolean   no          
log boolean   no          
verbose integer   0 0 5      

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input data set. If not a FITS primary image, must include the extension (eg: "foo.fits[EVENTS]").

Parameter=sourcefile (file required filetype=output autoname=yes)

File containing the output source list.

If auto-naming is used (sourcefile=.), the output file will have the suffix "_src".

Parameter=scellfile (file required filetype=output autoname=yes)

File name of the image showing the source cells, which delimit the image pixels which are used to estimate source properties (e.g. count rate).

If auto-naming is used (scellfile=.), the output file will have the suffix "_scell".

Parameter=imagefile (file required filetype=output autoname=yes)

Output file containing the reconstructed, noise-free source image.

If auto-naming is used (imagefile=.), the output file will have the suffix "_image".

Parameter=regfile (file default= autoname=yes)

File for ASCII region output.

If auto-naming is used (regfile=.), the output file will have the suffix "_reg". NB: not currently operational.

Parameter=clobber (boolean default=no)

If "yes", existing outputs will be overwritten.

Parameter=ellsigma (real default=3.0)

Size, in sigmas, to make the elliptical source regions.

ellsigma 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. ellsigma affects both the outfile and the ASCII region file (regfile). This feature is included so that the graphics overlay will be more visible and under the user's control. Often a value greater than 3 is helpful.

Parameter=srclist (file required filetype=input)

File name of stack (list) of candidate source correlation maxima, output at each scale by wtransform.

Parameter=correl (file required filetype=input)

File name of stack (list) of correlation images from each wavelet scale.

Parameter=nbkg (file required filetype=input)

File name of stack (list) of normalized (i.e. flat-field) background images computed at each wavelet scale by `wtransform'. These images must include error images.

Parameter=bkginput (file not required filetype=input default=)

Pre-determined background input image.

Use a previously computed background in the specified file in place of constructing a new default normalized background. When using bkginput, enter "none" for the default normalized background file.

Parameter=bkgerrinput (boolean not required default=no)

If yes, use background error in file bkginput[2].

Parameter=defnbkgfile (file required autoname=yes)

Default normalized background file.

`wrecon' makes one normalized background estimate from the stack of per-scale normalized backgrounds produced by `wtransform'. It writes this computed background to this file. If autonaming is used (defnbkgfile=.), the file name will have the suffix "_nbkg".

Parameter=fluxfile (file required)

File name of stack (list) of flux images computed at each user-defined scale pair. (See fluxscales.)

Parameter=outputinfix (file not required)

Leave blank. This parameter controls extra text to insert in output filenames. for internal use only.

Parameter=xscales (string default=)

The input of xscales must be identical to that used in `wtransform'.

Parameter=yscales (string default=)

The input of yscales must be identical to that used in `wtransform'.

Parameter=fluxscales (string not required default=)

Which of the x, y scales should be used for flux calculations.

Nominate (with integers) the locations in the x, y scales ordered lists which should be used for flux calculations. This list, like the scales input, uses spaces for separators.

Parameter=expfile (file not required filetype=input)

Image of exposure time for dataset.

Parameter=exptime (real default=0 min= units=seconds)

Time of the exposure, in seconds. If set to zero, the program estimates the exposure time from the exposure map.

Parameter=expthresh (float default=0.1)

Relative exposure threshold.

For each pixel, a relative exposure is calculated (pixel exposure time over detector livetime). If this relative exposure is less than the parameter expthresh (typically 0.1-0.2), then the pixel in question is not analyzed.

Only affects wrecon if the expthresh specified for it if higher than that specified for wtransform; in this case, a subset of correlation maxima identified by wtransform will not be examined. (This can come into play if, for instance, one wishes to only make a source list for highly exposed areas after running wtransform on the whole image.)

Parameter=bkgtime (real default=0 min= units=seconds)

Livetime of predetermined background (in seconds).

This parameter is only used *if* the user has provided a normalized background image. A value of 0 means use the exposure time as the background time.

Parameter=xoffset (integer default=INDEF)

Offset of x-axis for the calculation of the off-axis angle.

By default (when both offsets are set to INDEF), wrecon calculates the off-axis angle using the nominal pointing of the data file as the origin. Users may change this behavior by specifying offsets to any numerical values; the offsets provide the location of the optical axis with respect to the center of the data file.

Parameter=yoffset (integer default=INDEF)

Offset of y-axis for the calculation of the off-axis angle.

Parameter=eband (float default=1.4967)

Energy, in keV, at which the PSF size should be computed.

Parameter=eenergy (real default=0.393 min= max=)

Percentage of encircled energy, expressed as a fraction of 1.0, which the PSF size (see "eband") should contain.

Percentage of encircled energy, expressed as a fraction of 1.0, which the PSF size (see "eband") should contain. Suggested values: .393 (one-sigma percentage threshold for a two-dimensional Gaussian), or 0.500. The efficiency of the algorithm is reduced if this fraction is made too high (say, 0.900) or too low.

The encircled energy fraction of the PSF is used to estimate the PSF size, in pixels, at the location of each detected source. The default value (0.393) is the one-sigma integrated volume of a normalized two- dimensional Gaussian, thus the estimated PSF size should be approximately one sigma. The PSF size is used only to select a flux image; a source cell is computed using this image, and source properties are estimated using the data within the computed cell. NB: Unlike celldetect, the PSF library and eenergy have no effect on the detection process in wavdetect.

If the value of eenergy is set too high, there is the risk that the computed source cell will contain more than one source, rendering source property estimates moot. On the other hand, if the value is set too low, then the computed cell may be too small and contain only a fraction of the source counts.

Parameter=psftable (file required filetype=ARD default=)

FITS file of psf information. File is included with the release. The user may not specify "CALDB" for this parameter.

Parameter=stall (boolean default=no)

Special mode used to rendezvous a debugger with wrecon. Leave as "no".

Parameter=log (boolean default=no)

If set to "no", log information will go to stdout. If set to "yes", file "wrecon.log" will be created.

Parameter=verbose (integer default=0 min=0 max=5)

Level of log output. 0=none 5=highest.

Bugs

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

See Also

tools
celldetect, create_bkg_map, tgdetect, tgidselectsrc, tgmatchsrc, vtpdetect, wavdetect, wtransform

Last modified: December 2009