DATAMANIP commands


PROGRAM NAME

kunmask - Remove Mask from Data Object

DESCRIPTION

Unmask Data (kunmask) will remove the validity mask from the Input data object (i) in the manner specified by the user, and store the unmasked results in the Output data object (o). The object's mask may also be stored to an output data object, Output Mask (omask), as either Value (val) or Mask (mask) data (if neither option is selected, the data will be stored in the mask). This option may be useful for restoring an object's mask if it must be removed prior to an operation that is unable to interpret or operate on objects containing validity masks, or it may be used for operation gating purposes. Masks can be re-inserted into the object using the Copy Segments (kcpseg) or Copy from Value (kcpfromval) operators. There are currently 3 unmasking options:

Propagate The Propagate Original Data option (-prop) simply removes the mask from the data object. Masked, or invalid, data is propagated directly from the input to the output.

Replace The validity mask is used to mark points of data which are not valid for processing -- sometimes the data at these points is genuinely *not* processable, such as NaN or infinity. The Replace Masked Data with Values option (-replace) allows the invalid data to be replaced with the Real and Imaginary values (real, imag) specified by the user.

Use Attributes KPDS_MASKING_MODE and KPDS_MASK_SUBSTITUTE_VALUE are mask attributes that can be explicitly set and stored with the data object. These attributes allow the user to provide some information about the data under the validity mask, and processing routines can act accordingly. The Process as Defined by Object Mask Attributes option (-attr) queries these attributes to determine the unmasking process and the replacement values. If these attributes are not explicitly set in the input data object, the default unmasking operation is to propagate the input data to the output.

If none of the processing flags are selected, processing defaults to Use Attributes (attr).

If there is map, location, or time data associated with the source object, they are transferred to the destination object.

REQUIRED ARGUMENTS

-i
type: infile
desc: Input data object
-o
type: outfile
desc: Resulting output data object

OPTIONAL ARGUMENTS

-real
type: double
desc: If replace selected, replace real data with this value
default: 0
bounds: no range checking
-imag
type: double
desc: If replace selected, replace imaginary data with this value
default: 0
bounds: no range checking

Mutually Exclusive Group; if desired, specify ONE of:

-prop
type: flag
desc: Propagate masked (invalid) data to output
OR
-replace
type: flag
desc: Replace masked (invalid) data with real/imag values
OR
-attr
type: flag
desc: Process as defined by the object mask attributes

Mutually Inclusive Group; if desired, specify ALL of:

-omask
type: outfile
desc: Output file containing mask that was removed
default: {none}
AND

ONE OF the Mutually Exclusive Group:

-mask
type: flag
desc: If selected, save input mask as mask data in omask object
OR
-val
type: flag
desc: If selected, save input mask as value data in omask object

EXAMPLES

SEE ALSO

RESTRICTIONS

REFERENCES

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.