lezargus.library.interpolate module

Contents

lezargus.library.interpolate module#

Interpolation routines, across both multi-dimensional and multi-mode.

We have many interpolation functions for a wide variety of use cases. We store all of them here. We usually derive the more specialty interpolation functions from a set of base functions.

class lezargus.library.interpolate.Generic1DInterpolate(x: hint.NDArray, v: hint.NDArray, extrapolate: bool = False, extrapolate_fill: float = nan, gap: float = inf, gap_fill: float = nan)[source]#

Bases: object

Internal class for 1D interpolators, the exact method to be determined.

This class is mostly a wrapper class around other implementations of interpolators to provide a unified interface for special handling of the different styles of interpolations and some edge cases.

To build a more specific interpolation class, create a subclass of this method and override the _interpolator_generator() function with the detail implementation to integrate the wrapped interpolator.

x#

The input which we will be using to interpolate from. This is not always the same as the input parameters due to data sanitization.

Type:

ndarray

v#

The output which we will be using to interpolate from. This is not always the same as the input parameters due to data sanitization.

Type:

ndarray

raw_interpolator#

The interpolator generated which this class wraps around.

Type:

function

extrapolate#

If True, we extrapolate outside the bounds of the domain. Else we fill with extrapolate_fill

Type:

bool

extrapolate_fill#

The value used to fill out of bounds interpolations if extrapolate is False.

Type:

float

gap#

The minimum gap spacing in the domain values for the domain to be considered a gap. Interpolated values in a gap filled with gap_fill.

Type:

float

gap_fill#

The value used to fill interpolations in gaps.

Type:

float

gap_bounds#

The boundaries of the gaps, an internal cached value used to determine if inputted values are within gaps or not. One minimum and one maximum parallel tuples are stored.

Type:

tuple[tuple, tuple]

__call__(x: hint.NDArray) hint.NDArray#

Interpolate the input value.

Parameters:

x (ndarray) – The input that we are going to interpolate given the values we have.

Returns:

v – The values after interpolation, taking into account any criteria.

Return type:

ndarray

__init__(x: hint.NDArray, v: hint.NDArray, extrapolate: bool = False, extrapolate_fill: float = nan, gap: float = inf, gap_fill: float = nan) None[source]#

Create the interpolator.

Parameters:
  • x (ndarray) – The input for interpolation.

  • v (ndarray) – The output for interpolation.

  • extrapolate (bool, default = False) – If True, we extrapolate, else we use the fill value.

  • extrapolate_fill (float, default = np.nan) – The fill value for interpolations outside of the domain without extrapolation.

  • gap (float, default = 0) – The minimum spacing between input points for it to be a gap. We default to +inf, so no gaps.

  • gap_fill (float, default = np.nan) – The fill value to fill in for interpolations inside a gap region.

Return type:

None

_apply_extrapolation_criteria(interp_x: hint.NDArray, interp_v: hint.NDArray) hint.NDArray[source]#

Apply the extrapolation criteria to interpolated data.

Namely, if there was to be no extrapolation, we replace any data with the extrapolation fill value.

Parameters:
  • interp_x (ndarray) – The interpolated input values.

  • interp_v (ndarray) – The interpolated output values which we will apply the criteria too.

Returns:

output – A copy of the interpolated output after the criteria has been applied.

Return type:

ndarray

_apply_gap_criteria(interp_x: hint.NDArray, interp_v: hint.NDArray) hint.NDArray[source]#

Apply the gap criteria to interpolated data.

Namely, if the interpolated value falls within a gap, we replace the value with the gap fill value.

Parameters:
  • interp_x (ndarray) – The interpolated input values.

  • interp_v (ndarray) – The interpolated output values which we will apply the criteria too.

Returns:

output – A copy of the interpolated output after the criteria has been applied.

Return type:

ndarray

_calculate_gap_bounds() tuple[hint.NDArray, hint.NDArray][source]#

