cf.Field.match

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

Determine whether or not a field satisfies conditions.

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

Parameters :

prop : dict, optional

Dictionary for which each key/value pair is a CF property name and a condition for the property to be tested against. A match occurs if the CF property value equals the condition. The condition may be a scalar or a Comparison object. A scalar condition, x, is equivalent to the Comparison object cf.eq(x).

Note that:

• If the condition contains a regular expression pattern as recognised by the re module then special characters for the start and end of the string are assumed and need not be included. For example, ‘.*wind’ is equivalent to ‘^.*wind$’.

attr : dict, optional

Dictionary for which each key/value pair is an attribute name and a condition for the attribute to be tested against. A match occurs if the attribute value equals the condition. The condition may be a scalar or a Comparison object. A scalar condition, x, is equivalent to the Comparison object cf.eq(x).

Note that:

• If the condition contains a regular expression pattern as recognised by the re module then special characters for the start and end of the string are assumed and need not be included. For example, ‘.*wind’ is equivalent to ‘^.*wind$’.
• 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 identity and a condition for the coordinate to be tested against. A match occurs if at least one element of the coordinate’s data array equals the condition. The condition may be a scalar or a Comparison object. A scalar condition, x, is equivalent to the Comparison object cf.eq(x).

cellsize : dict, optional

Dictionary for which each key/value pair is a coordinate indentity and a condition for the coordinate’s cell sizes to be tested against. If the coordinate has not been specified with the coord parameter, then a match occurs if all of the coordinate’s cell sizes equal the condition, otherwise a match occurs if all of the cells meeting the coord condition equal the cell size condition. The condition may be a scalar or a Comparison object. A scalar condition, x, is equivalent to the Comparison object cf.eq(x).

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(prop={'standard_name': 'air_temperature'})
True        
>>> f.match(prop={'standard_name': ['air_temperature']})
True        
>>> f.match(prop={'standard_name': cf.set(['air_temperature', 'air_pressure'])})
True        
>>> f.match(prop={'standard_name': '.*temperature.*'})
True        
>>> f.match(prop={'standard_name': cf.set(['.*temperature.*', 'air_pressure'])})
True        
>>> f.match(prop={'standard_name': '.*pressure.*'})
False       

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

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

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

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