iris.coords

Definitions of coordinates.

In this module:

• AuxCoord
• Cell
• CellMethod
• Coord
• CoordDefn
• DimCoord

---

A CF auxiliary coordinate.

class iris.coords.AuxCoord(points, standard_name=None, long_name=None, units='1', bounds=None, attributes=None, coord_system=None)

Constructs a single coordinate.

Args:

• points:

  The values (or value in the case of a scalar coordinate) of the coordinate for each cell.

Kwargs:

• standard_name:

  CF standard name of coordinate

• long_name:

  Descriptive name of coordinate

• units

  Unit for coordinate’s values

• bounds

  An array of values describing the bounds of each cell. The shape of the array must be compatible with the points array.

• attributes

  A dictionary containing other cf and user-defined attributes.

• coord_system

  A CoordSystem, e.g a LatLonCS for a longitude Coord.

cell(index)

Return the single Cell instance which results from slicing the points/bounds with the given index.

cells()

Returns an iterable of Cell instances for this Coord.

For example:

for cell in self.cells():
   ...

collapsed(dims_to_collapse=None)

Returns a copy of this coordinate which has been collapsed along the specified dimensions.

Replaces the points & bounds with a simple bounded region.

contiguous_bounds()

Returns the N+1 bound values for a contiguous bounded coordinate of length N.

copy(points=None, bounds=None)

Returns a copy of this coordinate.

Kwargs:

• points: A points array for the new coordinate.

  This may be a different shape to the points of the coordinate being copied.

• bounds: A bounds array for the new coordinate.

  This must be the compatible with the points array of the coordinate being created.

Note

If the points argument is specified and bounds are not, the resulting coordinate will have no bounds.

cos()

Return a coordinate which represents cos(this coordinate).

Note

If coordinate is in degrees then it is converted into radians before applying the cos() function.

static from_coord(coord)

Create a new AuxCoord from the given coordinate.

guess_bounds(bound_position=0.5)

Try to add bounds to this coordinate using the coordinate’s points.

Kwargs:

• bound_position - The desired position of the bounds relative to the position of the points.

This method only works for coordinates with coord.ndim == 1.

has_bounds()

index(cell)

Return the index of a given Cell in this Coord.

intersect(other, return_indices=False)

Returns a new coordinate from the intersection of two coordinates.

Both coordinates must have the same metadata, i.e. standard_name, long_name, units, attributes and coord_system.

Kwargs:

• return_indices:

  If True, changes the return behaviour to return the intersection indices for the “self” coordinate.

is_contiguous()

Return True if, and only if, this Coord is bounded with contiguous bounds.

is_monotonic()

Return True if, and only if, this Coord is monotonic.

name(default='unknown')

Returns a human-readable name.

First it tries standard_name, then it tries the ‘long_name’ attributes, before falling back to the value of default (which itself defaults to ‘unknown’).

nearest_neighbour_index(point)

Returns the index of the cell nearest to the given point.

Note

If the coordinate contain bounds, these will be used to determine the nearest neighbour instead of the point values.

Note

Does not take into account the circular attribute of a coordinate.

rename(name)

sin()

Return a coordinate which represents sin(this coordinate).

Note

If coordinate is in degrees then it is converted into radians before applying the sin() function.

unit_converted(new_unit)

Return a coordinate converted to a given unit.

xml_element(doc)

Return a DOM element describing this Coord.

attributes

bounds

Property containing the bound values, as a numpy array, or None if no bound values are defined.

Note

The shape of the bound array should be: points.shape + (n_bounds, ).

dtype

Abstract property which returns the Numpy data type of the Coordinate.

nbounds

Return the number of bounds that this coordinate has (0 for no bounds).

ndim

Return the number of dimensions of the coordinate (not including the bounded dimension).

points

Property containing the points values as a numpy array

shape

The fundamental shape of the Coord, expressed as a tuple.

standard_name

The standard name for the Cube’s data.

unit

The iris.unit.Unit instance representing the unit of the phenomenon.

Deprecated since version 0.9.

units

The Unit instance of the phenomenon.

---

An immutable representation of a single cell of a coordinate, including the sample point and/or boundary position.

class iris.coords.Cell(point=None, bound=None)

Construct a Cell from point or point-and-bound information.

Notes on cell comparison:

Cells can be compared in a number of ways depending on how they are configured and the data type they are being compared to.

For equality comparison (i.e. checking that a cell is equal to something) the following rules apply:

1. When comparing to another cell, equality is determined by comparing tuples of attribute values from both objects.
2. When comparing to a string value and cell point is also a string then comparison is done by string comparison.
3. When comparing to an integer or float and there are bounds set on the cell then the comparison is True if the numeric value ‘other’ is within the cells bounds. If no bounds are set on the cell then the comparison is performed on the cells point value.

