iris.coords#

Definitions of coordinates and other dimensional metadata.

class iris.coords.AncillaryVariable(data, standard_name=None, long_name=None, var_name=None, units=None, attributes=None)[source]#

Bases: _DimensionalMetadata

Construct a single ancillary variable.

Parameters:

data – The values of the ancillary variable.
standard_name (optional) – CF standard name of the ancillary variable.
long_name (optional) – Descriptive name of the ancillary variable.
var_name (optional) – The netCDF variable name for the ancillary variable.
units (optional) – The Unit of the ancillary variable’s values. Can be a string, which will be converted to a Unit object.
attributes (optional) – A dictionary containing other cf and user-defined attributes.

__binary_operator__(other, mode_constant)#

Perform common code which is called by add, sub, mul and div.

Mode constant is one of ADD, SUB, MUL, DIV, RDIV

Note

The unit is not changed when doing scalar operations on a metadata object. This means that a metadata object which represents “10 meters” when multiplied by a scalar i.e. “1000” would result in a metadata object of “10000 meters”. An alternative approach could be taken to multiply the unit by 1000 and the resultant metadata object would represent “10 kilometers”.

__getitem__(keys)#: Return a new dimensional metadata whose values are obtained by conventional array indexing.

Note

Indexing of a circular coordinate results in a non-circular coordinate if the overall shape of the coordinate changes after indexing.

property attributes#

convert_units(unit)#: Change the units, converting the values of the metadata.

copy(values=None)#

Return a copy of this dimensional metadata object.

Parameters:: values (optional) – An array of values for the new dimensional metadata object. This may be a different shape to the original values array being copied.

core_data()[source]#

Return data array at the core of this ancillary variable.

The data array at the core of this ancillary variable, which may be a NumPy array or a dask array.

cube_dims(cube)[source]#

Return the cube dimensions of this AncillaryVariable.

Equivalent to “cube.ancillary_variable_dims(self)”.

property data#

property dtype#: The NumPy dtype of the current dimensional metadata object, as specified by its values.

has_bounds()#: Indicate whether the current dimensional metadata object has a bounds array.

has_lazy_data()[source]#: Indicate whether the ancillary variable’s data array is a lazy dask array or not.

is_compatible(other, ignore=None)#: Return whether the current dimensional metadata object is compatible with another.

lazy_data()[source]#

Return a lazy array representing the ancillary variable’s data.

Accessing this method will never cause the data values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the ancillary variable to have loaded data.

If the data have already been loaded for the ancillary variable, the returned Array will be a new lazy array wrapper.

Return type:: A lazy array, representing the ancillary variable data array.

property long_name#: The CF Metadata long name for the object.

property metadata#

name(default=None, token=False)#

Return a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Return type:

str

property ndim#: Return the number of dimensions of the current dimensional metadata object.

rename(name)#

Change the human-readable name.

If ‘name’ is a valid standard name it will assign it to standard_name, otherwise it will assign it to long_name.

property shape#: The fundamental shape of the metadata, expressed as a tuple.

property standard_name#: The CF Metadata standard name for the object.

summary(shorten=False, max_values=None, edgeitems=2, linewidth=None, precision=None, convert_dates=True, _section_indices=None)#

Make a printable text summary.

Parameters:

shorten (bool, default=False) – If True, produce an abbreviated one-line summary. If False, produce a multi-line summary, with embedded newlines.
max_values (int or None) – If more than this many data values, print truncated data arrays instead of full contents. If 0, print only the shape. The default is 5 if shorten=True, or 15 otherwise. This overrides numpy.get_printoptions['threshold'].
linewidth (int or None) – Character-width controlling line splitting of array outputs. If unset, defaults to numpy.get_printoptions['linewidth'].
edgeitems (int, default=2) – Controls truncated array output. Overrides numpy.getprintoptions['edgeitems'].
precision (int or None) – Controls number decimal formatting. When shorten=True this is defaults to 3, in which case it overrides numpy.get_printoptions()['precision'].
convert_dates (bool, default=True) – If the units has a calendar, then print array values as date strings instead of the actual numbers.

Returns:

Output text, with embedded newlines when shorten=False.

Return type:

str

Notes

Note

Arrays are formatted using numpy.array2string(). Some aspects of the array formatting are controllable in the usual way, via numpy.printoptions(), but others are overridden as detailed above. Control of those aspects is still available, but only via the call arguments.

property units#: The S.I. unit of the object.

property var_name#: The NetCDF variable name for the object.

xml_element(doc)#

Create XML element.

Create the xml.dom.minidom.Element that describes this _DimensionalMetadata.

Parameters:: doc – The parent xml.dom.minidom.Document.
Returns:: xml.dom.minidom.Element that will describe this _DimensionalMetadata.
Return type:: xml.dom.minidom.Element

class iris.coords.AuxCoord(*args, **kwargs)[source]#

Bases: Coord

A CF auxiliary coordinate.

Create a coordinate with mutable points and bounds.

Parameters:

points – The values (or value in the case of a scalar coordinate) for each cell of the coordinate.
standard_name (optional) – CF standard name of the coordinate.
long_name (optional) – Descriptive name of the coordinate.
var_name (optional) – The netCDF variable name for the coordinate.
unit (Unit, optional) – The Unit of the coordinate’s values. Can be a string, which will be converted to a Unit object.
bounds (optional) – An array of values describing the bounds of each cell. Given n bounds for each cell, the shape of the bounds array should be points.shape + (n,). For example, a 1D coordinate with 100 points and two bounds per cell would have a bounds array of shape (100, 2) Note if the data is a climatology, climatological should be set.
attributes (optional) – A dictionary containing other CF and user-defined attributes.
coord_system (CoordSystem, optional) – A CoordSystem representing the coordinate system of the coordinate, e.g., a GeogCS for a longitude coordinate.
bool (climatological) – When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a ‘climatology’ attribute and will create a boundary variable called ‘<coordinate-name>_climatology’ in place of a standard bounds attribute and bounds variable. Will set to True when a climatological time axis is loaded from NetCDF. Always False if no bounds exist.
optional – When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a ‘climatology’ attribute and will create a boundary variable called ‘<coordinate-name>_climatology’ in place of a standard bounds attribute and bounds variable. Will set to True when a climatological time axis is loaded from NetCDF. Always False if no bounds exist.

