cf.Field.item

Field.item(items=None, role=None, axes=None, ctype=None, exact=False, inverse=False, match_all=True, rank=None, regex=False, strict_axes=False, key=False)

Return an item, or its domain identifier, from the field.

An item is either a dimension coordinate, an auxiliary coordinate, a cell measure or a transform object.

The item may be selected with the keyword arguments. When multiple criteria are given, the item will be the intersection of the selections. If no unique item can be found then None is returned.

A returned item is not a copy, so in-place changes to it are stored in the domain.

Note that:

k = f.item(items, key=True, **args)
v = f.item(items, key=False, **args)

is equivalent to:

d = f.items(items, **args)
if len(d) == 1:
   k, v = d.popitem()
else:
   k, v = None, None

Parameters :

items : optional

Select items whose properties satisfy the given conditions. Set as for the items parameter of cf.Field.items.

role : (sequence of) str, optional

Select items of the given roles. Set as for the role parameter of cf.Field.items.

ctype : (sequence of) str, optional

Select dimension and auxiliary coordinate object items of the given CF types. Set as for the ctype parameter of cf.Field.items.

axes : optional

Select items which span at least one of the specified axes, taken in any order (as well as possibly spanning other, unspecified axes). Set as for the axes parameter of cf.Field.items.

rank : int or cf.Comparison, optional

Select items whose ranks satisfy the given condition, where an item’s rank is the number of axes which it spans. Set as for the rank parameter of cf.Field.items.

exact : bool, optional

The exact argument applies to the interpretion of particular conditions given by values of the items argument. Set as for the exact parameter of cf.Field.items.

inverse : bool, optional

If True then select items other than those selected by all other criteria.

match_all : bool, optional

The match_all argument applies to the interpretion of dictionaries given by the items argument. By default match_all is True and items are selected if they satisfy all of the conditions specified by a dictionary of the items argmuent.

If match_all is False then items are selected if they satisfy at least one of the specified by a dictionary of the items argmuent.

Example: To select items with a standard_name containing “temp” and/or units of temperature you could set items={'standard_name': cf.eq('temp', regex=True), 'units': 'K'}, match_all=False. If match_all were True in this case then the field would match only if it satisfied both conditions.

regex : bool, optional

By default regex is False and all strings given by values of the items argument are considered to be arbitrary abbreviations or else exact (see the exact argument).

If regex is True then such strings are considered to be regular expressions supported by the re module and are compared via the re.search function (see the exact argument).

Example: To select items with a long_name which starts with “a” and ends with “z” you could set items={'long_name': '^a.*z$'}, regex=True.

Note that cf.Comparison objects provide a mechanism for overriding regex for individual values.

Example: items={'long_name': cf.eq('^a.*z$', regex=True)} will select items a long_name which starts with “a” and ends with “z” regardless of the value of regex.

strict_axes : bool, optional

The strict_axes argument applies to the interpretion of strict_axes argument. Set as for the axes parameter of cf.Field.items.

key : bool, optional

If True then return the domain’s identifier for the item, rather than the item itself.

Returns :

out :

The unique item or its domain identifier or, if there is no unique item, None.

See also

aux, cm, coord, dim, item_axes, items, remove_item, transform

Examples