VorBin: Voronoi Binning of Two Dimensional Data
Project description
The VorBin Package
VorBin: Adaptive Voronoi Binning of Two Dimensional Data
This VorBin package is a Python implementation of the two-dimensional adaptive spatial binning method of Cappellari & Copin (2003). It uses Voronoi tessellations to bin data to a given minimum signal-to-noise ratio.
Attribution
If you use this software for your research, please cite Cappellari & Copin (2003) The BibTeX entry for the paper is:
@ARTICLE{Cappellari2003, author = {{Cappellari}, M. and {Copin}, Y.}, title = "{Adaptive spatial binning of integral-field spectroscopic data using Voronoi tessellations}", journal = {MNRAS}, eprint = {astro-ph/0302262}, year = 2003, volume = 342, pages = {345-354}, doi = {10.1046/j.1365-8711.2003.06541.x} }
Installation
install with:
pip install vorbin
Without writing access to the global site-packages directory, use:
pip install --user vorbin
Usage Example
To learn how to use the package VorBin run voronoi_2d_binning_example.py in the vorbin/examples directory, within the main package installation folder inside site-packages, and read the detailed documentation in the docstring of the file voronoi_2d_binning.py, on PyPi.
Perform the following simple steps to bin your own 2D data with minimal Python interaction:
Write your data vectors [X, Y, Signal, Noise] in the text file voronoi_2d_binning_example.txt, following the example provided;
Change the line targetSN = 50.0 in the procedure voronoi_2d_binning_example.py, to specify the desired target S/N of your final bins;
Run the program voronoi_2d_binning_example and wait for the final plot to appear. The output is saved in the text file voronoi_2d_binning_output.txt. The last column BIN_NUM in the file is all that is needed to actually bin the data;
Read the documentation at the beginning of the file voronoi_2d_binning.py to fully understand the meaning of the various optional output parameters.
voronoi_2d_binning Function
Perform adaptive spatial binning of 2D data to reach a chosen constant S/N per bin.
This program implements the algorithm described in section 5.1 of Cappellari & Copin (2003).
Calling Sequence
from vorbin.voronoi_2d_binning import voronoi_2d_binning
bin_number, x_gen, y_gen, x_bar, y_bar, sn, nPixels, scale = voronoi_2d_binning(
x, y, signal, noise, target_sn, cvt=True, pixelsize=None, plot=True,
quiet=True, sn_func=None, wvt=True)
Parameters
- x: array_like with shape (npix,)
A vector containing the X coordinates of the pixels to be binned. Arbitrary units can be used (e.g., arcseconds or pixels). In this context, “pixel” refers to a single spatial element of the dataset, sometimes called a “spaxel” in integral-field spectroscopy. It is assumed that the pixels are arranged on a regular grid; however, this grid can contain holes (pixels excluded from the binning) and have an irregular boundary.
- y: array_like with shape (npix,)
A vector containing the Y coordinates of the pixels to be binned.
- signal: array_like with shape (npix,)
A vector containing the signal associated with each pixel at coordinates (x, y). For an integral-field spectrograph, the signal could be the average flux in the spectral range of interest. For a CCD image, it would simply be the counts in each pixel.
- noise: array_like with shape (npix,)
A vector containing the corresponding noise (1-sigma error) for each pixel. While signal and noise are typically used to compute the binning, the S/N can also be calculated on-the-fly using the sn_func keyword. To create bins with approximately equal total signal, one can assume Poissonian noise by setting noise = np.sqrt(signal).
- target_sn: float
The desired signal-to-noise ratio for the final 2D-binned data. For example, a S/N of ~50 per spectral pixel is often a reasonable target for extracting stellar kinematics from galaxy spectra.
Other Parameters
- cvt: bool, optional
Set to False to skip the Centroidal Voronoi Tessellation (CVT) step (vii) of the algorithm from Cappellari & Copin (2003). This can be useful if the noise is strongly non-Poissonian, if the pixels are not optimally weighted, or if the CVT step appears to introduce significant gradients in the S/N. An alternative is to set wvt=True.
- plot: bool, optional
Set to True to generate a plot of the 2D bins and their corresponding S/N values at the end of the computation.
- pixelsize: float, optional
The pixel scale of the input data, which could be the size of a CCD pixel or a spaxel/lenslet in an integral-field spectrograph. This value is computed automatically by the program if not provided, but doing so can be time-consuming for large datasets. In such cases, it is recommended to provide the pixelsize value.
- sn_func: callable, optional
A generic function to calculate the S/N of a bin composed of spaxels at a given index. The function must have the following signature:
sn = func(index, signal, noise)
If sn_func=None, the binning will use the default _sn_func(), which implements equation (2) of Cappellari & Copin (2003). However, a more general user-defined function can be provided.
The value returned by sn_func() does not need to be an analytical function of S and N, nor does it need to be the actual S/N. Instead, it can be any quantity that the user wishes to equalize across the bins. For example, sn_func() could be a procedure that uses ppxf to measure the velocity dispersion from the coadded spectrum of the spaxels at index and returns the relative error in the dispersion.
Note that using an analytical approximation of S/N, like the default, will significantly speed up the calculation. For more details, refer to the docstring of _sn_func() in the voronoi_2d_binning.py file.
- quiet: bool, optional
By default, the program displays progress updates while accreting pixels and iterating the CVT. Set quiet=True to suppress these messages.
- wvt: bool, optional
When wvt=True, the bin2d_cvt_equal_mass routine is modified as proposed by Diehl & Statler (2006, MNRAS, 368, 497). In this case, the final step of the algorithm, following the bin-accretion stage, is a Weighted Voronoi Tessellation instead of a modified Centroidal Voronoi Tessellation. This may be beneficial if the noise is strongly non-Poissonian, if the pixels are not optimally weighted, or if the CVT step appears to introduce significant S/N gradients. An alternative is to set cvt=False. If you set wvt=True, please include a reference to “the WVT modification proposed by Diehl & Statler (2006).”
Returns
- bin_number: array_like with shape (npix,)
A vector containing the bin number assigned to each input pixel, with indices ranging from zero to nbin - 1.
IMPORTANT: This vector is all that is needed for any subsequent computations on the binned data. All other returned values are optional and can be disregarded.
- x_gen: array_like with shape (nbin,)
A vector of the X coordinates of the bin generators. These generators provide an alternative way of defining the Voronoi tessellation.
NOTE: The use of this vector is deprecated as it can be a source of confusion.
- y_gen: array_like with shape (nbin,)
A vector of the Y coordinates of the bin generators.
NOTE: The use of this vector is deprecated as it can be a source of confusion.
- x_bar: array_like with shape (nbin,)
A vector of the X coordinates of the luminosity-weighted centroids of the bins.
- y_bar: array_like with shape (nbin,)
A vector of the Y coordinates of the luminosity-weighted centroids of the bins.
- sn: array_like with shape (nbin,)
A vector of the final S/N for each bin.
- nPixels: array_like with shape (nbin,)
A vector of the number of pixels in each bin.
- scale: array_like with shape (nbin,)
A vector of the scale length for each bin. This is needed to reconstruct the tessellation if wvt=True.
When some pixels have no signal
Binning should not be used blindly when some pixels contain significant noise but virtually no signal. This situation may happen e.g. when extracting the gas kinematics from observed galaxy spectra. One way of using voronoi_2d_binning consists of first selecting the pixels with S/N above a minimum threshold and then binning each set of connected pixels separately. Alternatively one may optimally weight the pixels before binning. For details, see Sec. 2.1 of Cappellari & Copin (2003).
Binning X-ray data
For X-ray data, or other data coming from photon-counting devices the noise is generally accurately Poissonian. In the Poissonian case, the S/N in a bin can never decrease by adding a pixel [see Sec.2.1 of Cappellari & Copin (2003)], and it is preferable to bin the data without first removing the observed pixels with no signal.
Binning very big images
Computation time in voronoi_2d_binning scales nearly as npixels^1.5, so it may become a problem for large images (e.g. at the time of writing npixels > 1000x1000). Let’s assume that we really need to bin the image as a whole and that the S/N in a significant number of pixels is well above our target S/N. As for many other computational problems, a way to radically decrease the computation time consists of proceeding hierarchically. Suppose for example we have a 4000x4000 pixels image, we can do the following:
Rebin the image regularly (e.g. in groups of 8x8 pixels) to a manageable size of 500x500 pixels;
Apply the standard Voronoi 2D-binning procedure to the 500x500 image;
Transform all unbinned pixels (which already have enough S/N) of the 500x500 Voronoi 2D-binned image back into their original individual full-resolution pixels;
Now apply Voronoi 2D-binning only to the connected regions of full-resolution pixels;
Merge the set of lower resolution bins with the higher resolution ones.
License
Other/Proprietary License
Copyright (c) 2001-2025 Michele Cappellari
This software is provided as is with no warranty. You may use it for non-commercial purposes and modify it for personal or internal use, as long as you include this copyright and disclaimer in all copies. You may not redistribute the code.
Changelog
V3.1.7: MC, Oxford, 17 June 2025
Resolved a mismatch between the wheel and source distributions that could cause VorBin to fail in the wheel version. Thanks to Daniele Gasparri for reporting this issue.
V3.1.5: MC, Oxford, 24 February 2022
Included test for repetitions in _cvt_equal_mass to avoid the possibility of cycling. Thanks to Peter Weilbacher (aip.de) for the report, a detailed example of producing the problem, and subsequent testing.
V3.1.4: MC, Oxford, 19 February 2020
Formatted documentation as docstring.
V3.1.3: MC, Oxford, 27 September 2018
Fixed clock DeprecationWarning in Python 3.7.
V3.1.2: MC, Oxford, 10 May 2018
Dropped legacy Python 2.7 support.
V3.1.1: MC, Oxford, 15 September 2017
Stops if unbinned pixels do not have enough S/N.
Removed weighted centroid function.
V3.1.0: MC, Oxford, 17 July 2017
Use cKDTree for much faster un-weighted Voronoi Tessellation.
Removed loop over bins from Lloyd’s algorithm with CVT.
V3.0.9: MC, Oxford, 10 July 2017
Do not iterate down to diff==0 in _cvt_equal_mass().
Request pixelsize when the dataset is large. Thanks to Davor Krajnovic (Potsdam) for the feedback.
Make quiet really quiet.
Fixed some instances where sn_func() was not being used (only relevant when passing the sn_func keyword).
V3.0.8: MC, Oxford, 15 February 2017
New voronoi_tessellation() function.
V3.0.7: MC, Oxford, 23 January 2017
Print execution time.
V3.0.6: MC, Oxford, 14 June 2016
Use interpolation='nearest' to avoid crashes on MacOS. Thanks to Kyle Westfall (Portsmouth) for reporting the problem.
Allow for zero noise.
V3.0.5: MC, Oxford, 18 April 2016
Fixed deprecation warning in NumPy 1.11.
V3.0.4: MC, Oxford, 12 April 2016
Included keyword “sn_func” to pass a function which calculates the S/N of a bin, rather than editing _sn_func().
Included test to prevent the addition of a pixel from ever decreasing the S/N during the accretion stage.
V3.0.3: MC, Oxford, 31 March 2016
Use for loop to calculate Voronoi tessellation of large arrays to reduce memory usage. Thanks to Peter Weilbacher (Potsdam) for reporting the problem and providing the solution.
V3.0.2: MC, Oxford, 2 October 2014
Avoid potential runtime warnings while plotting.
V3.0.1: MC, Oxford, 25 May 2014
Support both Python 2.7 and Python 3.
V3.0.0: MC, London, 19 March 2014
Translated from IDL into Python and tested against the original.
V2.6.0: MC, London, 19 March 2014
Included new SN_FUNCTION to illustrate the fact that the user can define a custom function to estimate the S/N of a bin if needed.
V2.5.8: MC, La Palma, 15 May 2012
Update Voronoi tessellation at the exit of bin2d_cvt_equal_mass. This is only done when using /WVT, as DIFF may not be zero at the last iteration.
V2.5.7: MC, Oxford, 24 March 2012
Included safety termination criterion of Lloyd algorithm to prevent loops using /WVT.
V2.5.6: MC, Oxford, 11 November 2011
Use IDL intrinsic function DISTANCE_MEASURE for automatic pixelSize, when PIXSIZE keyword is not given.
V2.5.5: MC, Oxford, 28 April 2010
Added PIXSIZE keyword.
V2.5.4: MC, Oxford, 30 November 2009
Improved color shuffling for the final plot.
V2.5.3: MC, Oxford, 3 December 2007
Fixed program stop, introduced in V2.5.0, with /NO_CVT keyword.
V2.5.2: MC, Oxford, 28 March 2007
Print number of unbinned pixels.
V2.5.1: MC, Oxford, 3 November 2006
Updated documentation.
V2.5.0: MC, Leiden, 9 March 2006
Added two new lines of code and the corresponding /WVT keyword to implement the nice modification to the algorithm proposed by Diehl & Statler (2006).
V2.4.8: MC, Leiden, 23 December 2005
Use geometric centroid of a bin during the bin-accretion stage, to allow the routine to deal with negative signal (e.g. in background-subtracted X-ray images). Thanks to Steven Diehl for pointing out the usefulness of dealing with negative signal.
V2.4.7: MC, Leiden, 27 September 2005
Verify that SIGNAL and NOISE are non-negative vectors.
V2.4.6: MC, Leiden, 27 August 2005
Added /NO_CVT keyword to optionally skip the CVT step of the algorithm.
V2.4.5: MC, Leiden, 3 December 2004
Added BIN2D prefix to internal routines to avoid possible naming conflicts.
V2.4.4: MC, Leiden, 30 November 2004
Prevent division by zero for pixels with signal=0 and noise=sqrt(signal)=0, as can happen from X-ray data.
V2.4.3: MC, Leiden, 29 November 2004
Corrected bug introduced in version 2.3.1. It went undetected for a long time because it could only happen in special conditions. Now we recompute the index of the good bins after computing all centroids of the reassigned bins in reassign_bad_bins. Many thanks to Simona Ghizzardi for her clear analysis of the problem and the solution.
V2.4.2: MC, Leiden, 4 August 2004
Use LONARR instead of INTARR to define the CLASS vector, to be able to deal with big images. Thanks to Tom Statler.
V2.4.1: MC, Leiden, 14 December 2003
Added /QUIET keyword and verbose output during the computation. After suggestion by Richard McDermid.
V2.4.0: MC, Leiden, 10 December 2003
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.
V2.3.1: MC, Leiden, 13 April 2003
Do not assume the first bin is made of one single pixel.
Added computation of S/N scatter and plotting of 1-pixel bins.
V2.3.0: MC, Leiden, 9 April 2003
Unified the three tests to stop the accretion of one bin. This can improve some bins at the border.
V2.2.0: MC, Leiden, 11 March 2003
Added computation of useful bin quantities in output. Deleted some safety checks for zero-size bins in CVT. Minor polishing of the code.
V2.1.0: MC, Vicenza, 13 February 2003
First released version. Written documentation.
V2.0.0: MC, Leiden, 11 September 2001
Major revisions. Stable version.
V1.0.0: Michele Cappellari, Leiden, June 2001
First working implementation.
First working implementation.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file vorbin-3.1.7.tar.gz
.
File metadata
- Download URL: vorbin-3.1.7.tar.gz
- Upload date:
- Size: 116.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
a8568bbc55498d465bab8596da6db50fbc012600d22aac6f8d7cd032175ae293
|
|
MD5 |
1486cb5844e6a1f0391c86ae6b0d5400
|
|
BLAKE2b-256 |
dbc9f6ca39118a536dc41975d6b8b7319560000d2c1158e9b66d4f70e6ba4e02
|
File details
Details for the file vorbin-3.1.7-py3-none-any.whl
.
File metadata
- Download URL: vorbin-3.1.7-py3-none-any.whl
- Upload date:
- Size: 113.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
e886351235a7252239eec00d22b7e417b5ab2d6b3c2fccdd52a27dd77a31e37f
|
|
MD5 |
0ff8132f209f074cf56da79e2f0cb8db
|
|
BLAKE2b-256 |
555964fb45f0267d375082a118b221e85624de4cb5fcf116eef9cd23e7fff944
|