__binary_operator__(other, mode_constant)#

Perform common code which is called by add, sub, mul and div.

Mode constant is one of ADD, SUB, MUL, DIV, RDIV

Note

__getitem__(keys)#: Return a new dimensional metadata whose values are obtained by conventional array indexing.

Note

Indexing of a circular coordinate results in a non-circular coordinate if the overall shape of the coordinate changes after indexing.

property attributes#

property bounds#

Coordinate bounds values.

The coordinate bounds 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, ).

property bounds_dtype#

The NumPy dtype of the coordinates bounds.

The NumPy dtype of the coord’s bounds. Will be None if the coord does not have bounds.

cell(index)#

Point/bound cell at the given coordinate index.

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

cells()#

Return an iterable of Cell instances for this Coord.

For example:

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

property climatological#

Flag for representing a climatological time axis.

A boolean that controls whether the coordinate is a climatological time axis, in which case the bounds represent a climatological period rather than a normal period.

Always reads as False if there are no bounds. On set, the input value is cast to a boolean, exceptions raised if units are not time units or if there are no bounds.

collapsed(dims_to_collapse=None)#

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

Replaces the points & bounds with a simple bounded region.

contiguous_bounds()#

Contiguous bounds of 1D coordinate.

Return the N+1 bound values for a contiguous bounded 1D coordinate of length N, or the (N+1, M+1) bound values for a contiguous bounded 2D coordinate of shape (N, M).

Only 1D or 2D coordinates are supported.

Note

If the coordinate has bounds, this method assumes they are contiguous.

If the coordinate is 1D and does not have bounds, this method will return bounds positioned halfway between the coordinate’s points.

If the coordinate is 2D and does not have bounds, an error will be raised.

convert_units(unit)#

Change the coordinate’s units, converting the values in its points and bounds arrays.

For example, if a coordinate’s units attribute is set to radians then:

coord.convert_units('degrees')

will change the coordinate’s units attribute to degrees and multiply each value in points and bounds by 180.0/\(\pi\).

Full list of supported units can be found in the UDUNITS-2 documentation https://docs.unidata.ucar.edu/udunits/current/#Database

property coord_system#: The coordinate-system of the coordinate.

copy(points=None, bounds=None)#

Return a copy of this coordinate.

Parameters:

points (optional) – A points array for the new coordinate. This may be a different shape to the points of the coordinate being copied.
bounds (optional) – A bounds array for the new coordinate. Given n bounds for each cell, the shape of the bounds array should be points.shape + (n,). For example, a 1d coordinate with 100 points and two bounds per cell would have a bounds array of shape (100, 2).

Notes

Note

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

core_bounds()#: Core bounds. The points array at the core of this coord, which may be a NumPy array or a dask array.

core_points()#: Core points array at the core of this coord, which may be a NumPy array or a dask array.

cube_dims(cube)#

Return the cube dimensions of this Coord.

Equivalent to “cube.coord_dims(self)”.

property dtype#: The NumPy dtype of the current dimensional metadata object, as specified by its values.

classmethod from_coord(coord)#: Create a new Coord of this type, from the given coordinate.

guess_bounds(bound_position=0.5)#

Add contiguous bounds to a coordinate, calculated from its points.

Puts a cell boundary at the specified fraction between each point and the next, plus extrapolated lowermost and uppermost bound points, so that each point lies within a cell.

With regularly spaced points, the resulting bounds will also be regular, and all points lie at the same position within their cell. With irregular points, the first and last cells are given the same widths as the ones next to them.

Parameters:: bound_position (float, default=0.5) – The desired position of the bounds relative to the position of the points.

Notes

Note

An error is raised if the coordinate already has bounds, is not one-dimensional, or is not monotonic.

Note

Unevenly spaced values, such from a wrapped longitude range, can produce unexpected results : In such cases you should assign suitable values directly to the bounds property, instead.

has_bounds()#: Return a boolean indicating whether the coord has a bounds array.

has_lazy_bounds()#

Whether coordinate bounds are lazy.

Return a boolean indicating whether the coord’s bounds array is a lazy dask array or not.

has_lazy_points()#: Return a boolean whether the coord’s points array is a lazy dask array or not.

property ignore_axis#

A boolean controlling if iris.util.guess_coord_axis acts on this coordinate.

Defaults to False, and when set to True it will be skipped by iris.util.guess_coord_axis().

intersect(other, return_indices=False)#

Return a new coordinate from the intersection of two coordinates.

Both coordinates must be compatible as defined by is_compatible().

Parameters:: return_indices (bool, default=False) – If True, changes the return behaviour to return the intersection indices for the “self” coordinate.

is_compatible(other, ignore=None)#

Return whether the coordinate is compatible with another.

Compatibility is determined by comparing iris.coords.Coord.name(), iris.coords.Coord.units, iris.coords.Coord.coord_system and iris.coords.Coord.attributes that are present in both objects.

Parameters:

