wrecon

Synopsis

Combine wavelet transform coefficients into sources

wrecon  infile sourcefile scellfile imagefile [regfile] [clobber]
[ellsigma] [srclist] [correl] [nbkg] [bkginput] [bkgerrinput]
[defnbkgfile] [fluxfile] [outputinfix] [xscales] [yscales] [fluxscales]
[expfile] [exptime] [expthresh] [bkgtime] [psffile] [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
psffile=psfmap.fits 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. The PSF map "psfmap.fits" was generated from

mkpsfmap infile=pleiades.fits outfile=psfmap.fits energy=1.49 ecf=0.393

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

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 filetype=input)

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

Parameter=correl (file filetype=input)

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

Parameter=nbkg (file 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 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)

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=psffile (file default=)

FITS file of psf information. File is created by running the mkpsfmap tool.

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

There are no known bugs for this tool.

See Also

tools::background

create_bkg_map

tools::detect

celldetect, vtpdetect, wavdetect, wtransform

tools::gratings

tgdetect, tgidselectsrc, tgmatchsrc

tools::region

rank_roi, regphystocel, roi, splitroi