Extended IDL Help

This page was created by the IDL library routine mk_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type:

     ? mk_html_help

at the IDL command line prompt.

Last modified: Mon Dec 5 15:42:16 2005.


List of Routines


Routine Descriptions

WVT_APPLYBINNING

[Next Routine] [List of Routines]
 NAME:
     WVT_APPLYBINNING

 AUTHORS:
       Steven Diehl & Thomas S. Statler, Ohio University, US
       diehl@phy.ohiou.edu, statler@ohio.edu

 PURPOSE:
       Apply an existing binning structure to a given data set.

 CALLING SEQUENCE:
     binnedimage=WVT_APPLYBINNING(binnumber, inputsignal [, area=area, $
       xraycolor=xraycolor, input2=input2, binvalue=binvalue])

 INPUT:   
    BINNUMBER: Either 2d image or 1d pixel list, containing the bin
               number of each pixel
  INPUTSIGNAL: Has to be same size as binnumber and contain the signal per 
               pixel

 OUTPUT:
     BINVALUE: Binned signal value for each bin, divided by the bin AREA  
         AREA: Area per bin, can be used to undo the normalization of BINVALUE
    XRAYCOLOR: IF this keyword is set, the algorithm uses INPUTSIGNAL as 
               band A and INPUT2 as band B to compute the hardness ratio 
               A/B as the signal in the bin  
       INPUT2: Band B for hardness ratios

 RETURNS: array of the same size as BINNUMBER and INPUTIMG, containing the 
          binned signal, averaged over the bin area

 FUNCTIONS PROVIDED:
             WVT_APPLYBINNING             -- main program

 EXAMPLE:
    ; Adaptively bin an image, consisting of soft and hard band
    signal=softimage+hardimage
    noise=sqrt(softnoise^2+hardnoise^2)
    WVT_IMAGE, signal, noise, targetSN, binnedimage, binnumber=binnumber 
    ; Apply the binning from the full band to the soft band only
    binnedmodelimage=wvt_applybinning(binnumber, softimage)

 MODIFICATION HISTORY (ORIGINAL VORONOI_2D_BINNING):
       V2.0: First published version (12/05/2005)


(See wvt_applybinning.pro)


