cf.Field.where

Field.where(condition, x=None, y=None, i=False, item=None, **item_options)[source]

Set data array elements depending on a condition.

Elements are set differently depending on where the condition is True or False. Two assignment values are given. From one of them, the field’s data array is set where the condition is True and where the condition is False, the data array is set from the other.

Each assignment value may either contain a single datum, or is an array-like object which is broadcastable shape of the field’s data array.

Missing data

The treatment of missing data elements depends on the value of field’s hardmask attribute. If it is True then masked elements will not unmasked, otherwise masked elements may be set to any value.

In either case, unmasked elements may be set to any value (including missing data).

Unmasked elements may be set to missing data by assignment to the cf.masked constant or by assignment to a value which contains masked elements.

See also

cf.masked, hardmask, indices, mask, subspace

Examples 1: 
>>>
Parameters:
condition:

The condition which determines how to set the data array. The condition parameter may be one of:

  • Any object which is broadcastable to the field’s shape using the metadata-aware cf broadcasting rules (i.e. a suitable cf.Field object or any object, a, for which numpy.size(a) is 1). The condition is True where the object broadcast to the field’s data array evaluates to True.

    Example:

    To set all data array values of 10 to -999: f.where(10, -999).

    Example:

    To set all data array values of 100 metres to -999 metres: f.where(cf.Data(100, 'm'), -999).

    Example:

    To set all data array values to -999 where another field, g (which is broadcastable to f), evaluates to true: f.where(g, -999).

  • A cf.Query object which is evaluated against the field and the resulting field of booleans (which will always have the same shape as the original field) defines the condition.

    Example:

    f.where(cf.lt(0), -999) will set all data array values less than zero to -999. This will often be equivalent to f.where(f==cf.lt(0), -999), but the latter will fail if the field f has insufficient domain metadata whilst the former will always work.

If item or item_options are set then the condition must be a cf.Query object and is evaluated against the selected item’s data array (such as one containing coordinates). The field’s data array is set to x or y according to where in the domain the item’s data satisfies the condition.

Example:

f.where(cf.wi(-30, 30), cf.masked, -99, item='latitude') will set all data array values within the tropics to missing data and at all other locations will be set to -99.

x, y: optional

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

  • None. The appropriate elements of the field’s data array are unchanged. This the default.
  • Any object which is broadcastable to the field’s data array using the metadata-aware cf broadcasting rules (i.e. a suitable cf.Field object or any object, a, for which numpy.size(a) is 1). The appropriate elements of the field’s data array are set to the corresponding values from the object broadcast to the field’s data array shape.
item, **item_options: optional

If item and/or item_options are set then the condition is evaluated against a particular item of the field (such as one containing coordinates) and field’s data array is set to x or y according to where in the domain the item’s data satisfies the condition. The condition must be a cf.Query object.

item may be any value accepted by the description parameter of the field’s item method. The selected item is the one that would be returned by this call of the field’s item method: f.item(item, **item_options). See cf.Field.item for details.

Example:

f.where(cf.wi(-30, 30), cf.masked, -99, item='latitude') will set all data array values within the tropics to missing data and at all other locations will be set to -99.

Example:

f.where(cf.dt('2000-1-1'), 0, item'T', ndim=1) will set all data array values to zero where the uniques 1-d time coordinates are 2000-1-1.

Example:

f.where(cf.lt(2500, 'km2'), cf.masked, role='m') will mask all data values for grid cells with a cell area of less than 2500 km2 (assuming that there is a unique cell measure object in the field).

i: bool, optional

If True then update the field in place. By default a new field is created. In either case, a field is returned.
Returns:
out: cf.Field

The field with updated data array.
Examples 2:

Set data array values to 15 everywhere:

>>> f.where(True, 15)

This example could also be done with subspace assignment:

>>> f[...] = 15

Set all negative data array values to zero and leave all other elements unchanged:

>>> g = f.where(f<0, 0)

Multiply all positive data array elements by -1 and set other data array elements to 3.14:

>>> g = f.where(f>0, -f, 3.14)

Set all values less than 280 and greater than 290 to missing data:

>>> g = f.where((f < 280) | (f > 290), cf.masked)

This example could also be done with a cf.Query object:

>>> g = f.where(cf.wo(280, 290), cf.masked)

or equivalently:

>>> g = f.where(f==cf.wo(280, 290), cf.masked)

Set data array elements in the northern hemisphere to missing data in-place:

>>> condition = f.domain_mask(latitude=cf.ge(0))
>>> f.where(condition, cf.masked, i=True)

This in-place example could also be done with subspace assignment by indices:

>>> northern_hemisphere = f.indices(latitude=cf.ge(0))
>>> f.subspace[northern_hemisphere] = cf.masked

Set a polar rows to their zonal-mean values:

>>> condition = f.domain_mask(latitude=cf.set([-90, 90]))
>>> g = f.where(condition, f.collapse('longitude: mean'))