cf.Field.axes

Field.axes(axes=None, ordered=False, size=None, **kwargs)[source]

Return domain axis identifiers from the field.

The output is a set of domain axis identifiers, which may be empty.

By default all axes of the domain are returned, but particular axes may be selected with the keyword arguments. There are two types of selection:

Selection type Method
Explicit Select axes by domain axis identifiers, positions in the list of the field’s data array axes or axis size.
Implicit Select axes which are spanned by particular items of the domain. An item is a dimension coordinate, an auxiliary coordinate, a cell measure or a transform object.

When multiple criteria have been specified, the returned items are the intersection of the selections.

Parameters :
axes : optional

Select axes. The axes parameter may be one, or a sequence, of:

  • None. If there no kwargs arguments have been set then selects all axes.
  • A domain axis identifier (such as 'dim1'). Explicitly selects this axis.
  • An integer or slice object. Explcitly selects the axes coresponding to the given positions in the list of axes of the field’s data array.
  • Any value accepted by the items argument of the field’s items method. Used in conjunction with the kwargs arguments to implicitly select the axes which span the items that would be identified by this call of the field’s items method: f.items(items=axes, axes=None, **kwargs). See cf.Field.items for details.

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

Example:

>>> x = f.axes(['dim2', 'time', {'units': 'degree_north'}])
>>> y = set()
>>> for axes in ['dim2', 'time', {'units': 'degree_north'}]:
...     y.update(f.axes(axes))
...
>>> x == y
True

If the sequence is empty then no axes are selected.

ordered : bool, optional

Return an ordered list of axes instead of an unordered set. The order of the list will reflect any ordering specified by the selection keywords axes and kwargs.

Example: If the data array axes, as returned by the field’s data_axes method, are ['dim0', 'dim1', 'dim2'], then f.axes([2, 0, 1, 2]) will return set(['dim0', 'dim1', 'dim2']), but f.axes([2, 0, 1, 2], ordered=True) will return ['dim2', 'dim0', 'dim1', 'dim2'].

size : int or cf.Comparison, optional

Select axes whose sizes equal size. Axes with a range of sizes may be selected if size is a cf.Comparison object.

Example: size=1 selects size 1 axes and size=cf.ge(2) selects axes with sizes greater than 1.

kwargs : optional

For each implicit selection of the axes argument, any extra keyword arguments are used to modify the item selection.

Example: f.axes('grid_latitude', exact=True, rank=1) will select the axes spanned by all one dimensionsal items whose identities are exactly “grid_latitude”.

For each explicit selection of the axes argument, kwargs are ignored.

Example: f.axes(-1, ctype='T', rank=1) will select only the axis for the fastest varying dimension of the field’s data array, the keyword arguments being ignored in this case.

If axes has not been set then any extra keyword arguments are used to implicitly select the axes which span the items that would be identified by this call of the field’s items method: f.items(items=None, axes=None, **kwargs). See cf.Field.items for details. For example:

Example: f.axes(ctype='T', rank=1) will select the axes spanned by one dimensionsal CF time coordinate objects.

Returns :
out : set or list

A set of domain axis identifiers, or a list if ordered is True. The set or list may be empty.

Examples

All axes and their identities:

>>> f.axes()
set(['dim0', 'dim1', 'dim2', 'dim3'])
>>> dict([(axis, f.domain.axis_name(axis)) for axis in f.axes()])
{'dim0': time(12)
 'dim1': height(19)
 'dim2': latitude(73)
 'dim3': longitude(96)}

Axes which are not spanned by the data array:

>>> f.axes().difference(f.data_axes())

Previous topic

cf.Field.auxs

Next topic

cf.Field.binary_mask

This Page