MaskedArray.h

Classes

ROMaskedArray -- (full description)
MaskedArray -- (full description)

template<class T> class ROMaskedArray : public Cleanup

Interface

Public Members
ROMaskedArray(const Array<T> &inarray, const LogicalArray &inmask)
ROMaskedArray(const ROMaskedArray<T> &inarray, const LogicalArray &inmask)
ROMaskedArray(const Array<T> &inarray, const ROMaskedLogicalArray &inmask)
ROMaskedArray(const ROMaskedArray<T> &inarray, const ROMaskedLogicalArray &inmask)
ROMaskedArray(const ROMaskedArray<T> &other)
~ROMaskedArray()
void cleanup()
ROMaskedArray<T> operator() (const LogicalArray &mask) const
ROMaskedArray<T> operator() (const ROMaskedLogicalArray &mask) const
ROMaskedArray<T> copy() const
const Array<T> & getArray() const
const LogicalArray & getMask() const
uInt ndim() const
uInt nelements() const
uInt arrayNelements() const
Bool ok() const
Bool conform(const Array<T> &other) const
Bool conform(const ROMaskedArray<T> &other) const
IPosition origin() const
IPosition shape() const
const T * getArrayStorage (Bool &deleteIt) const
void freeArrayStorage(const T *&storage, Bool deleteIt) const
const LogicalArrayElem *getMaskStorage (Bool &deleteIt) const
void freeMaskStorage(const LogicalArrayElem *&storage, Bool deleteIt) const
Private Members
ROMaskedArray<T> &operator=(const ROMaskedArray<T> &other)
See Also
Related mathematical functions for MaskedArrays

Description

Prerequisite

Etymology

ROMaskedArray is a readonly MaskedArray. It is a MaskedArray where the underlying Array is not allowed to be modified by any operations on the ROMaskedArray. See the discussion of MaskedArray for more information on MaskedArrays.

Synopsis

A ROMaskedArray is a masked array where the underlying Array is not allowed to be modified by any operations on the ROMaskedArray. The MaskedArray class, which does allow the underlying Array to be modified, is derived from this class. See the discussion of MaskedArray for more information on MaskedArrays.

Many mathematical and logical global operators and functions which operate on ROMaskedArrays are defined. See the discussion in MaskedArrays for lists or click here (description) to go to the functions. (info) (info again!)

Example

   template<class T>
     const MaskedArray<T> & operator+= (const MaskedArray<T> &left,
                                        const ROMaskedArray<T> &other);
The operator operator+=() adds the second argument to the first argument, putting the result in the first argument. Therefore, the second argument can be a ROMaskedArray, since it is not modified, while the first argument must be a MaskedArray, since it is modified.

Motivation

A MaskedArray is an association between an Array and a LogicalArray which masks the Array. It was necessary that the meaning of const MaskedArray be that the association was const, but that the Array itself could be modified inside the MaskedArray. Therefore, it was necessary that there be a separate class for masked arrays where the Array itself could not be modified.

To Do

Member Description

ROMaskedArray(const Array<T> &inarray, const LogicalArray &inmask)

Create a ROMaskedArray from an Array and a LogicalArray.

The internal mask is a total copy of the input mask, and is completely independent of the input mask. However, the origin of the internal mask is shifted to coincide with that of the Array.

The Array is copy constructed, which means that it is a really smart pointer to the underlying Block, and shares this Block with the input Array.

Thrown Exceptions

ROMaskedArray(const ROMaskedArray<T> &inarray, const LogicalArray &inmask)

Create a ROMaskedArray from a ROMaskedArray and a LogicalArray.

The internal mask is the AND of the input mask and the mask of the input ROMaskedArray. The origin of the internal mask is set to coincide with that of the Array of the input ROMaskedArray.

The Array from the input ROMaskedArray is copy constructed, which means that it is a really smart pointer to the underlying Block, and shares this Block with the Array from the input ROMaskedArray.

Thrown Exceptions

ROMaskedArray(const Array<T> &inarray, const ROMaskedLogicalArray &inmask)