other – An instance of iris.coords.Coord, iris.common.CoordMetadata or iris.common.DimCoordMetadata.
ignore (optional) – A single attribute key or iterable of attribute keys to ignore when comparing the coordinates. Default is None. To ignore all attributes, set this to other.attributes.

Return type:

bool

is_contiguous(rtol=1e-05, atol=1e-08)#

Whether coordinate has contiguous bounds.

Return True if, and only if, this Coord is bounded with contiguous bounds to within the specified relative and absolute tolerances.

1D coords are contiguous if the upper bound of a cell aligns, within a tolerance, to the lower bound of the next cell along.

2D coords, with 4 bounds, are contiguous if the lower right corner of each cell aligns with the lower left corner of the cell to the right of it, and the upper left corner of each cell aligns with the lower left corner of the cell above it.

Parameters:

rtol (float, default=1e-05) – The relative tolerance parameter (default is 1e-05).
atol (float, default=1e-08) – The absolute tolerance parameter (default is 1e-08).

Return type:

bool

is_monotonic()#: Return True if, and only if, this Coord is monotonic.

lazy_bounds()#

Return a lazy array representing the coord bounds.

Accessing this method will never cause the bounds values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the coord to have loaded bounds.

If the data have already been loaded for the coord, the returned Array will be a new lazy array wrapper.

Returns:: A lazy array representing the coord bounds array or None if the coord does not have bounds.
Return type:: lazy array

lazy_points()#

Return a lazy array representing the coord points.

Accessing this method will never cause the points values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the coord to have loaded points.

If the data have already been loaded for the coord, the returned Array will be a new lazy array wrapper.

Return type:: A lazy array, representing the coord points array.

property long_name#: The CF Metadata long name for the object.

property metadata#

name(default=None, token=False)#

Return a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Return type:

str

property nbounds#: Return the number of bounds that this coordinate has (0 for no bounds).

property ndim#: Return the number of dimensions of the current dimensional metadata object.

nearest_neighbour_index(point)#

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

Only works for one-dimensional coordinates.

For example:

>>> cube = iris.load_cube(iris.sample_data_path('ostia_monthly.nc'))
>>> cube.coord('latitude').nearest_neighbour_index(0)
9
>>> cube.coord('longitude').nearest_neighbour_index(10)
12

Note

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

Note

For circular coordinates, the ‘nearest’ point can wrap around to the other end of the values.

property points#: The coordinate points values as a NumPy array.

rename(name)#

Change the human-readable name.

If ‘name’ is a valid standard name it will assign it to standard_name, otherwise it will assign it to long_name.

property shape#: The fundamental shape of the metadata, expressed as a tuple.

property standard_name#: The CF Metadata standard name for the object.

summary(shorten=False, max_values=None, edgeitems=2, linewidth=None, precision=None, convert_dates=True, _section_indices=None)#

Make a printable text summary.

Parameters:

shorten (bool, default=False) – If True, produce an abbreviated one-line summary. If False, produce a multi-line summary, with embedded newlines.
max_values (int or None) – If more than this many data values, print truncated data arrays instead of full contents. If 0, print only the shape. The default is 5 if shorten=True, or 15 otherwise. This overrides numpy.get_printoptions['threshold'].
linewidth (int or None) – Character-width controlling line splitting of array outputs. If unset, defaults to numpy.get_printoptions['linewidth'].
edgeitems (int, default=2) – Controls truncated array output. Overrides numpy.getprintoptions['edgeitems'].
precision (int or None) – Controls number decimal formatting. When shorten=True this is defaults to 3, in which case it overrides numpy.get_printoptions()['precision'].
convert_dates (bool, default=True) – If the units has a calendar, then print array values as date strings instead of the actual numbers.

Returns:

Output text, with embedded newlines when shorten=False.

Return type:

str

Notes

Note

property units#: The S.I. unit of the object.

property var_name#: The NetCDF variable name for the object.

xml_element(doc)#

Create the xml.dom.minidom.Element that describes this Coord.

Parameters:: doc – The parent xml.dom.minidom.Document.
Returns:: The xml.dom.minidom.Element that will describe this DimCoord.
Return type:: xml.dom.minidom.Element

class iris.coords.Cell(point=None, bound=None)[source]#

Bases: Cell

A coordinate cell containing a single point, or point and bounds.

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

Notes on cell comparison:

Cells are compared in two ways, depending on whether they are compared to another Cell, or to a number/string.

Cell-Cell comparison is defined to produce a strict ordering. If two cells are not exactly equal (i.e. including whether they both define bounds or not) then they will have a consistent relative order.

Cell-number and Cell-string comparison is defined to support Constraint matching. The number/string will equal the Cell if, and only if, it is within the Cell (including on the boundary). The relative comparisons (lt, le, ..) are defined to be consistent with this interpretation. So for a given value n and Cell cell, only one of the following can be true:

n < cell
n == cell
n > cell

Similarly, n <= cell implies either n < cell or n == cell. And n >= cell implies either n > cell or n == cell.

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

__common_cmp__(other, operator_method)[source]#

Common equality comparison.

Common method called by the rich comparison operators. The method of checking equality depends on the type of the object to be compared.

Cell vs Cell comparison is used to define a strict order. Non-Cell vs Cell comparison is used to define Constraint matching.

__eq__(other)[source]#: Compare Cell equality depending on the type of the object to be compared.

static __new__(cls, point=None, bound=None)[source]#: Construct a Cell from point or point-and-bound information.

bound#: Alias for field number 1

contains_point(point)[source]#: 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).

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.

point#: Alias for field number 0

class iris.coords.CellMeasure(data, standard_name=None, long_name=None, var_name=None, units=None, attributes=None, measure=None)[source]#

Bases: AncillaryVariable

A CF Cell Measure, providing area or volume properties of a cell.

