cf.Field.items

Field.items(items=None, role=None, axes=None, ctype=None, exact=False, inverse=False, match_all=True, rank=None, regex=False, strict_axes=False)[source]

Return domain items from the field.

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

The output is a dictionary whose key/value pairs are domain identifiers with corresponding values of items of the domain.

By default all items of the domain are returned, but particular items may be selected with the keyword arguments:

Keyword Selection
items Items whose properties satisfy given conditions
role Items with particular roles
axes Items which span particular axes
ctype Coordinate object items of particular types
rank Items with particular ranks

When multiple keyword arguments are given, the returned items are the intersection of the selections.

The returned items are not copies, so in-place changes to them are stored in the field’s domain.

Quick start examples

There is great flexibility in the types of item selection which can be specified, and as a result the documentation is very detailed. These preliminary, simple examples show that the usage need not always be complicated and may help with understanding the keyword descriptions.

  1. Select all items whose identities (as returned by their identity methods) start “height”:

    >>> f.items('height')
    
  2. Select all items which span only one axis:

    >>> f.items(rank=1)
    
  3. Select all cell measure objects:

    >>> f.items(role='c')
    
  4. Select all items which span the “time” axis:

    >>> f.items(axes='time')
    
  5. Select all CF latitude coordinate objects:

    >>> f.items(ctype='Y')
    
  6. Select all multidimensional dimension and auxiliary coordinate objects which span at least the “time” and/or “height” axes and whose long names contain the string “qwerty”:

    >>> f.items({'long_name': cf.eq('qwerty', regex=True)}, 
    ...         role='da',
    ...         axes=['time', 'height'],
    ...         rank=cf.ge(2))
    

Further examples are given within and after the description of the arguments.

Parameters :
items : optional

Select items whose properties satisfy the given conditions. The items argument may be one, or a sequence, of:

  • None or an empty dictionary. All items are selected. This is the default.
  • A domain item identifier (such as 'dim1', 'aux0', 'cm2', 'trans0', etc.). Selects the corresponding item.
  • A string or cf.Comparison object. Selects items whose identities, as returned by their identity methods, match the value. If it is a string then the usual rules for string comparisons apply (see the exact and regex arguments for details, e.g. by default a string value is tested for being an abbreviation).

    Example: To select items with an identity starting with “grid” you could set items='grid'.

    This case may be specified equivalently in a dictionary with the special key of None.

    Example: items='time' is equivalent to items={None: 'time'}.

  • A dictionary which identifies properties of the items with corresponding tests on their values. By default (see the match_all argument) selects items which satisfy all of the conditions. Each key/value pair is specified as follows:

    key:

    An unabbreviated property name (such as 'long_name', 'units', 'foo', etc).

    value:

    A condition to be tested against each item’s property for, in general, equality.

    The exceptions are for string valued conditions (see the exact and regex arguments for details, e.g. by default a string value is tested for being an abbreviation) and for values of some special keys (see the following table).

    The dictionary keys whose values have special interpretations are:

    Special key

    Value

    None

    The value is compared (with the usual rules) against each item’s identity, as returned by its identity method.

    'units'

    The value must be a string and, by default, is evaluated for equivalence with items’ units properties. See the exact argument.

    'calendar'

    The value must be a string and, by default, is evaluated for equivalence with items’ calendar properties. See the exact argument.

    Example: To select items with a standard_name starting with “air” and with units of temperature you could set items={'standard_name': 'air', 'units': 'K'}.

If items is a sequence of any combination of the above then the selected items are the union of those selected by each element of the sequence.

Example:

>>> x = f.items(['aux1', 'time', {'units': 'degreeN'}, {'units': 'K'}])
>>> y = {}
>>> for items in ['aux1', 'time', {'units': 'degreeN'}, {'units': 'K'}]:
...     y.update(f.items(items))
...
>>> set(x) == set(y)
True

If the sequence is empty then no items are selected.

role : (sequence of) str, optional

Select items of the given roles. Valid roles are:

Role

Selected items

'a'

Auxiliary coordinate objects

'c'

Cell measure objects

'd'

Dimension coordinate objects

't'

Transform objects

Multiple roles may be specified by a multi-character string or a sequence.

Example: Selecting auxiliary coordinate and cell measure objects may be done with any of the following values of role: 'ac', 'ca', ('a', 'c'), ['c', 'a'], set(['a', 'c']), etc.

ctype : (sequence of) str, optional

Select dimension and auxiliary coordinate object items of the given CF types. Valid types, as defined by the CF conventions, are:

Type

Selected items

'T'

Time coordinate objects

'X'

Longitude coordinate objects

'Y'

Latitude coordinate objects

'Z'

Vertical coordinate objects

Multiple types may be specified by a multi-character string or a sequence.

Example: Selecting time and longitude coordinate objects may be done with any of the following values of ctype: 'XT', 'TX', ('X', 'T'), ['X', 'T'], set(['X', 'T']), etc.

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). The axes are those that would be selected by this call of the field’s axes method: f.axes(axes). See cf.Field.axes for details. The strict_axes argument modifies this behaviour.

Note that more complex specifications of axes are possible, since the axes argument may take as its value any output of the field’s axes method.

Example: To specify the axes spanned by one dimensionsal CF time coordinate objects you could set axes=f.axes(ctype='T', rank=1).

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. If rank is an integer then only items with this rank are selected. Items with a range of ranks may be selected if rank is a cf.Comparison object.

Example: rank=1 selects items which span exactly one axis and rank=cf.ge(2) selects items which span two or more axes.

exact : bool, optional

The exact argument applies to the interpretion of particular conditions given by values of the items argument. By default exact is False, which means that:

  • If the regex argument is False (which is the default) then string values are considered to be arbitrary abbreviations.
  • If the regex argument is True then string values are considered to be regular expressions, which are evaluated using the re.search function.
  • units and calendar values are evaluated for equivalence rather then equality (e.g. 'metre' is equivalent to 'm' and to 'km').

Example: To select items with a standard_name starting with “air_pressure” and units of pressure you could set items={'standard_name': 'air_pressure', 'units': 'hPa'}, exact=False.

If exact is True then:

  • All string values are considered to be unabbreviated and not to be regular expressions (even if the regex argument is True).
  • units and calendar values are evaluated for exact equality rather than equivalence (e.g. 'metre' is equal to 'm', but not to 'km').

Example: To select items with a standard_name of exactly “air_pressure” and units of exactly hectopascals you could set items={'standard_name': 'air_pressure', 'units': 'hPa'}, exact=True.

Note that cf.Comparison objects provide a mechanism for overriding exact=False for individual values.

Example: items={None: cf.eq('grid_latitude'), 'units': 'degrees'} will select items with an identity of exactly “grid_latitude” and any units equivalent to degrees.

inverse : bool, optional

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

Example: f.items(role='da', inverse=True) selects the same items as f.items(role='ct').

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 axes argument. By default strict_axes is False and items are selected which span at least one of the specified axes, taken in any order (as well as possibly spanning other, unspecified axes).

If strict_axes is True then items are selected which span exactly all of the specified axes, taken in any order.

Returns :
out : dict

A dictionary whose keys are domain item identifiers with corresponding values of items of the domain. The dictionary may be empty.

Examples

Previous topic

cf.Field.item_axes

Next topic

cf.Field.iter

This Page