iris.analysis.interpolate

Interpolation and re-gridding routines.

See also: NumPy, and SciPy.

Deprecated since version 1.10: The module iris.analysis.interpolate is deprecated. Please use iris.cube.Cube.regrid() or iris.cube.Cube.interpolate() with the appropriate regridding and interpolation schemes from iris.analysis instead.

In this module:

iris.analysis.interpolate.nearest_neighbour_indices(cube, sample_points)

Returns the indices to select the data value(s) closest to the given coordinate point values.

The sample_points mapping does not have to include coordinate values corresponding to all data dimensions. Any dimensions unspecified will default to a full slice.

For example:

>>> cube = iris.load_cube(iris.sample_data_path('ostia_monthly.nc'))
>>> iris.analysis.interpolate.nearest_neighbour_indices(cube, [('latitude', 0), ('longitude', 10)])
(slice(None, None, None), 9, 12)
>>> iris.analysis.interpolate.nearest_neighbour_indices(cube, [('latitude', 0)])
(slice(None, None, None), 9, slice(None, None, None))

Args:

  • cube:

    An iris.cube.Cube.

  • sample_points

    A list of tuple pairs mapping coordinate instances or unique coordinate names in the cube to point values.

Returns:
The tuple of indices which will select the point in the cube closest to the supplied coordinate values.

Note

Nearest neighbour interpolation of multidimensional coordinates is not yet supported.

Deprecated since version 1.10: The module iris.analysis.interpolate is deprecated. Please replace usage of iris.analysis.interpolate.nearest_neighbour_indices() with iris.coords.Coord.nearest_neighbour_index().

↑ top ↑

iris.analysis.interpolate.extract_nearest_neighbour(cube, sample_points)

Returns a new cube using data value(s) closest to the given coordinate point values.

The sample_points mapping does not have to include coordinate values corresponding to all data dimensions. Any dimensions unspecified will default to a full slice.

For example:

>>> cube = iris.load_cube(iris.sample_data_path('ostia_monthly.nc'))
>>> iris.analysis.interpolate.extract_nearest_neighbour(cube, [('latitude', 0), ('longitude', 10)])
<iris 'Cube' of surface_temperature / (K) (time: 54)>
>>> iris.analysis.interpolate.extract_nearest_neighbour(cube, [('latitude', 0)])
<iris 'Cube' of surface_temperature / (K) (time: 54; longitude: 432)>

Args:

  • cube:

    An iris.cube.Cube.

  • sample_points

    A list of tuple pairs mapping coordinate instances or unique coordinate names in the cube to point values.

Returns:
A cube that represents uninterpolated data as near to the given points as possible.

Deprecated since version 1.10: The module iris.analysis.interpolate is deprecated. Please replace usage of iris.analysis.interpolate.extract_nearest_neighbour() with iris.cube.Cube.interpolate() using the scheme iris.analysis.Nearest.

↑ top ↑

iris.analysis.interpolate.nearest_neighbour_data_value(cube, sample_points)

Returns the data value closest to the given coordinate point values.

The sample_points mapping must include coordinate values corresponding to all data dimensions.

For example:

>>> cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
>>> iris.analysis.interpolate.nearest_neighbour_data_value(cube, [('latitude', 0), ('longitude', 10)])
299.21564
>>> iris.analysis.interpolate.nearest_neighbour_data_value(cube, [('latitude', 0)])
Traceback (most recent call last):
...
ValueError: The sample points [('latitude', 0)] was not specific enough to return a single value from the cube.

Args:

  • cube:

    An iris.cube.Cube.

  • sample_points

    A list of tuple pairs mapping coordinate instances or unique coordinate names in the cube to point values.

Returns:
The data value at the point in the cube closest to the supplied coordinate values.

Deprecated since version 1.10: The module iris.analysis.interpolate is deprecated. Please replace usage of iris.analysis.interpolate.nearest_neighbour_data_value() with iris.cube.Cube.interpolate() using the scheme iris.analysis.Nearest.

↑ top ↑

iris.analysis.interpolate.regrid(source_cube, grid_cube, mode='bilinear', **kwargs)

Returns a new cube with values derived from the source_cube on the horizontal grid specified by the grid_cube.

