Perform a quad-tree adaptive binning on 2D images
dmnautilus infile outfile snr [inerrfile] [outmaskfile] [outsnrfile] [outareafile] [verbose] [clobber]
`dmnautilus' does a form of adaptive binning of a 2D image known as a 'quad-tree' algorithm. A detailed description of the technique can be found in Samet, H. "The Quadtree and Related Hierarchical Data Structures", 1984, ACM Computing Surveys, 16, 187.
The tool looks at the entire image and computes the signal-to-noise ratio (SNR). If the SNR is greater than the input threshold, the image is divided in half in both the horizontal and vertical directions. For each sub-image, the process is repeated until the SNR drops below the user-supplied value or a single pixel remains above the SNR limit. 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.
While square images will give the most natural-looking binning, rectangular images can be input and rectangular bins will be used.
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.
dmnautilus inimg.fits outimg.fits 9
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).
dmnautilus inimg.fits outimg.fits 15 inerr=errs.fits
Bins the input image to a SNR threshold of 15. The error of each pixel is taken from the errs.fits file.
dmnautilus inimg.fits outimg.fits 9 outmaskfile=mask.fits
Similar to Example 1 but outputs the mask information. Each pixel in the mask.fits file indicates which group the pixel was assigned to.
dmnautilus inimg.fits . 9 outmask=. outsnr=. outarea=.
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.
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)
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=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
Parameter=clobber (boolean not required default=no)
Remove existing outputs?
Remove existing output files if they already exist?
Changes in CIAO 4.12
Now correctly propagates units from the input image to the output image.
There are no known bugs for this tool.
- dmappend, dmcontour, dmellipse, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimghull, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmregrid, dmregrid2, dmstat, evalpos, imgmoment, mean_energy_map, pileup_map