A CF Cell Measure, providing area or volume properties of a cell where these cannot be inferred from the Coordinates and Coordinate Reference System.

Construct a single cell measure.

Parameters:

data – The values of the measure for each cell. Either a ‘real’ array (numpy.ndarray) or a ‘lazy’ array (dask.array.Array).
standard_name (optional) – CF standard name of the coordinate.
long_name (optional) – Descriptive name of the coordinate.
var_name (optional) – The netCDF variable name for the coordinate.
units (optional) – The Unit of the coordinate’s values. Can be a string, which will be converted to a Unit object.
attributes (optional) – A dictionary containing other CF and user-defined attributes.
measure (optional) – A string describing the type of measure. Supported values are ‘area’ and ‘volume’. The default is ‘area’.

__binary_operator__(other, mode_constant)#

Perform common code which is called by add, sub, mul and div.

Mode constant is one of ADD, SUB, MUL, DIV, RDIV

Note

__getitem__(keys)#: Return a new dimensional metadata whose values are obtained by conventional array indexing.

Note

Indexing of a circular coordinate results in a non-circular coordinate if the overall shape of the coordinate changes after indexing.

property attributes#

convert_units(unit)#: Change the units, converting the values of the metadata.

copy(values=None)#

Return a copy of this dimensional metadata object.

Parameters:: values (optional) – An array of values for the new dimensional metadata object. This may be a different shape to the original values array being copied.

core_data()#

Return data array at the core of this ancillary variable.

The data array at the core of this ancillary variable, which may be a NumPy array or a dask array.

cube_dims(cube)[source]#

Return the cube dimensions of this CellMeasure.

Equivalent to “cube.cell_measure_dims(self)”.

property data#

property dtype#: The NumPy dtype of the current dimensional metadata object, as specified by its values.

has_bounds()#: Indicate whether the current dimensional metadata object has a bounds array.

has_lazy_data()#: Indicate whether the ancillary variable’s data array is a lazy dask array or not.

is_compatible(other, ignore=None)#: Return whether the current dimensional metadata object is compatible with another.

lazy_data()#

Return a lazy array representing the ancillary variable’s data.

Accessing this method will never cause the data values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the ancillary variable to have loaded data.

If the data have already been loaded for the ancillary variable, the returned Array will be a new lazy array wrapper.

Return type:: A lazy array, representing the ancillary variable data array.

property long_name#: The CF Metadata long name for the object.

property measure#: String naming the measure type.

property metadata#

name(default=None, token=False)#

Return a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Return type:

str

property ndim#: Return the number of dimensions of the current dimensional metadata object.

rename(name)#

Change the human-readable name.

If ‘name’ is a valid standard name it will assign it to standard_name, otherwise it will assign it to long_name.

property shape#: The fundamental shape of the metadata, expressed as a tuple.

property standard_name#: The CF Metadata standard name for the object.

summary(shorten=False, max_values=None, edgeitems=2, linewidth=None, precision=None, convert_dates=True, _section_indices=None)#

Make a printable text summary.

Parameters:

shorten (bool, default=False) – If True, produce an abbreviated one-line summary. If False, produce a multi-line summary, with embedded newlines.
max_values (int or None) – If more than this many data values, print truncated data arrays instead of full contents. If 0, print only the shape. The default is 5 if shorten=True, or 15 otherwise. This overrides numpy.get_printoptions['threshold'].
linewidth (int or None) – Character-width controlling line splitting of array outputs. If unset, defaults to numpy.get_printoptions['linewidth'].
edgeitems (int, default=2) – Controls truncated array output. Overrides numpy.getprintoptions['edgeitems'].
precision (int or None) – Controls number decimal formatting. When shorten=True this is defaults to 3, in which case it overrides numpy.get_printoptions()['precision'].
convert_dates (bool, default=True) – If the units has a calendar, then print array values as date strings instead of the actual numbers.

Returns:

Output text, with embedded newlines when shorten=False.

Return type:

str

Notes

Note

property units#: The S.I. unit of the object.

property var_name#: The NetCDF variable name for the object.

xml_element(doc)[source]#

Create the xml.dom.minidom.Element that describes this CellMeasure.

Parameters:: doc – The parent xml.dom.minidom.Document.
Returns:: The xml.dom.minidom.Element that describes this CellMeasure.
Return type:: xml.dom.minidom.Element

class iris.coords.CellMethod(method, coords=None, intervals=None, comments=None)[source]#

Bases: _OrderedHashable

Represents a sub-cell pre-processing operation.

Call Method initialise.

Parameters:

method – The name of the operation.
coords (Coord instances, optional) – A single instance or sequence of Coord instances or coordinate names.
intervals (optional) – A single string, or a sequence strings, describing the intervals within the cell method.
comments (optional) – A single string, or a sequence strings, containing any additional comments.

__str__()[source]#: Return a custom string representation of CellMethod.

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.

xml_element(doc)[source]#

Create the xml.dom.minidom.Element that describes this CellMethod.

Parameters:: doc – The parent xml.dom.minidom.Document.
Returns:: The xml.dom.minidom.Element that describes this CellMethod.
Return type:: xml.dom.minidom.Element

class iris.coords.Coord(points, standard_name=None, long_name=None, var_name=None, units=None, bounds=None, attributes=None, coord_system=None, climatological=False)[source]#

Bases: _DimensionalMetadata

Abstract base class for coordinates.

Coordinate abstract base class.

As of v3.0.0 you cannot create an instance of Coord.

Parameters:

