cf.Comparison

class cf.Comparison(operator, value, units=None, regex=False, attr=None)

Bases: object

Store a comparison operation.

The comparison operation is an operator with a right hand side operand. For example, an operator could be “strictly less than” and a right hand side operand could 3.

Such a comparison (such as “strictly less than 3”) may be evaluated for an arbitrary left hand side operand, x (such as “is x strictly less than 3?”).

The result of the comparison is dependent on the object type of left hand side operand, x. For example, if x is an integer then evaluating “is x strictly less than 3?” will result in a boolean; but if x is a numpy array then “is x strictly less than 3?” will likely produce a numpy array of booleans.

The comparison is evaluated with its evaluate method or equivalently with the == operator:

>>> c = cf.Comparison('lt', 3)
>>> c.evaluate(2)
True
>>> 2 == c
True
>>> c == 2
True
>>> 4 == c
False

The inverse of the comparison may be evaluated with the != operator:

>>> c = cf.Comparison('wi', [3, 5])
>>> c.evaluate(4)
True
>>> 4 == c
True
>>> 4 != c
False
>>> c != 6
True

The following operators are supported:

operator	Description	Constructor
'lt'	Is x strictly less than a value	cf.lt
'le'	Is x less than or equal to a value	cf.le
'gt'	Is x strictly greater than a value	cf.gt
'ge'	Is x greater than or equal to a value	cf.ge
'eq'	Is x equal to a value	cf.eq
'ne'	Is x not equal to a value	cf.ne
'wi'	Is x within a given range of values (range bounds included)	cf.wi
'wo'	Is x without a given range of values (range bounds excluded)	cf.wo
'set'	Is x equal to any member of a collection.	cf.set

For the 'wi', 'wo ' and 'set' operators, if the left hand side operand supports broadcasting over its elements (such as a numpy array or a cf.Field object) then each element is tested independently. For example:

>>> c = cf.Comparison('wi', [3, 4])
>>> c == [2, 3, 4]
False
>>> print c == numpy.array([2, 3, 4])
[ False  True  True]

As a convenience, for each operator there is an identically named constructor function which returns the appropriate cf.Comparison object. For example:

>>> cf.lt(3)
<CF Comparison: lt 3>

Compound comparisons

Multiple comparisons may be logically combined with the bitwise & and | operators to form a new cf.Comparison object. For example:

>>> c = cf.ge(3)
>>> d = cf.lt(5)
>>> e = c & d
>>> e 
>>> <CF Comparison: [(ge 3) & (lt 5)]>
>>> 4 == e
True
>>> f = c | d
<CF Comparison: [(ge 3) | (lt 5)]>
>>> 2 == f
True

Compound comparisons may be combined further:

>>> g = e | cf.wi(1.5, 2.5)
>>> g
<CF Comparison: [[(ge 3) & (lt 5)] | (wi (1.5, 2.5))]>
>>> 2 == g
True
>>> g & f
<CF Comparison: [[[(ge 3) & (lt 5)] | (wi (1.5, 2.5))] & [(ge 3) | (lt 5)]]>

If any of the component comparisons are for left hand side operand attributes, then these are retained in a compound comparison. For example:

>>> c = cf.ge(3)
>>> d = cf.lt(5, attr='A')
>>> e = c & d
>>> e = e.addattr('B')
>>> e
<CF Comparison: B[(ge 3) & A(lt 5)]>

In this example,

>>> x == e

is equivalent to

>>> (x.B == cf.ge(3)) & (x.B.A == cf.lt(5))

Initialization

Parameters :

operator : str

The comparison operation.

value :

The right hand side of the comparison operation.

units : str or cf.Units, optional

The units of value. By default, the same units, if any, as the left hand side of the comparison operation are assumed.

regex : str, optional

If True then string values are to be treated as regular expressions, which are evaluated using the re.search function. Ignored for all operators except 'eq', 'ne' and 'set'.

attr : str, optional

Specify an attribute name such that this attribute of the left hand side operand is compared, rather than the operand itself.

Example: cf.Comparison('ge', 2, attr='ndim') with return True when evaluated for an array with two or more dimensions.

Examples

>>> cf.Comparison('le', 5.6)
<CF Comparison: (le 5.6)>
>>> cf.Comparison('gt', 5.6, 'metres')
<CF Comparison: (gt <CF Data: 5.6 metres>)>
>>> cf.Comparison('gt', cf.Data(5.6, 'metres'))
<CF Comparison: (gt <CF Data: 5.6 metres>)>
>>> cf.Comparison('wi', [2, 56])
<CF Comparison: (wi [2, 56])>
>>> cf.Comparison('set', [2, 56], 'seconds')
<CF Comparison: (set <CF Data: [2, 56] seconds>)>
>>> cf.Comparison('set', cf.Data([2, 56], 'seconds'))
<CF Comparison: (set <CF Data: [2, 56] seconds>)>
>>> cf.Comparison('eq', 'air_temperature')
<CF Comparison: (eq 'air_temperature')>
>>> cf.Comparison('eq', 'temperature', regex=True)
<CF Comparison: (eq 'temperature')>
>>> cf.Comparison('gt', 1, attr='ndim')
<CF Comparison: ndim(gt 1)>

Comparison methods

addattr	Return a new comparison object with a new left hand side operand attribute to be used during evaluation.
copy	Return a deep copy.
dump	Return a string containing a full description of the instance.
evaluate	Evaluate the comparison operation for a given left hand side operand.