cf.Field.where

Field.where(condition, x=None, y=None, i=False, item=None, **kwargs)[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.

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

>>> # Create a condition which is True only in the northern hemisphere
>>> condition = f.domain_mask(latitude=cf.ge(0))
>>> # Set the data
>>> 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[northern_hemisphere] = cf.masked

Set a polar rows to their zonal-mean values:

>>> # Create a condition which is True only on polar rows
>>> condition = f.domain_mask(latitude=cf.set([-90, 90]))
>>> #Set each data polar row element to the polar row zonal mean 
>>> # and mask all other points
>>> g = f.where(condition, f.collapse('longitude: mean'))