cf.FieldList.select

FieldList.select(description=None, items=None, rank=None, ndim=None, exact=False, match_and=True, inverse=False)[source]

Return the fields that satisfy the given conditions.

Different types of conditions may be set with the parameters:

Parameter What gets tested
description Field properties and attributes
items Field domain items
rank The number of field domain axes
ndim The number of field data array axes

By default, when multiple criteria are given the field matches if it satisfies the conditions given by each one.

If no fields satisfy the conditions then an empty cf.FieldList is returned.

Note that fl.select(**kwargs) is equivalent to FieldList(g for g in f if g.match(**kwargs))

See also

cf.Field.items, cf.Field.match

Quick start examples

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

  1. Select fields which contain air temperature data, as given determined by the identity method:

    >>> fl.select('air_temperature')

  2. Select fields which contain air temperature data, as given determined by the identity method, or have a long name which contains the string “temp”:

    >>> fl.select(['air_temperature', {'long_name': cf.eq('.*temp.*', regex=true)}])

  3. Select fields which have at least one longitude grid cell point on the Greenwich meridian:

    >>> fl.select(items={'longitude': 0})

  4. Select fields which have at least one latitude grid cell of less than 1 degree in size:

    >>> fl.select(items={'latitude': cf.cellsize(cf.lt(1, 'degree'))})

  5. Select fields which have exactly 4 domain axes:

    >>> fl.select(rank=4)

  6. Examples 1 to 4 may be combined to select fields which have exactly 4 domain axes, contain air temperature data, has at least one longitude grid cell point on the Greenwich meridian and have at least one latitude grid cells with a size of less than 1 degree:

    >>> fl.select('air_temperature',
...           items={'longitude': 0,
...                  'latitude': cf.cellsize(cf.lt(1, 'degree'))},
...           rank=4)

  7. Select fields which contain at least one Gregorian calendar monthly mean data array value:

    >>> f.lselect({'cell_methods': cf.CellMethods('time: mean')},
...           items={'time': cf.cellsize(cf.wi(28, 31, 'days'))})

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

Parameters:
description: optional

