Field.coordinate(identity, default=ValueError(), key=False)[source]

Return a dimension coordinate construct, or its key.

New in version 3.0.0.


Select the dimension coordinate construct by one of:

  • The identity or key of a dimension coordinate construct.
  • The identity or key of a domain axis construct that is spanned by a unique 1-d coordinate construct’s data.
  • The position, in the field construct’s data, of a domain axis construct that is spanned by a unique 1-d coordinate construct’s data.

A construct identity is specified by a string (e.g. 'latitude', 'long_name=time', 'ncvar%lat', etc.); a Query object (e.g. cf.eq('longitude')); or a compiled regular expression (e.g. re.compile('^atmosphere')) that selects the relevant constructs whose identities match via

A construct has a number of identities, and is selected if any of them match any of those provided. A construct’s identities are those returned by its identities method. In the following example, the construct x has six identities:

>>> x.identities()
['time', 'long_name=Time', 'foo=bar', 'standard_name=time', 'ncvar%t', T']

A construct key may optionally have the 'key%' prefix. For example 'auxiliarycoordinate2' and 'key%dimensioncoordinate2' are both acceptable keys.

A position of a domain axis construct in the field construct’s data is specified by an integer index.

Note that in the output of a print call or dump method, a construct is always described by one of its identities, and so this description may always be used as an identity argument.

Parameter example:


Parameter example:


Parameter example:


Parameter example:


Parameter example:


Parameter example:


key: bool, optional

If True then return the selected construct key. By default the construct itself is returned.

default: optional

Return the value of the default parameter if a construct can not be found. If set to an Exception instance then it will be raised instead.

DimensionCoordinate or AuxiliaryCoordinate or str

The selected dimension or auxiliary coordinate construct, or its key.