# cf.Field.field¶

Field.field(description=None, role=None, axes=None, axes_all=None, axes_subset=None, axes_superset=None, exact=False, inverse=False, match_and=True, ndim=None, bounds=False)[source]

Create an independent field from a domain item.

An item is either a dimension coordinate, an auxiliary coordinate or a cell measure object of the domain.

Items are selected with the criteria specified by the keyword parameters. If no parameters are set then all items are selected. If multiple criteria are given then items that meet all of them are selected (see the match_and parameter).

If a unique item can not be found then no field is created and None is returned.

A field may also be created from coordinate bounds (see the bounds parameter).

New in version 1.1.

Create a field whose data are the latitude coordinates

>>> y = f.field('latitude')

Parameters:
description: optional

Select the items whose descriptive attributes or CF properties satisfy the given conditions. The description parameter may be one, or a sequence, of:

• A string specifying one of the CF coordinate types: 'T', 'X', 'Y' or 'Z'. An item has an attribute for each coordinate type and is selected if the attribute for the specified type is True.

Example:

To select CF time items: description='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 an item’s identity method

By default the part of the string to be compared with an item is treated as a regular expression understood by the re module and an item is selected if its corresponding 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”: description='lat'.

Example:

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

Example:

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

Example:

To select items with identities which end with the letter “z”: description='.*z$'. Example: To select items with long names which start with the string “.*a”: description='long_name%\.\*a'. • A dictionary that 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 corresponding 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”: description={'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 description parameter. For example, description={None: 'air'} is equivalent to description='air', description={None: 'ncvar%pressure'} is equivalent to description='ncvar%pressure' and description={None: 'Y'} is equivalent to description='Y'. Example: To select items with standard name starting with “air”, units of temperature and a netCDF variable name of “tas” you could set description={'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”: description='dim1'.

If description 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. 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 items
'a' Auxiliary coordinate items
'm' Cell measure items
'c' Domain ancillary items
'f' Field ancillary items
'r' Coordinate reference items

Multiple roles may be specified by a sequence of role identifiers. By default all roles except coordinate reference items are considered, i.e. by default role=('d', 'a', 'm', 'f', 'c').

Example:

To select dimension coordinate items: role='d' or role=[‘d’].

Example:

Selecting auxiliary coordinate and cell measure items 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, and possibly others. Axes are defined by identfiying items of the field (such as dimension coordinate objects) or by specifying axis sizes. In the former case the selected axes are those which span the identified items. The axes are interpreted as those that would be returned by the field’s axes method, i.e. by f.axes(axes) or, if axes is a dictionary, f.axes(**axes). See cf.Field.axes for details.

Example:

To select items which span a time axis, and possibly others, you could set: axes='T'.

Example:

To select items which span a latitude and/or longitude axes, and possibly others, you could set: axes=['X', 'Y'].

Example:

To specify axes with size 19 you could set axes={'size': 19}. To specify depth axes with size 40 or more, you could set: axes={'axes': 'depth', 'size': cf.ge(40)} (see cf.ge).

axes_all: optional

Select items whose data arrays span all of the specified axes, taken in any order, and no others. The axes are those that would be selected by this call of the field’s axes method: f.axes(axes_all) or, if axes_all is a dictionary of parameters, f.axes(**axes_all). Axes are defined by identfiying items of the field (such as dimension coordinate objects) or by specifying axis sizes. In the former case the selected axes are those which span the identified field items. See cf.Field.axes for details.

Example:

To select items which span a time axis, and no others, you could set: axes_all='T'.

Example:

To select items which span latitude and longitude axes, and no others, you could set: axes_all=['X', 'Y'].

Example:

To specify axes with size 19 you could set axes_all={'size': 19}. To specify depth axes with size 40 or more, you could set: axes_all={'axes': 'depth', 'size': cf.ge(40)} (see cf.ge).

axes_subset: optional

Select items whose data array spans all of the specified axes, taken in any order, and possibly others. The axes are those that would be selected by this call of the field’s axes method: f.axes(axes_subset) or, if axes_subset is a dictionary of parameters , f.axes(**axes_subset). Axes are defined by identfiying items of the field (such as dimension coordinate objects) or by specifying axis sizes. In the former case the selected axes are those which span the identified field items. See cf.Field.axes for details.

Example:

To select items which span a time axes, and possibly others, you could set: axes_subset='T'.

Example:

To select items which span latitude and longitude axes, and possibly others, you could set: axes_subset=['X', 'Y'].

Example:

To specify axes with size 19 you could set axes_subset={'size': 19}. To specify depth axes with size 40 or more, you could set: axes_subset={'axes': 'depth', 'size': cf.ge(40)} (see cf.ge).

axes_superset: optional

Select items whose data arrays span a subset of the specified axes, taken in any order, and no others. The axes are those that would be selected by this call of the field’s axes method: f.axes(axes_superset) or, if axes_superset is a dictionary of parameters, f.axes(**axes_superset). Axes are defined by identfiying items of the field (such as dimension coordinate objects) or by specifying axis sizes. In the former case the selected axes are those which span the identified field items. See cf.Field.axes for details.

Example:

To select items which span a time axis, and no others, you could set: axes_superset='T'.

Example:

To select items which span latitude and/or longitude axes, and no others, you could set: axes_superset=['X', 'Y'].

Example:

To specify axes with size 19 you could set axes_superset={'size': 19}. To specify depth axes with size 40 or more, you could set: axes_superset={'axes': 'depth', 'size': cf.ge(40)} (see cf.ge).

ndim: optional

Select the items whose number of data array dimensions satisfy the given condition. A range of dimensions may be selected if ndim is a cf.Query object.

Example:

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

match_and: bool, optional

By default match_and is True and items are selected if they satisfy the all of the specified conditions.

If match_and is False then items are selected if they satisfy at least one of the specified conditions.

Example:

To select items with identity beginning with “ocean” and two data array axes: f.field('ocean', ndim=2).

Example:

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

exact: bool, optional

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

• A string-valued condition is treated as a regular expression understood by the re module and an item is selected if its corresponding 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).
• Units and calendar strings are evaluated for equivalence rather then equality (e.g. 'metre' is equivalent to 'm' and to 'km').
Example:

