dmimgpm

Synopsis

Compute a low frequency spatial (modified poisson mean) background map

Syntax

dmimgpm  infile outfile [expfile] [outexpfile] [maxbin] [xhalf] [yhalf]
[clobber] [verbose]

Description

dmimgpm computes a low spatial frequency map. A modified Poisson mean is used to create the background map. The tool uses a measure of the distribution of counts for a given sampling region for each point in the map.

The typical user will run dmimgpm as part of the create_bkg_map script, not as a standalone tool.

General Algorithm

For the sampling area of each point in the image a histogram (h) is created of the count distribution. It is possible (if the readout streak has been subtracted) there may be some negative count pixels. As a result bin 0 will typically represent the range between -0.5 and +0.5 for ACIS. From the histogram the highest bin (a) and its lower and higher adjacent neighbors (b and c) are identified. The background is calculated as:

b_lf = mean(h[a] U h[b] U h[c] ).

This is a modified form of a Poisson Mean. That is essentially the mean value of all of the pixels contained in the histogram columns of h[a], h[b] and h[c]. This process is done for each point in the map.

Sampling Region (parameters xhalf and yhalf)

For each point in the image, a box of 2*xhalf by 2*yhalf pixels centered on that point is defined as the sampling region. The edges of the box are xhalf/yhalf away from the point. The values xhalf/yhalf represents the low frequency filter size (sizes smaller than this are filtered out and attenuated). Near the edges of the maps the area is truncated and some higher frequency information may propagate into the map. But this has not been found to create any major impacts on the low frequency map. For an unbinned ACIS observation, xhalf = yhalf = 64 (the default) corresponds to an angular scale size of ~1 arcminute.

Example

dmimgpm "img.fits[sky=circle(100,100,10)]"

Compute the modified Poisson mean background within the circle for img.fits.

Parameters

name	type	ftype	def	reqd
infile	file	input		yes
outfile	file	output		yes
expfile	file	input		no
outexpfile	file	output		no
maxbin	integer		49	no
xhalf	integer		64	no
yhalf	integer		64	no
clobber	boolean		no	no
verbose	integer		0	no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input image with optional filter

For more information on filtering, see "ahelp dmfiltering" and/or "ahelp dmregions".

Parameter=outfile (file required filetype=output)

Output background map

Parameter=expfile (file not required filetype=input)

Input exposure map file

If an exposure map is provided, it is smoothed the same as the image , except that the outexpfile is just the simple mean (or average) of the input exposure map, not a "modified Poisson mean". Smoothing ensures that all the edge effects (i.e. when the box goes off the active detector region) are properly accounted for.

The input exposure map must be the same size as the input image. The smoothed data are saved in the filename specified by the 'outexpfile' parameter.

Parameter=outexpfile (file not required filetype=output)

Output smoothed exposure map

See the 'expfile' parameter description for an explanation of how the exposure map is smoothed.

Parameter=maxbin (integer not required default=49)

Highest histogram bin to use

dmimgpm has a sampling region from which a histogram of various count values in the region is created. The maxbin parameter is the largest bin value used in creating the histogram. So if you had a few pixels in the region that were in the 100s of counts, they would be excluded in the calculation (assuming the default maxbin=49). This is done to save computation time, since the peak of the histogram is generally near 0-1.

The only time you are likely to change this parameter value is if you are dealing with a bright background of a highly binned image and the average number of counts per pixel are around or above 49 counts.

Parameter=xhalf (integer not required default=64)

half-width of the box over which the mean is computed.

For each point in the image, a box of 2*xhalf by 2*yhalf pixels centered on that point is defined as the sampling region. Refer to the section "Sampling Region", above, for details.

Parameter=yhalf (integer not required default=64)

half-height of the box over which the mean is computed.

For each point in the image, a box of 2*xhalf by 2*yhalf pixels centered on that point is defined as the sampling region. Refer to the section "Sampling Region", above, for details.

Parameter=clobber (boolean not required default=no)

Clobber output if it exists?

Parameter=verbose (integer not required default=0)

Display level (0-5)

Changes in CIAO 4.15

Updated the tool to recognize real-valued NULLs and to recognize valid data ranges.

Bugs

There are no known bugs for this tool.