iris.analysis.cartography¶
Various utilities and numeric transformations relevant to cartography.
In this module:

iris.analysis.cartography.
area_weights
(cube, normalize=False)[source]¶ 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:
 cube (
iris.cube.Cube
): The cube to calculate area weights for.
 cube (
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:
\[r^2 (lon_1  lon_0) (\sin(lat_1)  \sin(lat_0))\]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.

iris.analysis.cartography.
cosine_latitude_weights
(cube)[source]¶ Returns an array of latitude weights, with the same dimensions as the cube. The weights are the cosine of latitude.
These are ndimensional 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:
\[w_l = \cos \phi_l\]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))

iris.analysis.cartography.
get_xy_contiguous_bounded_grids
(cube)[source]¶ 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)

iris.analysis.cartography.
get_xy_grids
(cube)[source]¶ Return 2D X and Y points for a given cube.
 Parameters
cube  The cube for which to generate 2D X and Y points. (*) –
Example:
x, y = get_xy_grids(cube)

iris.analysis.cartography.
gridcell_angles
(x, y=None, cell_angle_boundpoints='midlhs, midrhs')[source]¶ Calculate gridcell orientations for an arbitrary 2dimensional grid.
The input grid is defined by two 2dimensional coordinate arrays with the same dimensions (ny, nx), specifying the geolocations of a 2D mesh.
Input values may be coordinate points (ny, nx) or bounds (ny, nx, 4). However, if points, the edges in the X direction are assumed to be connected by wraparound.
Input can be either two arrays, two coordinates, or a single cube containing two suitable coordinates identified with the ‘x’ and ‘y’ axes.
Args:
The inputs (x [,y]) can be any of the following :
 x (
Cube
): a grid cube with 2D X and Y coordinates, identified by ‘axis’. The coordinates must be 2dimensional with the same shape. The two dimensions represent grid dimensions in the order Y, then X.
 x (
 x, y (
Coord
): X and Y coordinates, specifying grid locations on the globe. The coordinates must be 2dimensional with the same shape. The two dimensions represent grid dimensions in the order Y, then X. If there is no coordinate system, they are assumed to be true longitudes and latitudes. Units must convertible to ‘degrees’.
 x, y (
 x, y (2dimensional arrays of same shape (ny, nx)):
longitude and latitude cell center locations, in degrees. The two dimensions represent grid dimensions in the order Y, then X.
 x, y (3dimensional arrays of same shape (ny, nx, 4)):
longitude and latitude cell bounds, in degrees. The first two dimensions are grid dimensions in the order Y, then X. The last index maps cell corners anticlockwise from bottomleft.
Optional Args:
 cell_angle_boundpoints (string):
Controls which gridcell bounds locations are used to calculate angles, if the inputs are bounds or bounded coordinates. Valid values are ‘lowerleft, lowerright’, which takes the angle from the lower left to the lower right corner, and ‘midlhs, midrhs’ which takes an angles between the average of the lefthand and righthand pairs of corners. The default is ‘midlhs, midrhs’.
 Returns
(2dimensional cube)
Cube of angles of gridx vector from true Eastward direction for each gridcell, in degrees. It also has “true” longitude and latitude coordinates, with no coordinate system. When the input has coords, then the output ones are identical if the inputs are truelatlons, otherwise they are transformed truelatlon versions. When the input has bounded coords, then the output coords have matching bounds and centrepoints (possibly transformed). When the input is 2d arrays, or has unbounded coords, then the output coords have matching points and no bounds. When the input is 3d arrays, then the output coords have matching bounds, and the centrepoints are an average of the 4 boundpoints.
 Return type
angles

iris.analysis.cartography.
project
(cube, target_proj, nx=None, ny=None)[source]¶ 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 latitudelongitude 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.
 Parameters
cube (*) – An instance of
iris.cube.Cube
.target_proj (*) – An instance of the Cartopy Projection class, or an instance of
iris.coord_systems.CoordSystem
from which a projection will be obtained.
 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/nonlinear 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.
Warning
If the target projection is nonrectangular, e.g. Robinson, the target grid may include points outside the boundary of the projection. The latitude/longitude of such points may be unpredictable.

iris.analysis.cartography.
rotate_grid_vectors
(u_cube, v_cube, grid_angles_cube=None, grid_angles_kwargs=None)[source]¶ Rotate distance vectors from gridoriented to truelatlonoriented.
Can also rotate by arbitrary angles, if they are passed in.
Note
This operation overlaps somewhat in function with
iris.analysis.cartography.rotate_winds()
. However, that routine only rotates vectors according to transformations between coordinate systems. This function, by contrast, can rotate vectors by arbitrary angles. Most commonly, the angles are estimated solely from grid sampling points, usinggridcell_angles()
: This allows operation on complex meshes defined by twodimensional coordinates, such as most ocean grids.Args:
 u_cube, v_cube(cube)
Cubes of gridu and gridv vector components. Units should be differentials of truedistance, e.g. ‘m/s’.
Optional args:
 grid_angles_cube(cube)
gridcell orientation angles. Units must be angular, i.e. can be converted to ‘radians’. If not provided, grid angles are estimated from ‘u_cube’ using the
gridcell_angles()
method.
 grid_angles_kwargs(dict or None)
Additional keyword args to be passed to the
gridcell_angles()
method, if it is used.
 Returns
 (cube)
Cubes of truenorth oriented vector components. Units are same as inputs.
Note
Vector magnitudes will always be the same as the inputs.
 Return type
true_u, true_v

iris.analysis.cartography.
rotate_pole
(lons, lats, pole_lon, pole_lat)[source]¶ Convert arrays of longitudes and latitudes to arrays of rotatedpole longitudes and latitudes. The values of
pole_lon
andpole_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 rotatedpole 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.
 Parameters
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 rotatedpole longitudes and an array of rotatedpole latitudes.

iris.analysis.cartography.
rotate_winds
(u_cube, v_cube, target_cs)[source]¶ 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 2dimensional auxiliary coordinates containing the X and Y locations in the target coordinate system.
Args:
 u_cube
An instance of
iris.cube.Cube
that contains the xcomponent of the vector.
 v_cube
An instance of
iris.cube.Cube
that contains the ycomponent of the vector.
 target_cs
An instance of
iris.coord_systems.CoordSystem
that specifies the new grid directions.
 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 s1’. 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 rotatedpole and nonrotated 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.

iris.analysis.cartography.
unrotate_pole
(rotated_lons, rotated_lats, pole_lon, pole_lat)[source]¶ Convert arrays of rotatedpole longitudes and latitudes to unrotated arrays of longitudes and latitudes. The values of
pole_lon
andpole_lat
should describe the location of the rotated pole that describes the arrays of rotatedpole longitudes and latitudes.As the arrays of rotatedpole longitudes and latitudes must describe a rectilinear grid, the arrays of rotatedpole 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.
 Parameters
rotated_lons (*) – An array of rotatedpole longitude values.
rotated_lats (*) – An array of rotatedpole latitude values.
pole_lon (*) – The longitude of the rotated pole that describes the arrays of rotatedpole longitudes and latitudes.
pole_lat (*) – The latitude of the rotated pole that describes the arrays of rotatedpole longitudes and latitudes.
 Returns
An array of unrotated longitudes and an array of unrotated latitudes.

iris.analysis.cartography.
wrap_lons
(lons, base, period)[source]¶ 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.]
DistanceDifferential(dx1, dy1, dx2, dy2)
 class
iris.analysis.cartography.
DistanceDifferential
(_cls, dx1, dy1, dx2, dy2)¶Create new instance of DistanceDifferential(dx1, dy1, dx2, dy2)
count
(value, /)¶Return number of occurrences of value.
index
(value, start=0, stop=9223372036854775807, /)¶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
PartialDifferential(dx1, dy1)
 class
iris.analysis.cartography.
PartialDifferential
(_cls, dx1, dy1)¶Create new instance of PartialDifferential(dx1, dy1)
count
(value, /)¶Return number of occurrences of value.
index
(value, start=0, stop=9223372036854775807, /)¶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