Calculate the gap lower and upper bounds.

Parameters:

None

Returns:

  • lower_bounds (tuple) – The lower bound values of the found gaps.

  • upper_bounds (tuple) – The upper bound values of the found gaps.

static _interpolator_generator(x: hint.NDArray, v: hint.NDArray) hint.Callable[[hint.NDArray], hint.NDArray][source]#

Define the integration with the wrapped interpolator here.

This function needs to be overwritten with the implementation of the wrapped interpolator before using a class derived from this class.

Parameters:
  • x (ndarray) – The input data which will be fed to the interpolator.

  • v (ndarray) – The output data which will be fed to the interpolator.

Returns:

interpolator – The interpolator function. It should accept the input provided by py:meth:interpolate as a parameter.

Return type:

Callable

interpolate(x: hint.NDArray) hint.NDArray[source]#

Interpolate the input value.

Parameters:

x (ndarray) – The input that we are going to interpolate given the values we have.

Returns:

v – The values after interpolation, taking into account any criteria.

Return type:

ndarray

classmethod template_class(**kwargs: hint.Any) hint.Callable[[hint.NDArray, hint.NDArray], hint.Self][source]#

Provide a template with the same flags as this interpolator class.

This function does the same thing as template_instance(), but this function operates on the class itself as opposed to the instance.

Parameters:

**kwargs (Any) – Any keyword arguments provided will be passed to the constructor, overriding any local flags for the purposes of creating the template function.

Returns:

interpolator_template – The interpolator template with all of the flags the same as this current instance.

Return type:

Callable

template_instance(**kwargs: hint.Any) hint.Callable[[hint.NDArray, hint.NDArray], hint.Self][source]#

Provide a template with the same flags as this interpolator.

Sometimes it is needed to have an interpolator which you can make on the fly. This function makes an interpolator template. Data still needs to be provided to defined to make the interpolator from the template; but the flags are kept the same.

Parameters:

**kwargs (Any) – Any keyword arguments provided will be passed to the constructor, overriding any local flags for the purposes of creating the template function.

Returns:

interpolator_template – The interpolator template with all of the flags the same as this current instance.

Return type:

Callable

class lezargus.library.interpolate.Linear1DInterpolate(x: hint.NDArray, v: hint.NDArray, extrapolate: bool = False, extrapolate_fill: float = nan, gap: float = inf, gap_fill: float = nan)[source]#

Bases: Generic1DInterpolate

Linear based interpolation class.

A simple linear interpolator.

static _interpolator_generator(x: hint.NDArray, v: hint.NDArray) hint.Callable[[hint.NDArray], hint.NDArray][source]#

Linear interpolator.

Parameters:
  • x (ndarray) – The input data fed to the linear interpolator.

  • v (ndarray) – The output data fed to the linear interpolator.

Returns:

interpolator – The linear interpolator.

Return type:

Callable

class lezargus.library.interpolate.Nearest1DInterpolate(x: hint.NDArray, v: hint.NDArray, extrapolate: bool = False, extrapolate_fill: float = nan, gap: float = inf, gap_fill: float = nan)[source]#

Bases: Generic1DInterpolate

Nearest value based interpolation class.

A simple linear interpolator.

static _interpolator_generator(x: hint.NDArray, v: hint.NDArray) hint.Callable[[hint.NDArray], hint.NDArray][source]#

Linear interpolator.

Parameters:
  • x (ndarray) – The input data fed to the linear interpolator.

  • v (ndarray) – The output data fed to the linear interpolator.

Returns:

interpolator – The linear interpolator.

Return type:

Callable

class lezargus.library.interpolate.RegularNDInterpolate(domain: list[hint.NDArray], v: hint.NDArray)[source]#

Bases: RegularGridInterpolator

Wrapper for Scipy’s regular grid interpolator.

This interpolator is more reliable than the RepeatNDInterpolate for cases where the regular grid is strictly preserved and no extrapolation is needed. This interpolation is strictly cubic interpolation.

