API_CHANGES

.. -*- rest -*-

================================================== API changes in the new masked array implementation ==================================================

Masked arrays are subclasses of ndarray ---------------------------------------

Contrary to the original implementation, masked arrays are now regular ndarrays::

>>> x = masked_array([1,2,3],mask=[0,0,1]) >>> print isinstance(x, numpy.ndarray) True

``_data`` returns a view of the masked array --------------------------------------------

Masked arrays are composed of a ``_data`` part and a ``_mask``. Accessing the ``_data`` part will return a regular ndarray or any of its subclass, depending on the initial data::

>>> x = masked_array(numpy.matrix([[1,2],[3,4]]),mask=[[0,0],[0,1]]) >>> print x._data [[1 2] [3 4]] >>> print type(x._data)

In practice, ``_data`` is implemented as a property, not as an attribute. Therefore, you cannot access it directly, and some simple tests such as the following one will fail::

>>>x._data is x._data False

``filled(x)`` can return a subclass of ndarray ---------------------------------------------- The function ``filled(a)`` returns an array of the same type as ``a._data``::

>>> x = masked_array(numpy.matrix([[1,2],[3,4]]),mask=[[0,0],[0,1]]) >>> y = filled(x) >>> print type(y) >>> print y matrix([[ 1, 2], [ 3, 999999]])

``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 "", line 1, in ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

================================== New features (non exhaustive list) ==================================

``mr_`` -------

``mr_`` mimics the behavior of ``r_`` for masked arrays::

>>> np.ma.mr_[3,4,5] masked_array(data = [3 4 5], mask = False, fill_value=999999)

``anom`` --------

The ``anom`` method returns the deviations from the average (anomalies).