cf.Field.where¶

Field.
where
(condition, x=None, y=None, inplace=False, construct=None, i=False, verbose=None, item=None, **item_options)[source]¶ Assign to data 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 field’s array.Performance
If any of the shapes of the condition, x, or y parameters, or the field, 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.
 Parameters
 condition: array_like,
Field
orQuery
The condition which determines how to assign values to the field’s data.
Assignment from the x and y parameters will be done where elements of the condition evaluate to
True
andFalse
respectively.If condition is a
Query
object then this implies a condition defined by applying the query to the data. Parameter example:
f.where(f.data<0, x=999)
will set all data values that are less than zero to 999. Parameter example:
f.where(True, x=999)
will set all data values to 999. This is equivalent tof[...] = 999
. Parameter example:
f.where(False, y=999)
will set all data values to 999. This is equivalent tof[...] = 999
. Parameter example:
If field construct
f
has shape(5, 3)
thenf.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 field construct’s shape. Parameter example:
f.where(cf.lt(0), x=999)
will set all data values that are less than zero to 999. This is equivalent tof.where(f.data<0, x=999)
.
If condition is a
Field
then it is first transformed so that it is broadcastable to the data being assigned to. This is done by using the metadata constructs of the two field constructs to create a mapping of physically identical dimensions between the fields, and then manipulating the dimensions of other field construct’s data to ensure that they are broadcastable. If either of the field constructs does not have sufficient metadata to create such a mapping then an exception will be raised. In this case, any manipulation of the dimensions must be done manually, and theData
instance of construct (rather than the field construct itself) may be used for the condition. Parameter example:
If field construct
f
has shape(5, 3)
andg = f.transpose() < 0
thenf.where(g, x=999)
will set all data values that are less than zero to 999, provided there are sufficient metadata for the data dimensions to be mapped. However,f.where(g.data, x=999)
will always fail in this example, because the shape of the condition is(3, 5)
, which does not broadcast to the shape of thef
.
 x, y: arraylike or
Field
orNone
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 anycondition
, 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)
 Parameter example:
f.where(condition)
, for anycondition
, returns a field construct with identical data values. Parameter example:
f.where(cf.lt(0), x=f.data, y=cf.masked)
will change the sign of all negative data values, and set all other data values to missing data.
If x or y is a
Field
then it is first transformed so that its data is broadcastable to the data being assigned to. This is done by using the metadata constructs of the two field constructs to create a mapping of physically identical dimensions between the fields, and then manipulating the dimensions of other field construct’s data to ensure that they are broadcastable. If either of the field constructs does not have sufficient metadata to create such a mapping then an exception will be raised. In this case, any manipulation of the dimensions must be done manually, and theData
instance of x or y (rather than the field construct itself) may be used for the condition. Parameter example:
If field construct
f
has shape(5, 3)
andg = f.transpose() * 10
thenf.where(cf.lt(0), x=g)
will set all data values that are less than zero to the equivalent elements of field constructg
, provided there are sufficient metadata for the data dimensions to be mapped. However,f.where(cf.lt(0), x=g.data)
will always fail in this example, because the shape of the condition is(3, 5)
, which does not broadcast to the shape of thef
.
 construct:
str
, optional Define the condition by applying the construct parameter to the given metadata construct’s data, rather than the data of the field construct. Must be
The identity or key of a metadata coordinate construct that has data.
The construct parameter selects the metadata construct that is returned by this call of the field construct’s
construct
method:f.construct(construct)
. Seecf.Field.construct
for details. Parameter example:
f.where(cf.wi(30, 30), x=cf.masked, construct='latitude')
will set all data values within 30 degrees of the equator to missing data.
 inplace:
bool
, optional If True then do the operation inplace and return
None
. i: deprecated at version 3.0.0
Use the inplace parameter instead.
 item: deprecated at version 3.0.0
Use the construct parameter instead.
item_options: deprecated at version 3.0.0
 condition: array_like,
 Returns
Examples
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
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 inplace:
>>> condition = f.domain_mask(latitude=cf.ge(0)) >>> f.where(condition, cf.masked, inplace=True)
Missing data can only be changed if the mask is “soft”:
>>> f[0] = cf.masked >>> g = f.where(True, 99) >>> print(g[0],array) [] >>> f.hardmask = False >>> g = f.where(True, 99) >>> print(g[0],array) [99]
This inplace 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 zonalmean values:
>>> condition = f.domain_mask(latitude=cf.set([90, 90])) >>> g = f.where(condition, f.collapse('longitude: mean'))