apbase.idw

High-level inverse distance weighting API.

This package exports the public class used to run IDW interpolation.

class apbase.idw.IDW(*, radius=None, power=2.0, max_neighbors=40, min_neighbors=3)

Bases: object

Interpolate projected coordinates with inverse distance weighting.

Stores finite source samples with coordinates x/y and values z, then estimates values for target coordinates using inverse distance weights. Coordinates are not projected internally; pass metric/projected coordinates when radius is in meters.

Parameters:

  • radius (float | None) – Local search radius. If None, fit estimates a variogram and uses range (range / 3 with 10 000 or more points).

  • power (float) – Exponent applied to distance in the IDW weights. 2.0 is the common inverse-square weighting.

  • max_neighbors (int) – Maximum source points used per target coordinate.

  • min_neighbors (int) – Minimum sources within radius; below it the max_neighbors nearest sources are used regardless of distance.

Examples

>>> import numpy as np
>>> from apbase.idw import IDW
>>> x = np.ascontiguousarray([0.0, 10.0, 0.0, 10.0])
>>> y = np.ascontiguousarray([0.0, 0.0, 10.0, 10.0])
>>> z = np.ascontiguousarray([5.0, 7.0, 8.0, 10.0])
>>> targets = np.ascontiguousarray([[5.0, 5.0], [10.0, 10.0]])
>>> values = IDW(radius=20.0, min_neighbors=1).fit(x, y, z).interpolate(targets)
property radius: float | None

Local search radius.

Returns:

Explicit radius, or None to derive it from the variogram range during fit().

Return type:

float or None

property power: float

Exponent applied to distance in the IDW weights.

Returns:

Positive distance exponent.

Return type:

float

property max_neighbors: int

Maximum source points used per target coordinate.

Returns:

Upper bound on local neighbors.

Return type:

int

property min_neighbors: int

Minimum sources within radius before the nearest-sources fallback.

Returns:

Lower bound on local neighbors.

Return type:

int

property n_threads: int

OpenMP thread count passed to native routines.

Resolved live from apbase.config["n_threads"] (see the class docstring) on every access – not cached at construction time.

Returns:

Current OpenMP thread count.

Return type:

int

classmethod from_data(x, y, z, **kwargs)

Create and fit an IDW interpolator.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

  • **kwargs – Keyword arguments forwarded to IDW.

Returns:

Fitted IDW interpolator.

Return type:

IDW

property is_fitted: bool

Whether finite source data are available.

Returns:

True after fit() succeeds.

Return type:

bool

property model_params: dict[str, float | int | str]

Readable parameters for the variogram used by the default radius.

Returns:

Variogram parameters used to derive the implicit radius.

Return type:

dict

Raises:

ValueError – If the interpolator is not fitted or was fitted with an explicit radius, so no variogram was estimated.

fit(x, y, z)

Store finite source samples used by later interpolation.

Parameters:

  • x (ArrayLike) – One-dimensional source x coordinates. Use projected/metric units when radius is metric.

  • y (ArrayLike) – One-dimensional source y coordinates. Must have the same length as x.

  • z (ArrayLike) – One-dimensional source values to interpolate. Must have the same length as x and y.

Returns:

The fitted interpolator. Rows where x, y, or z are NaN or infinite are ignored.

Return type:

IDW

Raises:

ValueError – If input arrays have inconsistent size or fewer than min_neighbors finite rows.

Examples

>>> idw = IDW(radius=30.0, min_neighbors=1)
>>> idw.fit(x, y, z)
>>> idw.is_fitted
True
interpolate(targets)

Estimate values at target coordinates.

Parameters:

targets (Grid | ArrayLike) – Target coordinates as an (n_targets, 2) array, where column 0 is x and column 1 is y. A fitted Grid, GeoDataFrame/GeoSeries, or list of Point-like objects is also accepted; these are parsed by the shared extract_target_xy helper.

Returns:

One-dimensional float64 array with one interpolated value per target coordinate. Targets with fewer than min_neighbors sources within radius use the max_neighbors nearest ones.

Return type:

numpy.ndarray

Examples

>>> targets = np.ascontiguousarray([[5.0, 5.0], [20.0, 20.0]])
>>> values = idw.interpolate(targets)
predict(targets)

Estimate values at target coordinates.

Parameters:

targets (Grid or array_like) – Target coordinates accepted by interpolate().

Returns:

One interpolated value per target coordinate.

Return type:

numpy.ndarray

apbase.idw.idw(x, y, z, targets, *, radius=None, power=2.0, max_neighbors=40, min_neighbors=3)

Fit IDW from source data and estimate target values.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

  • targets (array_like) – Target coordinates accepted by apbase.idw.IDW.interpolate().

  • radius (float or None, default None) – Local search radius. If None, derive range from a fitted variogram (range / 3 with 10 000 or more points).

  • power (float, default 2.0) – IDW distance exponent.

  • max_neighbors (int) – Neighbor bounds used by the local search.

  • min_neighbors (int) – Neighbor bounds used by the local search.

Returns:

One interpolated value per target coordinate.

Return type:

numpy.ndarray