Synopsis
Perform polar quadtree 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 quadtree 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 signaltonoise ratio (SNR) for the entire image and for the four subimages 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 subimages, repeating the dividebytwo 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 subimages is greater than the input threshold, then the subimages are used.
With method=2, if the SNR of two subimages that share a common side (ie not diagonal) are greater than the input threshold then the subimages are used.
With method=3, if the SNR of any three of the subimages is greater than the input threshold, then the subimages are used.
With method=4, the SNR of all of the subimages must be above the threshold for the subimages 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 subimages are used. This make the threshold behave as an upper limit (image keeps dividing until SNR of the subimage 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 subimage, the process is repeated until the SNR criteria is met.
The output pixels are then the sum of the pixels in the subimage divided by the area of the subimage. 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 broadband 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 pieannulus 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)
SignalToNoiseRatio threshold
The signal to noise ration to split the image into 4 subimages. See the method parameter for a description of the how the limit is applied.
Parameter=xcenter (real required)
The physical xcoordinate 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 ycoordinate 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 subimages that must be above the SNR threshold for the subimages to be further divided. A value of 1 means that only 1 of the subimages must be above threshold for them all to be divided. A value of 2 means that two subimages that specifically share a common side (ie not diagonal) are above threshold then all 4 subimages are divided. 3 requires any three subimage be above threshold, and 4 requires all 4 subimage be above threshold for them to be further subdivided.
The value of 0 is different in that the subimages 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 quadtree 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 sectorwedge of the data. This value is the starting angle for the wedge to include in the algorithm. It is measures in degrees, counterclockwise (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 minoraxis 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 counterclockwise 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/subimage
The SNR value computed for each subimage 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 subimage.
The area of each subimage 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?
Changes in CIAO 4.15

Updated the tool to recognize realvalued NULLs and to recognize valid data ranges.
Bugs
There are no known bugs for this tool.
See Also
 dm
 dmfiltering
 tools
 dmappend, dmcontour, dmellipse, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimghull, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmregrid, dmregrid2, dmstat, evalpos, imgmoment, mean_energy_map, pileup_map