points – The values (or value in the case of a scalar coordinate) for each cell of the coordinate.
standard_name (optional) – CF standard name of the coordinate.
long_name (optional) – Descriptive name of the coordinate.
var_name (optional) – The netCDF variable name for the coordinate.
units (optional) – The Unit of the coordinate’s values. Can be a string, which will be converted to a Unit object.
bounds (optional) – An array of values describing the bounds of each cell. Given n bounds for each cell, the shape of the bounds array should be points.shape + (n,). For example, a 1D coordinate with 100 points and two bounds per cell would have a bounds array of shape (100, 2) Note if the data is a climatology, climatological should be set.
attributes (optional) – A dictionary containing other CF and user-defined attributes.
coord_system (optional) – A CoordSystem representing the coordinate system of the coordinate, e.g., a GeogCS for a longitude coordinate.
climatological (bool, default=False) – When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a ‘climatology’ attribute and will create a boundary variable called ‘<coordinate-name>_climatology’ in place of a standard bounds attribute and bounds variable. Will set to True when a climatological time axis is loaded from NetCDF. Always False if no bounds exist.

__binary_operator__(other, mode_constant)#

Perform common code which is called by add, sub, mul and div.

Mode constant is one of ADD, SUB, MUL, DIV, RDIV

Note

__getitem__(keys)#: Return a new dimensional metadata whose values are obtained by conventional array indexing.

Note

Indexing of a circular coordinate results in a non-circular coordinate if the overall shape of the coordinate changes after indexing.

property attributes#

property bounds#

Coordinate bounds values.

The coordinate bounds 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, ).

property bounds_dtype#

The NumPy dtype of the coordinates bounds.

The NumPy dtype of the coord’s bounds. Will be None if the coord does not have bounds.

cell(index)[source]#

Point/bound cell at the given coordinate index.

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

cells()[source]#

Return an iterable of Cell instances for this Coord.

For example:

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

property climatological#

Flag for representing a climatological time axis.

A boolean that controls whether the coordinate is a climatological time axis, in which case the bounds represent a climatological period rather than a normal period.

Always reads as False if there are no bounds. On set, the input value is cast to a boolean, exceptions raised if units are not time units or if there are no bounds.

collapsed(dims_to_collapse=None)[source]#

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

Replaces the points & bounds with a simple bounded region.

contiguous_bounds()[source]#

Contiguous bounds of 1D coordinate.

Return the N+1 bound values for a contiguous bounded 1D coordinate of length N, or the (N+1, M+1) bound values for a contiguous bounded 2D coordinate of shape (N, M).

Only 1D or 2D coordinates are supported.

Note

If the coordinate has bounds, this method assumes they are contiguous.

If the coordinate is 1D and does not have bounds, this method will return bounds positioned halfway between the coordinate’s points.

If the coordinate is 2D and does not have bounds, an error will be raised.

convert_units(unit)[source]#

Change the coordinate’s units, converting the values in its points and bounds arrays.

For example, if a coordinate’s units attribute is set to radians then:

coord.convert_units('degrees')

will change the coordinate’s units attribute to degrees and multiply each value in points and bounds by 180.0/\(\pi\).

Full list of supported units can be found in the UDUNITS-2 documentation https://docs.unidata.ucar.edu/udunits/current/#Database

property coord_system#: Relevant coordinate system (if any).

copy(points=None, bounds=None)[source]#

Return a copy of this coordinate.

Parameters:

points (optional) – A points array for the new coordinate. This may be a different shape to the points of the coordinate being copied.
bounds (optional) – A bounds array for the new coordinate. Given n bounds for each cell, the shape of the bounds array should be points.shape + (n,). For example, a 1d coordinate with 100 points and two bounds per cell would have a bounds array of shape (100, 2).

Notes

Note

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

core_bounds()[source]#: Core bounds. The points array at the core of this coord, which may be a NumPy array or a dask array.

core_points()[source]#: Core points array at the core of this coord, which may be a NumPy array or a dask array.

cube_dims(cube)[source]#

Return the cube dimensions of this Coord.

Equivalent to “cube.coord_dims(self)”.

property dtype#: The NumPy dtype of the current dimensional metadata object, as specified by its values.

classmethod from_coord(coord)[source]#: Create a new Coord of this type, from the given coordinate.

guess_bounds(bound_position=0.5)[source]#

Add contiguous bounds to a coordinate, calculated from its points.

Puts a cell boundary at the specified fraction between each point and the next, plus extrapolated lowermost and uppermost bound points, so that each point lies within a cell.

Parameters:: bound_position (float, default=0.5) – The desired position of the bounds relative to the position of the points.

Notes

Note

An error is raised if the coordinate already has bounds, is not one-dimensional, or is not monotonic.

Note

Unevenly spaced values, such from a wrapped longitude range, can produce unexpected results : In such cases you should assign suitable values directly to the bounds property, instead.

has_bounds()[source]#: Return a boolean indicating whether the coord has a bounds array.

has_lazy_bounds()[source]#

Whether coordinate bounds are lazy.

Return a boolean indicating whether the coord’s bounds array is a lazy dask array or not.

has_lazy_points()[source]#: Return a boolean whether the coord’s points array is a lazy dask array or not.

property ignore_axis#

A boolean controlling if iris.util.guess_coord_axis acts on this coordinate.

Defaults to False, and when set to True it will be skipped by iris.util.guess_coord_axis().

intersect(other, return_indices=False)[source]#

Return a new coordinate from the intersection of two coordinates.

Both coordinates must be compatible as defined by is_compatible().

Parameters:: return_indices (bool, default=False) – If True, changes the return behaviour to return the intersection indices for the “self” coordinate.

is_compatible(other, ignore=None)[source]#

Return whether the coordinate is compatible with another.

