numarray Manual

18.6 Helper classes

This section discusses other classes defined in module numarray.ma.

class MAError( T): his class inherits from Exception, used to raise exceptions in the numarray.ma module. Other exceptions are possible, such as errors from the underlying numarray module.

18.6.1 The constant masked

A constant named masked in numarray.ma serves several purposes.

When a indexing operation on an MaskedArray instance returns a scalar result, but the location indexed was masked, then masked is returned. For example, given a one-dimensional array x such that x.mask()[3] is 1, then x[3] is masked.
When masked is assigned to elements of an array via indexing or slicing, those elements become masked. So after x[3] = masked, x[3] is masked.
Some other operations that may return scalar values, such as average, may return masked if given only invalid data.
To test whether or not a variable is this element, use the is or is not operator, not == or !=.
Operations involving the constant masked may result in an exception. In operations, masked behaves as an integer array of shape () with one masked element. For example, using + for illustration,
- masked + masked is masked.
- masked + numeric scalar or numeric scalar + masked is masked.
- masked + array or array + masked is a masked array with all elements masked if array is of a numeric type. The same is true if array is a numarray array.

18.6.2 The constant masked_print_option

Another constant, masked_print_option controls what happens when masked arrays and the constant masked are printed:

display( ): Returns a string that may be used to indicate those elements of an array that are masked when the array is converted to a string, as happens with the print statement.

set_display( string): This functions can be used to set the string that is used to indicate those elements of an array that are masked when the array is converted to a string, as happens with the print statement.

enable( flag): can be used to enable (flag = 1, default) the use of the display string. If disabled (flag = 0), the conversion to string becomes equivalent to str(self.filled()).

enabled( ): Returns the state of the display-enabling flag.

Example of masked behavior

>>> from numarray.ma import *
>>> x=arange(5)
>>> x[3] = masked
>>> print x
[0 ,1 ,2 ,-- ,4 ,]
>>> print repr(x)
array(data = 
 [0,1,2,0,4,],
      mask = 
 [0,0,0,1,0,],
      fill_value=[0,])
>>> print x[3]
--
>>> print x[3] + 1.0
--
>>> print masked + x
[-- ,-- ,-- ,-- ,-- ,]
>>> masked_print_option.enable(0)
>>> print x
[0,1,2,0,4,]
>>> print x + masked
[0,0,0,0,0,]
>>> print filled(x+masked, -99)
[-99,-99,-99,-99,-99,]

class masked_unary_function( f, fill=0, domain=None): Given a unary array function f, give a function which when applied to an argument x returns f applied to the array filled(x, fill), with a mask equal to mask_or(getmask(x), domain(x)).
The argument domain therefore should be a callable object that returns true where x is not in the domain of f.

The following domains are also supplied as members of module numarray.ma:

class domain_check_interval( a, b)(x): Returns true where x < a or y > b.

class domain_tan( eps): x This is true where abs(cos (x)) < eps, that is, a domain suitable for the tangent function.

class domain_greater( v)(x): True where x <= v.

class domain_greater_equal( v)(x): True where x < v.

class masked_binary_function( f, fillx=0, filly=0): Given a binary array function f, masked_binary_function(f, fillx=0, filly=0) defines a function whose value at x is f(filled(x, fillx), filled (y, filly)) with a resulting mask of mask_or(getmask (x), getmask(y)). The values fillx and filly must be chosen so that (fillx, filly) is in the domain of f.

In addition, an instance of masked_binary_function has two methods defined upon it:

reduce( target, axis = 0)

accumulate( target, axis = 0)

outer( a, b): These methods perform reduction, accumulation, and applying the function in an outer-product-like manner, as discussed in the section 7.1.2.

class domained_binary_function( ): This class exists to implement division-related operations. It is the same as masked_binary_function, except that a new second argument is a domain which is used to mask operations that would otherwise cause failure, such as dividing by zero. The functions that are created from this class are divide, remainder (mod), and fmod.

The following domains are available for use as the domain argument:

class domain_safe_divide( )(x, y): True where absolute(x)*divide_tolerance > absolute(y). As the comments in the code say, better ideas welcome. The constant divide_tolerance is set to 1.e-35 in the source and can be changed by editing its value in MA.py and reinstalling. This domain is used for the divide operator.

Send comments to the NumArray community.