Note, we do not document attributes for the parent class. See scipy.interpolate.RegularGridInterpolator for more information.

domain#

A list of the domain axes values which define the multidimensional data.

Type:

list

v#

The multi-dimensional data who’s axes are defined. This data is the data interpolated.

Type:

ndarray

__init__(domain: list[hint.NDArray], v: hint.NDArray) None[source]#

Create the interpolator, using the Scipy interpolator as a base.

Parameters:
  • domain (list) – The list of domain axis values of the multi-dimensional data.

  • v (ndarray) – The data itself, the dimensions must match the provided axes.

Return type:

None

interpolate(*domain: hint.NDArray) hint.NDArray[source]#

Interpolate the data points provided their axis values.

Parameters:

*domain (ndarray) – The domain value axes which we are interpolating at, given in order as the axes domain of this class.

Returns:

v – The interpolated values.

Return type:

ndarray

interpolate_point(*point: float) float[source]#

Interpolate a single point.

Parameters:

*point (float) – The point that we are interpolating to. The order of the float values in this point should match the interpolation order of the axes; similar to a Cartesian grid point.

Returns:

v – The interpolated output value.

Return type:

float

interpolate_slice(*slice_: float | None) hint.NDArray[source]#

Interpolate a single slice of the data.

A “slice” is provided by specifying the values of specific points to interpolate the given axis at. Specifying None keeps that dimension part of the slice.

Parameters:

slice (float | None) – The slice specification to interpolate at. The order of the parameters corresponds to the axis order. Specifying None means the axis is part of the slice and is not interpolated.

Returns:

v – The interpolated output value.

Return type:

float

class lezargus.library.interpolate.Repeat2DInterpolate(x: hint.NDArray, y: hint.NDArray, v: hint.NDArray, template: hint.Callable)[source]#

Bases: RepeatNDInterpolate

A 2D interpolator class for multi-dimensional interpolation.

This interpolation requires a rectilinear grid, with the structure defined. Like the parent class, we do interpolation by successive 1D interpolation. However, we wrap the parent class to make it more understandable.

x#

The first axis of the multi-dimensional data.

Type:

ndarray

y#

The second axis of the multi-dimensional data.

Type:

ndarray

v#

The data itself.

Type:

ndarray

interpolator_template#

The template function for the 1D interpolations.

Type:

Callable

_parent#

The parent instance that does all of the heavy lifting.

Type:

RepeatNDInterpolate

__call__(x: hint.NDArray, y: hint.NDArray) hint.NDArray#

Interpolate the data points.

We interpolate the data at the given x and y values. The shapes of all of the inputs must be the same, and the output shape is preserved as based as possible.

Parameters:
  • x (ndarray) – The x values for interpolation.

  • y (ndarray) – The y values for interpolation.

Returns:

v – The interpolated values.

Return type:

ndarray

__init__(x: hint.NDArray, y: hint.NDArray, v: hint.NDArray, template: hint.Callable) None[source]#

Create the 2D interpolator, constructed from many 1D interpolations.

Parameters:
  • x (ndarray) – The first axis of the multi-dimensional data.

  • y (ndarray) – The second axis of the multi-dimensional data.

  • v (ndarray) – The data itself, the dimensions must match x and y.

  • template (Callable) – The 1D interpolator template function which will be used to build the needed 1D interpolators. A template function can be constructed from the helper function generate_template().

interpolate(x: hint.NDArray, y: hint.NDArray) hint.NDArray[source]#

Interpolate the data points.

We interpolate the data at the given x and y values. The shapes of all of the inputs must be the same, and the output shape is preserved as based as possible.

Parameters:
  • x (ndarray) – The x values for interpolation.

  • y (ndarray) – The y values for interpolation.

Returns:

v – The interpolated values.

Return type:

ndarray

interpolate_point(x: float, y: float) float[source]#

Interpolate a single point.

