cf.Field.items

Field.items(items=None, role=None, axes=None, ndim=None, exact=False, inverse=False, match_and=True, strict_axes=False)[source]

Return domain items from the field.

An item is a dimension coordinate, an auxiliary coordinate, a cell measure or a coordinate reference 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 parameters:

Parameter Selection
items Items whose properties or attributes satisfy given conditions
role Items with particular roles
axes Items which span particular axes
ndim Items with particular numbers of data array axes

When multiple keyword parameters 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(ndim=1)
    
  3. Select all cell measure objects:

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

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

    >>> f.items('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:.*qwerty', 
    ...         role='da',
    ...         axes=['time', 'height'],
    ...         ndim=cf.ge(2))
    

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

Parameters:
items : optional

Select items whose properties or attributes satisfy the given conditions.

items may be None, a string, a dictionary or a cf.Query object; or a sequence of any of these:

  • None or an empty dictionary. All items are selected. This is the default.
  • A string specifying one of the CF coordinate type: 'T', 'X', 'Y' or 'Z'

    Example:

    To select CF time items: items='T'.

  • A string which identifies items based on their string-valued metadata. The value may take one of the following forms:

    Value Interpretation
    Contains ':' Selects on the CF property specified before the first ':'
    Contains '%' Selects on the attribute specified before the first '%'
    Anything else Selects on identity as returned by the identity method

    By default the part of the string to be compared with the item is treated as a regular expression understood by the re module and an item is selected if its appropriate value matches the regular expression using the re.match method (i.e. if zero or more characters at the beginning of item’s value match the regular expression pattern). See the exact parameter for details.

    Example:

    To select items with standard names which begin “lat”: items='lat'.

    Example:

    To select items with long names which begin “air”: items='long_name:air'.

    Example:

    To select items with netCDF variable names which begin “lon”: items='ncvar%lon'.

    Example:

    To select items with identities which end with the letter “z”: items='.*z$'.

    Example:

    To select items with long names which start with the string ”.*a”: items='long_name%\.\*a'.

  • A dictionary which identifies properties of the items with corresponding tests on their values. An item is selected if all of the tests in the dictionary are passed.

    In general, each dictionary key is a CF property name with a corresponding value to be compared against the item’s CF property value.

    If the dictionary value is a string then by default it is treated as a regular expression understood by the re module and an item is selected if its appropriate value matches the regular expression using the re.match method (i.e. if zero or more characters at the beginning of item’s value match the regular expression pattern). See the exact parameter for details.

    Example:

    To select items with standard name of exactly “air_temperature” and long name beginning with the letter “a”: items={'standard_name': cf.eq('air_temperature'), 'long_name': 'a'} (see cf.eq).

    Some key/value pairs have a special interpretation:

    Special key Value
    'units' The value must be a string and by default is evaluated for equivalence, rather than equality, with an item’s units property, for example a value of 'Pa' will match units of Pascals or hectopascals, etc. See the exact parameter.
    'calendar' The value must be a string and by default is evaluated for equivalence, rather than equality, with an item’s calendar property, for example a value of 'noleap' will match a calendar of noleap or 365_day. See the exact parameter.
    None The value is interpreted as for a string value of the items parameter. For example, items={None: 'air'} is equivalent to items='air', items={None: 'ncvar%pressure'} is equivalent to items='ncvar%pressure' and items={None: 'Y'} is equivalent to items='Y'.
    Example:

    To select items with standard name starting with “air”, units of temperature and a netCDF variable name of “tas” you could set items={'standard_name': 'air', 'units': 'K', None: 'ncvar%tas$'}.

  • A domain item identifier (such as 'dim1', 'aux0', 'msr2', 'ref0', etc.). Selects the corresponding item.

    Example:

    To select the item with domain identifier “dim1”: items='dim1'.

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', 'long_name': 'foo'}])
>>> y = {}
>>> for items in ['aux1', 'time', {'units': 'degreeN', 'long_name': 'foo'}]:
...     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 Items selected
'd' Dimension coordinate objects
'a' Auxiliary coordinate objects
'm' Cell measure objects
'r' Coordinate reference 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: 'am', 'ma', ('a', 'm'), ['m', 'a'], set(['a', 'm']), 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, exact=exact). See cf.Field.axes for details. The strict_axes parameter modifies this behaviour.

Example:

To select items which the time axes you could set: axes='T'.

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

Example:

To select items which span one dimensional time axes you could set: axes=f.axes('T', ndim=1).

ndim : optional

Select items whose number of data array axes satisfy the given condition. Items are selected if they have ndim data aray axes. A range of data numbers of array axes may be selected if ndim is a cf.Query object.

Example:

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

exact : bool, optional

The exact parameter applies to the interpretation of string-valued conditions given by values of the items parameter. By default exact is False, which means that:

  • A string value is treated as a regular expression understood by the re module.
  • Units and calendar values in an items dictionary 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 which begins with “air” and any units of pressure: f.items({'standard_name': 'air', 'units': 'hPa'}).

If exact is True then:

  • A string value is not treated as a regular expression.
  • Units and calendar values in an items dictionary 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: f.items({'standard_name': 'air_pressure', 'units': 'hPa'}, exact=True).

Note that cf.Query objects provide a mechanism for overriding the exact parameter for individual values.

Example:

f.items({'standard_name': cf.eq('air', exact=False), 'units': 'hPa'}, exact=True) will select items with a standard name which begins “air” but with units of exactly hectopascals (see cf.eq).

Example:

f.items({'standard_name': cf.eq('air_pressure'), 'units': 'hPa'}) will select items with a standard name of exactly “air_pressure” but with any units of pressure (see cf.eq).

match_and : bool, optional

By default match_and is True and then an item is selected if it satisfies the conditions specified by each test parameter (items, role, axes and ndim).

If match_and is False then an item is selected if it satisfies at least one of the conditions specified by the test parameters (items, role, axes and ndim).

Example:

To select items with identity beginning with “ocean” and at least 2 data array axes: f.items('ocean', ndim=cf.ge(2)) (see cf.gt).

Example:

To select items with identity beginning with “ocean” or at least 2 data array axes: f.items('ocean', ndim=cf.ge(2), match_and=False)

strict_axes : bool, optional

The strict_axes parameter applies to the interpretation of axes parameter. 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.

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='mr').

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.items_axes

This Page