diff options
Diffstat (limited to 'numpy/ma/core.py')
| -rw-r--r-- | numpy/ma/core.py | 59 |
1 files changed, 51 insertions, 8 deletions
diff --git a/numpy/ma/core.py b/numpy/ma/core.py index e0e5403a9..9c9dfac68 100644 --- a/numpy/ma/core.py +++ b/numpy/ma/core.py @@ -3542,15 +3542,17 @@ class MaskedArray(ndarray): def harden_mask(self): """ - Force the mask to hard. + Force the mask to hard, preventing unmasking by assignment. Whether the mask of a masked array is hard or soft is determined by its `~ma.MaskedArray.hardmask` property. `harden_mask` sets - `~ma.MaskedArray.hardmask` to ``True``. + `~ma.MaskedArray.hardmask` to ``True`` (and returns the modified + self). See Also -------- ma.MaskedArray.hardmask + ma.MaskedArray.soften_mask """ self._hardmask = True @@ -3558,15 +3560,17 @@ class MaskedArray(ndarray): def soften_mask(self): """ - Force the mask to soft. + Force the mask to soft (default), allowing unmasking by assignment. Whether the mask of a masked array is hard or soft is determined by its `~ma.MaskedArray.hardmask` property. `soften_mask` sets - `~ma.MaskedArray.hardmask` to ``False``. + `~ma.MaskedArray.hardmask` to ``False`` (and returns the modified + self). See Also -------- ma.MaskedArray.hardmask + ma.MaskedArray.harden_mask """ self._hardmask = False @@ -3574,16 +3578,55 @@ class MaskedArray(ndarray): @property def hardmask(self): - """ Hardness of the mask """ + """ + Specifies whether values can be unmasked through assignments. + + By default, assigning definite values to masked array entries will + unmask them. When `hardmask` is ``True``, the mask will not change + through assignments. + + See Also + -------- + ma.MaskedArray.harden_mask + ma.MaskedArray.soften_mask + + Examples + -------- + >>> x = np.arange(10) + >>> m = np.ma.masked_array(x, x>5) + >>> assert not m.hardmask + + Since `m` has a soft mask, assigning an element value unmasks that + element: + + >>> m[8] = 42 + >>> m + masked_array(data=[0, 1, 2, 3, 4, 5, --, --, 42, --], + mask=[False, False, False, False, False, False, + True, True, False, True], + fill_value=999999) + + After hardening, the mask is not affected by assignments: + + >>> hardened = np.ma.harden_mask(m) + >>> assert m.hardmask and hardened is m + >>> m[:] = 23 + >>> m + masked_array(data=[23, 23, 23, 23, 23, 23, --, --, 23, --], + mask=[False, False, False, False, False, False, + True, True, False, True], + fill_value=999999) + + """ return self._hardmask def unshare_mask(self): """ - Copy the mask and set the sharedmask flag to False. + Copy the mask and set the `sharedmask` flag to ``False``. Whether the mask is shared between masked arrays can be seen from - the `sharedmask` property. `unshare_mask` ensures the mask is not shared. - A copy of the mask is only made if it was shared. + the `sharedmask` property. `unshare_mask` ensures the mask is not + shared. A copy of the mask is only made if it was shared. See Also -------- |