cf.Field.domain_ancillary

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

Return a domain ancillary construct, or its key.

New in version 3.0.0.

See also

construct, auxiliary_coordinate, cell_measure, cell_method, coordinate, coordinate_reference, dimension_coordinate, domain_ancillaries, domain_axis, field_ancillary

Parameters
identity: optional

Select the domain ancillary construct by one of:

  • None. This is the default, which selects the domain ancillary construct when there is only one of them.

  • The identity or key of a domain ancillary construct.

  • The identity or key of a domain axis construct that is spanned by a unique 1-d domain ancillary construct’s data.

  • The position, in the field construct’s data, of a domain axis construct that is spanned by a unique 1-d domain ancillary 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 re.search.

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 'domainancillary2' and 'key%domainancillary2' 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:

identity='Y'

Parameter example:

identity='latitude'

Parameter example:

identity='long_name=Latitude'

Parameter example:

identity='domainancillary1'

Parameter example:

identity='ncdim%y'

Parameter example:

identity='domainaxis2'

Parameter example:

identity=0

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.

Returns
DomainAncillary or str

The selected domain ancillary coordinate construct, or its key.

Examples:

TODO