windkit.spatial.nearest_points#

windkit.spatial.nearest_points(ds_ref: Dataset, ds_target: Dataset, dims=['west_east', 'south_north', 'height'], n_nearest=1, return_rank=False, return_distance=False, keep_duplicates=True, workers=1)[source]#

Select the nearest source point(s) for each target location.

For every location in ds_target, find the nearest location(s) in ds_ref by Euclidean distance over dims and return the exact selected source coordinates and data. No source values are interpolated.

Parameters:

  • ds_ref (xr.Dataset) – Source dataset. Any WindKit spatial structure is accepted.

  • ds_target (xr.Dataset) – Dataset whose locations and spatial structure define the result.

  • dims (list of str, default ["west_east", "south_north", "height"]) – Coordinate names used to measure distance. When a source spatial coordinate is omitted, its first representative is selected deterministically and a warning is issued.

  • n_nearest (int, default 1) – Number of distinct source locations in lookup space to return per target. Values greater than one require a point target.

  • return_rank (bool, default False) – Add a rank coordinate when n_nearest > 1.

  • return_distance (bool, default False) – Add a distance data variable containing query distances.

  • keep_duplicates (bool, default True) – Keep repeated source selections. When False, repeated selections are removed and n_nearest must be one.

  • workers (int, default 1) – Number of workers passed to scipy.spatial.KDTree.query(). Use -1 to use all available CPU threads.

Returns:

Exact selected source cells represented with the target spatial structure.

Return type:

xr.Dataset

Raises:

ValueError – If coordinate systems differ; lookup coordinates are missing or non-finite; arguments are invalid; distance or rank would collide with an existing source variable; or the exact source selections cannot represent the target spatial structure.

Warns:

UserWarning – For geographic coordinate lookup, omitted source spatial coordinates, or removed duplicate mappings.

Notes

Dimension order is not part of the return contract. Equal-distance neighbour ordering follows SciPy and is unspecified; selected coordinates, data, distance, and rank always remain paired. Structured output is accepted only when the exact selected coordinates are separable and unique, and grid output additionally satisfies WindKit’s regular-raster requirements. Pass to_point(ds_target) to request lossless point output explicitly.

On this page