Synopsis
Perform polar quad-tree adaptive binning on 2D images
Syntax
dmradar infile outfile snr xcenter ycenter [method] [shape] [rinner] [router] [astart] [arange] [ellipticity] [rotang] [minradius] [minangle] [inerrfile] [outmaskfile] [outsnrfile] [outareafile] [verbose] [clobber]
Description
`dmradar' performs the a polar equivalent of a quad-tree adaptive binning algorithm used in `dmnautilus'. Rather than splitting the image in X and Y, it works in polar coordinates: angle and radii.
The tool computes the signal-to-noise ratio (SNR) for the entire image and for the four sub-images taken by dividing the angle in half and the radius 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.
SNR Criteria: method parameter
With method=1, if the SNR of any one of the sub-images is greater than the input threshold, then the sub-images are used.
With method=2, if the SNR of two sub-images 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 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.
Users can also specify different shapes to be used. The default is circular pie-annulus shaped regions. Users can also use elliptical annulii (epanda) or box annulli (bpanda). The special shape=box uses a Cartesian grid (ie an enhanced version of the original dmnautilus).
Examples
Example 1
dmradar inimg.fits outimg.fits 9 method=0 xcenter=4096 ycenter=4096
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
dmradar inimg.fits outimg.fits 15 inerr=errs.fits method=0 xcenter=4096 ycenter=4096
Bins the input image to a SNR threshold of 15. The error of each pixel is taken from the errs.fits file.
Example 3
dmradar inimg.fits outimg.fits 9 outmaskfile=mask.fits method=4 xcenter=4096 ycenter=4096
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
dmradar inimg.fits . 9 outmask=. outsnr=. outarea=. method=4 xcenter=4096 ycenter=4096
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
| name | type | ftype | def | min | max | reqd | autoname |
|---|---|---|---|---|---|---|---|
| infile | file | input | yes | ||||
| outfile | file | output | yes | yes | |||
| snr | real | 0 | 0 | yes | |||
| xcenter | real | yes | |||||
| ycenter | real | yes | |||||
| method | integer | 0 | 0 | 4 | |||
| shape | string | pie | |||||
| rinner | real | 5 | 0 | ||||
| router | real | 1000 | 0 | ||||
| astart | real | 0 | 0 | ||||
| arange | string | 360 | 0 | ||||
| ellipticity | real | 1 | 0 | 1 | |||
| rotang | real | 0 | 0 | 360 | |||
| minradius | real | 0.5 | 0 | ||||
| minangle | real | 1 | 0 | ||||
| inerrfile | file | input | no | ||||
| outmaskfile | file | output | no | yes | |||
| outsnrfile | file | output | no | yes | |||
| outareafile | file | output | no | yes | |||
| verbose | integer | 0 | 0 | 5 | no | ||
| clobber | boolean | no | no |
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. See the method parameter for a description of the how the limit is applied.
Parameter=xcenter (real required)
The physical x-coordinate to use for the center of the binning.
The xcenter and ycenter parameters are used as the center of the binning.
The inner most shape, centered on this location, out to a radius of rinner is always the first bin.
Parameter=ycenter (real required)
The physical y-coordinate to use for the center of the binning.
See xcenter.
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=shape (string default=pie)
The shape of the bins: pie, epanda, bpanda, or box.
The shape of the bins can be circular annulii (pie), elliptical annulii (epanda), box annulii (bpanda), or rotated rectangles (box).
shape=box is a special case where a Cartesian rather than polar grid is used. This makes is very similar to the original dmnautilus, but with more options like the choice of bin center and rotation angle.
Where does panda come from?
The abbreviation panda comes from ds9. It means Pie AND Annulus.
Parameter=rinner (real default=5 min=0)
The inner most radius, in physical pixels.
Pixels within the inner radius of the center are grouped into a single group with the defined shape: circle, ellipse, or box.
Parameter=router (real default=1000 min=0)
The outer most radius, in physical pixels.
The outer most radius to use for the initial quad-tree search algorithm. Pixels outside this radius are ungrouped.
Parameter=astart (real default=0 min=0)
The starting angle, in degrees CCW from the +X axis.
Users can choose to use the entire range of angles (0:360), or can compute the algorithm in just a specific sector|wedge of the data. This value is the starting angle for the wedge to include in the algorithm. It is measures in degrees, counter-clock-wise (CCW) from the +X axis.
Parameter=arange (string default=360 min=0)
The stopping angle, measured in degrees CCW from astart.
The arange is the number of degrees to include in the grid. Pixels outside the range astart to astart+arange are not grouped. Setting arange=360 includes all angles. Setting to less than 360 means only a wedge of angles will be grouped.
Parameter=ellipticity (real default=1 min=0 max=1)
Ellipticity of epanda and bpanda regions.
In this case, ellipticity is simply the ratio of the minor-axis divided by the major axis. A value of 1 means that major==minor which produces circles and squares for epanda and bpanda. A value of 0 mean minor=0, which is bad -- basically the shapes collapse down to a line.
Parameter=rotang (real default=0 min=0 max=360)
Rotation angle of the major axis for epanda and bpanda regions.
This value is in degrees, measured counter-clock-wise from the +X axis.
Parameter=minradius (real default=0.5 min=0)
The minimum allowable radius, in pixels, when dividing subimages.
This parameter controls how far we will let the algorithm go to try to split up pixels into groups. It can continue to divide the image until the minradius is reach at which point the group is used regardless of the SNR criteria.
Parameter=minangle (real default=1 min=0)
The minimum allowable angle, in degrees, when dividing subimages.
See minradius.
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.
The output mask file contains a REGION extension which contains the individual regions that describe each group. The REGION logic for epanda and bpanda is
shape_outer *! shape_inner * sector
where shape is either rotated ellipse or rotated box. The sector captures the angle range. It takes 3 shapes to describe a grid. In the FITS table, this will be 3 rows in the table all with the same COMPONENT value (the component value will not necessarily equal the map pixel value).
Note: ds9
Note that ds9 does not render the sector shape. If you load the region in ds9 it will skip over those shapes, omitting the angular boundaries between groups.
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=5)
Tool chatter level
Parameter=clobber (boolean not required default=no)
Remove existing outputs?
Remove existing output files if they already exist?
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, dmnautilus, 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