iris.analysis.interpolate

Interpolation and re-gridding routines.

See also: NumPy, and SciPy.

In this module:

• extract_nearest_neighbour
• linear
• nearest_neighbour_data_value
• nearest_neighbour_indices
• regrid
• regrid_to_max_resolution
• Linear1dExtrapolator

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.

↑ 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.

↑ 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.

↑ top ↑

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.

↑ 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:

3. Both CS instances must be compatible:

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

4. No new data dimensions can be created.

5. 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:

  • ‘bilinear’ for bi-linear interpolation (default), see iris.analysis.interpolate.linear().
  • ‘nearest’ for nearest neighbour interpolation.

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.

↑ 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:

• cubes:

  An iterable of iris.cube.Cube instances.

Returns:

A list of new iris.cube.Cube instances.

↑ top ↑

Extension class to scipy.interpolate.interp1d to provide linear extrapolation.

See also: scipy.interpolate.

class iris.analysis.interpolate.Linear1dExtrapolator(interpolator)

Bases: object

Given an already created scipy.interpolate.interp1d instance, return a callable object which supports linear extrapolation.

all_points_in_range(requested_x)

Given the x points, do all of the points sit inside the interpolation range.

roll_y = False

y = None

The y values given to the interpolator object.

Note

These are stored with the interpolator.axis last.