Set selected elements of the data array in place.
The value to which the selected elements of the data array will be set
may be any object which is broadcastable across the selected elements,
but some options insist that the value is logically scalar.
A subspace of elements may be selected by indices of the data array or
by locations where coordinates satisfy given conditions. A further
selection method may also be included (such as’only set elements whose
data array value is less than zero’), which applies only to the
previously selected subspace.
If the data array’s mask is to be treated as a hard mask then it will
remain unchanged after the assignment with the one exception of the
assignment value being cf.masked, in which case selected unmasked
elements will always be masked.
If and only if the value to be assigned is cf.masked then the
selected elements of data array’s mask will be set to True
(masked). This is consistent with the behaviour of numpy masked
arrays.
Note the following equivalences and alternative means of assignment:
| setitem method |
Alternative method |
|---|
| f.setitem(value) |
f.subspace[...]=value |
| f.setitem(value, indices) |
f.subspace[indices]=value |
| f.setitem(value, coord_conditions) |
f.subspace[f.indices(**coord_conditions)]=value |
| f.setitem(cf.masked, indices) |
f.setmask(True, indices) |
| Parameters : |
- value : array-like
The value to which the selected elements of the data array
will be set. Must be an object which is broadcastable across
the selected elements. The special case of value being a
field is equivalent to providing the field’s cf.Data object,
or its array attribute. Some element selection options
insist that value is logically scalar.
- indices : optional
Select elements of the data array to be set as indices or
coordinate conditions as would be accepted by the field’s
subspace attribute. By default, the entire data array is
considered.
Only elements of the data array described by indices, and
where other conditions (if any) are met, are set to
value. How masked elements of the data array are treated
depends on the hardmask parameter. The value must be any
object broadcastable across the shape implied by indices.
- condition : scalar or Comparison, optional
A condition applied to each element of the data array
specified by indices which determines whether or not that
element is set to the logically scalar value. The condition
is evaluated by checking if each element equals the condition,
and if it does then that element is set to value. How masked
elements of the data array are treated depends on the
hardmask parameter. If condition is a scalar then this is
equivalent to the cf.Comparison object
cf.eq(condition). by default there is no selection by data
array condition.
- masked : bool, optional
If False then each element of the data array specified by
indices which is unmasked is set to the logically scalar
value. If True then each element of the data array specified
by indices which is masked is unmasked and set to the
logically scalar value, regardless of the hardmask is
parameter. By default no there is no selection by data array
mask.
- ref_mask : array-like, optional
Each element of the data array specified by indices and
which corresponds to an element which evaluates to False from
the reference mask ref_mask is set to the logically scalar
value. ref_mask may be any object which is broadcastable
across the shape implied by indices. How masked elements of
the data array are treated depends on the hardmask
parameter. By default there is no seelction by reference mask.
- hardmask : bool, optional
If True then any selected elements of the data array which are
masked will not be unmasked and assigned to. If False then
any selected elements of the data array which are masked will
be unmasked and assigned to. By default, the value of the
instance’s hardmask attribute is used.
|
|---|
| Returns : | None
|
|---|
Examples
>>> f.setitem(273.15)
>>> f.setitem(273.15, dict(longitude=cf.wi(210, 270, 'degrees_east'),
latitude=cf.wi(-5, 5, 'degrees_north'))
>>> f.setitem(1, masked=False)
>>> f.setitem(2, ref_mask=g)