Replace pixel values in source regions of an image with values
interpolated from surrounding background regions
dmfilth infile outfile method srclist bkglist [randseed] [clobber]
[verbose]
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.
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.
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).
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).
Please see the "bugs" section of this file (e.g. "ahelp -b
BUGS dmfilth") if you plan to use the POISSON method.
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.
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).
The value for each source region pixel
is a bilinear interpolation of the form
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.
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).
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.
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.
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.
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 "".
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.
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=method (string required default=GLOBAL)
The interpolation method.
The allowed values of this enumerated type are
POLY, DIST, GLOBAL, POISSON, and BILINT.
The srclist is a stack of region specifications to be
interpolated over.
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.
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.
Specifies if an existing output file should be overwritten.
Specifies the level of verbosity in displaying diagnostic
messages (0-5).
The statistical distribution of total counts in regions filled
with method=POISSON is broader than expected. In particular,
tests with simulated blank fields containing hundreds of counts
in each source region reveal that the quantity
[(counts in filled region)-(original counts in region)]/sqrt(original counts in region)
has a standard deviation approximately 70% broader than
expected from simple Gaussian statistics. Users should proceed
with caution in performing rigorous quantitative analysis with
dmfilth.
See the
bugs page for this tool
on the CIAO website for an up-to-date listing of known bugs.
- calibration
-
ardlib
- dm
-
dmbinning,
dmimages,
dmimfiltering
- tools
-
acis_bkgrnd_lookup,
acis_fef_lookup,
acis_set_ardlib,
acisspec,
aconvolve,
acrosscorr,
add_grating_orders,
add_grating_spectra,
arestore,
asphist,
dither_region,
dmappend,
dmarfadd,
dmcontour,
dmcoords,
dmcopy,
dmextract,
dmgroup,
dmimg2jpg,
dmimgcalc,
dmimghist,
dmimgpick,
dmimgthresh,
dmregrid,
fullgarf,
get_sky_limits,
mkacisrmf,
mkarf,
mkexpmap,
mkgarf,
mkgrmf,
mkinstmap,
mkpsf,
mkrmf,
mkwarf,
psextract,
psf_project_ray,
rmfimg,
specextract,
tgextract
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}