lezargus.library.convolution module#

Convolution functions and kernel producing functions.

Here, we group all convolution functions and kernel functions. A lot of the convolution functions are brief wrappers around Astropy’s convolution. All three dimensionalities are covered.

lezargus.library.convolution._check_array_dimensionality(array: hint.NDArray, dimensions: int) bool[source]#

Check if the array has the expected number of dimensions.

This function checks if the array has the correction number of dimensions. Of course, the expected dimensions are different so this function is more a wrapper around the logging message and it serves as a basic check.

Parameters:
  • array (ndarray) – The array that we are testing if it has the same number of dimensions.

  • dimensions (int) – The number of expected dimensions the array should have.

Returns:

valid_dimensionality – If True, the array has the expected dimensionality, as input.

Return type:

bool

lezargus.library.convolution._check_array_kernel_variable_stack(array: hint.NDArray, kernel_stack: hint.NDArray, axis: int | tuple[int]) bool[source]#

Check if the kernel stack and array have the exact slice count.

For variable kernels, we need to make sure that there are enough kernels in the kernel stack for each slice of the array which are being convolved. The axes which are variable (and not dynamic, i.e. changing with the convolution axis) are checked to be the same size in the array and the kernel stack.

Parameters:
  • array (ndarray) – The array which would be convolved and which we are checking is compatible with the kernel stack.

  • kernel_stack (ndarray) – The kernel stack which holds all of the kernels that are being used. We are checking if it is compatible with the kernel stack.

  • axis (int, tuple[int]) – Either a single axis index, or a tuple of axis indexes which the kernel is variable. The axis or axes should not be the same as the convolution axis or axes.

Returns:

valid_stack – If True, the kernel stack has the correct amount of kernels for the array, for the axes which are variable.

Return type:

bool

lezargus.library.convolution._check_kernel_dimensionality(kernel: hint.NDArray, dimensions: int) bool[source]#

Check if the kernel has the expected number of dimensions.

Same function as _check_array_dimensionality(), just different error message.

Parameters:
  • kernel (ndarray) – The kernel that we are testing if it has the same number of dimensions.

  • dimensions (int) – The number of expected dimensions the kernel should have.

Returns:

valid_dimensionality – If True, the kernel has the expected dimensionality, as input.

Return type:

bool

lezargus.library.convolution._static_astropy_convolve(array: hint.NDArray, kernel: hint.NDArray) hint.NDArray[source]#

Use Astropy to convolve the array provided the kernel.

The Astropy convolve function only can convolve up to 3D, and they determine it based on the array and kernel dimensionality. We attempt to do an FFT convolution, but, should it fail, we fall back to discrete convolution.

Parameters:
  • array (ndarray) – The array we are convolving by the kernel.

  • kernel (ndarray) – The kernel we are using to convolve.

Returns:

convolved – The result of the convolution.

Return type:

ndarray

lezargus.library.convolution.kernel_1d_gaussian(shape: tuple | int, stddev: float) hint.NDArray[source]#

Return a 1D Gaussian convolution kernel.

We normalize the kernel via the amplitude of the Gaussian function as a whole for maximal precision: volume = 1. The stddev must be expressed in pixels.

Parameters:
  • shape (tuple | int) – The shape of the 1D kernel, in pixels. If a single value (i.e. a size value instead), we attempt convert it to a shape-like value.

  • stddev (float) – The standard deviation of the Gaussian, in pixels.

Returns:

gaussian_kernel – The discrete kernel array.

Return type:

ndarray

lezargus.library.convolution.kernel_1d_gaussian_resolution(shape: tuple | int, template_wavelength: hint.NDArray | float, base_resolution: float | None = None, target_resolution: float | None = None, base_resolving_power: float | None = None, target_resolving_power: float | None = None, reference_wavelength: float | None = None) hint.NDArray[source]#

Gaussian 1D kernel adapted for resolution convolution conversions.

This function is a wrapper around a normal 1D Gaussian kernel. Instead of specifying the standard deviation, we calculate the approximate required standard deviation needed to down-sample a base resolution to some target resolution. We accept both resolution values or resolving power values for the calculation; but we default to resolution based determination if possible.

