dmnautilus

Synopsis

Perform a quad-tree adaptive binning on 2D images

dmnautilus  infile outfile snr [method] [inerrfile] [outmaskfile]
[outsnrfile] [outareafile] [verbose] [clobber]

Description

`dmnautilus' does a form of adaptive binning of a 2D image known as a 'quad-tree' algorithm.

The tool computes the signal-to-noise ratio (SNR) for the entire image and for the four sub-images taken by dividing the axis lengths in half. Based on the 'method' parameter the algorithm will then either accept the full image, or iterate over each of the sub-images, repeating the divide-by-two algorithm until the threshold criteria is met or a single pixel remains.

With method=1, if the SNR of any one of the sub-image greater than the input threshold, then the sub-images are used.

With method=2, if the SNR of two sub-image that share a common side (ie not diagonal) are greater than the input threshold then the sub-images are used.

With method=3, if the SNR of any three of the sub-images is greater than the input threshold, then the sub-images are used.

With method=4, the SNR of all of the sub-images must be above the threshold for the sub-images to be used. This is the most strict lower limit test; it may lead to some unexpected behavior with rotated images -- especially around the edge of the image. Users may see better results by rotating images to make the edges parallel to the X and Y axes.

With method=0, if the SNR of the entire image is greater than the input threshold, the sub-images are used. This make the threshold behave as an upper limit (image keeps dividing until SNR of the sub-image falls below the threshold). A description of the technique can be found in Samet, H. "The Quadtree and Related Hierarchical Data Structures", 1984, ACM Computing Surveys, 16, 187.

For each sub-image, the process is repeated until the SNR criteria is met.

The output pixels are then the sum of the pixels in the sub-image divided by the area of the sub-image. The tool can also optionally output the area, SNR, and a mask/group number for each output pixel.

Pixels that fall outside of the data subspace, NaNs, and integer NULL value pixels are all ignored when computing the sum, area and SNR.

If no error file is supplied (inerrfile parameter), then a Gaussian approximation "(sqrt(image value))" is used. If an error file is supplied, it must be the same size as the input image.

The output mask file can be used with dmmaskbin to group another image of the same dimensions using the same bin sizes. This is useful say to group the data based on broad-band energy filter and then group narrow band images using the same grouping scheme.

While square images will give the most natural-looking binning, rectangular images can be input and rectangular bins will be used.

Image Edges

There is some special treatment for the edge of images, or more specifically, pixels outside the subspace. If all the pixels in the sub-image are outside the subspace, then that sub-image will be treated as having a SNR above threshold. This allows for some better edge handing when working with images that contain large borders or gaps of unexposed pixels.

Examples

Example 1

dmnautilus inimg.fits outimg.fits 9 method=0

Adaptivly bins the image in inimg.fits to a SNR threshold of 9. Since no error image is supplied the SNR is computed as the sqrt(inimg.fits).

Example 2

dmnautilus inimg.fits outimg.fits 15 inerr=errs.fits method=0

Bins the input image to a SNR threshold of 15. The error of each pixel is taken from the errs.fits file.

Example 3

dmnautilus inimg.fits outimg.fits 9 outmaskfile=mask.fits method=4

Similar to Example 1 but outputs the mask information. Each pixel in the mask.fits file indicates which group the pixel was assigned to. With method=4 and no input error image, the output will contain bins with a minimum SNR=9 (ie 81 counts).

Example 4

dmnautilus inimg.fits . 9 outmask=. outsnr=. outarea=. method=4

Similar to above but also outputs the output SNR threshold image and the area image. It uses autonaming to name the outfile, outmaskfile, outsnrfile, and outareafile files.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input 2D image

Image to be adaptive binned.

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

Output adaptive binned image.

Output of the adaptive binning routine. Data will be stored as floating point values.

Parameter=snr (real required default=0 min=0)

Signal-To-Noise-Ratio threshold

The signal to noise ration to split the image into 4 sub-images. It may seem unnatural but this is an upper-limit on the SNR.

Parameter=method (integer default=0 min=0 max=4)

SNR threshold method

The method parameter describes the number of sub-images that must be above the SNR threshold for the sub-images to be further divided. A value of 1 means that only 1 of the sub-images must be above threshold for them all to be divided. A value of 2 means that two sub-images that specifically share a common side (ie not diagonal) are above threshold then all 4 sub-images are divided. 3 requires any three sub-image be above threshold, and 4 requires all 4 sub-image be above threshold for them to be further subdivided.

The value of 0 is different in that the sub-images are always divided if the parent image is above the SNR threshold. So while the other methods act as lower limits, a value of 0 acts as an upper limit.

Parameter=inerrfile (file not required filetype=input)

Input error image

Image containing the error estimate for each pixel in infile. The square of the pixel values is used when computing the SNR. The error image must be the same dimensionality as infile (datatype is arbitrary).

Parameter=outmaskfile (file not required filetype=output autoname=yes)

Image with grouping information

Indicated which group number (arbitrary) the pixel belongs to. Can be used with dmmaskbin to bin another image of the same dimension using the same grouping scheme.

Parameter=outsnrfile (file not required filetype=output autoname=yes)

Image containg the SNR for each pixel/sub-image

The SNR value computed for each sub-image is stored in this file. Sharp edges in the SNR map can be used to detect extended emission.

Parameter=outareafile (file not required filetype=output autoname=yes)

The area (in number of pixels) of each sub-image.

The area of each sub-image is stored. This can be useful to exclude particularly large regions where statistics may dominate the analysis or to remove data from the edge of the image.

Parameter=verbose (integer not required default=0 min=0 max=0)

Tool chatter level

Currently disabled.

Parameter=clobber (boolean not required default=no)

Remove existing outputs?

Remove existing output files if they already exist?

Changes in CIAO 4.14.0

The 'method' parameter is new. The original behavior of the tool, which uses the SNR as an upper limit (keeps dividing the image until the SNR drops below the limit) is achieved using method=0.

Setting method=1, 2, 3, or 4 allows using the SNR as a lower limit with increasing strictness on the number of sub-images that must exceed the SNR for them to be further divided.

Bugs

There are no known bugs for this tool.

See Also

dm

dmfiltering

tools::core

dmappend

tools::image

centroid_map, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmradar, dmregrid, dmregrid2, energy_hue_map, evalpos, hexgrid, map2reg, merge_too_small, mkregmap, pathfinder, vtbin

tools::region

dmcontour, dmellipse, dmimghull, dmimglasso

tools::response

mean_energy_map, pileup_map

tools::statistics

dmstat, imgmoment, statmap