Permalink
Browse files

Clarified MaskedArray.view documentation, and added more tests

  • Loading branch information...
1 parent 4bacc46 commit ab66c255dc867ac00450960adeac29910dc4fa66 @astrofrog astrofrog committed Nov 22, 2012
Showing with 48 additions and 10 deletions.
  1. +34 −6 numpy/ma/core.py
  2. +14 −4 numpy/ma/tests/test_core.py
View
@@ -2854,14 +2854,42 @@ def __array_wrap__(self, obj, context=None):
def view(self, dtype=None, type=None, fill_value=None):
"""
- Return a view of the MaskedArray
+ Return a view of the MaskedArray data
- If `fill_value` is not specified, but `dtype` is specified, the
- `fill_value` of the MaskedArray will be reset. If neither `fill_value`
- nor `dtype` are specified, then the fill value is preserved. Finally,
- if `fill_value` is specified, but `dtype` is not, the fill value is
- set to the specified value.
+ Parameters
+ ----------
+ dtype : data-type or ndarray sub-class, optional
+ Data-type descriptor of the returned view, e.g., float32 or int16.
+ The default, None, results in the view having the same data-type
+ as `a`. As with ``ndarray.view``, dtype can also be specified as
+ an ndarray sub-class, which becomes the type of the returned
+ object (this is equivalent to setting the ``type`` parameter).
+ type : Python type, optional
+ Type of the returned view, e.g., ndarray or matrix. Again, the
+ default None results in type preservation.
+
+ Notes
+ -----
+
+ ``a.view()`` is used two different ways:
+
+ ``a.view(some_dtype)`` or ``a.view(dtype=some_dtype)`` constructs a view
+ of the array's memory with a different data-type. This can cause a
+ reinterpretation of the bytes of memory.
+
+ ``a.view(ndarray_subclass)`` or ``a.view(type=ndarray_subclass)`` just
+ returns an instance of `ndarray_subclass` that looks at the same array
+ (same shape, dtype, etc.) This does not cause a reinterpretation of the
+ memory.
+
+ If `fill_value` is not specified, but `dtype` is specified (and is not
+ an ndarray sub-class), the `fill_value` of the MaskedArray will be
+ reset. If neither `fill_value` nor `dtype` are specified (or if
+ `dtype` is an ndarray sub-class), then the fill value is preserved.
+ Finally, if `fill_value` is specified, but `dtype` is not, the fill
+ value is set to the specified value.
"""
+
if dtype is None:
if type is None:
output = ndarray.view(self)
@@ -1565,19 +1565,29 @@ def test_fillvalue_in_view(self):
assert_(y.fill_value==1)
# Check that fill_value is preserved if dtype is specified and the
- # dtype has a _fill_value attribute
+ # dtype is an ndarray sub-class and has a _fill_value attribute
y = x.view(MaskedArray)
assert_(y.fill_value==1)
- print y.fill_value
- # Check that code does not crash if passed a dtype that does not have
- # a _fill_value attribute
+ # Check that fill_value is preserved if type is specified and the
+ # dtype is an ndarray sub-class and has a _fill_value attribute (by
+ # default, the first argument is dtype, not type)
+ y = x.view(type=MaskedArray)
+ assert_(y.fill_value==1)
+
+ # Check that code does not crash if passed an ndarray sub-class that
+ # does not have a _fill_value attribute
y = x.view(np.ndarray)
+ y = x.view(type=np.ndarray)
# Check that fill_value can be overriden with view
y = x.view(MaskedArray, fill_value=2)
assert_(y.fill_value==2)
+ # Check that fill_value can be overriden with view (using type=)
+ y = x.view(type=MaskedArray, fill_value=2)
+ assert_(y.fill_value==2)
+
# Check that fill_value gets reset if passed a dtype but not a
# fill_value. This is because even though in some cases one can safely
# cast the fill_value, e.g. if taking an int64 view of an int32 array,

0 comments on commit ab66c25

Please sign in to comment.