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 (i.e. a
scalar or an array with size 1).
A subspace of elements may be selected by indices of the data array or
by locations where coordinates satisfy given conditions. If a further
selection method is included (such as ‘only set elements whose data
array value is less than zero’), then this will apply 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:
- f.subspace[...]=value is equivalent to f.setitem(value).
- f.subspace[indices]=value is equivalent to f.setitem(value,
indices).
- f.subspace[f.indices(**coord_conditions)]=value is equivalent
to f.setitem(value, coord_conditions) .
- f.setmask(True, indices) is equivalent to f.setitem(cf.masked,
indices).
- a=f.varray; a[indices]=value is equivalent to f.setitem(value,
indices). Note that the varray method will fail if there is
insufficient memory for the numpy array a, but the setitem
method will always work.
| 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, unless the selection method insists
that value is logically scalar.
- indices : optional
Select elements of the mask to be set. Either as:
- Indices as would be accepted by f.subspace.
- A dictionary of coordinate identifiers and conditions on
their data array values as would be accepted as keyword
arguments to f.indices.
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. By
default, the entire data array is considered
- 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, x, then
this is equivalent to the Comparison object cf.eq(x). 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)