This function determines the interpolated value for a given single point. We suggest that this method is not called directly unless really only a single point is needed.

Parameters:
  • x (float) – The x axis value we are interpolating at.

  • y (float) – The y axis value we are interpolating at.

Returns:

v – The interpolated output value.

Return type:

float

interpolate_slice(x: float | None, y: float | None) np.ndarray[source]#

Interpolate a single slice of the data.

A “slice” is provided by specifying the values of specific points to interpolate the given axis at. Specifying None keeps that dimension part of the slice.

Parameters:
  • x (float | None) – The x axis value we are interpolating the slice at. If None, then the slice runs down this axis.

  • y (float | None) – The y axis value we are interpolating at. If None, then the slice runs down this axis.

Returns:

v – The interpolated output slice.

Return type:

float

class lezargus.library.interpolate.Repeat3DInterpolate(x: hint.NDArray, y: hint.NDArray, z: hint.NDArray, v: hint.NDArray, template: hint.Callable)[source]#

Bases: RepeatNDInterpolate

A 3D interpolator class for multi-dimensional interpolation.

This interpolation requires a rectilinear grid, with the structure defined. Like the parent class, we do interpolation by successive 1D interpolation. However, we wrap the parent class to make it more understandable.

x#

The first axis of the multi-dimensional data.

Type:

ndarray

y#

The second axis of the multi-dimensional data.

Type:

ndarray

z#

The third axis of the multi-dimensional data.

Type:

ndarray

v#

The data itself.

Type:

ndarray

interpolator_template#

The template function for the 1D interpolations.

Type:

Callable

_parent#

The parent instance that does all of the heavy lifting.

Type:

RepeatNDInterpolate

__call__(x: hint.NDArray, y: hint.NDArray, z: hint.NDArray) hint.NDArray#

Interpolate the data points.

We interpolate the data at the given x, y, and z values. The shapes of all of the inputs must be the same, and the output shape is preserved as based as possible.

Parameters:
  • x (ndarray) – The x values for interpolation.

  • y (ndarray) – The y values for interpolation.

  • z (ndarray) – The z values for interpolation.

Returns:

v – The interpolated values.

Return type:

ndarray

__init__(x: hint.NDArray, y: hint.NDArray, z: hint.NDArray, v: hint.NDArray, template: hint.Callable) None[source]#

Create the 2D interpolator, constructed from many 1D interpolations.

Parameters:
  • x (ndarray) – The first axis of the multi-dimensional data.

  • y (ndarray) – The second axis of the multi-dimensional data.

  • z (ndarray) – The third axis of the multi-dimensional data.

  • v (ndarray) – The data itself, the dimensions must match x and y.

  • template (Callable) – The 1D interpolator template function which will be used to build the needed 1D interpolators. A template function can be constructed from the helper function generate_template().

interpolate(x: hint.NDArray, y: hint.NDArray, z: hint.NDArray) hint.NDArray[source]#

Interpolate the data points.

We interpolate the data at the given x, y, and z values. The shapes of all of the inputs must be the same, and the output shape is preserved as based as possible.

Parameters:
  • x (ndarray) – The x values for interpolation.

  • y (ndarray) – The y values for interpolation.

  • z (ndarray) – The z values for interpolation.

Returns:

v – The interpolated values.

Return type:

ndarray

interpolate_point(x: float, y: float, z: float) float[source]#

Interpolate a single point.

This function determines the interpolated value for a given single point. We suggest that this method is not called directly unless really only a single point is needed.

Parameters:
  • x (float) – The x axis value we are interpolating at.

  • y (float) – The y axis value we are interpolating at.

  • z (float) – The z axis value we are interpolating at.

Returns:

v – The interpolated output value.

Return type:

float

interpolate_slice(x: float | None, y: float | None, z: float | None) np.ndarray[source]#

Interpolate a single slice of the data.

A “slice” is provided by specifying the values of specific points to interpolate the given axis at. Specifying None keeps that dimension part of the slice.

