Skip to main content
`Ctrl`+`K`

# 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)

  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:
    array `NDData` or numpy: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.

    kernel `numpy.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`.

    boundary `python:str`, 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_value `python:float`, optional

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

    normalize_kernel bool, 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_nan bool, optional

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

    mask `python:None` 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_tol `python:float`, 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:
    result `numpy.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.