convolve

sofia_redux.toolkit.convolve.kernel.convolve(*args, error=None, mask=None, stats=False, do_error=None, robust=0, eps=0.01, maxiter=100, normalize=True, ignorenans=True, **kwargs)[source]

Convolve an N-dimensional array with a user defined kernel or fixed box.

A wrapper function for the KernelConvolve.

Parameters:
args[samples], data, kernel

“data” must be an n-dimensional array of size (shape,). Optionally, coordinate values for each data element may be provided for each dimension (“samples”). If not provided, they will be determined to be regularly spaced at unit intervals. “samples” must be provided for each dimension (x, y, z, … order), where each array matches the data (shape,). Finally, a kernel of the same dimensions as “data” must be provided following the “data” argument. If “kernel” is an integer, a box kernel will be applied with a width of “kernel” over each dimension.

errorfloat or int or array, optional

A scalar value containing the error for each data point or an array of values may be provided and propagated through the convolution and interpolation. If provided, and “do_error” is None or True, the returned result will be a tuple of the form (convolved_result, error).

maskarray of bool, optional

If provided must match data (shape,). False values indicate data locations that should be excluded from convolution calculations. False values will be replaced by linear interpolated values.

statsbool, optional

If True, return statistics on the convolution/interpolation in the returned result.

do_errorbool, optional

If True, and error is not None, return the propagated error in addition to the result.

robustint or float, optional

If non-zero, will perform iterations of the convolution, masking out data points if the abs(residual/error) is greater than “robust”. Iteration will continue until the delta_sigma/sigma ratio is less than “eps”.

epsfloat, optional

The precision limit for use in the “robust” iteration process.

maxiterint, optional

The maximum number of iterations to attempt in “robust” iteration.

normalizebool, optional

If True, the kernel will be normalized such that sum(kernel) = 1 prior to convolution.

ignorenansbool, optional

If True, NaNs will be masked out during convolution and interpolation. Otherwise, they will propagate through all calculations.

kwargsdict, optional

Optional keyword arguments to pass into BoxConvolve or KernelConvolve parent class.

Returns:
convolved_result, [error], [statistics]array or tuple of array

The convolved result, and optional propagated error (if “error” is provided and “do_error” is not “False”) and statistics (if “stats” is True. The output shape for the result and error will be the same as the input data.