iris.analysis.cartography

Various utilities and numeric transformations relevant to cartography.

In this module:

iris.analysis.cartography.area_weights(cube, normalize=False)

Returns an array of area weights, with the same dimensions as the cube.

This is a 2D lat/lon area weights array, repeated over the non lat/lon dimensions.

Args:

Kwargs:

  • normalize (False/True):

    If False, weights are grid cell areas. If True, weights are grid cell areas divided by the total grid area.

The cube must have coordinates ‘latitude’ and ‘longitude’ with bounds.

Area weights are calculated for each lat/lon cell as:

Currently, only supports a spherical datum. Uses earth radius from the cube, if present and spherical. Defaults to iris.analysis.cartography.DEFAULT_SPHERICAL_EARTH_RADIUS.

↑ top ↑

iris.analysis.cartography.cosine_latitude_weights(cube)

Returns an array of latitude weights, with the same dimensions as the cube. The weights are the cosine of latitude.

These are n-dimensional latitude weights repeated over the dimensions not covered by the latitude coordinate.

The cube must have a coordinate with ‘latitude’ in the name. Out of range values (greater than 90 degrees or less than -90 degrees) will be clipped to the valid range.

Weights are calculated for each latitude as:

Examples:

Compute weights suitable for averaging type operations:

from iris.analysis.cartography import cosine_latitude_weights
cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
weights = cosine_latitude_weights(cube)

Compute weights suitable for EOF analysis (or other covariance type analyses):

import numpy as np
from iris.analysis.cartography import cosine_latitude_weights
cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
weights = np.sqrt(cosine_latitude_weights(cube))

↑ top ↑

iris.analysis.cartography.get_xy_contiguous_bounded_grids(cube)

Return 2d arrays for x and y bounds.

Returns array of shape (n+1, m+1).

Example:

xs, ys = get_xy_contiguous_bounded_grids(cube)

↑ top ↑

iris.analysis.cartography.get_xy_grids(cube)

Return 2D X and Y points for a given cube.

Args:

  • cube - The cube for which to generate 2D X and Y points.

Example:

x, y = get_xy_grids(cube)

↑ top ↑

iris.analysis.cartography.project(cube, target_proj, nx=None, ny=None)

Nearest neighbour regrid to a specified target projection.

Return a new cube that is the result of projecting a cube with 1 or 2 dimensional latitude-longitude coordinates from its coordinate system into a specified projection e.g. Robinson or Polar Stereographic. This function is intended to be used in cases where the cube’s coordinates prevent one from directly visualising the data, e.g. when the longitude and latitude are two dimensional and do not make up a regular grid.

Args:
Kwargs:
  • nx

    Desired number of sample points in the x direction for a domain covering the globe.

  • ny

    Desired number of sample points in the y direction for a domain covering the globe.

Returns:
An instance of iris.cube.Cube and a list describing the extent of the projection.

Note

This function assumes global data and will if necessary extrapolate beyond the geographical extent of the source cube using a nearest neighbour approach. nx and ny then include those points which are outside of the target projection.

Note

Masked arrays are handled by passing their masked status to the resulting nearest neighbour values. If masked, the value in the resulting cube is set to 0.

Warning

This function uses a nearest neighbour approach rather than any form of linear/non-linear interpolation to determine the data value of each cell in the resulting cube. Consequently it may have an adverse effect on the statistics of the data e.g. the mean and standard deviation will not be preserved.

↑ top ↑

iris.analysis.cartography.rotate_pole(lons, lats, pole_lon, pole_lat)

Convert arrays of longitudes and latitudes to arrays of rotated-pole longitudes and latitudes. The values of pole_lon and pole_lat should describe the rotated pole that the arrays of longitudes and latitudes are to be rotated onto.

As the arrays of longitudes and latitudes must describe a rectilinear grid, the arrays of rotated-pole longitudes and latitudes must be of the same shape as each other.

Example:

