convolve

astropy.convolution.convolve(array, kernel, boundary='fill', fill_value=0.0, nan_treatment='interpolate', normalize_kernel=True, mask=None, preserve_nan=False, normalization_zero_tol=1e-08)[source]

Convolve an array with a kernel.

This routine differs from scipy.ndimage.convolve because it includes a special treatment for NaN values. Rather than including NaN values in the array in the convolution calculation, which causes large NaN holes in the convolved array, NaN values are replaced with interpolated values using the kernel as an interpolation function.

Parameters:
arrayNDData or array_like

The array to convolve. This should be a 1, 2, or 3-dimensional array or a list or a set of nested lists representing a 1, 2, or 3-dimensional array. If an NDData, the mask of the NDData will be used as the mask argument.

kernelnumpy.ndarray or Kernel

The convolution kernel. The number of dimensions should match those for the array, and the dimensions should be odd in all directions. If a masked array, the masked values will be replaced by fill_value.

boundarystr, optional
A flag indicating how to handle boundaries:
  • None

    Set the result values to zero where the kernel extends beyond the edge of the array.

  • ‘fill’

    Set values outside the array boundary to fill_value (default).

  • ‘wrap’

    Periodic boundary that wrap to the other side of array.

  • ‘extend’

    Set values outside the array to the nearest array value.

fill_valuefloat, optional

The value to use outside the array when using boundary='fill'.

normalize_kernelbool, optional

Whether to normalize the kernel to have a sum of one.

nan_treatment{‘interpolate’, ‘fill’}, optional
The method used to handle NaNs in the input array:

  • 'interpolate': NaN values are replaced with interpolated values using the kernel as an interpolation function. Note that if the kernel has a sum equal to zero, NaN interpolation is not possible and will raise an exception.

  • 'fill': NaN values are replaced by fill_value prior to convolution.

preserve_nanbool, optional

After performing convolution, should pixels that were originally NaN again become NaN?

maskNone or ndarray, optional

A “mask” array. Shape must match array, and anything that is masked (i.e., not 0/False) will be set to NaN for the convolution. If None, no masking will be performed unless array is a masked array. If mask is not None and array is a masked array, a pixel is masked if it is masked in either mask or array.mask.

normalization_zero_tolfloat, optional

The absolute tolerance on whether the kernel is different than zero. If the kernel sums to zero to within this precision, it cannot be normalized. Default is “1e-8”.

Returns:
resultnumpy.ndarray

An array with the same dimensions and as the input array, convolved with kernel. The data type depends on the input array type. If array is a floating point type, then the return array keeps the same data type, otherwise the type is numpy.float.

Notes

For masked arrays, masked values are treated as NaNs. The convolution is always done at numpy.float precision.