# cf.Field.field_ancillary¶

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

Return a field ancillary construct, or its key.

New in version 3.0.0.

Parameters
identity: optional

Select the field ancillary construct by one of:

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

• 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