Parameters:
  • x (float | None) – The x axis value we are interpolating the slice at. If None, then the slice runs down this axis.

  • y (float | None) – The y axis value we are interpolating at. If None, then the slice runs down this axis.

  • z (float | None) – The z axis value we are interpolating at. If None, then the slice runs down this axis.

Returns:

v – The interpolated output slice.

Return type:

float

class lezargus.library.interpolate.RepeatNDInterpolate(domain: list[hint.NDArray], v: hint.NDArray, template: hint.Callable)[source]#

Bases: object

An ND interpolator class for multi-dimensional interpolation.

This interpolation requires a rectilinear grid like arrangement of data, but we do accept gaps and NaNs in the data. We perform interpolation by repeated 1D interpolations across the dimensions until we get the interpolated value. The order of the interpolations and the actual 1D interpolation algorithm is provided on instantiation.

We do suggest using the repeat interpolators which actually define their axes; such are built for 2D Repeat2DInterpolate and 3D Repeat3DInterpolate interpolators. For single dimensions, see Generic1DInterpolate and its subclasses. For higher dimensions, we suggest using this class.

domain#

A list of the domain axes values which define the multidimensional data.

Type:

list

v#

The multi-dimensional data who’s axes are defined. This data is the data interpolated.

Type:

ndarray

interpolator_template#

The template function for the 1D interpolations.

Type:

Callable

__call__(*domain: hint.NDArray) hint.NDArray#

Interpolate the data points; internal function.

The shape and arrangement of the input points provided is preserved. We just assume the shape of the input axis points, interpolate point by point, then reshape the result based on the shape of the input.

This function is hidden so this class can be subclassed easily. Please call the public interface class to interpolate: interpolate().

Parameters:

*domain (ndarray) – The domain value axes which we are interpolating at, given in order as the axes domain of this class.

Returns:

v – The interpolated values.

Return type:

ndarray

__init__(domain: list[hint.NDArray], v: hint.NDArray, template: hint.Callable) None[source]#

Create the 2D interpolator, constructed from many 1D interpolations.

Parameters:
  • domain (list) – The list of domain axis values of the multi-dimensional data. Note, the repeated interpolation procedure follows the axis order provided.

  • v (ndarray) – The data itself, the dimensions must match the provided axes.

  • template (Callable) – The 1D interpolator template function which will be used to build the needed 1D interpolators.

Return type:

None

_interpolate(*domain: hint.NDArray) hint.NDArray[source]#

Interpolate the data points; internal function.

The shape and arrangement of the input points provided is preserved. We just assume the shape of the input axis points, interpolate point by point, then reshape the result based on the shape of the input.

This function is hidden so this class can be subclassed easily. Please call the public interface class to interpolate: interpolate().

Parameters:

*domain (ndarray) – The domain value axes which we are interpolating at, given in order as the axes domain of this class.

Returns:

v – The interpolated values.

Return type:

ndarray

_interpolate_point(*point: float) float[source]#

Interpolate a single point.

This function determines the interpolated value for a given single point. We suggest that this method is not called directly unless really only a single point is needed.

Parameters:

*point (float) – The point that we are interpolating to. The order of the float values in this point should match the interpolation order of the axes; similar to a Cartesian grid point.

Returns:

v – The interpolated output value.

Return type:

float

static _interpolate_reduce_dimension(data: hint.NDArray, single_domain: hint.NDArray, point: float, template: hint.Callable, axis: int = -1) hint.NDArray[source]#

Interpolate and reduce the multi-dimensional data by one dimension.

This function interpolates a multi-dimensional data set by creating 1D interpolators along the dimension that we will reduce. We evaluate the interpolators at a single point, replacing that entire dimension with single values. The new interpolated data is one dimension reduced from the original. This is basically an “iteration” in the repeated 1D interpolations.

This function generally should not be used by an end-user and should only be used internally.

