erlab.analysis.interpolate¶

Utilities for interpolation.

Functions

`interpn`(points, values, xi[, method, ...])	Multidimensional interpolation on evenly spaced coordinates.
`slice_along_path`(darr, vertices[, ...])	Interpolate a DataArray along a path defined by a sequence of vertices.

Classes

FastInterpolator(points, values[, method, ...])

Fast linear multidimensional interpolation on evenly spaced coordinates.

class erlab.analysis.interpolate.FastInterpolator(points, values, method='linear', bounds_error=False, fill_value=np.nan)[source]¶

Bases: RegularGridInterpolator

Fast linear multidimensional interpolation on evenly spaced coordinates.

This is an extension from scipy.interpolate.RegularGridInterpolator with vast performance improvements and integration with xarray.

The input arguments are identical to scipy.interpolate.RegularGridInterpolator except bounds_error, which is set to False by default.

Performance improvements are enabled for 1D, 2D and 3D linear interpolation on uniformly spaced coordinates with extrapolation disabled. Otherwise, scipy.interpolate.RegularGridInterpolator is called. See below for more information.

Note

Parallel acceleration is only applied when all of the following are true.

method is "linear".
Coordinates along all dimensions are evenly spaced.
Values are 1D, 2D or 3D.
Extrapolation is disabled, i.e., fill_value is not None.
The dimension of coordinates xi matches the number of dimensions of the values. Also, each coordinate array in xi must have the same shape.

See also

interpn: a convenience function which wraps FastInterpolator

classmethod from_xarray(data, method='linear', bounds_error=False, fill_value=np.nan)[source]¶

Construct an interpolator from a xarray.DataArray.

Parameters:

data (DataArray) – The source xarray.DataArray.
method – The method of interpolation to perform.
fill_value (float | None) – The value to use for points outside of the interpolation domain.

erlab.analysis.interpolate.interpn(points, values, xi, method='linear', bounds_error=False, fill_value=np.nan)[source]¶

Multidimensional interpolation on evenly spaced coordinates.

This can be used as a drop-in replacement for scipy.interpolate.interpn. Performance optimization is applied in some special cases, documented in FastInterpolator.

Parameters:

points (Sequence[ndarray]) – The points defining the regular grid in n dimensions. The points in each dimension (i.e. every element of the points tuple) must be strictly ascending.
values (ndarray) – The data on the regular grid in n dimensions.
xi (Sequence[ndarray] | ndarray) – The coordinates to sample the gridded data at. In addition to the scipy-compatible syntax, a tuple of coordinates is also acceptable.
method (str) – The method of interpolation to perform.
fill_value (float | None) – The value to use for points outside of the interpolation domain.

Returns:

values_x – Interpolated values at input coordinates.

Return type:

numpy.ndarray

Note

This optimized version of linear interpolation can be used with the xarray interpolation methods xarray.Dataset.interp and xarray.DataArray.interp by supplying method="linearfast". Note that the fallback to scipy will be silent except when a non-uniform dimension is found, when a warning will be issued.

erlab.analysis.interpolate.slice_along_path(darr, vertices, step_size=None, dim_name='path', interp_kwargs=None, **vertices_kwargs)[source]¶

Interpolate a DataArray along a path defined by a sequence of vertices.

Parameters:

darr (DataArray) – The data array to interpolate.
vertices (Mapping[Hashable, Sequence]) – Dictionary specifying the vertices of the path along which to interpolate the DataArray. The keys of the dictionary should correspond to the dimensions of the DataArray along which to interpolate.
step_size (float | None) – The step size to use for the interpolation. This determines the number of points along the path at which the data array will be interpolated. If None, the step size is determined automatically as the smallest step size of the coordinates along the dimensions of the vertices if all coordinates are evenly spaced. If there exists a dimension where the coordinates are not evenly spaced, step_size must be specified.
dim_name (str) – The name of the new dimension that corresponds to the distance along the interpolated path. Default is “path”.
interp_kwargs (dict | None) – Additional keyword arguments passed to xarray.DataArray.interp.
**vertices_kwargs – The keyword arguments form of vertices. One of vertices or vertices_kwargs must be provided.

Returns:

interpolated – New dataarray on the new coordinate.

Return type:

DataArray

Examples

>>> import numpy as np
>>> import xarray as xr
>>> from erlab.analysis.interpolate import slice_along_path
>>> x = np.linspace(0, 10, 11)
>>> y = np.linspace(0, 10, 11)
>>> z = np.linspace(0, 10, 11)
>>> data = np.random.rand(11, 11, 11)
>>> darr = xr.DataArray(data, coords={"x": x, "y": y, "z": z}, dims=["x", "y", "z"])
>>> vertices = {"x": [0, 5, 10], "y": [0, 5, 10], "z": [0, 5, 10]}
>>> interp = slice_along_path(darr, vertices)