rotated_lons, rotated_lats = rotate_pole(lons, lats,         pole_lon, pole_lat)

Note

Uses proj.4 to perform the conversion.

Args:

  • lons:

    An array of longitude values.

  • lats:

    An array of latitude values.

  • pole_lon:

    The longitude of the rotated pole that the arrays of longitudes and latitudes are to be rotated onto.

  • pole_lat:

    The latitude of the rotated pole that the arrays of longitudes and latitudes are to be rotated onto.

Returns:
An array of rotated-pole longitudes and an array of rotated-pole latitudes.

↑ top ↑

iris.analysis.cartography.rotate_winds(u_cube, v_cube, target_cs)

Transform wind vectors to a different coordinate system.

The input cubes contain U and V components parallel to the local X and Y directions of the input grid at each point.

The output cubes contain the same winds, at the same locations, but relative to the grid directions of a different coordinate system. Thus in vector terms, the magnitudes will always be the same, but the angles can be different.

The outputs retain the original horizontal dimension coordinates, but also have two 2-dimensional auxiliary coordinates containing the X and Y locations in the target coordinate system.

Args:

Returns:
A (u’, v’) tuple of iris.cube.Cube instances that are the u and v components in the requested target coordinate system. The units are the same as the inputs.

Note

The U and V values relate to distance, with units such as ‘m s-1’. These are not the same as coordinate vectors, which transform in a different manner.

Note

The names of the output cubes are those of the inputs, prefixed with ‘transformed_’ (e.g. ‘transformed_x_wind’).

Warning

Conversion between rotated-pole and non-rotated systems can be expressed analytically. However, this function always uses a numerical approach. In locations where this numerical approach does not preserve magnitude to an accuracy of 0.1%, the corresponding elements of the returned cubes will be masked.

↑ top ↑

iris.analysis.cartography.unrotate_pole(rotated_lons, rotated_lats, pole_lon, pole_lat)

Convert arrays of rotated-pole longitudes and latitudes to unrotated arrays of longitudes and latitudes. The values of pole_lon and pole_lat should describe the location of the rotated pole that describes the arrays of rotated-pole longitudes and latitudes.

As the arrays of rotated-pole longitudes and latitudes must describe a rectilinear grid, the arrays of rotated-pole longitudes and latitudes must be of the same shape as each other.

Example:

lons, lats = unrotate_pole(rotated_lons, rotated_lats,           pole_lon, pole_lat)

Note

Uses proj.4 to perform the conversion.

Args:

  • rotated_lons:

    An array of rotated-pole longitude values.

  • rotated_lats:

    An array of rotated-pole latitude values.

  • pole_lon:

    The longitude of the rotated pole that describes the arrays of rotated-pole longitudes and latitudes.

  • pole_lat:

    The latitude of the rotated pole that describes the arrays of rotated-pole longitudes and latitudes.

Returns:
An array of unrotated longitudes and an array of unrotated latitudes.

↑ top ↑

iris.analysis.cartography.wrap_lons(lons, base, period)

Wrap longitude values into the range between base and base+period.

For example:
>>> print(wrap_lons(np.array([185, 30, -200, 75]), -180, 360))
[-175.   30.  160.   75.]

↑ top ↑

DistanceDifferential(dx1, dy1, dx2, dy2)

class iris.analysis.cartography.DistanceDifferential(_cls, dx1, dy1, dx2, dy2)

Bases: tuple

Create new instance of DistanceDifferential(dx1, dy1, dx2, dy2)

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

dx1

Alias for field number 0

dx2

Alias for field number 2

dy1

Alias for field number 1

dy2

Alias for field number 3

↑ top ↑

PartialDifferential(dx1, dy1)

class iris.analysis.cartography.PartialDifferential(_cls, dx1, dy1)

Bases: tuple

Create new instance of PartialDifferential(dx1, dy1)

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

dx1

Alias for field number 0

dy1

Alias for field number 1