To select items with with any units of pressure: f.field('units:hPa'). To select items with a standard name which begins with “air” and with any units of pressure: f.field({'standard_name': 'air', 'units': 'hPa'}).

If exact is True then:

• A string-valued condition is not treated as a regular expression and an item is selected if its corresponding value equals the string.
• Units and calendar strings are evaluated for exact equality rather than equivalence (e.g. 'metre' is equal to 'm', but not to 'km').
Example:

To select items with with units of hectopascals but not, for example, Pascals: f.field('units:hPa', exact=True). To select items with a standard name of exactly “air_pressure” and with units of exactly hectopascals: f.field({'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.field({'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.field({'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).

inverse: bool, optional

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

bounds: bool, optional

If true then create a field from a coordinate object’s bounds.

Returns:
out: cf.Field

The field based on the selected domain item.

Examples 2:
>>> print f
eastward_wind field summary
---------------------------
Data           : eastward_wind(time(3), grid_latitude(110), grid_longitude(106)) m s-1
Cell methods   : time: mean
Axes           : time(3) = [1979-05-01 12:00:00, ..., 1979-05-03 12:00:00] gregorian
: grid_longitude(106) = [-20.54, ..., 25.66] degrees
: grid_latitude(110) = [23.32, ..., -24.64] degrees
Aux coords     : latitude(grid_latitude(110), grid_longitude(106)) = [[67.12, ..., 22.89]] degrees_north
: longitude(grid_latitude(110), grid_longitude(106)) = [[-45.98, ..., 35.29]] degrees_east
Coord refs     : <CF CoordinateReference: rotated_latitude_longitude>

>>> print f.field('X')
grid_longitude field summary
----------------------------
Data           : grid_longitude(grid_longitude(106)) degrees
Axes           : grid_longitude(106) = [-20.54, ..., 25.66] degrees
Coord refs     : <CF CoordinateReference: rotated_latitude_longitude>

>>> print f.field('X', bounds=True)
grid_longitude field summary
----------------------------
Data           : grid_longitude(grid_longitude(106), domain%dim1(2)) degrees
Axes           : domain%dim1(2)
: grid_longitude(106) = [-20.54, ..., 25.66] degrees
Coord refs     : <CF CoordinateReference: rotated_latitude_longitude>

>>> print f.field('lat')
latitude field summary
----------------------
Data           : latitude(grid_latitude(110), grid_longitude(106)) degrees_north
Axes           : grid_longitude(106) = [-20.54, ..., 25.66] degrees
: grid_latitude(110) = [23.32, ..., -24.64] degrees
Aux coords     : latitude(grid_latitude(110), grid_longitude(106)) = [[67.12, ..., 22.89]] degrees_north
: longitude(grid_latitude(110), grid_longitude(106)) = [[-45.98, ..., 35.29]] degrees_east
Coord refs     : <CF CoordinateReference: rotated_latitude_longitude>


To multiply the field by the cosine of its latitudes:

>>> latitude = f.field({'units': 'radian', None: 'Y'})
>>> latitude
<CF Field: grid_latitude(grid_latitude(110)) degrees>
>>> g = f * latitude.cos()
`