MArray.h

Go to the documentation of this file.
00001 //# MArray.h: Class to handle an Array with an optional mask
00002 //# Copyright (C) 2012
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: MArray.h 21399 2013-11-12 07:55:35Z gervandiepen $
00027 
00028 #ifndef CASA_MARRAY_H
00029 #define CASA_MARRAY_H
00030 
00031 //# Includes
00032 #include <casacore/casa/aips.h>
00033 #include <casacore/tables/TaQL/MArrayBase.h>
00034 
00035 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00036 
00037   // <summary>
00038   // Class to handle an Array with an optional mask
00039   // </summary>
00040 
00041   // <use visibility=local>
00042 
00043   // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
00044   // </reviewed>
00045 
00046   // <prerequisite>
00047   //# Classes you should understand before using this one.
00048   //   <li> <linkto class=Array>Array</linkto>
00049   //   <li> <linkto class=MArrayBase>MArrayBase</linkto>
00050   // </prerequisite>
00051 
00052   // <synopsis> 
00053   // This class makes it easier to handle arrays with ot without mask.
00054   // The array is always present, but the mask is optional. The mask is
00055   // contained in the non-templated base class MArrayBase and functions
00056   // to operate on the mask are defined there.
00057   // <br> The class is primarily developed for TaQL masked arrays, but
00058   // could be used elsewhere as well.
00059   //
00060   // A mask value True means that the corresponding value is masked off, thus
00061   // not taken into account in reduction functions like <src>sum</src>. This
00062   // is the same as the numpy masked array.
00063   //
00064   // MArrayMath.h contains many functions to operate on MArray objects
00065   // (addition, sin, etc.).
00066   // </synopsis> 
00067 
00068   template <typename T>
00069   class MArray: public MArrayBase
00070   {
00071   public:
00072     // Default constructor creates a null array.
00073     MArray()
00074       : MArrayBase (True)
00075     {}
00076 
00077     // Construct from an array without a mask.
00078     // It references the given array.
00079     explicit MArray (const Array<T>& array)
00080       : MArrayBase (False),
00081         itsArray  (array)
00082     {
00083       resizeBase (array, False);
00084     }
00085 
00086     // Construct from an array and a mask.
00087     // It references the given arrays.
00088     // <src>isNull=True</src> requires the arrays to be empty.
00089     MArray (const Array<T>& array, const Array<Bool>& mask, Bool isNull=False)
00090       : MArrayBase (array, mask, isNull),
00091         itsArray   (array)
00092     {}
00093 
00094     // Construct from an array with the mask and null from another MArray.
00095     // It references the given arrays.
00096     // The shapes of both arrays must match.
00097     MArray (const Array<T>& array, const MArrayBase& marray)
00098       : MArrayBase (array, marray),
00099         itsArray   (array)
00100     {}
00101 
00102     // Construct from two MArrays, one the array, the other the mask.
00103     // If one of them is null, the constructed MArray is null.
00104     MArray (const MArray<T>& array, const MArray<Bool>& mask)
00105       : MArrayBase (array.isNull()  ||  mask.isNull())
00106     {
00107       if (! isNull()) {
00108         itsArray.reference (array.array());
00109         setBase (itsArray, mask.array());
00110       }
00111     }
00112 
00113     // Reference another array.
00114     void reference (const MArray<T>& other)
00115     {
00116       itsArray.reference (other.itsArray);
00117       referenceBase (other);
00118     }
00119 
00120     // Resize the array and optionally the mask.
00121     // It always sets the MArray to non-null.
00122     void resize (const IPosition& shape, Bool useMask)
00123     {
00124       itsArray.resize (shape);
00125       resizeBase (itsArray, useMask);
00126     }
00127 
00128     // Copy the array data and possible mask from another one.
00129     // The shapes do not need to match.
00130     // The array data is copied, but the new mask references the possible
00131     // mask in <src>from</src>.
00132     template <typename U>
00133     void fill (const MArray<U>& from)
00134     {
00135       itsArray.resize (from.shape());
00136       convertArray (itsArray, from.array());
00137       setBase (itsArray, from.mask());
00138     }
00139 
00140     // Copy the array from a normal Array. The possible mask is removed.
00141     // The shapes do not need to match.
00142     // The array data is always copied.
00143     template <typename U>
00144     void fill (const Array<U>& from)
00145     {
00146       itsArray.resize (from.shape());
00147       convertArray (itsArray, from);
00148       resizeBase (itsArray, False);
00149     }
00150 
00151     // Get access to the array.
00152     // <group>
00153     const Array<T>& array() const
00154       { return itsArray; }
00155     Array<T>& array()
00156       { return itsArray; }
00157     // </group>
00158 
00159     // Flatten the unmasked elements of the array to a vector.
00160     Vector<T> flatten() const;
00161     // Copy the unmasked elements to the out. The argument <src>size</src>
00162     // gives the size of the output buffer which should be at least the
00163     // size of the array. It returns the nr of unmasked elements.
00164     size_t flatten (T* out, size_t size) const;
00165 
00166     // Get a subset of the array.
00167     MArray<T> operator() (const IPosition& start, const IPosition& end,
00168                           const IPosition& stride)
00169     {
00170       if (hasMask()) {
00171         return MArray<T> (itsArray(start, end, stride),
00172                           mask()(start, end, stride));
00173       }
00174       return MArray<T> (itsArray(start, end, stride));
00175     }
00176 
00177   private:
00178     Array<T> itsArray;
00179   };
00180 
00181 
00182   //# Implement functions.
00183   template<typename T>
00184   Vector<T> MArray<T>::flatten() const
00185   {
00186     Vector<T> vec(nvalid());
00187     // We lie about the size, because we know the buffer has the right size.
00188     flatten (vec.data(), itsArray.size());
00189     return vec;
00190   }
00191 
00192   template<typename T>
00193   size_t MArray<T>::flatten (T* out, size_t size) const
00194   {
00195     if (size < itsArray.size()) {
00196       throw ArrayError ("MArray::flatten - size " + String::toString(size) +
00197                         " of output buffer is too small");
00198     }
00199     size_t nr = 0;
00200     if (!hasMask()) {
00201       // No mask, so copy all elements.
00202       Array<T> arr(itsArray.shape(), out, SHARE);
00203       arr = itsArray;
00204       nr  = arr.size();
00205     } else {
00206       // Copy only the valid elements.
00207       if (itsArray.contiguousStorage() && mask().contiguousStorage()) {
00208         typename Array<Bool>::const_contiter miter = mask().cbegin();
00209         typename Array<T>::const_contiter iterEnd = itsArray.cend();
00210         for (typename Array<T>::const_contiter iter=itsArray.cbegin();
00211              iter!=iterEnd; ++iter, ++miter) {
00212           if (!*miter) out[nr++] = *iter;
00213         }
00214       } else {
00215         typename Array<Bool>::const_iterator miter = mask().begin();
00216         typename Array<T>::const_iterator iterEnd = itsArray.end();
00217         for (typename Array<T>::const_iterator iter=itsArray.begin();
00218              iter!=iterEnd; ++iter, ++miter) {
00219           if (!*miter) out[nr++] = *iter;
00220         }
00221       }
00222     }
00223     return nr;
00224   }
00225 
00226 
00227 } //# NAMESPACE CASACORE - END
00228 
00229 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1