Interpolation

Summary

Fast linear interpolation for 1D, 2D, and 3D data.

This module provides functions for efficient linear interpolation of 1D, 2D, and 3D data using NumPy and Numba. It includes both a high-level interface (interp()) and lower-level functions for specific dimensionalities.

Key Features:

• Fast linear interpolation for 1D, 2D, and 3D data

• Support for both grid-based and point-based interpolation

• Numba-accelerated core interpolation functions

• Input validation and error checking

• Visualization tool for comparing original and interpolated data

Main Functions:

• interp(): High-level interface for linear interpolation

• interp_linear_1d(), interp_linear_2d(), interp_linear_3d(): Dimension-specific interpolation

• plot_interp_comparison_heatmap(): Visualize original vs interpolated data

Dependencies:

• NumPy

• Numba

• Matplotlib

• SciPy (for comparison function)

Example

>>> import numpy as np
>>> from pymedphys.interpolate import interp
>>>
>>> # Define known data
>>> x = np.linspace(0, 10, 11)
>>> y = np.linspace(0, 10, 11)
>>> z = np.linspace(0, 10, 11)
>>> values = np.random.rand(11, 11, 11)
>>>
>>> # Define interpolation points
>>> x_interp = np.linspace(0, 10, 21)
>>> y_interp = np.linspace(0, 10, 21)
>>> z_interp = np.linspace(0, 10, 21)
>>>
>>> # Perform interpolation
>>> interpolated_values = interp(
...     [x, y, z], values, axes_interp=[x_interp, y_interp, z_interp]
... )

For more detailed information, refer to the individual function docstrings.

Performance Comparison Between Implementations

(Right-click and open in a new tab for better viewing)

API

Interpolation - High Level Interface (Recommended)

pymedphys.interpolate.interp(axes_known: Sequence[ndarray], values: ndarray, axes_interp: Sequence[ndarray] = None, points_interp: ndarray = None, keep_dims=False, bounds_error=True, extrap_fill_value=None, skip_checks=False) → ndarray

Perform fast linear interpolation on 1D, 2D, or 3D data.

Parameters:

• axes_known (Sequence[np.ndarray]) – The coordinate vectors or axis coordinates of the known data points.

• values (np.ndarray) – The known values at the points defined by axes_known. Its shape should match a tuple of the lengths of the axes in axes_known in the same order.

• axes_interp (Sequence[np.ndarray], optional) – The coordinate vectors or axis coordinates for which to interpolate values. These axes will be expanded to flattened meshgrids and interpolation will occur for each point in these grids. Either axes_interp or points_interp must be provided, but not both.

• points_interp (np.ndarray, optional) – The exact coordinates of the points where interpolation is desired. Shape should be (n, d) where n is the number of points and d is the number of dimensions. Either axes_interp or points_interp must be provided, but not both.

• keep_dims (bool, optional) – If True, return the interpolated values with the same shape as defined by axes_interp. Only applicable when axes_interp is provided. Default is False.

• bounds_error (bool, optional) – If True, raise an error when interpolation is attempted outside the bounds of the input data. Default is True.

• extrap_fill_value (float, optional) – The value to use for points outside the bounds of the input data when bounds_error is False. Default is None, which results in using np.nan.

• skip_checks (bool, optional) – If True, skip input validation checks. Skipping these checks can produce a significant improve in performance for some applications. Default is False.

Returns:

The interpolated values. If keep_dims is True and axes_interp is provided, the output will have the same shape as defined by axes_interp. Otherwise, it will be a 1D array.

Return type:

np.ndarray

Raises:

ValueError – If neither or both of axes_interp and points_interp are provided. If keep_dims is True but axes_interp is not provided. If the input axes are not monotonically increasing or evenly spaced.

Notes

This function performs linear interpolation for 1D, 2D, or 3D data. It supports both grid-based interpolation (using axes_interp) and point-based interpolation (using points_interp).

The input axes must be monotonically increasing and evenly spaced.

Interpolation - Low Level Interfaces

It generally shouldn’t be necessary to use these in lieu of pymedphys.interpolate.interp(), since running interp() with skip_checks=True will produce similar speed performance. See Performance Comparison Between Implementations

pymedphys.interpolate.interp_linear_1d(axis_known, values, points_interp, extrap_fill_value=None)

pymedphys.interpolate.interp_linear_2d(axes_known, values, points_interp, extrap_fill_value=None)

pymedphys.interpolate.interp_linear_3d(axes_known, values, points_interp, extrap_fill_value=None)

Interpolation - Visualisation

pymedphys.interpolate.plot_interp_comparison_heatmap(values, values_interp, slice_axis: int, slice_number: int, slice_number_interp: int)

Plot a comparison heatmap of original and interpolated 3D data slices.

This function creates a side-by-side heatmap comparison of a slice from the original data and a corresponding slice from the interpolated data.

Parameters:

• values (array-like) – The original 3D data array.

• values_interp (array-like) – The interpolated 3D data array.

• slice_axis (int) – The axis along which to take the slice (0, 1, or 2).

• slice_number (int) – The index of the slice to display from the original data.

• slice_number_interp (int) – The index of the slice to display from the interpolated data. Note that auto matching between the original and interpolated slices is not implemented. The user must ensure the slices correspond.

Returns:

This function displays the plot directly and does not return any value.

Return type:

None

Notes

• The function creates a figure with two subplots side by side.

• The left subplot shows the slice from the original data.

• The right subplot shows the slice from the interpolated data.

• It is up to the user to ensure that

• Both heatmaps use the same color scale, determined by the minimum and maximum values across both datasets.

• A shared colorbar is displayed on the right side of the figure.

• The plot is automatically displayed using plt.show().