Compatibility is determined by comparing iris.coords.Coord.name(), iris.coords.Coord.units, iris.coords.Coord.coord_system and iris.coords.Coord.attributes that are present in both objects.

Parameters:

other – An instance of iris.coords.Coord, iris.common.CoordMetadata or iris.common.DimCoordMetadata.
ignore (optional) – A single attribute key or iterable of attribute keys to ignore when comparing the coordinates. Default is None. To ignore all attributes, set this to other.attributes.

Return type:

bool

is_contiguous(rtol=1e-05, atol=1e-08)[source]#

Whether coordinate has contiguous bounds.

Return True if, and only if, this Coord is bounded with contiguous bounds to within the specified relative and absolute tolerances.

1D coords are contiguous if the upper bound of a cell aligns, within a tolerance, to the lower bound of the next cell along.

Parameters:

rtol (float, default=1e-05) – The relative tolerance parameter (default is 1e-05).
atol (float, default=1e-08) – The absolute tolerance parameter (default is 1e-08).

Return type:

bool

is_monotonic()[source]#: Return True if, and only if, this Coord is monotonic.

lazy_bounds()[source]#

Return a lazy array representing the coord bounds.

Accessing this method will never cause the bounds values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the coord to have loaded bounds.

If the data have already been loaded for the coord, the returned Array will be a new lazy array wrapper.

Returns:: A lazy array representing the coord bounds array or None if the coord does not have bounds.
Return type:: lazy array

lazy_points()[source]#

Return a lazy array representing the coord points.

Accessing this method will never cause the points values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the coord to have loaded points.

If the data have already been loaded for the coord, the returned Array will be a new lazy array wrapper.

Return type:: A lazy array, representing the coord points array.

property long_name#: The CF Metadata long name for the object.

property metadata#

name(default=None, token=False)#

Return a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Return type:

str

property nbounds#: Return the number of bounds that this coordinate has (0 for no bounds).

property ndim#: Return the number of dimensions of the current dimensional metadata object.

nearest_neighbour_index(point)[source]#

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

Only works for one-dimensional coordinates.

For example:

>>> cube = iris.load_cube(iris.sample_data_path('ostia_monthly.nc'))
>>> cube.coord('latitude').nearest_neighbour_index(0)
9
>>> cube.coord('longitude').nearest_neighbour_index(10)
12

Note

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

Note

For circular coordinates, the ‘nearest’ point can wrap around to the other end of the values.

property points#: The coordinate points values as a NumPy array.

rename(name)#

Change the human-readable name.

If ‘name’ is a valid standard name it will assign it to standard_name, otherwise it will assign it to long_name.

property shape#: The fundamental shape of the metadata, expressed as a tuple.

property standard_name#: The CF Metadata standard name for the object.

summary(shorten=False, max_values=None, edgeitems=2, linewidth=None, precision=None, convert_dates=True, _section_indices=None)#

Make a printable text summary.

Parameters:

shorten (bool, default=False) – If True, produce an abbreviated one-line summary. If False, produce a multi-line summary, with embedded newlines.
max_values (int or None) – If more than this many data values, print truncated data arrays instead of full contents. If 0, print only the shape. The default is 5 if shorten=True, or 15 otherwise. This overrides numpy.get_printoptions['threshold'].
linewidth (int or None) – Character-width controlling line splitting of array outputs. If unset, defaults to numpy.get_printoptions['linewidth'].
edgeitems (int, default=2) – Controls truncated array output. Overrides numpy.getprintoptions['edgeitems'].
precision (int or None) – Controls number decimal formatting. When shorten=True this is defaults to 3, in which case it overrides numpy.get_printoptions()['precision'].
convert_dates (bool, default=True) – If the units has a calendar, then print array values as date strings instead of the actual numbers.

Returns:

Output text, with embedded newlines when shorten=False.

Return type:

str

Notes

Note

property units#: The S.I. unit of the object.

property var_name#: The NetCDF variable name for the object.

xml_element(doc)[source]#

Create the xml.dom.minidom.Element that describes this Coord.

Parameters:: doc – The parent xml.dom.minidom.Document.
Returns:: The xml.dom.minidom.Element that will describe this DimCoord.
Return type:: xml.dom.minidom.Element

class iris.coords.CoordExtent(name_or_coord, minimum, maximum, min_inclusive=True, max_inclusive=True)[source]#

Bases: _CoordExtent

Defines a range of values for a coordinate.

Create a CoordExtent for the specified coordinate and range of values.

Parameters:

name_or_coord – Either a coordinate name or a coordinate, as defined in iris.cube.Cube.coords().
minimum – The minimum value of the range to select.
maximum – The maximum value of the range to select.
min_inclusive (bool, default=True) – If True, coordinate values equal to minimum will be included in the selection. Default is True.
max_inclusive (bool, default=True) – If True, coordinate values equal to maximum will be included in the selection. Default is True.

static __new__(cls, name_or_coord, minimum, maximum, min_inclusive=True, max_inclusive=True)[source]#

Create a CoordExtent for the specified coordinate and range of values.

Parameters:

name_or_coord – Either a coordinate name or a coordinate, as defined in iris.cube.Cube.coords().
minimum – The minimum value of the range to select.
maximum – The maximum value of the range to select.
min_inclusive (bool, default=True) – If True, coordinate values equal to minimum will be included in the selection. Default is True.
max_inclusive (bool, default=True) – If True, coordinate values equal to maximum will be included in the selection. Default is True.

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.

max_inclusive#: Alias for field number 4

maximum#: Alias for field number 2

min_inclusive#: Alias for field number 3

minimum#: Alias for field number 1

name_or_coord#: Alias for field number 0

iris.coords.DEFAULT_IGNORE_AXIS = False#: The default value for ignore_axis which controls guess_coord_axis’ behaviour

