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=np.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=np.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: np.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=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, default: "linear") – The method of interpolation to perform.

  • fill_value (float | None, default: np.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.

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) – 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, 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) – The interpolated data along the path.

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]) – The length of the vector in both directions in data units. If a single value is given, the vector is stretched in both directions by the same amount. If a tuple is given, the vector is stretched by different amounts in the negative and positive directions.

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

Returns:

interpolated (DataArray) – The interpolated data along the vector.

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()