Create a ROMaskedArray from an Array and a ROMaskedLogicalArray.

The internal mask is the AND of the internal LogicalArray and the internal mask of the ROMaskedLogicalArray. The origin of the internal mask is set to coincide with that of the Array of the input ROMaskedArray.

The Array is copy constructed, which means that it is a really smart pointer to the underlying Block, and shares this Block with the input Array.

Thrown Exceptions

ROMaskedArray(const ROMaskedArray<T> &inarray, const ROMaskedLogicalArray &inmask)

Create a ROMaskedArray from a ROMaskedArray and a ROMaskedLogicalArray.

The internal mask is the AND of the internal LogicalArray and the internal mask of the ROMaskedLogicalArray, ANDed with the mask of the input ROMaskedArray. The origin of the internal mask is set to coincide with that of the Array of the input ROMaskedArray.

The Array from the input ROMaskedArray is copy constructed, which means that it is a really smart pointer to the underlying Block, and shares this Block with the Array from the input ROMaskedArray.

Thrown Exceptions

ROMaskedArray(const ROMaskedArray<T> &other)

Copy constructor.

The internal mask is a total copy of the mask from the input ROMaskedArray, and is completely independent of this input mask.

The Array from the input ROMaskedArray is copy constructed, which means that it is a really smart pointer to the underlying Block, and shares this Block with the Array from the input ROMaskedArray.

Thrown Exceptions

~ROMaskedArray()

void cleanup()

This functions is used by the exception handling mechanism we have defined. It merely calls the destructor. When real exceptions are available it will be unnecessary.

ROMaskedArray<T> operator() (const LogicalArray &mask) const

Return a ROMaskedArray. The new ROMaskedArray is masked by the input LogicalArray "anded" with the mask of the original ROMaskedArray. This mask must conform to the array, but it does not need to have the same origin.

ROMaskedArray<T> operator() (const ROMaskedLogicalArray &mask) const

Return a ROMaskedArray. The new ROMaskedArray is masked by the input ROMaskedLogicalArray "anded" with the mask of the original ROMaskedArray. This mask must conform to the array, but it does not need to have the same origin.

ROMaskedArray<T> copy() const

Make a copy of the masked array. This is a deep copy. The Array and mask components of the returned ROMaskedArray are deep copies of the Array and mask in the input ROMaskedArray pointed to by this. In other words, the Array and mask in the output ROMaskedArray are completely independent of those in the input ROMaskedArray.

const Array<T> & getArray() const

Return the internal Array.

const LogicalArray & getMask() const

Return the (const) internal Mask.

uInt ndim() const

The dimensionality of this masked array.

uInt nelements() const

The number of elements of this masked array. This is the number of elements of the mask which are TRUE.

uInt arrayNelements() const

The number of elements in the underlying Array.

Bool ok() const

Check to see if the masked array is consistent. This is about the same thing as checking for invariants. If AIPS_DEBUG is defined, this is invoked after construction and on entry to most member functions.

Bool conform(const Array<T> &other) const
Bool conform(const ROMaskedArray<T> &other) const

Are the shapes identical? The origins do NOT need to be the same. Binary operations will "line up" the masked arrays at their origins, so as long as the shapes are the same the masked arrays conform.

IPosition origin() const

The IPosition of the first element of the underlying Array. NOTE: The mask origin is defined to be this also.

IPosition shape() const

The length of each axis.

const T * getArrayStorage (Bool &deleteIt) const
void freeArrayStorage(const T *&storage, Bool deleteIt) const

Manipulate the storage for the underlying Array. See the description of the corresponding Array functions for more information.

const LogicalArrayElem *getMaskStorage (Bool &deleteIt) const
void freeMaskStorage(const LogicalArrayElem *&storage, Bool deleteIt) const

Manipulate the storage for the underlying Mask. See the description of the corresponding Array functions for more information.

ROMaskedArray<T> &operator=(const ROMaskedArray<T> &other)


template<class T> class MaskedArray : public ROMaskedArray<T>

Interface