Set conditions on the field’s CF property and attribute values. description may be one, or a sequence of:

  • None or an empty dictionary. Always matches the field. This is the default.

  • A string which identifies string-valued metadata of the field and a value to compare it against. The value may take one of the following forms:

    description 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 the field matches if its appropriate value matches the regular expression using the re.match method (i.e. if zero or more characters at the beginning of field’s value match the regular expression pattern). See the exact parameter for details.

    Example:

    To select a field with identity beginning with “lat”: description='lat'.

    Example:

    To select a field with long name beginning with “air”: description='long_name:air'.

    Example:

    To select a field with netCDF variable name of exactly “tas”: description='ncvar%tas$'.

    Example:

    To select a field with identity which ends with the letter “z”: description='.*z$'.

    Example:

    To select a field with long name which starts with the string “.*a”: description='long_name%\.\*a'.

  • A cf.Query object to be compared with field’s identity, as returned by its identity method.

    Example:

    To select a field with identity of exactly “air_temperature” you could set description=cf.eq('air_temperature') (see cf.eq).

    Example:

    To select a field with identity ending with “temperature” you could set description=cf.eq('.*temperature$', exact=False) (see cf.eq).

  • A dictionary which identifies properties of the field with corresponding tests on their values. The field matches 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 field’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 the field matches if its appropriate value matches the regular expression using the re.match method (i.e. if zero or more characters at the beginning of field’s value match the regular expression pattern). See the exact parameter for details.

    Example:

    To select a field 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 the field’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 the field’s calendar property, for example a value of 'noleap' will match a calendar of noleap or 365_day. See the exact parameter.
    'cell_methods' The value must be a cf.CellMethods object containing N cell methods and by default is evaluated for equivalence with the last N cell methods contained within the field’s cell_methods property. 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' and description={None: 'ncvar%pressure'} is equivalent to description='ncvar%pressure'.
    Example:

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

    Example:

    To select a field whose last two cell methods are equivalent to “time: minimum area: mean”: description={'cell_methods': cf.Cellmethods('time: minimum area: mean'). This would select a field which has, for example, cell methods of “height: mean time: minimum area: mean”.

If description is a sequence of any combination of the above then the field matches if it matches at least one element of the sequence:

Example:

>>> f.select('air_temperature')
<CF Field: air_temperature(latitude(73), longitude(96) K>
>>> f.select({'units': 'hPa'})
[]
>>> f.select(['air_temperature', {'units': 'hPa'])
<CF Field: air_temperature(latitude(73), longitude(96) K>

If the sequence is empty then the field always matches.

items: dict, optional

A dictionary which identifies domain items of the field (dimension coordinate, auxiliary coordinate, cell measure or coordinate reference objects) with corresponding tests on their elements. The field matches if all of the specified items exist and their tests are passed.

Each dictionary key specifies an item to test as the one that would be returned by this call of the field’s item method: f.item(key, exact=exact) (see cf.Field.item).

The corresponding value is, in general, any object for which the item may be compared with for equality (==). The test is passed if the result evaluates to True, or if the result is an array of values then the test is passed if at least one element evaluates to true.

If the value is None then the test is always passed, i.e. this case tests for item existence.

Example:

To select a field which has a latitude coordinate value of exactly 30: items={'latitude': 30}.

Example:

To select a field whose longitude axis spans the Greenwich meridian: items={'longitude': cf.contain(0)} (see cf.contain).

Example:

To select a field which has a time coordinate value of 2004-06-01: items={'time': cf.dt('2004-06-01')} (see

cf.dt).

Example:

To select a field which has a height axis: items={'Z': None}.

Example:

To select a field which has a time axis and depth coordinates greater then 1000 metres: items={'T': None, 'depth': cf.gt(1000, 'm')} (see cf.gt).

Example:

To select a field with time coordinates after than 1989 and cell sizes of between 28 and 31 days: items={'time': cf.dtge(1990) & cf.cellsize(cf.wi(28, 31, 'days'))} (see cf.dtge, cf.cellsize and cf.wi).

rank: optional

Specify a condition on the number of axes in the field’s domain. The field matches if its number of domain axes equals rank. A range of values may be selected if rank is a cf.Query object. Not to be confused with the ndim parameter (the number of data array axes may be fewer than the number of domain axes).

Example:

rank=2 selects a field with exactly two domain axes and rank=cf.wi(3, 4) selects a field with three or four domain axes (see cf.wi).

ndim: optional

Specify a condition on the number of axes in the field’s data array. The field matches if its number of data array axes equals ndim. A range of values may be selected if ndim is a cf.Query object. Not to be confused with the rank parameter (the number of domain axes may be greater than the number of data array axes).

Example:

ndim=2 selects a field with exactly two data array axes and ndim=cf.le(2) selects a field with fewer than three data array axes (see cf.le).

exact: bool, optional

The exact parameter applies to the interpretation of string values of the description parameter and of keys 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 a description dictionary are evaluated for equivalence rather then equality (e.g. “metre” is equivalent to “m” and to “km”).
  • A cell methods value containing N cell methods in a description dictionary is evaluated for equivalence with the last N cell methods contained within the field’s cell_methods property.
Example:

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

Example:

f.select({'cell_methods': cf.CellMethods('time: mean (interval 1 hour)')}) would select a field with cell methods of “area: mean time: mean (interval 60 minutes)”.

If exact is True then:

  • A string value is not treated as a regular expression.
  • Units and calendar values in a description dictionary are evaluated for exact equality rather than equivalence (e.g. “metre” is equal to “m”, but not to “km”).
  • A cell methods value in a description dictionary is evaluated for exact equality to the field’s cell methods.
Example:

To select a field with a standard name of exactly “air_pressure” and units of exactly hectopascals: f.select({'standard_name': 'air_pressure', 'units': 'hPa'}, exact=True).

Example:

To select a field with a cell methods of exactly “time: mean (interval 1 hour)”: f.select({'cell_methods': cf.CellMethods('time: mean (interval 1 hour)').

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

Example:

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

Example:

f.select({'standard_name': cf.eq('air_pressure'), 'units': 'hPa'}) will select a field with a standard name of exactly “air_pressure” but with units which equivalent to hectopascals (see cf.eq).

match_and: bool, optional

By default match_and is True and the field matches if it satisfies the conditions specified by each test parameter (description, items, rank and ndim).

If match_and is False then the field will match if it satisfies at least one test parameter’s condition.

Example:

To select a field with a standard name of “air_temperature” and 3 data array axes: f.select('air_temperature', ndim=3). To select a field with a standard name of “air_temperature” or 3 data array axes: f.select('air_temperature", ndim=3, match_and=False).

inverse: bool, optional

If True then return the field matches if it does not satisfy the given conditions.

Example:

>>> len(f.select('air', ndim=4, inverse=True)) == len(f) - len(f.select('air', ndim=4))
True
Returns:
out: cf.FieldList

A cf.FieldList of the matching fields.
Examples:

Field identity starts with “air”:

>>> fl.select('air')

Field identity ends contains the string “temperature”:

>>> fl.select('.*temperature')

Field identity is exactly “air_temperature”:

>>> fl.select('^air_temperature$')
>>> fl.select('air_temperature', exact=True)

Field has units of temperature:

>>> fl.select({'units': 'K'}):

Field has units of exactly Kelvin:

>>> fl.select({'units': 'K'}, exact=True)

Field identity which starts with “air” and has units of temperature:

>>> fl.select({None: 'air', 'units': 'K'})

Field identity starts with “air” and/or has units of temperature:

>>> fl.select(['air', {'units': 'K'}])

Field standard name starts with “air” and/or has units of exactly Kelvin:

>>> fl.select([{'standard_name': cf.eq('air', exact=False), {'units': 'K'}],
...           exact=True)

Field has height coordinate values greater than 63km:

>>> fl.select(items={'height': cf.gt(63, 'km')})

Field has a height coordinate object with some values greater than 63km and a north polar point on its horizontal grid:

>>> fl.select(items={'height': cf.gt(63, 'km'),
...                  'latitude': cf.eq(90, 'degrees')})

Field has some longitude cell sizes of 3.75:

>>> fl.select(items={'longitude': cf.cellsize(3.75)})

Field latitude cell sizes within a tropical region are all no greater than 1 degree:

>>> fl.select(items={'latitude': (cf.wi(-30, 30, 'degrees') &
...                               cf.cellsize(cf.le(1, 'degrees')))})

Field contains monthly mean air pressure data and all vertical levels within the bottom 100 metres of the atmosphere have a thickness of 20 metres or less:

>>> fl.select({None: '^air_pressure$', 'cell_methods': cf.CellMethods('time: mean')},
...           items={'height': cf.le(100, 'm') & cf.cellsize(cf.le(20, 'm')),
...                  'time': cf.cellsize(cf.wi(28, 31, 'days'))})