cf.Field.match

Field.match(attr={}, priv={}, coord={}, cellsize={})

Determine whether or not a field satisfies conditions.

Conditions may be specified on the field’s attributes, coordinate values and coordinate cell sizes.

Parameters :

attr : dict, optional

Dictionary for which each key/value pair is a standard or non-standard CF attribute name and a condition for the attribute to be tested against. If the value is a sequence of conditions then the attribute matches if at least one of the conditions is passed.

In general, a condition is any object and it is passed if the attribute is equal to the object, with the following exception:

• If the attribute is string-valued, then the condition may be a regular expression pattern recognised by the re module and the condition is passed if the attribute matches the regular expression. Special characters for the start and end of the string are assumed and need not be included. For example, ‘.*wind’ is equivalent to ‘^.*wind$’.

priv : dict, optional

Dictionary for which each key/value pair is an attribute name other than their standard and non-standard CF attribute and a condition for the attribute to be tested against. If the value is a sequence of conditions then the attribute matches if at least one of the conditions is passed.

In general, a condition behaves as for attr, with the following exception:

• For the Units attribute, the condition is passed if the attribute is equivalent (rather than equal) to the object. (Note that this behaviour does not apply to the units attribute.)

coord : dict, optional

Dictionary for which each key/value pair is a coordinate name and a condition for the coordinate to be tested against. A match occurs if at least one element of the coordinate’s array passes the condition. If the value is a sequence of conditions then the coordinate matches if at least one of the conditions is passed.

cellsize : dict, optional

Dictionary for which each key/value pair is a coordinate name and a condition for the coordinate’s cell sizes to be tested against. A match occurs if all of the coordinate’s cell’s sizes pass the condition. Only one cell size condition may be given per coordinate.

If the same coordinate is specified in the coord and cellsize dictionaries then the cell size condition only needs to be passed for cells which pass all if the coordinate’s conditions.

Returns :

out : bool

True if the field satisfies the given criteria, False otherwise.

Examples

>>> print f
Data            : air_temperature(time, latitude, longitude)
Cell methods    : time: mean
Dimensions      : time(12) = [15, ..., 345] days since 1860-1-1
                : latitude(73) = [-90, ..., 90] degrees_north
                : longitude(96) = [0, ..., 356.25] degrees_east
                : height(1) = [2] m

>>> f.match(attr={'standard_name': 'air_temperature'})
True
>>> f.match(attr={'standard_name': ['air_temperature']})
True
>>> f.match(attr={'standard_name': ['air_temperature', 'air_pressure']})
True
>>> f.match(attr={'standard_name': '.*temperature.*'})
True
>>> f.match(attr={'standard_name': ['.*temperature.*', 'air_pressure']})
True
>>> f.match(attr={'standard_name': '.*pressure.*'})
False

>>> f.match(attr={'Units': 'K'})
True
>>> f.match(attr={'Units': cf.Units('1.8 K @ 459.67')})
True
>>> f.match(attr={'Units': [cf.Units('Pa'), 'K']})
True
>>> f.match(attr={'Units': cf.Units('Pa')})
False

>>> f.match(attr={'cell_methods': 'time: mean'})
True
>>> f.match(attr={'cell_methods': cf.CellMethods('time: mean')})
True
>>> f.match(attr={'cell_methods': ['time: mean', 'time: max']})
True
>>> f.match(attr={'cell_methods': cf.CellMethods('time: max')})
False
>>> f.match(attr={'cell_methods': 'time: mean time: min')})
False

>>> f.match(coord={'latitude': 0})
False
>>> f.match(coord={'latitude': [0, cf.gt(30)]})
True

>>> f.match(cellsize={'time': cf.inside(28, 31, 'days')})
True