Public Members
MaskedArray(const Array<T> &inarray, const LogicalArray &inmask)
MaskedArray(const MaskedArray<T> &inarray, const LogicalArray &inmask)
MaskedArray(const Array<T> &inarray, const ROMaskedLogicalArray &inmask)
MaskedArray(const MaskedArray<T> &inarray, const ROMaskedLogicalArray &inmask)
MaskedArray(const MaskedArray<T> &other)
~MaskedArray()
void cleanup()
MaskedArray<T> &operator=(const Array<T> &inarray)
MaskedArray<T> &operator=(const ROMaskedArray<T> &other)
MaskedArray<T> &operator=(const T &value)
ROMaskedArray<T> operator() (const LogicalArray &mask) const
MaskedArray<T> operator() (const LogicalArray &mask)
ROMaskedArray<T> operator() (const ROMaskedLogicalArray &mask) const
MaskedArray<T> operator() (const ROMaskedLogicalArray &mask)
Array<T> & getRWArray() const
T * getRWArrayStorage (Bool &deleteIt) const
void putArrayStorage(T *&storage, Bool deleteAndCopy) const
See Also
Related mathematical functions for MaskedArrays

Description

Prerequisite

Etymology

MaskedArray is a class for masking elements of an Array while performing operations on that Array.

Synopsis

A MaskedArray is an association between an Array and a mask. The mask selects elements of the Array. Only elements of the Array where the corresponding element of the mask is True are defined. Thus, operations on a MaskedArray only operate on those elements of the Array where the corresponding element of the mask is True.

A MaskedArray should be thought of as a manipulator for an Array, analogous to an iterator. It allows one to perform whole Array operations on selected elements of the Array.

The mask used in the constructor for the MaskedArray must conform to the Array. However, it does not need to have the same origin. The internal mask is (will be) copy constructed with reference semantics from the input mask. Its origin is then shifted to have the same origin as the Array. Therefore, it is (will be) possible to change the internal mask by changing values in the input mask *after* the MaskedArray has been constructed. To ensure that the internal mask is independent of the input mask after construction, use mask.copy() as the input argument.

One can explicitly construct a MaskedArray from an Array and a mask or a MaskedArray and a mask. One can also use operator() on an Array or a MaskedArray to implicitly create a MaskedArray.

One can create a MaskedArray from a MaskedArray and a mask. The resulting MaskedArray has as its Array the Array from the original MaskedArray. The mask for the resulting MaskedArray is the AND of the mask from the original MaskedArray and the input mask.

Any operation involving a MaskedArray or a set of MaskedArrays is only performed for those elements where the AND of the masks is True.

Any operation involving a MaskedArray or a set of MaskedArrays results in a MaskedArray whose mask is the AND of the masks of the original MaskedArrays. The only exception to this is assignment, where the mask determines which elements of the underlying Array are assigned.

Masks, which are LogicalArrays, can be constructed by logical operations involving Arrays. They can also, of course, be constructed by individually setting individual elements of an LogicalArray.

Many mathematical and logical global operators and functions which operate on ROMaskedArrays and MaskedArrays are defined. Typically, they are defined for all sensible combinations of "MaskedArrays", Arrays, and scalars. "MaskedArrays" means ROMaskedArrays if the underlying Array will not be modified, and means MaskedArrays if the underlying Array will be modified.

Mathematical global operators and functions are defined in Arrays/MaskArrMath.h . The list is:

Logical global operators and functions are defined in Arrays/MaskArrLogi.h . The list is:

Example

Use an explicit MaskedArray to limit the maximum value of an Array.

   Array<Int> arr (20);
      . . .
   MaskedArray<Int> marr (arr, (arr > 5));
   marr = 5;

This sets all elements of arr which are greater than 5 to 5.

Example

Use an implicit MaskedArray to limit the minimum value of an Array.

   Array<Int> arr (20);
      . . .
   arr (arr < 0) = 0;

This sets all elements of arr which are less than 0 to 0.

Example

It does not matter where in an expression the MaskedArrays are located. The operation is only performed on those elements where the AND of the masks is True.