Parameters:
  • shape (tuple | int) – The shape of the 1D kernel, in pixels. If a single value (i.e. a size value instead), we attempt convert it to a shape-like value.

  • template_wavelength (ndarray or float) – An example wavelength array which this kernel will be applied to. This is required to convert the physical standard deviation value calculated from the resolution/resolving power to one of length in pixels/points. If an array, we try and compute the conversion factor. If a float, that is the conversion factor of wavelength per pixel.

  • base_resolution (float, default = None) – The base resolution that we are converting from. Must be provided along with target_resolution for the resolution mode.

  • target_resolution (float, default = None) – The target resolution we are converting to. Must be provided along with base_resolution for the resolution mode.

  • base_resolving_power (float, default = None) – The base resolving power that we are converting from. Must be provided along with target_resolving_power and reference_wavelength for the resolving power mode.

  • target_resolving_power (float, default = None) – The target resolving power that we are converting from. Must be provided along with base_resolving_power and reference_wavelength for the resolving power mode.

  • reference_wavelength (float, default = None) – The reference wavelength used to convert from resolving power to resolution. Must be provided along with base_resolving_power and target_resolving_power for the resolving power mode.

Returns:

resolution_kernel – The Gaussian kernel with the appropriate parameters to convert from the base resolution to the target resolution with a convolution.

Return type:

ndarray

lezargus.library.convolution.kernel_2d_gaussian(shape: tuple, x_stddev: float, y_stddev: float, rotation: float) hint.NDArray[source]#

Return a 2D Gaussian convolution kernel.

We normalize the kernel via the amplitude of the Gaussian function as a whole for maximal precision: volume = 1. We require the input of the shape of the kernel to allow for x_stddev and y_stddev to be expressed in pixels to keep it general. By definition, the center of the Gaussian kernel is in the center of the array.

Parameters:
  • shape (tuple) – The shape of the 2D kernel, in pixels.

  • x_stddev (float) – The standard deviation of the Gaussian in the x direction, in pixels.

  • y_stddev (float) – The standard deviation of the Gaussian in the y direction, in pixels.

  • rotation (float) – The rotation angle, increasing counterclockwise, in radians.

Returns:

gaussian_kernel – The discrete kernel array.

Return type:

ndarray

lezargus.library.convolution.static_1d_with_1d(array: hint.NDArray, kernel: hint.NDArray) hint.NDArray[source]#

Convolve a 1D array using a static 1D kernel.

Parameters:
  • array (ndarray) – The 1D array data which we will convolve.

  • kernel (ndarray) – The 1D kernel that we are using to convolve.

Returns:

convolved – The convolved 1D array data.

Return type:

ndarray

lezargus.library.convolution.static_2d_with_2d(array: hint.NDArray, kernel: hint.NDArray) hint.NDArray[source]#

Convolve a 2D array using a static 2D kernel.

Parameters:
  • array (ndarray) – The 2D array data which we will convolve.

  • kernel (ndarray) – The 2D kernel that we are using to convolve.

Returns:

convolved – The convolved 2D array data.

Return type:

ndarray

lezargus.library.convolution.static_3d_with_1d_over_z(array: hint.NDArray, kernel: hint.NDArray) hint.NDArray[source]#

Convolve a 3D array using a 1D kernel, over the z dimension.

This convolution convolves 1D slices of the 3D array. The convolution itself then is a 1D array being convolved with a 1D kernel. We take slices of the last dimension (z), iterating over the 1st and 2nd dimension.

Parameters:
  • array (ndarray) – The 3D array data which we will convolve.

  • kernel (ndarray) – The 1D kernel that we are using to convolve over the z axis of the array.

Returns:

convolved – The convolved 3D array data.

Return type:

ndarray

lezargus.library.convolution.static_3d_with_2d_over_xy(array: hint.NDArray, kernel: hint.NDArray) hint.NDArray[source]#

Convolve a 3D array using a 2D kernel, over the x-y plane.

This convolution convolves 2D slices of the 3D array. The convolution itself then is a 2D array being convolved with a 3D kernel. A full 3D array and 3D kernel convolution is not done here.

Parameters:
  • array (ndarray) – The 3D array data which we will convolve.

  • kernel (ndarray) – The 2D kernel that we are using to convolve over the x-y plane of the array.

Returns:

convolved – The convolved 3D array data.

Return type:

ndarray

lezargus.library.convolution.variable_3d_with_2d_over_xy(array: hint.NDArray, kernel_stack: hint.NDArray) hint.NDArray[source]#

Convolve a 3D array using a variable 2D kernel, over the x-y plane.

Like py:func:static_3d_with_2d_over_xy, this convolution convolves 2D slices of the 3D array. However, the kernel here is variable in in the z dimension.

Parameters:
  • array (ndarray) – The 3D array data which we will convolve.

  • kernel_stack (ndarray) – The 2D kernel stack that we are using to convolve over the x-y plane of the array. Each slice of the stack should correspond to the kernel for the slice of the array.

Returns:

convolved – The convolved 3D array data.

Return type:

ndarray