axsdb.interpolation¶

Fast xarray interpolation.

This module provides high-performance interpolation functions for xarray DataArrays that bypass xarray’s built-in interpolation. This is motivated by performance regressions in recent xarray versions (see https://github.com/pydata/xarray/issues/10683).

Functions:

interp_dataarray(da, coords[, bounds, ...])

Fast linear interpolation for xarray DataArrays.

axsdb.interpolation.interp_dataarray(da: DataArray, coords: dict[Hashable, float | ndarray | DataArray], bounds: Literal['fill', 'clamp', 'raise'] | dict[Hashable, Literal['fill', 'clamp', 'raise']] = 'fill', fill_value: float | tuple[float, float] | dict[Hashable, float | tuple[float, float]] = nan) → DataArray[source]¶

Fast linear interpolation for xarray DataArrays.

This function provides a high-performance alternative to xarray’s .interp() method for linear interpolation, with the possibility to control out-of-bound handling behaviour per dimension.

Parameters:

da (DataArray) – The input DataArray to interpolate.
coords (dict) – Mapping from dimension names to new coordinate values. Each value can be a scalar, numpy array, or xarray DataArray. Dimensions are interpolated sequentially in the order given.
bounds ({"fill", "clamp", "raise"} or dict, default: "fill") –
How to handle out-of-bounds query points. Can be a single value applied to all dimensions, or a dict mapping dimension names to bounds modes. Missing dimensions default to "fill".
- ”fill”: Use fill_value for points outside the data range.
- ”clamp”: Use the nearest boundary value.
- ”raise”: Raise a ValueError if any query point is out of bounds.
fill_value (float or tuple or dict, default: np.nan) –
Value(s) to use for out-of-bounds points when bounds="fill". Can be:
- a single float (used for both lower and upper bounds, all dims);
- a 2-tuple (fill_lower, fill_upper) for all dimensions;
- a dict mapping dimension names to floats or 2-tuples.
Missing dimensions default to np.nan.

Returns:

Interpolated DataArray with the new coordinates. Preserves the original DataArray’s name and attributes.

Return type:

DataArray

Raises:

ValueError – If a dimension in coords does not exist in the DataArray. If bounds="raise" and any query point is out of bounds. The error message includes the dimension name for easier debugging.

Notes

The function assumes coordinates are sorted in ascending order along each interpolation dimension. Results are undefined if this assumption is violated.

Interpolation is performed sequentially across dimensions in the order given in coords. This is equivalent to chained .interp() calls but significantly faster due to the optimized gufunc implementation.

Examples

Basic multi-dimensional interpolation:

>>> # Create sample data
>>> da = xr.DataArray(
...     np.random.rand(10, 20, 30),
...     dims=["wavelength", "angle", "time"],
...     coords={
...         "wavelength": np.linspace(400, 700, 10),
...         "angle": np.linspace(0, 90, 20),
...         "time": np.linspace(0, 1, 30),
...     },
... )
>>>
>>> # Interpolate to new coordinates
>>> result = interp_dataarray(
...     da,
...     {
...         "wavelength": np.array([450.0, 550.0, 650.0]),
...         "angle": np.array([30.0, 60.0]),
...     },
... )
>>> result.shape
(3, 2, 30)

Different bounds handling per dimension:

>>> new_wavelengths = np.array([450.0, 550.0, 650.0])
>>> new_angles = np.array([30.0, 60.0])
>>> result = interp_dataarray(
...     da,
...     {"wavelength": new_wavelengths, "angle": new_angles},
...     bounds={"wavelength": "raise", "angle": "clamp"},
... )

Custom fill values per dimension:

>>> result = interp_dataarray(
...     da,
...     {"wavelength": new_wavelengths, "angle": new_angles},
...     bounds="fill",
...     fill_value={"wavelength": 0.0, "angle": (-1.0, 1.0)},
... )