# 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 $ *