WVT_BINNING

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     WVT_BINNING

 AUTHORS:
       MODIFIED CODE (WVT_BINNING)      
       Steven Diehl & Thomas S. Statler, Ohio University, US
       diehl@helios.phy.ohiou.edu, tss@coma.phy.ohiou.edu

       ORIGINAL CODE (VORONOI_2D_BINNING)
       Michele Cappellari, Leiden Observatory, The Netherlands
       cappellari@strw.leidenuniv.nl

 CREDIT:
       In case you are using this method for you data analysis, please
       refer to it as the "WVT adaptive binning algorithm by Diehl &
       Statler (2006), based on the Voronoi 2D-binning method by 
       Cappellari & Copin (2003)" 

 PURPOSE:
       Adaptive spatial binning of any type of 2-dimensional data with
       the aim of obtaining a uniform signal-to-noise per bin distribution.
       The code uses weighted Voronoi tesselations (WVT) and is
       designed in particular to work with X-ray intensity image, color images,
       or integral-field spectroscopic data.
       WVT_BINNING operates only on pixel lists. WVT_IMAGE provides an 
       interface to directly use 2d images instead.

 EXPLANATION:
       For additional information about WVT binning
       please refer to Diehl, S. & Statler, T.S. (2006).
       Further information on the original VORONOI_2D_BINNING algorithm can 
       be found in Cappellari M., Copin Y., 2003, MNRAS, 342, 345.

 CALLING SEQUENCE:
       WVT_BINNING, x, y, pixelSize, targetSN, binnumber, xNode, yNode, area 
         [, /QUIET=quiet, dens=dens, binvalue=binvalue, snbin=snbin, $
         plotit=plotit, resume=resume, neighborlist=neighborlist, 
         max_area=max_area, gersho=gersho, keepfixed=keepfixed ]

 REQUIREMENTS:
       There have to be two external, compiled functions ADD_SIGNAL and 
       ADD_NOISE, which define how the signal and noise inside a bin are 
       added. The wrappers WVT_IMAGE, WVT_XRAYCOLOR or WVT_PIXELLIST contain
       these functions already. See WVT_GENERIC for an example on how
       to build your own S/N calculation.

 INPUTS (REQUIRED):
            X: Vector containing the X coordinate of the pixels to bin.
               It is assumed here that pixels are arranged in a regular
               grid, so that the PIXELSIZE is a well defined quantity.
               The pixel grid however can contain holes (some pixels can be
               excluded from the binning, e.g point sources in X-ray data) 
               and can have an irregular boundary. However, the data should be
               continuous, as the uniformity of the S/N distribution can not 
               be guaranteed otherwise. Arbitrary units can be used 
               (e.g. arcsec or pixels).
            Y: Vector (same size as X) containing the Y coordinate
               of the pixels to bin.
    PIXELSIZE: Side length of one pixel. Pixels are assumed to be square.
     TARGETSN: The desired signal-to-noise ratio in the final
               2D-binned data. A TARGETSN between ~4-10 is standard for X-ray 
               images, a temperature map would require higher TARGETSN 
               (~30-100), depending on the spectral model used. For integral 
               field spectroscopy, a TARGETSN of ~50 per pixel may be a
               reasonable value to extract stellar kinematics
               information from galaxy spectra.
       SIGNAL: Vector (same size as X) containing the signal
               associated with each pixel, having coordinates (X,Y).
               If pixels are the actual pixels of the CCD in a galaxy
               image, the signal will be simply the counts in each pixel.
               The image can be background subtracted or exposure map 
               corrected,as long as the NOISE image reflects this. 
               If the `pixels' are actually the apertures of an
               integral-field spectrograph, then the signal can be
               defined as the average flux in the spectral range under
               study, for each aperture.
        NOISE: Vector (same size as X) containing the corresponding
               noise associated with each pixel.

 OUTPUTS:
    BINNUMBER: Vector (same size as X) containing the bin number assigned
               to each input pixel. The index goes from zero to Nbins-1.
               This vector alone is enough for making *any* subsequent
               computation on the binned data. Everything else is optional.
        XNODE: Vector (size Nbins) of the X coordinates of the bin generators, 
               i.e the geometric centers of the bins.
        YNODE: Vector (size Nbins) of Y coordinates of the bin generators.
        SNBIN: Vector (size Nbins) with the final SN of each bin.
         AREA: Vector (size Nbins) with the number of pixels for each bin.
     BINVALUE: Vector (size Nbins) with the final signal of each bin

 KEYWORDS (OPTIONAL):
       PLOTIT: Set this keyword to one to produce a plot of the two-dimensional
               bins and of the corresponding S/N at the end of the
               computation. A value of two will produce a similar plot 
               after the bin accretion step. Setting PLOTIT higher than 
        QUIET: by default the program shows the progress while accreting
               pixels and then while iterating the CVT. Set this keyword
               to avoid printing progess results. 
       GERSHO: Use Gersho's conjecture with normal Voronoi tesselations, 
               instead of the WVT algorithm. Except for some changes in the 
               bin accretion step, this procedures is identical to the one 
               implemented in Cappellari & Copin's code VORONOI_2D_BINNING.
               Be aware, that Gersho's conjecture is only valid for strictly
               positive data, where the S/N adds in quadrature!
       RESUME: Set this keyword, if you want to start from an existing WVT, 
               which is uniquely defined by the vectors XNODE, YNODE, and SNBIN
               The WVT iteration scheme will be applied to the supplied WVT, 
               and the values overwritten with the final output.
    KEEPFIXED: [Input] Vector (size 2 x n_fixed) containing x and y coordinates 
               of bin generators that you want to keep fixed in their position.
               The binning algorithm will move all other bins around as usual.
               Example use: Keep one bin fixed on the center of a galaxy.

 EXTERNAL INTERACTIVE CONTROLS
       PLOTIT: If you decide that you want to plot the iteration steps, create 
               file in the current directory with the name 'plotit'. A simple
               way to do this is to issue the command 'touch plotit' in a 
               shell. Remove the file if you want to stop plotting.
    STOPMENOW: If you want to terminate the iteration at the next possible time,
               create a file named 'stopmenow' in the current directory (e.g 
               'touch stopmenow').

 PROCEDURES PROVIDED:
       The following procedures are contained in the main WVT_BINNING program.
       Refer to the main code for further explanations.
            WVT_FIND_BINNEIGHBORS         -- find neighboring bins
            WVT_CHECK_ALL_BINS            -- check for zero sized bins
            WVT_CHECK_BINISLANDS          -- check if one bin encloses another
            WVT_RENUMBER_BINNUMBER        -- kick out zero size bins, renumber
            WVT_UNWEIGHTED_CENTROID       -- calculate geometric center
            WVT_ADDTO_UNWEIGHTED_CENTROID -- update center when pixels added
            WVT_WEIGHTED_CENTROID         -- calculated weighted centroid
            WVT_BIN_ACCRETION             -- modified bin accretion algorithm
            WVT_REASSIGN_BAD_BINS         -- unallocated pixels to closest bin
            WVT_EQUAL_MASS                -- main iteration scheme
            WVT_DISPLAY_PIXELS            -- display pixel list
            WVT_MAKENEIGHBORLIST          -- create list of pixel neighbors
            WVT_FINDNEIGHBORS             -- find all neighbors of a bin
            WVT_BINNING                   -- MAIN PROGRAM

 FUNCTIONS PROVIDED:
       The following functions are contained in the main WVT_BINNING program.
       Refer to the main code for further explanations.
            WVT_ASSIGN_TO_BIN             -- create the WVT
            WVT_ASSIGN_NEIGHBORS          -- find bin numbers of neighbors
            WVT_RECURSIVE_NEIGHBORS       -- recursive list of nearby bins
            WVT_BIN_ROUNDNESS             -- computes roundness of a bin

 NOTE:
       This program uses the function MATCH from the IDL astro library. We
       included this function in the main program release for completeness.
       Feel free to remove the file match.pro if you already have the IDL 
       astro library (see idlastro.gsfc.nasa.gov/homepage.html) installed.

 MODIFICATION HISTORY (ORIGINAL VORONOI_2D_BINNING):
       V1.0: First implementation. Michele Cappellari, Leiden, June 2001
       V2.0: Major revisions. Stable version. MC, Leiden, 11 September 2001
       V2.1: First released version. Written documentation.
           MC, Vicenza, 13 February 2003
       V2.2: Added computation of bin quantities in output. Deleted some
           safety checks for zero size bins in CVT. Minor polishing of code.
           MC, Leiden, 11 March 2003
       V2.3: Unified the three tests to stop the accretion of one bin.
           This can improve some bins at the border. MC, Leiden, 9 April 2003
       V2.31: Do *not* assume the first bin is made of one single pixel.
           Added computation of S/N scatter and plotting of 1-pixel bins.
           MC, Leiden, 13 April 2003
       V2.4: Added basic error checking of input S/N. Reintroduced the
           treatment for zero-size bins in CVT, which was deleted in V2.2.
           Thanks to Robert Sharp and Kambiz Fathi for reporting problems.
           MC, Leiden, 10 December 2003.
       V2.41: Added /QUIET keyword and verbose output during the computation.
           After suggestion by Richard McDermid. MC, Leiden, 14 December 2003

 MODIFICATION HISTORY (WVT_BINNING):
       V0.0: Made loop indices long integers to work with big images.
           Changed binnumber to a long integer array. (10/2004)
       V0.1: Added code to relax the requirement that S/N increase with every
           added pixel in bin accretion. This includes a test for good enough
           S/N at head of pixel addition loop. (These options currently
           commented out.) (10/2004)
       V0.2 User specifies pixelsize when calling voronoi_2d_binning, to avoid
           lengthy search through all pairs of pixels. (10/2004)
       V0.3 Added procedures makeneighborlist and findneighbors. bin_accretion
           calls makeneighborlist and findneighbors in order
           to expedite search for candidate pixels (10/2004)
       V0.4 Modified cvt_equal_mass to use nearest-neighbor list of voronoi
           nodes. (10/2004)
       V1.0: Complete haulover. Removal of Gersho's conjecture, use of S/N 
           density instead, together with weighted Voronoi tesselations, 
           really the first WVT binning algorithm (11/2004)
       V1.1: Added stability checks, redistribute "bin islands" (12/2004) 
       V1.2: Added possibility to resume an old session (11/2004)
       V1.3: Added flexibility for a general signal and noise calculation
           Exported the functions add_signal and add_noise to a separate 
           file  (11/2004)
       V1.4: Introduced the optional keyword max_area to limit the absolute 
           size of bins (01/05/2005)
       V1.5: Added possibility to keep a number of supplied centers fixed
           (06/14/2005)       
       V1.6: Code polishing, renaming of functions to wvt_* (07/14/2005)
       V1.7: Replaced "class" with "binnumber", for consistency with
           interfaces (07/22/2005)
       V1.8: Replaced the external function "histo" by the IDL equivalent
           histogram to resolve portability issues. Minor bug fix for 
           choosing the center in bin accretion (07/29/2005)
     V1.9.0: Checked new convergence criteria (09/06/2005)
     V1.9.1: Added explicit CENTER keyword to avoid problems with bin
           accretion (09/08/2005)
     V1.9.2: Reduced possibility of limit cycle by 'slowing down' the 
           movement of nodes for only half of all nodes (randomly chosen) 
     V1.9.3: Increased speed for WVT_FINDNEIGHBORS in the bin accretion 
           step. Necessary for cases with large individual bins. (09/15/2005)
       V2.0: First published version (12/05/2005)



(See wvt_binning.pro)


WVT_GENERATEBINNING

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     WVT_GENERATEBINNING

 AUTHORS:
       Steven Diehl & Thomas S. Statler, Ohio University, US
       diehl@phy.ohiou.edu, statler@ohio.edu

 PURPOSE:
       Reconstruct a weighted Voronoi tesselation from the positions of 
       the generators and the weight values.

 EXPLANATION:
       For additional information about WVT binning,
       please refer to Diehl, S. & Statler, T.S. (2006).
       Further information on the original VORONOI_2D_BINNING algorithm can 
       be found in Cappellari M., Copin Y., 2003, MNRAS, 342, 345.

 CALLING SEQUENCE:
     WVT_GENERATEBINNING, xnode, ynode, weight, binnumber, outmask $
       [, do_pixellist=do_pixellist, x=x, y=y]

 EXAMPLE
     ; Adaptively bin an image, INMASK has point sources masked out    
     inmask=outmask-psrc_mask
     WVT_IMAGE, signal, noise, targetSN, binnedimage, xnode, ynode, weight, $
       mask=inmask, binvalue=binvalue, binnumber
     ; Regenerate the binning for OUTMASK, which has no point sources 
     ; excluded. (remember: binnumber starts at 1, not 0)
     WVT_GENERATEBINNING, xnode, ynode, weight, binnumber_filled, outmask
     binneddimage_filled=binvalue[binnumber_filled-1]

 INPUTS (REQUIRED):
        XNODE: Vector (size Nbins) of the X coordinates of the bin 
               generators, i.e the geometric centers of the bins.
        YNODE: Vector (size Nbins) of Y coordinates of the bin generators.
       WEIGHT: Weight of each bin in the WVT
      OUTMASK: Two-dimensional image (n_x,n_y) specifying which 
               pixels should be included in the WVT binning algorithm. 
               Valid pixels are designated as "1", excluded pixels as "0" 
               (integer or byte). The size of BINNUMBER will be equal to 
               the dimensions of OUTMASK. 
               
 OUTPUT:
    BINNUMBER: Two-dimensional image (n_x,n_y) containing the bin number 
               assigned to each input pixel. The index goes from 1 to 
               Nbins. Pixels that were excluded during the binning process 
               are marked "0" (see also the keyword OUTMASK).
               This vector alone is enough for making *any* subsequent
               computation on the binned data. Everything else is optional.
         AREA: Vector (size Nbins) with the number of pixels for each bin.
     BINVALUE: Vector (size Nbins) with the final signal of each bin

 KEYWORDS (OPTIONAL):
 DO_PIXELLIST: If this keyword is set, the input is taken as a list of 
               pixels, whose xy coordinates should be specified by X and Y
               keywords
            X: x-coordinates of the pixel list
            Y: y-coordinates of the pixel list

 PROCEDURES PROVIDED:
       The following procedures are contained in the main WVT_BINNING program.
       Refer to the main code for further explanations.
            WVT_GENERATEBINNING           -- main program 

 FUNCTIONS PROVIDED:
       The following functions are contained in the main WVT_BINNING program.
       Refer to the main code for further explanations.
            WVT_ASSIGN_TO_BIN            -- assigns a pixel to its WVT bin

 MODIFICATION HISTORY (ORIGINAL VORONOI_2D_BINNING):
       V2.0: First published version (12/05/2005)


(See wvt_generatebinning.pro)


WVT_GENERIC

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     WVT_GENERIC

 AUTHORS:
       Steven Diehl & Thomas S. Statler, Ohio University, US
       diehl@phy.ohiou.edu, statler@ohio.edu

 PURPOSE:
       Adaptive spatial binning of any type of 2-dimensional data with
       the aim of obtaining a uniform signal-to-noise per bin distribution.

 NOTE:
       This wrapper provides the external ADD_SIGNAL and ADD_NOISE functions
       and gives a little hands-on tutorial on how to modify them according 
       to your own needs. 

 EXPLANATION:
       For additional information about WVT binning,
       please refer to Diehl, S. & Statler, T.S. (2005).
       Further information on the original VORONOI_2D_BINNING algorithm can 
       be found in Cappellari M., Copin Y., 2003, MNRAS, 342, 345.

(See wvt_generic.pro)


WVT_IMAGE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     WVT_IMAGE

 AUTHORS:
       Steven Diehl & Thomas S. Statler, Ohio University, US
       diehl@phy.ohiou.edu, statler@ohio.edu

 PURPOSE:
       Adaptive spatial binning of any type of 2-dimensional data with
       the aim of obtaining a uniform signal-to-noise per bin distribution.
       WVT_IMAGE provides an interface to directly use 2d images as opposed
       to pixel lists which are compatible with WVT_BINNING.

 EXPLANATION:
       For additional information about WVT binning,
       please refer to Diehl, S. & Statler, T.S. (2006).
       Further information on the original VORONOI_2D_BINNING algorithm can 
       be found in Cappellari M., Copin Y., 2003, MNRAS, 342, 345.

 CALLING SEQUENCE:
     WVT_IMAGE, signal, noise, targetSN, binnedimage, xnode, ynode, weight $
         [, snbin=snbin, mask=mask, ctsimage=ctsimage, 
            binnumber=binnumber, binvalue=binvalue, center=center, 
            plotit=plotit, resume=resume, save_all=save_all, 
            max_area=max_area, gersho=gersho, keepfixed=keepfixed, 
            quiet=quiet ]

 EXAMPLE
       See wvt_image.example

 INPUTS (REQUIRED):
       SIGNAL: Two-dimensional image (n_x,n_y), containing the signal per 
               pixel. If pixels are the actual pixels of the CCD in a galaxy
               image, the signal will be simply the counts in each pixel.
               The image can be background subtracted or exposure map 
               corrected, as long as the NOISE image reflects this. 
               If the `pixels' are actually the apertures of an
               integral-field spectrograph, then the signal can be
               defined as the average flux in the spectral range under
               study, for each aperture.
        NOISE: Two-dimensional image (n_x,n_y), containing the noise 
               associated with each pixel (sqrt(variance))
     TARGETSN: The desired signal-to-noise ratio in the final
               2D-binned data. A TARGETSN between ~4-10 is standard for 
               X-ray images, a temperature map would require higher 
               TARGETSN (~30-100), depending on the spectral model used. 
               For integral field spectroscopy, a TARGETSN of ~50 per pixel 
               may be a reasonable value to extract stellar kinematics
               information from galaxy spectra.
            
 OUTPUTS:
  BINNEDIMAGE: Two-dimensional image (n_x,n_y) containing the binned signal.
        XNODE: Vector (size Nbins) of the X coordinates of the bin 
               generators, i.e the geometric centers of the bins.
        YNODE: Vector (size Nbins) of Y coordinates of the bin generators.
        SNBIN: Vector (size Nbins) with the final SN of each bin.
    BINNUMBER: Two-dimensional image (n_x,n_y) containing the bin number 
               assigned to each input pixel. The index goes from 1 to 
               Nbins. Pixels that were excluded during the binning process 
               are marked "0" (see also the keyword MASK).
               This vector alone is enough for making *any* subsequent
               computation on the binned data. Everything else is optional.
         AREA: Vector (size Nbins) with the number of pixels for each bin.
     BINVALUE: Vector (size Nbins) with the final signal of each bin

 KEYWORDS (OPTIONAL):
       CENTER: [Input] Vector (size 2) containing x and y values for the 
               center. If this keyword is NOT supplied, [0,0] will be 
               assumed and the algorithm will start at the highest S/N 
               pixel with the bin accretion step. If the center is given, 
               bin accretion will start there. 
     MAX_AREA: [Input] Scalar specifying a maximum bin size (in pixel). 
               Useful in cases where there is essentially no signal in a 
               certain region. ATTENTION: In area where the bin size hits
               MAX_AREA, the algorithm does NOT enforce a uniform S/N 
               anymore. Use with care. 
         MASK: [Input] Two-dimensional image (n_x,n_y) specifying which 
               pixels should be included in the WVT binning algorithm. 
               Valid pixels are designated as "1", excluded pixels as "0" 
               (integer or byte). 
     CTSIMAGE: [Input] Two-dimensional image (n_x,n_y) containing the counts 
               per pixel. Necessary for very sparse X-ray data, where some 
               pixels can contain no counts. Nevertheless, in certain cases,
               you can "artificially" have a high S/N value for this pixel, 
               e.g. when you subtract two background corrected components 
               (example: remove the point source contribution in 
               ellipticals). Supply the counts image in order to avoid that 
               the binning algorithm produces bins without any counts.
    KEEPFIXED: [Input] Vector (size 2 x n_fixed) containing x and y 
               coordinates of bin generators that you want to keep fixed 
               in their position. The binning algorithm will move all other 
               bins around as usual. Example use: Keep one bin fixed on 
               the center of a galaxy.
       PLOTIT: Set this keyword to one to produce a plot of the 
               two-dimensional bin distribution and of the corresponding 
               S/N at the end of the computation. A PLOTIT value of 2 will 
               produce a similar plot after the bin accretion step. Setting 
               PLOTIT to 3 results in graphical output for each iteration.
               One should keep in mind that plotting slows down the 
               algorithm significantly.
        QUIET: by default the program shows the progress while accreting
               pixels and then while iterating the CVT. Set this keyword
               to avoid printing progess results. 
       GERSHO: Use Gersho's conjecture with normal Voronoi tesselations, 
               instead of the WVT algorithm. Except for some changes in the 
               bin accretion step, this procedures is identical to the one 
               implemented in Cappellari & Copin's code VORONOI_2D_BINNING.
               Be aware, that Gersho's conjecture is only valid for strictly
               positive data, where the S/N adds in quadrature!
       RESUME: Set this keyword, if you want to start from an existing WVT. 
               which is uniquely defined in the structure SAVE_ALL
     SAVE_ALL: [Output/Input] Structure that saves all of the necessary 
               information to restart WVT_IMAGE from any given point. If the
               keyword RESUME is set, the WVT iteration scheme is applied 
               to the supplied WVT.

 EXTERNAL INTERACTIVE CONTROLS
       PLOTIT: If you decide to plot the iteration steps, create 
               file in the current directory with the name 'plotit'. A simple
               way to do this is to issue the command 'touch plotit' in a 
               shell. Remove the file if you want to stop plotting.
    STOPMENOW: If you want to terminate the iteration at the next iteration,
               create a file named 'stopmenow' in the current directory (e.g 
               'touch stopmenow').

 PROCEDURES PROVIDED:
       The following procedures are contained in the main WVT_BINNING program.
       Refer to the main code for further explanations.
            WVT_IMAGE                     -- main interface

 FUNCTIONS PROVIDED:
       The following functions are contained in the main WVT_BINNING program.
       Refer to the main code for further explanations.
            ADD_SIGNAL                    -- adds the signal of a bin
            ADD_NOISE                     -- adds the noise of a bin
      
 NOTE:
       WVT_BINNING uses the function MATCH from the IDL astro library. We
       included this function in the main program release for completeness.
       Feel free to remove the file match.pro if you already have the IDL 
       astro library (see idlastro.gsfc.nasa.gov/homepage.html) installed.

 MODIFICATION HISTORY (ORIGINAL VORONOI_2D_BINNING):
       V0.1: First interface (10/2004)
       V0.1: Exported the functions ADDSIGNAL and ADD_NOISE to make 
           WVT_BINNING more flexible (11/2004)
       V1.0: Major changes to work with the new WVT_BINNING calling sequence 
           (07/12/2005)
       V1.1: Fixed bug for keepfixed: the variable is no longer 
           overwritten and also saved in SAVE_ALL now. (09/06/2005) 
       V1.2: Fixed bug when incompatible ADD_SIGNAL or ADD_NOISE functions
           are precompiled. (09/08/2005)
       V2.0: First published version (12/05/2005)