class iris.coords.DimCoord(points, standard_name=None, long_name=None, var_name=None, units=None, bounds=None, attributes=None, coord_system=None, circular=False, climatological=False)[source]#

Bases: Coord

A coordinate that is 1D, and numeric.

With values that have a strict monotonic ordering. Missing values are not permitted in a DimCoord.

Create a 1D, numeric, and strictly monotonic coordinate with immutable points and bounds.

Missing values are not permitted.

Parameters:

points – 1D numpy array-like of values (or single value in the case of a scalar coordinate) for each cell of the coordinate. The values must be strictly monotonic and masked values are not allowed.
standard_name (optional) – CF standard name of the coordinate.
long_name (optional) – Descriptive name of the coordinate.
var_name (optional) – The netCDF variable name for the coordinate.
units (Unit, optional) – The Unit of the coordinate’s values. Can be a string, which will be converted to a Unit object.
bounds (optional) – An array of values describing the bounds of each cell. Given n bounds and m cells, the shape of the bounds array should be (m, n). For each bound, the values must be strictly monotonic along the cells, and the direction of monotonicity must be consistent across the bounds. For example, a DimCoord with 100 points and two bounds per cell would have a bounds array of shape (100, 2), and the slices bounds[:, 0] and bounds[:, 1] would be monotonic in the same direction. Masked values are not allowed. Note if the data is a climatology, climatological should be set.
attributes (optional) – A dictionary containing other CF and user-defined attributes.
coord_system (CoordSystem, optional) – A CoordSystem representing the coordinate system of the coordinate, e.g., a GeogCS for a longitude coordinate.
circular (bool, default=False) – Whether the coordinate wraps by the modulus i.e., the longitude coordinate wraps around the full great circle.
climatological (bool, default=False) – When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a ‘climatology’ attribute and will create a boundary variable called ‘<coordinate-name>_climatology’ in place of a standard bounds attribute and bounds variable. Will set to True when a climatological time axis is loaded from NetCDF. Always False if no bounds exist.

__binary_operator__(other, mode_constant)#

Perform common code which is called by add, sub, mul and div.

Mode constant is one of ADD, SUB, MUL, DIV, RDIV

Note

__deepcopy__() → Deep copy of coordinate.[source]#: Used if copy.deepcopy is called on a coordinate.

property attributes#

property bounds#

Coordinate bounds values.

The coordinate bounds 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, ).

property bounds_dtype#

The NumPy dtype of the coordinates bounds.

The NumPy dtype of the coord’s bounds. Will be None if the coord does not have bounds.

cell(index)#

Point/bound cell at the given coordinate index.

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

cells()#

Return an iterable of Cell instances for this Coord.

For example:

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

property circular#: Whether the coordinate wraps by coord.units.modulus.

property climatological#

Flag for representing a climatological time axis.

A boolean that controls whether the coordinate is a climatological time axis, in which case the bounds represent a climatological period rather than a normal period.

Always reads as False if there are no bounds. On set, the input value is cast to a boolean, exceptions raised if units are not time units or if there are no bounds.

collapsed(dims_to_collapse=None)[source]#

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

Replaces the points & bounds with a simple bounded region.

contiguous_bounds()#

Contiguous bounds of 1D coordinate.

Return the N+1 bound values for a contiguous bounded 1D coordinate of length N, or the (N+1, M+1) bound values for a contiguous bounded 2D coordinate of shape (N, M).

Only 1D or 2D coordinates are supported.

Note

If the coordinate has bounds, this method assumes they are contiguous.

If the coordinate is 1D and does not have bounds, this method will return bounds positioned halfway between the coordinate’s points.

If the coordinate is 2D and does not have bounds, an error will be raised.

convert_units(unit)#

Change the coordinate’s units, converting the values in its points and bounds arrays.

For example, if a coordinate’s units attribute is set to radians then:

coord.convert_units('degrees')

will change the coordinate’s units attribute to degrees and multiply each value in points and bounds by 180.0/\(\pi\).

Full list of supported units can be found in the UDUNITS-2 documentation https://docs.unidata.ucar.edu/udunits/current/#Database

property coord_system#: The coordinate-system of the coordinate.

copy(points=None, bounds=None)[source]#

Return a copy of this coordinate.

Parameters:

points (optional) – A points array for the new coordinate. This may be a different shape to the points of the coordinate being copied.
bounds (optional) – A bounds array for the new coordinate. Given n bounds for each cell, the shape of the bounds array should be points.shape + (n,). For example, a 1d coordinate with 100 points and two bounds per cell would have a bounds array of shape (100, 2).

Notes

Note

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

core_bounds()#: Core bounds. The points array at the core of this coord, which may be a NumPy array or a dask array.

core_points()#: Core points array at the core of this coord, which may be a NumPy array or a dask array.

cube_dims(cube)#

Return the cube dimensions of this Coord.

Equivalent to “cube.coord_dims(self)”.

property dtype#: The NumPy dtype of the current dimensional metadata object, as specified by its values.

classmethod from_coord(coord)#: Create a new Coord of this type, from the given coordinate.

classmethod from_regular(zeroth, step, count, standard_name=None, long_name=None, var_name=None, units=None, attributes=None, coord_system=None, circular=False, climatological=False, with_bounds=False)[source]#

Create a DimCoord with regularly spaced points, and optionally bounds.

The majority of the arguments are defined as for Coord, but those which differ are defined below.

Parameters:

zeroth – The value prior to the first point value.
step – The numeric difference between successive point values.
count – The number of point values.
with_bounds (bool, default=False) – If True, the resulting DimCoord will possess bound values which are equally spaced around the points. Otherwise no bounds values will be defined. Defaults to False.

