cf.Field.match

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

Determine whether or not a field matches the given conditions.

Conditions may be specified on the field’s:

• CF properties
• Attributes
• Coordinate values
• Coordinate cell sizes.

A match occurs if all of the given conditions are satified.

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 cf.Comparison object.

In general, a scalar condition x is equivalent to the cf.Comparison object cf.eq(x), unless x is a string. In this case, x is automatically interpreted as ^x$ and is treated as a regular expression pattern as recognised by the re module. For example, the string '.*wind' would be equivalent to '^.*wind$'. To prevent interpretation as a regular expression, replace the string with a comparison object, as in the general case. For example, cf.eq('.*wind') would only match a property whose value was a string with those same six characters.

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. See the prop parameter for details on how to specify the condition. In addition, for the cf.Units attribute the condition is passed if the attribute is equivalent (rather than equal) to the condition.

coord : dict, optional

Dictionary for which each key/value pair is a coordinate’s identity and a condition for the coordinate’s data array 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 cf.Comparison object. A scalar condition x is equivalent to the cf.Comparison object cf.eq(x).

cellsize : dict, optional

Dictionary for which each key/value pair is a coordinate’s indentity and a condition for the coordinate’s cell sizes to be tested against. The condition may be a scalar or a cf.Comparison object. A scalar condition x is equivalent to the cf.Comparison object cf.eq(x). Whether or not a match occurs also depends on the coord parameter:

• If the coordinate has not also been specified with the coord parameter then a match occurs if all of the coordinate’s cell sizes equal the condition.
• If the coordinate has also been specified with the coord parameter then a match occurs if all of the cells meeting the coord condition equal the cell size condition.

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