Parameters:
  • data (ndarray) – The multi-dimensional data we will be interpolating and reducing in one dimension.

  • single_domain (ndarray) – The input domain axis of the data for the axis that we are reducing.

  • point (ndarray) – The single point value we are evaluating the interpolation instances at to reduce the dimension down.

  • template (Callable) – The 1D interpolator template function which will be used to build the needed 1D interpolators.

  • axis (int, default = -1) – The axis we are reducing down. By default, we reduce along the first axis in the order provided by this class.

Returns:

reduced – The new interpolated multi-dimensional data after the reduction of the dimension from the interpolation.

Return type:

ndarray

_interpolate_slice(*slice_: float | None) hint.NDArray[source]#

Interpolate a single slice of the data.

A “slice” is provided by specifying the values of specific points to interpolate the given axis at. Specifying None keeps that dimension part of the slice.

Parameters:

slice (float | None) – The slice specification to interpolate at. The order of the parameters corresponds to the axis order. Specifying None means the axis is part of the slice and is not interpolated.

Returns:

v – The interpolated output value.

Return type:

float

interpolate(*domain: hint.NDArray) hint.NDArray#

Interpolate the data points; internal function.

The shape and arrangement of the input points provided is preserved. We just assume the shape of the input axis points, interpolate point by point, then reshape the result based on the shape of the input.

This function is hidden so this class can be subclassed easily. Please call the public interface class to interpolate: interpolate().

Parameters:

*domain (ndarray) – The domain value axes which we are interpolating at, given in order as the axes domain of this class.

Returns:

v – The interpolated values.

Return type:

ndarray

interpolate_point(*point: float) float#

Interpolate a single point.

This function determines the interpolated value for a given single point. We suggest that this method is not called directly unless really only a single point is needed.

Parameters:

*point (float) – The point that we are interpolating to. The order of the float values in this point should match the interpolation order of the axes; similar to a Cartesian grid point.

Returns:

v – The interpolated output value.

Return type:

float

interpolate_slice(*slice_: float | None) hint.NDArray#

Interpolate a single slice of the data.

A “slice” is provided by specifying the values of specific points to interpolate the given axis at. Specifying None keeps that dimension part of the slice.

Parameters:

slice (float | None) – The slice specification to interpolate at. The order of the parameters corresponds to the axis order. Specifying None means the axis is part of the slice and is not interpolated.

Returns:

v – The interpolated output value.

Return type:

float

class lezargus.library.interpolate.Spline1DInterpolate(x: hint.NDArray, v: hint.NDArray, extrapolate: bool = False, extrapolate_fill: float = nan, gap: float = inf, gap_fill: float = nan)[source]#

Bases: Generic1DInterpolate

Spline based interpolation class.

We use a polynomial piece-wise spline. This is better than a pure cubic interpolator as the modified Akima spline method used preserves the curve shapes better.

static _interpolator_generator(x: hint.NDArray, v: hint.NDArray) hint.Callable[[hint.NDArray], hint.NDArray][source]#

Generate modified Akima interpolator.

Parameters:
  • x (ndarray) – The input data fed to the modified Akima interpolator.

  • v (ndarray) – The output data fed to the modified Akima interpolator.

Returns:

interpolator – The modified Akima interpolator.

Return type:

Callable

lezargus.library.interpolate.get_smallest_gap(wavelength: hint.NDArray) float[source]#

Find the smallest possible gap value for a wavelength array.

Gaps, which are important in gap-based interpolation, are where there is no data. Gaps are primarily a wavelength criterion: should data be missing for enough of a wavelength range, it is determined to be a gap. This function determines the smallest possible gap in the provided wavelength array for which a data-only gap may exist.

Basically, we find the maximum spacing in the wavelength array and assume that is it perfect and determine a gap from it.

Parameters:

wavelength (ndarray) – The wavelength array which is used to find the small gap.

Returns:

small_gap – The wavelength spacing for the small gap, in the same units as the provided wavelength array.

Return type:

float