# cf.Field.where

`Field.``where`(condition, x=None, y=None, i=False, item=None, _debug=False, **item_options)

  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'))