For rich comparisions i.e. (less than, greater than, less than or equals and greater than or equals) the following rules apply:

1. When comparing to an integer, float or numpy.number and the cell is bounded, the comparison is performed on the max or min of the cells bounds. If the cell is unbounded then the numeric value is compared with the cells point value.

2. If both comparison objects are cells the following table describes how the objects are compared:

   # TODO: This seem wrong, due to the inconsistency between the first two scenarios. See #1278.

   Primary and comparison cell styles	Comparison method
   Bounded vs unbounded	Comparison point is compared to primary bounds.
   Unbounded vs bounded	Point values are compared.
   Bounded vs bounded	Points values and max or min of both bounds are compared

contains_point(point)

For a bounded cell, returns whether the given point lies within the bounds.

Note

The test carried out is equivalent to min(bound) <= point <= max(bound).

---

Represents a sub-cell pre-processing operation.

class iris.coords.CellMethod(method, coords=None, intervals=None, comments=None)

Args:

• method:

  The name of the operation.

Kwargs:

• coords:

  A single instance or sequence of Coord instances or coordinate names.

• intervals:

  A single string, or a sequence strings, describing the intervals within the cell method.

• comments:

  A single string, or a sequence strings, containing any additional comments.

xml_element(doc)

Return a dom element describing itself

comments = None

Additional comments.

coord_names = None

The tuple of coordinate names over which the operation was applied.

intervals = None

A description of the original intervals over which the operation was applied.

method = None

The name of the operation that was applied. e.g. “mean”, “max”, etc.

---

Abstract superclass for coordinates.

class iris.coords.Coord(points, standard_name=None, long_name=None, units='1', bounds=None, attributes=None, coord_system=None)

Constructs a single coordinate.

Args:

• points:

  The values (or value in the case of a scalar coordinate) of the coordinate for each cell.

Kwargs:

• standard_name:

  CF standard name of coordinate

• long_name:

  Descriptive name of coordinate

• units

  Unit for coordinate’s values

• bounds

  An array of values describing the bounds of each cell. The shape of the array must be compatible with the points array.

• attributes

  A dictionary containing other cf and user-defined attributes.

• coord_system

  A CoordSystem, e.g a LatLonCS for a longitude Coord.

cell(index)

Return the single Cell instance which results from slicing the points/bounds with the given index.

cells()

Returns an iterable of Cell instances for this Coord.

For example:

for cell in self.cells():
   ...

collapsed(dims_to_collapse=None)

Returns a copy of this coordinate which has been collapsed along the specified dimensions.

Replaces the points & bounds with a simple bounded region.

contiguous_bounds()

Returns the N+1 bound values for a contiguous bounded coordinate of length N.

copy(points=None, bounds=None)

Returns a copy of this coordinate.

Kwargs:

• points: A points array for the new coordinate.

  This may be a different shape to the points of the coordinate being copied.

• bounds: A bounds array for the new coordinate.

  This must be the compatible with the points array of the coordinate being created.

Note

If the points argument is specified and bounds are not, the resulting coordinate will have no bounds.

cos()

Return a coordinate which represents cos(this coordinate).

Note

If coordinate is in degrees then it is converted into radians before applying the cos() function.

guess_bounds(bound_position=0.5)

Try to add bounds to this coordinate using the coordinate’s points.

Kwargs:

• bound_position - The desired position of the bounds relative to the position of the points.

This method only works for coordinates with coord.ndim == 1.

has_bounds()

index(cell)

Return the index of a given Cell in this Coord.

intersect(other, return_indices=False)

Returns a new coordinate from the intersection of two coordinates.

Both coordinates must have the same metadata, i.e. standard_name, long_name, units, attributes and coord_system.

Kwargs:

• return_indices:

  If True, changes the return behaviour to return the intersection indices for the “self” coordinate.

is_contiguous()

Return True if, and only if, this Coord is bounded with contiguous bounds.

is_monotonic()

Return True if, and only if, this Coord is monotonic.

name(default='unknown')

Returns a human-readable name.

First it tries standard_name, then it tries the ‘long_name’ attributes, before falling back to the value of default (which itself defaults to ‘unknown’).

nearest_neighbour_index(point)

Returns the index of the cell nearest to the given point.

Note

If the coordinate contain bounds, these will be used to determine the nearest neighbour instead of the point values.

Note

Does not take into account the circular attribute of a coordinate.

rename(name)

sin()

Return a coordinate which represents sin(this coordinate).

Note

If coordinate is in degrees then it is converted into radians before applying the sin() function.

unit_converted(new_unit)

Return a coordinate converted to a given unit.

xml_element(doc)

Return a DOM element describing this Coord.