guess_bounds(bound_position=0.5)#

Add contiguous bounds to a coordinate, calculated from its points.

Puts a cell boundary at the specified fraction between each point and the next, plus extrapolated lowermost and uppermost bound points, so that each point lies within a cell.

Parameters:: bound_position (float, default=0.5) – The desired position of the bounds relative to the position of the points.

Notes

Note

An error is raised if the coordinate already has bounds, is not one-dimensional, or is not monotonic.

Note

Unevenly spaced values, such from a wrapped longitude range, can produce unexpected results : In such cases you should assign suitable values directly to the bounds property, instead.

has_bounds()#: Return a boolean indicating whether the coord has a bounds array.

has_lazy_bounds()#

Whether coordinate bounds are lazy.

Return a boolean indicating whether the coord’s bounds array is a lazy dask array or not.

has_lazy_points()#: Return a boolean whether the coord’s points array is a lazy dask array or not.

property ignore_axis#

A boolean controlling if iris.util.guess_coord_axis acts on this coordinate.

Defaults to False, and when set to True it will be skipped by iris.util.guess_coord_axis().

intersect(other, return_indices=False)#

Return a new coordinate from the intersection of two coordinates.

Both coordinates must be compatible as defined by is_compatible().

Parameters:: return_indices (bool, default=False) – If True, changes the return behaviour to return the intersection indices for the “self” coordinate.

is_compatible(other, ignore=None)#

Return whether the coordinate is compatible with another.

Compatibility is determined by comparing iris.coords.Coord.name(), iris.coords.Coord.units, iris.coords.Coord.coord_system and iris.coords.Coord.attributes that are present in both objects.

Parameters:

other – An instance of iris.coords.Coord, iris.common.CoordMetadata or iris.common.DimCoordMetadata.
ignore (optional) – A single attribute key or iterable of attribute keys to ignore when comparing the coordinates. Default is None. To ignore all attributes, set this to other.attributes.

Return type:

bool

is_contiguous(rtol=1e-05, atol=1e-08)#

Whether coordinate has contiguous bounds.

Return True if, and only if, this Coord is bounded with contiguous bounds to within the specified relative and absolute tolerances.

1D coords are contiguous if the upper bound of a cell aligns, within a tolerance, to the lower bound of the next cell along.

Parameters:

rtol (float, default=1e-05) – The relative tolerance parameter (default is 1e-05).
atol (float, default=1e-08) – The absolute tolerance parameter (default is 1e-08).

Return type:

bool

is_monotonic()[source]#: Return True if, and only if, this Coord is monotonic.

lazy_bounds()#

Return a lazy array representing the coord bounds.

Accessing this method will never cause the bounds values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the coord to have loaded bounds.

If the data have already been loaded for the coord, the returned Array will be a new lazy array wrapper.

Returns:: A lazy array representing the coord bounds array or None if the coord does not have bounds.
Return type:: lazy array

lazy_points()#

Return a lazy array representing the coord points.

Accessing this method will never cause the points values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the coord to have loaded points.

If the data have already been loaded for the coord, the returned Array will be a new lazy array wrapper.

Return type:: A lazy array, representing the coord points array.

property long_name#: The CF Metadata long name for the object.

property metadata#

name(default=None, token=False)#

Return a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Return type:

str

property nbounds#: Return the number of bounds that this coordinate has (0 for no bounds).

property ndim#: Return the number of dimensions of the current dimensional metadata object.

nearest_neighbour_index(point)#

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

Only works for one-dimensional coordinates.

For example:

>>> cube = iris.load_cube(iris.sample_data_path('ostia_monthly.nc'))
>>> cube.coord('latitude').nearest_neighbour_index(0)
9
>>> cube.coord('longitude').nearest_neighbour_index(10)
12

Note

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

Note

For circular coordinates, the ‘nearest’ point can wrap around to the other end of the values.

property points#: The coordinate points values as a NumPy array.

rename(name)#

Change the human-readable name.

If ‘name’ is a valid standard name it will assign it to standard_name, otherwise it will assign it to long_name.

property shape#: The fundamental shape of the metadata, expressed as a tuple.

property standard_name#: The CF Metadata standard name for the object.

summary(shorten=False, max_values=None, edgeitems=2, linewidth=None, precision=None, convert_dates=True, _section_indices=None)#

Make a printable text summary.

Parameters:

shorten (bool, default=False) – If True, produce an abbreviated one-line summary. If False, produce a multi-line summary, with embedded newlines.
max_values (int or None) – If more than this many data values, print truncated data arrays instead of full contents. If 0, print only the shape. The default is 5 if shorten=True, or 15 otherwise. This overrides numpy.get_printoptions['threshold'].
linewidth (int or None) – Character-width controlling line splitting of array outputs. If unset, defaults to numpy.get_printoptions['linewidth'].
edgeitems (int, default=2) – Controls truncated array output. Overrides numpy.getprintoptions['edgeitems'].
precision (int or None) – Controls number decimal formatting. When shorten=True this is defaults to 3, in which case it overrides numpy.get_printoptions()['precision'].
convert_dates (bool, default=True) – If the units has a calendar, then print array values as date strings instead of the actual numbers.

Returns:

Output text, with embedded newlines when shorten=False.

Return type:

str

Notes

Note

property units#: The S.I. unit of the object.

property var_name#: The NetCDF variable name for the object.

xml_element(doc)[source]#

Create the xml.dom.minidom.Element that describes this DimCoord.

Parameters:: doc – The parent xml.dom.minidom.Document.
Returns:: The xml.dom.minidom.Element that describes this DimCoord.
Return type:: xml.dom.minidom.Element