cf.Data.where

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

Assign to data elements depending on a condition.

Data can be changed by assigning to elements that are selected by a condition based on the data values.

Different values can be assigned to where the conditions are, and are not, met.

Missing data

Data array elements may be set to missing values by assigning them to the cf.masked constant, or by assignment missing data elements of array-valued x and y parameters.

By default the data mask is “hard”, meaning that masked values can not be changed by assigning them to another value. This behaviour may be changed by setting the hardmask attribute to False, thereby making the data mask “soft” and allowing masked elements to be set to non-masked values.

See also

cf.masked, hardmask, __setitem__

Parameters
condition:

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

In general it may be any scalar or array-like object (such as a numpy array or Data instance) that is broadcastable to the shape of the data. Assignment from the x and y parameters will be done where elements of the condition evaluate to True and False respectively.

Parameter example:

d.where(d.data<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 data 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.

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

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: optional

Specify the assignment values. Where the condition evaluates to True, assign to the data from x, and where the condition evaluates to False, assign to the data from y. The x and y parameters are each one of:

  • None. The appropriate data elements array are unchanged. This the default.

  • Any scalar or array-like object (such as a numpy array, or Data instance) that is broadcastable to the shape of the data.

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.

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: