cf.Field.field_ancillary

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

Return a field 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_ancillary, domain_axis, field_ancillaries

Parameters:
identity:

Select the field ancillary construct by one of:

  • The identity or key of an field ancillary construct.
  • The identity or key of a domain axis construct that is spanned by a unique 1-d field 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 field 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 'fieldancillary2' and 'key%fieldancillary2' 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='fieldancillary1'

Parameter example:

identity='domainaxis2'

Parameter example:

identity='ncdim%y'

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:
FieldAncillary or str

The selected field ancillary coordinate construct, or its key.

Examples:

TODO