mask

Masks one multi-dimensional array against another given a single mask value.

Synopsis

	function mask(
		array,
		marray,
		mvalue[1]
	)

Arguments

array
main array of any type and dimensionality but must be a super set of the dimensionality of marray
marray
mask array of any type and dimensionality but must have at most the same dimensionality as array and its dimension sizes must correspond to array as defined below.
mvalue
A single mask value which must be the same type as marray or coercible to that type

Description

mask masks the argument array against the mask array marray at locations where marray is equal to the argument mvalue. Missing values are placed in the output array in locations where marray is NOT equal to the mask value, mvalue.

If array has n dimensions and marray has m dimensions, then the dimensionality restrictions are as follows: 

	m is less-than-or-equal-to n
	The dimension sizes of marray must be equal to 
		dimensions n-m through n-1 of array

Example

The following demonstrates how mask works in addition to showing how to reshape array such that the dimensionality restrictions are met. Try running ncl and entering the following statements: 
;
; Create array a and fill with integer values
;
	a = onedtond(ispan(1,120,1),(/4,5,6/))
	a!0 = "time"
	a!1 = "x"
	a!2 = "y"
;
; Create mask arrays:
; ma0 has the same dimension sizes as dimensions 1 and 2 
; of a respectively.
; ma1 has the same dimension sizes as dimensions 2 and 0 
; of a respectively.
;
	ma0 = onedtond( (/1,1,2,2,3,3/), (/5,6/))
	ma1 = onedtond( (/1,2,2,3/), (/6,4/))

;
; Simple case mask a at locations where ma0 is equal-to 2
;
	out0 = mask( a, ma0, 2)

;
; More advanced case mask a at locations where ma0 is not-equal-to 2
;
	out1 = mask( a, (ma0.ne.2), True)

;
; Now reshape a to mask a at locations where ma1 is equal-to 2
; using Named Subscripting
;
	out2 = mask( a( x | : , y | :,  time | :), ma1, 2)

;
; Same masking as above but it reshapes output of mask to 
; original dimensionality
;
	out2!0 = "x"
	out2!1 = "y"
	out2!2 = "time"

	out2a = out2( time | :, x | : , y | :)

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?

$Revision: 1.5 $ $Date: 1998/06/15 21:30:09 $