The following expressions are all equivalent. The first (and second) expressions are the most efficient, since the sum is only performed for those elements where ((a > 0) && (b > 0)). The third example is less efficient, since the sum is performed for all elements of a and b, and then the assignment is only performed for those elements where ((a > 0) && (b > 0)).

   Array<Int> arr (20);
   Array<Int> a (20);
   Array<Int> b (20);
      . . .
   arr = a(a > 0) + b(b > 0);

   arr = a(b > 0) + b(a > 0);

   arr ((a > 0) && (b > 0)) = a + b;

   arr = (a + b) ((a > 0) && (b > 0));

   arr (a > 0) = a + b(b > 0);

All of these expressions set those elements of arr where ((a > 0) && (b > 0)) to a + b. Those elements of arr where the condition is False are unchanged.

Motivation

A MaskedArray is an association between an Array and a LogicalArray which masks the Array. It allows one to perform whole Array manipulations with a single expression, selecting those elements of the Array to modify based either on a logical expression, typically involving some of the Arrays involved in the expression, or based on a specifically set mask.

To Do

Member Description

MaskedArray(const Array<T> &inarray, const LogicalArray &inmask)

Create a MaskedArray from an Array and a LogicalArray.

MaskedArray(const MaskedArray<T> &inarray, const LogicalArray &inmask)

Create a MaskedArray from a MaskedArray and a LogicalArray.

MaskedArray(const Array<T> &inarray, const ROMaskedLogicalArray &inmask)

Create a MaskedArray from an Array and a ROMaskedLogicalArray.

MaskedArray(const MaskedArray<T> &inarray, const ROMaskedLogicalArray &inmask)

Create a MaskedArray from a MaskedArray and a ROMaskedLogicalArray.

MaskedArray(const MaskedArray<T> &other)

~MaskedArray()

Frees up storage.

void cleanup()

This function is used by the exception handling mechanism we have defined. It merely calls the destructor. When real exceptions are available it will be unnecessary.

MaskedArray<T> &operator=(const Array<T> &inarray)

Copy the values in inarray to this, only copying those elements for which the corresponding mask element is True.

Thrown Exceptions

MaskedArray<T> &operator=(const ROMaskedArray<T> &other)

Copy the values in other to this, only copying those elements for which the logical AND of the corresponding mask elements of both MaskedArrays is True.

Thrown Exceptions

MaskedArray<T> &operator=(const T &value)

Set every element of this array to "value", only setting those elements for which the corresponding mask element is True. In other words, a scalar behaves as if it were a constant conformant array.

ROMaskedArray<T> operator() (const LogicalArray &mask) const

Return a ROMaskedArray. The new ROMaskedArray is masked by the input LogicalArray "anded" with the mask of the original ROMaskedArray. This mask must conform to the array, but it does not need to have the same origin.

MaskedArray<T> operator() (const LogicalArray &mask)

Return a MaskedArray. The new MaskedArray is masked by the input LogicalArray "anded" with the mask of the original MaskedArray. This mask must conform to the array, but it does not need to have the same origin.

ROMaskedArray<T> operator() (const ROMaskedLogicalArray &mask) const

Return a ROMaskedArray. The new ROMaskedArray is masked by the input ROMaskedLogicalArray "anded" with the mask of the original ROMaskedArray. This mask must conform to the array, but it does not need to have the same origin.

MaskedArray<T> operator() (const ROMaskedLogicalArray &mask)

Return a MaskedArray. The new MaskedArray is masked by the input ROMaskedLogicalArray "anded" with the mask of the original MaskedArray. This mask must conform to the array, but it does not need to have the same origin.

Array<T> & getRWArray() const

Return the internal Array, writeable.

T * getRWArrayStorage (Bool &deleteIt) const
void putArrayStorage(T *&storage, Bool deleteAndCopy) const

Manipulate the storage for the underlying Array. See the description of the corresponding Array functions for more information.


Copyright © 1995 Associated Universities Inc., Washington, D.C.