attributes

Other attributes, including user specified attributes that have no meaning to Iris.

bounds

Property containing the bound values as a numpy array

coord_system = None

Relevant CoordSystem (if any).

dtype

Abstract property which returns the Numpy data type of the Coordinate.

long_name = None

Descriptive name of the coordinate.

nbounds

Return the number of bounds that this coordinate has (0 for no bounds).

ndim

Return the number of dimensions of the coordinate (not including the bounded dimension).

points

Property containing the points values as a numpy array

shape

The fundamental shape of the Coord, expressed as a tuple.

standard_name

CF standard name of the quantity that the coordinate represents.

unit

The iris.unit.Unit instance representing the unit of the phenomenon.

Deprecated since version 0.9.

units

Unit of the quantity that the coordinate represents.

---

Criterion for identifying a specific type of DimCoord or AuxCoord based on its metadata.

class iris.coords.CoordDefn(_cls, standard_name, long_name, units, attributes, coord_system)

Create new instance of CoordDefn(standard_name, long_name, units, attributes, coord_system)

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.

name(default='unknown')

Returns a human-readable name.

First it tries self.standard_name, then it tries the ‘long_name’ attributes, before falling back to the value of default (which itself defaults to ‘unknown’).

attributes

Alias for field number 3

coord_system

Alias for field number 4

long_name

Alias for field number 1

standard_name

Alias for field number 0

units

Alias for field number 2

---

A coordinate that is 1D, numeric, and strictly monotonic.

class iris.coords.DimCoord(points, standard_name=None, long_name=None, units='1', bounds=None, attributes=None, coord_system=None, circular=False)

Create a 1D, numeric, and strictly monotonic Coord with read-only points and bounds.

cell(index)

Return the single Cell instance which results from slicing the points/bounds with the given index.

cells()

Returns an iterable of Cell instances for this Coord.

For example:

for cell in self.cells():
   ...

collapsed(dims_to_collapse=None)

contiguous_bounds()

Returns the N+1 bound values for a contiguous bounded coordinate of length N.

copy(points=None, bounds=None)

Returns a copy of this coordinate.

Kwargs:

• points: A points array for the new coordinate.

  This may be a different shape to the points of the coordinate being copied.

• bounds: A bounds array for the new coordinate.

  This must be the compatible with the points array of the coordinate being created.

Note

If the points argument is specified and bounds are not, the resulting coordinate will have no bounds.

cos()

Return a coordinate which represents cos(this coordinate).

Note

If coordinate is in degrees then it is converted into radians before applying the cos() function.

static from_coord(coord)

Create a new DimCoord from the given coordinate.

guess_bounds(bound_position=0.5)

Try to add bounds to this coordinate using the coordinate’s points.

Kwargs:

• bound_position - The desired position of the bounds relative to the position of the points.

This method only works for coordinates with coord.ndim == 1.

has_bounds()

index(cell)

Return the index of a given Cell in this Coord.

intersect(other, return_indices=False)

Returns a new coordinate from the intersection of two coordinates.

Both coordinates must have the same metadata, i.e. standard_name, long_name, units, attributes and coord_system.

Kwargs:

• return_indices:

  If True, changes the return behaviour to return the intersection indices for the “self” coordinate.

is_contiguous()

Return True if, and only if, this Coord is bounded with contiguous bounds.

is_monotonic()

name(default='unknown')

Returns a human-readable name.

First it tries standard_name, then it tries the ‘long_name’ attributes, before falling back to the value of default (which itself defaults to ‘unknown’).

nearest_neighbour_index(point)

Returns the index of the cell nearest to the given point.

Note

If the coordinate contain bounds, these will be used to determine the nearest neighbour instead of the point values.

Note

Does not take into account the circular attribute of a coordinate.

rename(name)

sin()

Return a coordinate which represents sin(this coordinate).

Note

If coordinate is in degrees then it is converted into radians before applying the sin() function.

unit_converted(new_unit)

Return a coordinate converted to a given unit.

xml_element(doc)

Return a DOM element describing this Coord.

attributes

bounds

The bounds values as a read-only NumPy array, or None if no bounds have been set.

circular = None

Whether the coordinate wraps by coord.units.modulus.

dtype

Abstract property which returns the Numpy data type of the Coordinate.

nbounds

Return the number of bounds that this coordinate has (0 for no bounds).

ndim

Return the number of dimensions of the coordinate (not including the bounded dimension).

points

The local points values as a read-only NumPy array.

shape

The fundamental shape of the Coord, expressed as a tuple.

standard_name

The standard name for the Cube’s data.

unit

The iris.unit.Unit instance representing the unit of the phenomenon.

Deprecated since version 0.9.

units

The Unit instance of the phenomenon.