/ ciao4.16 / ahelp / dmfilth.html

Jump to: Description · Examples · Parameters · Changes in CIAO 4.16 · Bugs · See Also

AHELP for CIAO 4.16

dmfilth

Synopsis

Replace pixel values in source regions of an image with values interpolated from surrounding background regions

Syntax

dmfilth  infile outfile method srclist bkglist [randseed] [clobber]
[verbose]

Description

This tool replaces pixel values in a source region or stack of source regions in an input image with values interpolated from surrounding background regions. All regions are specified using standard region library syntax.

Interpolation methods

There are two different types of method for calculating the replacement pixels:

The DIST, POISSON, and GLOBAL methods randomly sample values from a probability distribution.
The POLY and BILINT methods fit a function to the data in the background region and use this fit to calculate the new pixel values.

These methods are described in more detail below.

DIST

Pixel values in the source region(s) are sampled from the distribution of pixel values in the background region(s). A single background region or stack of background regions may be used, but they must not include pixels in the source region(s).

POISSON

Pixel values in the source region(s) are sampled from the Poisson distribution whose mean is that of the pixel values in the background region. A single background region or stack of background regions may be used, but they must not include pixels in the source region(s).

GLOBAL

Pixel values in the source region(s) are sampled from the Poisson distribution whose mean is that of all pixel values not within the source regions. The bkglist parameter is not used in this method.

POLY

A 2D bi-quadratic function of the form

A1+A2(X)+A3(X^2)+A4(Y)+A5(Y^2)+A6(X)(Y)+A7(X)(Y^2)+A8(X^2)(Y)+A9(X^2)(Y^2)

is fit to the data within the background region(s), and the results are used to compute pixel values within the source region(s). Users may specify one background region that includes all source regions, or a stack of background regions with one for each source region; in either case the background region(s) must include the pixels in the source region(s).

BILINT

The value for each source region pixel is a bilinear interpolation of the form

A1+A2*X+A3*Y+A4*X*Y,

using the 4 values in the nearest background pixels in the perpendicular directions +/-45 degrees and +/-135 degrees to determine the 4 interpolation coefficients. Since only 4 pixels are used, this method may produce noticable "pattern noise" due to statistical fluctuations in regions of few counts. The bkglist parameter is not used in this method.

Examples

Example 1

dmfilth in1.fits out1.fits DIST "circle(4200.0,3600.0,15.0)"
"circle(3800.0,3900.0,7.0)"

Interpolate over the region

circle(4200.0,3600.0,15.0)

by sampling from the pixel distribution in the background region

circle(3800.0,3900.0,7.0).

Example 2

dmfilth in1.fits out1.fits DIST "circle(4200.0,3600.0,15.0)"
"circle(3800.0,3900.0,7.0)" randseed=123

This is the same as the first example except that the random-number generator is seeded with the value 123, rather than using the system time. Repeated runs of this example will create exactly the same output file, whereas they would be different if randseed=0.

Example 3

dmfilth in1.fits out1.fits POLY "circle(4200.0,3600.0,15.0)"
"circle(4200.0,3600.0,25.0)"

Here we have the same source image and source region as previously, but we use a two-dimensional polynomial fit over the region

circle(4200.0,3600.0,25.0)

to define the replace values. Note that the source region is entirely within the region used to fit the background.

Example 4

dmfilth in1.fits out1.fits POISSON @src.lis @bkg.lis

Each separate region in the file src.lis is filled with values drawn from a Poisson distribution whose mean is the mean level in the corresponding background region in bkg.lis.

Example 5

dmfilth in1.fits out1.fits GLOBAL "box(4200.0,3800.0,20.0,10.0)"
bkglist=""

The box region centered on (4200.0,3800.0) with width 20 and height 10 is replaced with values dran from a Poisson distribution. The mean of this distribution is set to the mean level in all pixels in the image that do not lie within the source region. The bkglist parameter is not used here, and so is set to "".

Example 6

dmfilth in1.fits out1.fits BILINT @src.lis bkglist=""

Interpolate over the source region stack using bilinear interpolation between the nearest non-source pixels in directions of +/-45 degrees and +/-135 degrees. If, for a particular pixel within the source region, the interpolation matrix is singular, the average of the 2 linear interpolations between the nearest background pixels in the x- and y-directions is used instead. The bkglist is not used in this example.

Parameters

name	type	ftype	def	min	max	reqd	stacks
infile	file	input				yes
outfile	file	output				yes
method	string		GLOBAL			yes
srclist	string					yes	yes
bkglist	string					yes	yes
randseed	integer		1	0	65536
clobber	boolean		no
verbose	integer		0	0	5

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input image. If using an event file, add a binning specification to the filename, e.g. infile="acis_evt2.fits[bin sky=4]"; see "ahelp dmbinning" for more information.

Parameter=outfile (file required filetype=output)

The output dataset.

Parameter=method (string required default=GLOBAL)

The interpolation method.

The allowed values of this enumerated type are POLY, DIST, GLOBAL, POISSON, and BILINT.

Parameter=srclist (string required stacks=yes)

The srclist is a stack of region specifications to be interpolated over.

Parameter=bkglist (string required stacks=yes)

Region(s) from which to define the background (if the method is not GLOBAL or BILINT).

The bkglist is a stack of region specifications to be sampled from for the methods POISSON and DIST. For these methods, the background regions may not include any pixels contained in source regions. For the POLY method, a 2D polynomial is fit over the bkglist region(s), which must include all source region pixels.

For all three methods, if the number of background regions in bkglist is 1, that background region will be applied to all source regions. If the number of background regions in bkglist is equal to the number of source regions, each background region will be used with the corresponding source region. In all other cases, a fatal error will be reported.

The bkglist is not used for the GLOBAL and BILINT methods.

Parameter=randseed (integer default=1 min=0 max=65536)

The seed for the random number generator.

Specifies the seed for the random number generator used by the POISSON, DIST, and GLOBAL methods. A value of 0 uses the system time to set the seed.

Parameter=clobber (boolean default=no)

Specifies if an existing output file should be overwritten.

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

Specifies the level of verbosity in displaying diagnostic messages (0-5).

Changes in CIAO 4.16

Some error handling cleanup.
Corrected the units from "degrees" to "deg" as per the FITS standard.
Images that do not provide a full world coordinate system can now be used. The only requirement is that the regions used must be in physical coordinates rather than celestial coordinates.

Bugs

Caveats

ERROR: Could not allocate memory for 'output_pixels'.

A common error with dmfilth is to use an event file as input instead of an image. If an event file is used event file, the tool bins it into a very large image (8192 x 8192 for ACIS). With an image that large all the system memory can easily be exhausted -- especially if running on a 32bit machine which is limited to ~2Gb of memory per-application (regardless of how much memory is installed).

Ensure that an image is being used (dmlist the file will show either 'Table' or 'Image'). If using a table (ie event file) then it should be binned into an image first.