FilterConvolution

class speclite.filters.FilterConvolution(response, wavelength, photon_weighted=True, interpolate=False, units=None)

Bases: object

Convolve a filter response with a tabulated function.

See above for details on how the convolution operator implemented by this class is defined, and here for details on how the convolution integrand is sampled.

Most of the computation involved depends only on the tabulated function’s wavelength grid, and not on the function values, so this class does the necessary initialization in its constructor, resulting in a function object that can be efficiently re-used with different function values.

Use this class to efficiently perform repeated convolutions of different tabulated functions for the same filter on the same wavelength grid. When efficiency is not important or the wavelength grid changes for each convolution, the convencience method FilterResponse.convolve_with_array() can be used instead.

Parameters:

responseFilterResponse or str

A FilterResponse object or else a fully qualified name of the form “<group_name>-<band_name>”, which will be loaded using load_filter().

wavelengtharray

A valid array of wavelengths that must cover the full range of the filter response.

photon_weightedbool

Use weights appropriate for a photon-counting detector such as a CCD when this parameter is True. Otherwise, use unit weights.

interpolatebool

Allow interpolation of the tabulated function if necessary. Interpolation is required if two or more of the wavelengths where the filter response is tabulated fall between a consecutive pair of input wavelengths. Linear interpolation is then performed to estimate the input function at the undersampled filter response wavelengths. Interpolation has a performance impact when evaluating a convolution, so is not enabled by default and can usually be avoided with finer sampling of the input function.

unitsastropy.units.Quantity or None

When this parameter is not None, then any explicit units attached to the values passed to a convolution must be convertible to these units. When values are passed without units they are assumed to be in these units.

Attributes:

responseFilterResponse

The filter response used for this convolution.

input_unitsastropy.units.Unit

Units expected for values passed to __call__().

output_unitsastropy.units.Unit

Units of __call__() result.

num_wavelengthint

The number of wavelengths used to tabulate input functions.

response_gridnumpy.ndarray

Array of filter response values evaluated at each wavelength.

response_sliceslice

Slice of the input wavelength grid used for convolution.

interpolate_wavelengthnumpy.ndarray or None

Array of wavelengths where the input function will be interpolated.

interpolate_responsenumpy.ndarray or None

Array of filter response values at each interpolate_wavelength.

interpolate_sort_ordernumpy.ndarray or None

Integer array specifying the sort order required to combine wavelength and interpolate_wavelength.

quad_wavelengthnumpy.ndarray

Array of wavelengths used for numerical quadrature, combining both wavelength and interpolate_wavelength.

quad_weightastropy.units.Quantity or None

Array of weights corresponding to each quad_wavelength. Will be None if the parameter photon_weighted = False.

Methods Summary

__call__(values[, axis, method, plot])

Evaluate the convolution for arbitrary tabulated function values.

Methods Documentation

__call__(values, axis=-1, method='trapz', plot=False)

Evaluate the convolution for arbitrary tabulated function values.

Parameters:

valuesarray or astropy.units.Quantity

Array of function values to use. Values are assumed to be tabulated on our wavelength grid. Values can be multidimensional, in which case an array of convolution results is returned. If values have units, then these are propagated to the result.

axisint

In case of multidimensional function values, this specifies the index of the axis corresponding to the wavelength dimension.

methodstr

Specifies the numerical integration scheme to use and must be either ‘trapz’ or ‘simps’, to select the corresponding scipy.integration function. The ‘simps’ method may be more accurate than the default ‘trapz’ method, but should be used with care since it is also less robust and more sensitive to the wavelength grids.

plotbool

Displays a plot illustrating how the convolution integrand is constructed. Requires that the matplotlib package is installed and does not support multidimensional input values. This option is primarily intended for debugging and to generate figures for the documentation.

Returns:

float or numpy.ndarray or astropy.units.Quantity

Convolution integral result. If the input values have units then these are propagated to the result, including the units associated with the photon weights (if these are selected). Otherwise, the result will be a plain float or numpy array. If the input is multidimensional, then so is the result but with the specified axis integrated out.