interpolate
interpolate
Classes
| Name | Description |
|---|---|
| Interpolator | Interpolate/select a Dataset onto new coordinates. |
| Locator | The purpose of these classes is to locate values in coordinate axes. |
Interpolator
interpolate.Interpolator(data, backend='scipy', **kwargs)Interpolate/select a Dataset onto new coordinates.
This class is similar to xr.interp and xr.sel, but: - Supports dask-based coordinates inputs without triggering immediate computation as is done by xr.interp - Supports combinations of selection and interpolation. This is faster and more memory efficient than performing independently the selection and interpolation. - Supports pointwise indexing/interpolation using dask arrays (see https://docs.xarray.dev/en/latest/user-guide/indexing.html#more-advanced-indexing) - Supports per-dimension options (nearest neighbour selection, linear/spline interpolation, out-of-bounds behaviour, cyclic dimensions…) - Works with full Datasets, allowing interpolation of multiple variables at once.
The interp function is a convenience wrapper around this class for single DataArrays.
Args: data (xr.Dataset): The input Dataset containing variables to interpolate. backend (str): Backend for index finding, either “scipy” (default) or “numba”. **kwargs: definition of the selection/interpolation coordinates for each dimension, using the following classes: - Linear: linear interpolation (like xr.DataArray.interp) - Nearest: nearest neighbour selection (like xr.DataArray.sel) - Index: integer index selection (like xr.DataArray.isel) These classes store the coordinate data in their .values attribute and have a .get_indexer method which returns an indexer for the passed coordinates.
Example: >>> interpolator = Interpolator( … # input Dataset with variables ozone and wind, dimensions (lat, lon) … data, … # perform linear interpolation along dimension lat … # using variable “latitude” in coords_dataset … # clip out-of-bounds values to the axis min/max. … lat = Linear(“latitude”, bounds=‘clip’),
… # perform nearest neighbour selection along … # dimension lon, using variable “longitude” … # in coords … lon = Nearest(“longitude”), … ) >>> result = interpolator.map_blocks(coords_dataset) # coords_dataset has lat and lon variables … # returns a Dataset with variables “ozone” and “wind”, interpolated over the … # coordinates lat and lon provided in coords_dataset
Methods
| Name | Description |
|---|---|
| process_block | ex: block is a xr.Dataset with |
process_block
interpolate.Interpolator.process_block(block)ex: block is a xr.Dataset with latitude (x, y) longitude (x, y) Returns interpolated_data, interpolated over the coordinates provided in block. interpolated_data is of the same type as data
Locator
interpolate.Locator(coords, bounds, backend='scipy')The purpose of these classes is to locate values in coordinate axes.
Methods
| Name | Description |
|---|---|
| handle_oob | handle out of bound values |
| locate_index_weight | Find indices and dist of values for linear and spline interpolation in self.coords |
handle_oob
interpolate.Locator.handle_oob(values)handle out of bound values
Note: when bounds == “cycle”, does nothing
locate_index_weight
interpolate.Locator.locate_index_weight(values)Find indices and dist of values for linear and spline interpolation in self.coords
Returns a list of indices, dist (float 0 to 1) and oob
Functions
| Name | Description |
|---|---|
| broadcast_numpy | Returns all data variables in ds as numpy arrays |
| broadcast_shapes | For each data variable in ds, returns the shape for broadcasting |
| create_locator | Locator factory |
| determine_output_dimensions | Determine output dimensions for an interpolated/selected DataArray. |
| find_indices | Multi-dimensional grid interpolation index finding. |
| interp | Interpolate/select a DataArray onto new coordinates. |
| interp_var | Interpolate a single variable da, with indices and weights |
| product_dict | Cartesian product of a dictionary of lists |
broadcast_numpy
interpolate.broadcast_numpy(ds, out_dims)Returns all data variables in ds as numpy arrays broadcastable against each other, with dimensions orderes as out_dims. (with new single-element dimensions)
This requires the input to be broadcasted to common dimensions.
broadcast_shapes
interpolate.broadcast_shapes(ds, dims)For each data variable in ds, returns the shape for broadcasting in the dimensions defined by dims
create_locator
interpolate.create_locator(
coords,
bounds,
spacing,
period=None,
backend='scipy',
)Locator factory
The purpose of this method is to instantiate the appropriate “Locator” class.
The args are passed from the indexers.
determine_output_dimensions
interpolate.determine_output_dimensions(data, mapping, coordinates)Determine output dimensions for an interpolated/selected DataArray.
This function implements NumPy’s advanced indexing rules to determine the final dimension ordering of the output DataArray after interpolation/selection operations.
The key principle is that when advanced indexing is applied to some dimensions of an array, those dimensions are replaced by the dimensions of the indexing arrays, and these new dimensions are inserted at the position of the first indexed dimension.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| data | xr.DataArray | The input DataArray being interpolated/selected. | required |
| mapping | dict | A dictionary mapping dimension names in data (keys) to variable names in coordinates (values). Only dimensions being interpolated/selected should be included. |
required |
| coordinates | xr.Dataset | The Dataset containing coordinate variables referenced in mapping. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| list | A list of dimension names for the output DataArray, in the order they will appear. |
find_indices
interpolate.find_indices(grid, xi, backend='scipy')Multi-dimensional grid interpolation index finding.
Args: grid: Tuple of 1D arrays defining grid coordinates for each dimension. xi: 2D array where each row represents a dimension and each column a query point. backend: One of “scipy” (default) or “numba”.
Returns: indices: Grid interval indices for each query point in each dimension. distances: Normalized distances within each interval.
Raises: ImportError: If backend is “numba” but numba is not installed. ValueError: If backend is not recognized.
interp
interpolate.interp(da, backend='scipy', **kwargs)Interpolate/select a DataArray onto new coordinates.
This function is similar to xr.interp and xr.sel, but: - Supports dask-based coordinates inputs without triggering immediate computation as is done by xr.interp - Supports combinations of selection and interpolation. This is faster and more memory efficient than performing independently the selection and interpolation. - Supports pointwise indexing/interpolation using dask arrays (see https://docs.xarray.dev/en/latest/user-guide/indexing.html#more-advanced-indexing) - Supports per-dimension options (nearest neighbour selection, linear/spline interpolation, out-of-bounds behaviour, cyclic dimensions…)
Args: da (xr.DataArray): The input DataArray backend (str): Backend for index finding, either “scipy” (default) or “numba”. **kwargs: definition of the selection/interpolation coordinates for each dimension, using the following classes: - Linear: linear interpolation (like xr.DataArray.interp) - Nearest: nearest neighbour selection (like xr.DataArray.sel) - Index: integer index selection (like xr.DataArray.isel) These classes store the coordinate data in their .values attribute and have a .get_indexer method which returns an indexer for the passed coordinates.
Example: >>> interp( … data, # input DataArray with dimensions (a, b, c) … a = Linear( # perform linear interpolation along dimension a … a_values, # a_values is a DataArray with dimension (x, y); … bounds=‘clip’), # clip out-of-bounds values to the axis min/max. … b = Nearest(b_values), # perform nearest neighbour selection along … # dimension b; b_values is a DataArray … # with dimension (x, y) … ) # returns a DataArray with dimensions (x, y, c) No interpolation or selection is performed along dimension c thus it is left as-is.
Returns: xr.DataArray: DataArray on the new coordinates.
interp_var
interpolate.interp_var(
da,
indices_weights,
w_shape,
current_out_dims,
current_dims,
shared_dims_info=None,
)Interpolate a single variable da, with indices and weights
shared_dims_info maps dim names that are shared between da and the coordinate variables to their position in the index arrays. These dims need element-wise range indexing instead of slice(None).
product_dict
interpolate.product_dict(**kwargs)Cartesian product of a dictionary of lists