[Numpy-svn] r4627 - branches/maskedarray/numpy/ma

[numpy-svn at scipy.org]

Author: stefan
Date: 2007-12-21 03:33:46 -0600 (Fri, 21 Dec 2007)
New Revision: 4627

Added:
   branches/maskedarray/numpy/ma/API_CHANGES.txt
Log:
Document API changes.


Added: branches/maskedarray/numpy/ma/API_CHANGES.txt
===================================================================
--- branches/maskedarray/numpy/ma/API_CHANGES.txt	2007-12-21 09:00:24 UTC (rev 4626)
+++ branches/maskedarray/numpy/ma/API_CHANGES.txt	2007-12-21 09:33:46 UTC (rev 4627)
@@ -0,0 +1,68 @@
+.. -*- rest -*-
+
+==================================================
+API changes in the new masked array implementation
+==================================================
+
+``put``, ``putmask`` behave like their ndarray counterparts
+-----------------------------------------------------------
+
+Previously, ``putmask`` was used like this::
+
+  mask = [False,True,True]
+  x = array([1,4,7],mask=mask)
+  putmask(x,mask,[3])
+
+which translated to::
+  
+  x[~mask] = [3]
+
+(Note that a ``True``-value in a mask suppresses a value.)
+
+In other words, the mask had the same length as ``x``, whereas
+``values`` had ``sum(~mask)`` elements.
+
+Now, the behaviour is similar to that of ``ndarray.putmask``, where
+the mask and the values are both the same length as ``x``, i.e.
+
+::
+
+  putmask(x,mask,[3,0,0])
+
+
+``fill_value`` is a property
+----------------------------
+
+``fill_value`` is no longer a method, but a property::
+
+  >>> print x.fill_value
+  999999
+
+``cumsum`` and ``cumprod`` ignore missing values
+------------------------------------------------
+
+Missing values are assumed to be the identity element, i.e. 0 for
+``cumsum`` and 1 for ``cumprod``::
+
+  >>> x = N.ma.array([1,2,3,4],mask=[False,True,False,False])
+  >>> print x
+  [1 -- 3 4]
+  >>> print x.cumsum()
+  [1 -- 4 8]
+  >> print x.cumprod()
+  [1 -- 3 12]
+
+``bool(x)`` raises a ValueError
+-------------------------------
+
+Masked arrays now behave like regular ``ndarrays``, in that they cannot be
+converted to booleans:
+
+::
+
+  >>> x = N.ma.array([1,2,3])
+  >>> bool(x)
+  Traceback (most recent call last):
+    File "<stdin>", line 1, in <module>
+  ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()
+