Fundamental input requirements:
  1. Both cubes must have a CoordSystem.
  2. The source ‘x’ and ‘y’ coordinates must not share data dimensions with any other coordinates.
In addition, the algorithm currently used requires:
  1. Both CS instances must be compatible:

    i.e. of the same type, with the same attribute values, and with compatible coordinates.

  2. No new data dimensions can be created.

  3. Source cube coordinates to map to a single dimension.

Args:

  • source_cube:

    An instance of iris.cube.Cube which supplies the source data and metadata.

  • grid_cube:

    An instance of iris.cube.Cube which supplies the horizontal grid definition.

Kwargs:

  • mode (string):

    Regridding interpolation algorithm to be applied, which may be one of the following:

Returns:
A new iris.cube.Cube instance.

Note

The masked status of values are currently ignored. See regrid_bilinear_rectilinear_src_and_grid() for regrid support with mask awareness.

Deprecated since version 1.10: Please use iris.cube.Cube.regrid() instead, with an appropriate regridding scheme:

  • For mode=’bilinear’, simply use the Linear scheme.
  • For mode=’nearest’, use the Nearest scheme, with extrapolation_mode=’extrapolate’, but be aware of the following possible differences:
    • Any missing result points, i.e. those which match source points which are masked or NaN, are returned as as NaN values by this routine. The ‘Nearest’ scheme, however, represents missing results as masked points in a masked array. Which points are missing is unchanged.
    • Longitude wrapping for this routine is controlled by the ‘circular’ property of the x coordinate. The ‘Nearest’ scheme, however, always wraps any coords with modular units, such as (correctly formed) longitudes. Thus, behaviour can be different if “x_coord.circular” is False : In that case, if the original non-longitude-wrapped operation is required, it can be replicated by converting all X and Y coordinates’ units to ‘1’ and removing their coordinate systems.

↑ top ↑

iris.analysis.interpolate.regrid_to_max_resolution(cubes, **kwargs)

Returns all the cubes re-gridded to the highest horizontal resolution.

Horizontal resolution is defined by the number of grid points/cells covering the horizontal plane. See iris.analysis.interpolation.regrid() regarding mode of interpolation.

Args:

Returns:
A list of new iris.cube.Cube instances.

Deprecated since version 1.10: The module iris.analysis.interpolate is deprecated. Please replace usage of regrid_to_max_resolution() with iris.cube.Cube.regrid().

↑ top ↑

iris.analysis.interpolate.linear(cube, sample_points, extrapolation_mode='linear')

Return a cube of the linearly interpolated points given the desired sample points.

Given a list of tuple pairs mapping coordinates (or coordinate names) to their desired values, return a cube with linearly interpolated values. If more than one coordinate is specified, the linear interpolation will be carried out in sequence, thus providing n-linear interpolation (bi-linear, tri-linear, etc.).

If the input cube’s data is masked, the result cube will have a data mask interpolated to the new sample points

For example:

>>> cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
>>> sample_points = [('latitude', np.linspace(-90, 90, 10)),
...                  ('longitude', np.linspace(-180, 180, 20))]
>>> iris.analysis.interpolate.linear(cube, sample_points)
<iris 'Cube' of air_temperature / (K) (latitude: 10; longitude: 20)>

Note

By definition, linear interpolation requires all coordinates to be 1-dimensional.

Note

If a specified coordinate is single valued its value will be extrapolated to the desired sample points by assuming a gradient of zero.

Args:

  • cube

    The cube to be interpolated.

  • sample_points

    List of one or more tuple pairs mapping coordinate to desired points to interpolate. Points may be a scalar or a numpy array of values. Multi-dimensional coordinates are not supported.

Kwargs:

  • extrapolation_mode - string - one of ‘linear’, ‘nan’ or ‘error’

    • If ‘linear’ the point will be calculated by extending the gradient of closest two points.
    • If ‘nan’ the extrapolation point will be put as a NaN.
    • If ‘error’ a value error will be raised notifying of the attempted extrapolation.

Note

If the source cube’s data, or any of its resampled coordinates, have an integer data type they will be promoted to a floating point data type in the result.

Deprecated since version 1.10: The module iris.analysis.interpolate is deprecated. Please replace usage of iris.analysis.interpolate.linear() with iris.cube.Cube.interpolate() using the scheme iris.analysis.Linear.