cf.Data.where

Data.where(condition, x=None, y=None, inplace=False, i=False, verbose=None)[source]

Assign array elements depending on a condition.

The elements to be changed are identified by a condition. Different values can be assigned according to where the condition is True (assignment from the x parameter) or False (assignment from the y parameter).

Missing data

Array elements may be set to missing values if either x or y are the cf.masked constant, or by assignment from any missing data elements in x or y.

If the data mask is hard (see the hardmask attribute) then missing data values in the array will not be overwritten, regardless of the content of x and y.

If the condition contains missing data then the corresponding elements in the array will not be assigned to, regardless of the contents of x and y.

Broadcasting

The array and the condition, x and y parameters must all be broadcastable across the original array, such that the size of the result is identical to the original size of the array. Leading size 1 dimensions of these parameters are ignored, thereby also ensuring that the shape of the result is identical to the original shape of the array.

If condition is a Query object then for the purposes of broadcasting, the condition is considered to be that which is produced by applying the query to the array.

Performance

If any of the shapes of the condition, x, or y parameters, or the array, is unknown, then there is a possibility that an unknown shape will need to be calculated immediately by executing all delayed operations on that object.

See also

cf.masked, hardmask, __setitem__

Parameters
condition: array_like or Query

The condition which determines how to assign values to the data.

Assignment from the x and y parameters will be done where elements of the condition evaluate to True and False respectively.

If condition is a Query object then this implies a condition defined by applying the query to the data.

Parameter example:

d.where(d < 0, x=-999) will set all data values that are less than zero to -999.

Parameter example:

d.where(True, x=-999) will set all data values to -999. This is equivalent to d[...] = -999.

Parameter example:

d.where(False, y=-999) will set all data values to -999. This is equivalent to d[...] = -999.

Parameter example:

If d has shape (5, 3) then d.where([True, False, True], x=-999, y=cf.masked) will set data values in columns 0 and 2 to -999, and data values in column 1 to missing data. This works because the condition has shape (3,) which broadcasts to the data shape.

Parameter example:

d.where(cf.lt(0), x=-999) will set all data values that are less than zero to -999. This is equivalent to d.where(d < 0, x=-999).

x, y: array-like or None

Specify the assignment values. Where the condition is True assign to the data from x, and where the condition is False assign to the data from y.

If x is None (the default) then no assignment is carried out where the condition is True.

If y is None (the default) then no assignment is carried out where the condition is False.

Parameter example:

d.where(condition), for any condition, returns data with identical data values.

Parameter example:

d.where(cf.lt(0), x=-d, y=cf.masked) will change the sign of all negative data values, and set all other data values to missing data.

Parameter example:

d.where(cf.lt(0), x=-d) will change the sign of all negative data values, and leave all other data values unchanged. This is equivalent to, but faster than, d.where(cf.lt(0), x=-d, y=d)

inplace: bool, optional

If True then do the operation in-place and return None.

verbose: int or str or None, optional

If an integer from -1 to 3, or an equivalent string equal ignoring case to one of:

  • 'DISABLE' (0)

  • 'WARNING' (1)

  • 'INFO' (2)

  • 'DETAIL' (3)

  • 'DEBUG' (-1)

set for the duration of the method call only as the minimum cut-off for the verboseness level of displayed output (log) messages, regardless of the globally-configured cf.log_level. Note that increasing numerical value corresponds to increasing verbosity, with the exception of -1 as a special case of maximal and extreme verbosity.

Otherwise, if None (the default value), output messages will be shown according to the value of the cf.log_level setting.

Overall, the higher a non-negative integer or equivalent string that is set (up to a maximum of 3/'DETAIL') for increasing verbosity, the more description that is printed to convey information about the operation.

i: deprecated at version 3.0.0

Use the inplace parameter instead.

Returns
Data or None

The new data with updated values, or None if the operation was in-place.

Examples

>>> d = cf.Data([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> e = d.where(d < 5, d, 10 * d)
>>> print(e.array)
[ 0  1  2  3  4 50 60 70 80 90]

>>> d = cf.Data([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], 'km')
>>> e = d.where(d < 5, cf.Data(10000 * d, 'metre'))
>>> print(e.array)
[ 0. 10. 20. 30. 40.  5.  6.  7.  8.  9.]

>>> e = d.where(d < 5, cf.masked)
>>> print(e.array)
[-- -- -- -- -- 5 6 7 8 9]

>>> d = cf.Data([[1, 2,],
...              [3, 4]])
>>> e = d.where([[True, False], [True, True]], d, [[9, 8], [7, 6]])
>>> print(e.array)
[[1 8]
 [3 4]]
>>> e = d.where([[True, False], [True, True]], [[9, 8], [7, 6]])
>>> print(e.array)
[[9 2]
 [7 6]]

The shape of the result must have the same shape as the original data:

>>> e = d.where([True, False], [9, 8])
>>> print(e.array)
[[9 2]
 [9 4]]

>>> d = cf.Data(np.array([[0, 1, 2],
...                       [0, 2, 4],
...                       [0, 3, 6]]))
>>> d.where(d < 4, None, -1)
>>> print(e.array)
[[ 0  1  2]
 [ 0  2 -1]
 [ 0  3 -1]]

>>> x, y = np.ogrid[:3, :4]
>>> print(x)
[[0]
 [1]
 [2]]
>>> print(y)
[[0 1 2 3]]
>>> condition = x < y
>>> print(condition)
[[False  True  True  True]
 [False False  True  True]
 [False False False  True]]
>>> d = cf.Data(x)
>>> e = d.where(condition, d, 10 + y)
    ...
ValueError: where: 'condition' parameter with shape (3, 4) can not be broadcast across data with shape (3, 1) when the result will have a different shape to the data

>>> d = cf.Data(np.arange(9).reshape(3, 3))
>>> e = d.copy()
>>> e[1, 0] = cf.masked
>>> f = e.where(d > 5, None, -3.1416)
>>> print(f.array)
[[-3.1416 -3.1416 -3.1416]
 [-- -3.1416 -3.1416]
 [6.0 7.0 8.0]]
>>> e.soften_mask()
>>> f = e.where(d > 5, None, -3.1416)
>>> print(f.array)
[[-3.1416 -3.1416 -3.1416]
 [-3.1416 -3.1416 -3.1416]
 [ 6.      7.      8.    ]]