(See wvt_image.pro)


WVT_PIXELLIST

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
     WVT_PIXELLIST

 AUTHORS:
       Steven Diehl & Thomas S. Statler, Ohio University, US
       diehl@phy.ohiou.edu, statler@ohio.edu

 PURPOSE:
       Adaptive spatial binning of any type of 2-dimensional data with
       the aim of obtaining a uniform signal-to-noise per bin distribution.
       WVT_PIXELLIST provides an interface to directly use pixel lists, 
       similar to the code VORONOI_2D_BINNING (Cappellari & Copin, 2003), 
       which this algorithm was inspired by.

 NOTE:
       This procedure is identical in use to the more flexible WVT_BINNING
       but doesn't require the external ADD_SIGNAL and ADD_NOISE functions.
       Signal is supposed to simply add, whereas noise is expected to add
       in quadrature. Look at WVT_GENERIC for a template on how to define
       your own signal-to-noise criterion.

 EXPLANATION:
       For additional information about WVT binning,
       please refer to Diehl, S. & Statler, T.S. (2005).
       Further information on the original VORONOI_2D_BINNING algorithm can 
       be found in Cappellari M., Copin Y., 2003, MNRAS, 342, 345.

 CALLING SEQUENCE:
       WVT_LIST, x, y, pixelSize, targetSN, class, xNode, yNode, area 
         [, /QUIET=quiet, dens=dens, binvalue=binvalue, snbin=snbin, $
         plotit=plotit, resume=resume, neighborlist=neighborlist, 
         max_area=max_area, gersho=gersho, xray=xray, keepfixed=keepfixed ]

 INPUTS (REQUIRED):
            X: Vector containing the X coordinate of the pixels to bin.
               It is assumed here that pixels are arranged in a regular
               grid, so that the PIXELSIZE is a well defined quantity.
               The pixel grid however can contain holes (some pixels can be
               excluded from the binning, e.g point sources in X-ray data) 
               and can have an irregular boundary. However, the data should be
               continuous, as the uniformity of the S/N distribution can not 
               be guaranteed otherwise. Arbitrary units can be used 
               (e.g. arcsec or pixels).
            Y: Vector (same size as X) containing the Y coordinate
               of the pixels to bin.
    PIXELSIZE: Side length of one pixel. Pixels are assumed to be square.
     TARGETSN: The desired signal-to-noise ratio in the final
               2D-binned data. A TARGETSN between ~4-10 is standard for X-ray 
               images, a temperature map would require higher TARGETSN 
               (~30-100), depending on the spectral model used. For integral 
               field spectroscopy, a TARGETSN of ~50 per pixel may be a
               reasonable value to extract stellar kinematics
               information from galaxy spectra.
       SIGNAL: Vector (same size as X) containing the signal
               associated with each pixel, having coordinates (X,Y).
               If pixels are the actual pixels of the CCD in a galaxy
               image, the signal will be simply the counts in each pixel.
               The signal list can be background subtracted or exposure map 
               corrected, as long as the NOISE vector reflects this. 
               If the `pixels' are actually the apertures of an
               integral-field spectrograph, then the signal can be
               defined as the average flux in the spectral range under
               study, for each aperture.
        NOISE: Vector (same size as X) containing the corresponding
               noise associated with each pixel.

 OUTPUTS:
        CLASS: Vector (same size as X) containing the bin number assigned
               to each input pixel. The index goes from zero to Nbins-1.
               This vector alone is enough for making *any* subsequent
               computation on the binned data. Everything else is optional.
        XNODE: Vector (size Nbins) of the X coordinates of bin generators, 
               i.e the geometric centers of the bins.
        YNODE: Vector (size Nbins) of Y coordinates of the bin generators.
        SNBIN: Vector (size Nbins) with the final SN of each bin.
         AREA: Vector (size Nbins) with the number of pixels for each bin.
     BINVALUE: Vector (size Nbins) with the final signal of each bin

 KEYWORDS (OPTIONAL):
       PLOTIT: Set this keyword to one to produce a plot of the 2-D
               bins and of the corresponding S/N at the end of the
               computation. A value of two will produce a similar plot 
               after the bin accretion step. Setting PLOTIT higher than 
        QUIET: by default the program shows the progress while accreting
               pixels and then while iterating the CVT. Set this keyword
               to avoid printing progess results. 
       GERSHO: Use Gersho's conjecture with normal Voronoi tesselations, 
               instead of the WVT algorithm. Except for some changes in the 
               bin accretion step, this procedures is identical to the one 
               implemented in Cappellari & Copin's code VORONOI_2D_BINNING.
               Be aware, that Gersho's conjecture is only valid for strictly
               positive data, where the S/N adds in quadrature!
       RESUME: Set this keyword, if you want to start from an existing WVT, 
               which is uniquely defined by the vectors XNODE, YNODE, and 
               WEIGHT. The WVT iteration scheme will be applied to the 
               supplied WVT, and the values overwritten with the final output.

 EXTERNAL INTERACTIVE CONTROLS
       PLOTIT: If you decide to plot the iteration steps, create 
               file in the current directory with the name 'plotit'. A simple
               way to do this is to issue the command 'touch plotit' in a 
               shell. Remove the file if you want to stop plotting.
    STOPMENOW: If you want to terminate the iteration at the next iteration
               create a file named 'stopmenow' in the current directory (e.g 
               'touch stopmenow').

 PROCEDURES PROVIDED:
       The following procedures are contained in the main WVT_BINNING program.
       Refer to the main code for further explanations.
            WVT_PIXELLIST                 -- main interface

 FUNCTIONS PROVIDED:
       The following functions are contained in the main WVT_PIXELLIST 
       program. Refer to the main code for further explanations.
            ADD_SIGNAL                    -- adds the signal of a bin
            ADD_NOISE                     -- adds the noise of a bin

 NOTE:
       WVT_BINNING uses the function MATCH from the IDL astro library. We
       included this function in the main program release for completeness.
       Feel free to remove the file match.pro if you already have the IDL 
       astro library (see idlastro.gsfc.nasa.gov/homepage.html) installed.

 MODIFICATION HISTORY:
       V1.0: Provided the functions ADD_SIGNAL and ADD_NOISE in this wrapper.
           Usage is now similar to the original code by Cappellari & Copin.
           (07/12/2005)
       V1.1: Fixed bug when incompatible ADD_SIGNAL or ADD_NOISE functions
           are precompiled. (09/08/2005)
       V2.0: First published version (12/05/2005)


(See wvt_pixellist.pro)


WVT_XRAYCOLOR

[Previous Routine] [List of Routines]
 NAME:
     WVT_XRAYCOLOR

 AUTHORS:
       Steven Diehl & Thomas S. Statler, Ohio University, U.S.
       diehl@phy.ohiou.edu, statler@ohio.edu

 PURPOSE:
       Adaptive spatial binning of 2 two-dimensional images to produce
       a hardness ratio map (also called color map), while keeping a
       uniform signal-to-noise per bin distribution.

 EXPLANATION:
       For additional information about WVT binning,
       please refer to Diehl, S. & Statler, T.S. (2005).
       Further information on the original VORONOI_2D_BINNING algorithm can 
       be found in Cappellari M., Copin Y., 2003, MNRAS, 342, 345.

 CALLING SEQUENCE:
    WVT_XRAYCOLOR, signal, signal2, noise, noise2, targetSN, binnedimage, $
      xnode, ynode, weight, [, snbin=snbin, mask=mask, ctsimage=ctsimage, $
      binnumber=binnumber, binvalue=binvalue, center=center, plotit=plotit, $
      resume=resume, save_all=save_all, max_area=max_area, $
      keepfixed=keepfixed ]

 EXAMPLE
       See wvt_xraycolor.example

 INPUTS (REQUIRED):
        SIGNAL: Two-dimensional image (n_x,n_y), contains the signal per pixel
               in the first bandpass. You can use exposure and background 
               corrected images, as well as simple counts images.
       SIGNAL2: Analogous to SIGNAL (n_x,n_y), but for bandpass 2.
        NOISE: Two-dimensional image (n_x,n_y), containing the noise 
               associated with each pixel (sqrt(variance))
        NOISE2: Analogous to NOISE (n_x,n_y), but for bandpass 2.
     TARGETSN: The desired signal-to-noise ratio in the final
               2D-binned data. Choice depends if the emphasis is on spatial 
               resolution or accuracy.
            
 OUTPUTS:
  BINNEDIMAGE: Two-dimensional image (n_x,n_y) containing the hardness 
               ratios of each bin.
        XNODE: Vector (size Nbins) of the X coordinates of bin generators, 
               i.e the geometric centers of the bins.
        YNODE: Vector (size Nbins) of Y coordinates of the bin generators.
        SNBIN: Vector (size Nbins) with the final SN of each bin.
    BINNUMBER: Two-dimensional image (n_x,n_y) containing the bin number 
               assigned to each input pixel. The index goes from 1 to Nbins. 
               Pixels that were excluded during the binning process are 
               marked "0" (see also the keyword MASK).
               This vector alone is enough for making *any* subsequent
               computation on the binned data. Everything else is optional.
         AREA: Vector (size Nbins) with the number of pixels for each bin.
     BINVALUE: Vector (size Nbins) with the final signal of each bin

 KEYWORDS (OPTIONAL):
       CENTER: [Input] Vector (size 2) contains x and y values of the center. 
               If this keyword is NOT supplied, [0,0] will be assumed and the 
               algorithm will start at the highest S/N pixel with the bin 
               accretion step. If the center is given, bin accretion will 
               start there. 
     MAX_AREA: [Input] Scalar specifying a maximum bin size (in pixel). 
               Useful in cases where there is essentially no signal in a 
               certain region.
               ATTENTION: In area where the bin size hits MAX_AREA, the 
                 algorithm does NOT enforce a uniform S/N anymore. 
                 Use with care. 
         MASK: [Input] Two-dimensional image (n_x,n_y) specifies which pixels 
               should be included in the WVT binning algorithm. Valid pixels 
               are designated as "1", excluded pixels as "0" (int or byte). 
     CTSIMAGE: [Input] Two-dimensional image (n_x,n_y) containing the counts 
               per pixel of the *added* images IMAGE and IMAGE2. Necessary 
               for very sparse X-ray data, where some pixels can contain no 
               counts. In these empty pixels, you might "artificially" have 
               a high S/N value, if both images are background subtracted.
               In this case, the so-called signal would simply be the
               hardness ratio of the two background values, instead of the 
               desired hardness of the object. If the counts image is 
               supplied, the binning algorithm doesn't allow bins without 
               any counts in them (recommended). However, note that this is 
               only a very rare case. Most hardness ratio maps will run fine 
               without this.
    KEEPFIXED: [Input] Vector (size 2 x n_fixed) contains x and y coordinates 
               of bin generators that you want to keep fixed in position.
               The binning algorithm will move all other bins around as usual.
               Example use: Keep one bin fixed on the center of a galaxy.
       PLOTIT: Set this keyword to one to produce a plot of the 2-D
               bins and of the corresponding S/N at the end of the
               computation. A value of two will produce a similar plot 
               after the bin accretion step. Setting PLOTIT higher than 
        QUIET: by default the program shows the progress while accreting
               pixels and then while iterating the CVT. Set this keyword
               to avoid printing progess results. 
       RESUME: Set this keyword, if you want to start from an existing WVT. 
               which is uniquely defined in the structure SAVE_ALL
     SAVE_ALL: [Output/Input] Structure that saves all of the necessary 
               information to restart WVT_XRAYCOLOR from any given point. If
               keyword RESUME is set, the WVT iteration scheme is applied 
               to the supplied WVT.

 EXTERNAL INTERACTIVE CONTROLS
       PLOTIT: If you decide to plot the iteration steps, create 
               file in the current directory with the name 'plotit'. A simple
               way to do this is to issue the command 'touch plotit' in a 
               shell. Remove the file if you want to stop plotting.
    STOPMENOW: If you want to terminate the iteration at the next iteration,
               create a file named 'stopmenow' in the current directory (e.g 
               'touch stopmenow').

 PROCEDURES PROVIDED:
       The following procedures are contained in the main WVT_BINNING program.
       Refer to the main code for further explanations.
            WVT_IMAGE           -- main interface

 FUNCTIONS PROVIDED:
       The following functions are contained in the main WVT_BINNING program.
       Refer to the main code for further explanations.
            ADD_SIGNAL          -- adds the signal of a bin (hardness ratios)
            ADD_NOISE           -- adds the noise of a bin 
      
 NOTE:
       WVT_BINNING uses the function MATCH from the IDL astro library. We
       included this function in the main program release for completeness.
       Feel free to remove the file match.pro if you already have the IDL 
       astro library (see idlastro.gsfc.nasa.gov/homepage.html) installed.

 MODIFICATION HISTORY:
       V1.0: First version, built on the old SD_VORONOI_COLOR and WVT_IMAGE
           (07/12/2005)
       V1.1: Bugfixes for keepfixed and max_area keywords (09/08/05)
       V1.2: Fixed bug when incompatible ADD_SIGNAL or ADD_NOISE functions
           are precompiled. (08/09/2005)
       V2.0: First published version (12/05/2005)
     

(See wvt_xraycolor.pro)