ndfilters

ndfilters is a library of n-dimensional image filters similar to those in scipy.ndimage, but accelerated and parallelized using Numba.

Compared to their scipy.ndimage equivalents, the filters in this library offer some additional capabilities:

• Axis selection. Every filter accepts an axis argument, so the kernel can be applied to any subset of the array's axes while the remaining axes act as batch dimensions.
• Masking. A boolean where mask excludes selected elements of the input array from the calculation.
• Physical units. Inputs can be either numpy.ndarray or astropy.units.Quantity instances.
• Varying kernels. The convolution kernel is allowed to change along axes orthogonal to the convolution axes.

Differences from scipy.ndimage

Where a filter in this library has a scipy.ndimage counterpart, the two agree except in the following cases.

• Boundary modes. Only "mirror", "nearest", and "wrap" are supported, plus "truncate", which has no scipy.ndimage equivalent and simply drops the parts of the kernel that fall outside the array. SciPy's "reflect", "constant", and "grid-*" modes raise a ValueError here.
• Integer input. Integer arrays are promoted to floating point, so the result is a float and is not truncated. scipy.ndimage returns the dtype of the input, and for the separable filters it truncates its intermediates as well. The promotion is what lets a where mask that excludes an entire kernel footprint return NaN.
• Even-sized median footprints. ndfilters.median_filter averages the two middle elements, like numpy.median, while scipy.ndimage.median_filter selects the element of rank size // 2, the larger of the two. SciPy's convention keeps the result in the dtype of the input and never introduces a value that was not already in the footprint, but it is a biased estimator: on unit-variance noise a size=2 filter shifts the signal by roughly 0.57. The two conventions agree exactly for odd-sized footprints.

The full documentation is hosted on Read the Docs.

Installation

ndfilters is published on PyPI and can be installed using pip.

pip install ndfilters

Quickstart

Every filter takes an array and the shape of the kernel, and returns the filtered array.

import scipy.datasets
import ndfilters

img = scipy.datasets.ascent()
img_filtered = ndfilters.median_filter(img, size=21)

Gallery

Mean filter

The mean filter calculates a multidimensional rolling mean for the given kernel shape.

Trimmed mean filter

The trimmed mean filter is like the mean filter except it ignores a given portion of the dataset before calculating the mean at each pixel.

Median filter

The median filter calculates a multidimensional rolling median for the given kernel shape.

Variance filter

The variance filter calculates the rolling variance for the given kernel shape.

Generic filter

The generic filter applies an arbitrary compiled function to each kernel footprint. It is the engine behind the other rolling filters in this library, and it can be used directly to build custom filters.

Convolution

ndfilters.convolve() convolves an array with a given kernel. Unlike scipy.ndimage.convolve() or astropy.convolution.convolve(), the kernel is allowed to vary along axes orthogonal to the convolution axes.

Citation

If you use ndfilters in your research, please cite it. The citation metadata is kept in CITATION.cff, which the "Cite this repository" button on GitHub can export as BibTeX or APA. Please include the version of ndfilters that you used, which is given by importlib.metadata.version("ndfilters").

@software{ndfilters,
  author = {Smart, Roy T.},
  title = {ndfilters},
  version = {X.Y.Z},
  url = {https://github.com/sun-data/ndfilters},
}