erlab.analysis.interpolate

Utilities for interpolation.

Functions

interpn(points, values, xi[, method, ...])

Multidimensional interpolation on evenly spaced coordinates.

leading_edge(darr[, fraction, dim, ...])

Calculate leading edges in a DataArray with subpixel precision.

slice_along_path(darr, vertices[, ...])

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

slice_along_vector(data, center, direction, ...)

Slice along a vector defined by the center point, direction vector, and lengths.

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=nan, *, solver=None, solver_args=None)[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.

  • Points are 1D, 2D or 3D.

  • Extrapolation is disabled, i.e., fill_value is not None.

See also

interpn

a convenience function that wraps FastInterpolator

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

Construct an interpolator from a xarray.DataArray.

Parameters:

  • data (DataArray) – The source xarray.DataArray.

  • method (default: 'linear') – The method of interpolation to perform.

  • fill_value (float | None, default: nan) – 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=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, default: 'linear') – The method of interpolation to perform.

  • fill_value (float | None, default: nan) – The value to use for points outside of the interpolation domain.

Returns:

values_x (numpy.ndarray) – Interpolated values at input coordinates.

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.leading_edge(darr, fraction=0.5, *, dim='eV', direction='positive', on_failure='nan')[source]

Calculate leading edges in a DataArray with subpixel precision.

The leading edge is defined as the coordinate where the intensity reaches a given fraction of the maximum intensity along dim, by default 50%.

It is calculated by interpolating each curve with a spline and finding the root of the function defined as the difference between the curve and the target intensity.

Changed in version 3.26.0: Non-finite samples are ignored when fitting each curve. The spline degree is reduced when fewer than four finite samples remain.

Parameters:

  • darr (xr.DataArray) – The input DataArray containing curves along dim.

  • fraction (float, optional) – The fraction of the maximum intensity to define the leading edge, by default 0.5.

  • dim (Hashable, optional) – The dimension along which to solve for the leading edge, by default "eV".

  • direction ({"positive", "negative"}, optional) – Direction from the curve maximum in which to solve. "positive" solves toward larger coordinate values, while "negative" solves toward smaller coordinate values.

  • on_failure ({"nan", "raise"}, optional) – How to handle curves where the requested edge cannot be estimated. "nan" returns NaN for those curves, while "raise" propagates the failure as a ValueError.

Returns:

leading_edge (xr.DataArray) – A DataArray containing the leading edge coordinate for each curve in the input DataArray. The shape will be the same as the input DataArray, but without dim.

Return type:

DataArray

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[float]]) – 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, default: None) – Approximate sampling interval along the path, in the same units as the selected coordinates. This determines the number of interpolation points. If None, the smallest coordinate step among uniformly spaced selected dimensions is used. Each selected dimension must then contain at least two coordinate values. If none of those coordinates is uniformly spaced, step_size is required.

  • dim_name (str, default: 'path') – The name of the new dimension that corresponds to the distance along the interpolated path. Default is “path”.

  • interp_kwargs (dict | None, default: 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 (DataArray) – A new interpolated array. The dimensions named in vertices are replaced by dim_name; other dimensions are retained. The new dimension coordinate starts at zero and contains cumulative distance along the path. The original selected coordinates become one-dimensional auxiliary coordinates along that dimension. The data name and attributes are retained, and the input is not modified.

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)

See also

xarray.DataArray.interp

The method used to perform the interpolation.

erlab.analysis.interpolate.slice_along_vector()

Slice along a vector defined by a center point, direction vector, and lengths.

erlab.analysis.interpolate.slice_along_vector(data, center, direction, stretch, **kwargs)[source]

Slice along a vector defined by the center point, direction vector, and lengths.

Parameters:

  • data (DataArray) – The data to be sliced.

  • center (dict[str, float]) – The center point of the vector given as a dictionary. The keys should correspond to dimensions in data.

  • direction (dict[str, float]) – The direction vector given as a dictionary with the same keys as center. The direction is normalized before slicing.

  • stretch (float | tuple[float, float]) – Distance from center in the coordinate units used by direction. A single value gives the same distance in both directions. A tuple gives separate distances in the negative and positive directions.

  • **kwargs – Additional keyword arguments to be passed to slice_along_path.

Returns:

interpolated (DataArray) – A new interpolated array with the selected dimensions replaced by the path dimension. See slice_along_path().

Examples

import erlab.analysis as era
import numpy as np
from erlab.io.exampledata import generate_data

# Generate some example data: a 3D kx-ky-eV ARPES map.
data = generate_data()

# Slice along a vector centered at (kx, ky) = (-0.5, -0.3).
# The direction of the vector is defined by (kx, ky) = (sqrt(3), 1.0).
# The slice starts from -0.1 inverse Å and ends at 0.2 inverse Å.

era.interpolate.slice_along_vector(
    data,
    center=dict(kx=-0.5, ky=-0.3),
    direction=dict(kx=np.sqrt(3), ky=1.0),
    stretch=(0.1, 0.3),
)

See also

erlab.analysis.interpolate.slice_along_path()