cfdm.Field.domain_axis

Field.domain_axis(*identity, key=False, default=ValueError(), item=False, **filter_kwargs)

Select a domain axis construct.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

New in version (cfdm): 1.10.0.0

See also

construct, domain_axes

Parameters

identities: tuple, optional

Select domain axis constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

Additionally, if for a given value, f.coordinates(value, filter_by_naxes=(1,)) returns 1-d coordinate constructs that all span the same domain axis construct then that domain axis construct is selected. See coordinates for details.

Additionally, if there is a Field data array and a value matches the integer position of an array dimension, then the corresponding domain axis construct is selected.

If no values are provided then all domain axis constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

key: bool, optional

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

item: bool, optional

If True then return as a tuple the selected construct identifier and the construct itself. By default only the construct itself is returned. If key is True then item is ignored.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

Returns

The selected construct, or its identifier if key is True, or a tuple of both if item is True.

Examples

>>> f = cfdm.example_field(1)
>>> f.domain_axis('domainaxis0')
<DomainAxis: size(1)>
>>> f.domain_axis('domainaxis0', key=True)
'domainaxis0'
>>> f.domain_axis('domainaxis0', item=True)
('domainaxis0', <DomainAxis: size(1)>)