MArrayBase.h

Go to the documentation of this file.
00001 //# MArrayBase.h: Base class for 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: MArrayBase.h 21399 2013-11-12 07:55:35Z gervandiepen $
00027 
00028 #ifndef CASA_MARRAYBASE_H
00029 #define CASA_MARRAYBASE_H
00030 
00031 //# Includes
00032 #include <casacore/casa/aips.h>
00033 #include <casacore/casa/Arrays/Array.h>
00034 #include <casacore/casa/Arrays/ArrayLogical.h>
00035 
00036 //# Define the mask value indicating a valid value.
00037 //# In this way it is easy to change it to another value (if ever needed).
00038 //# The current setting is the same as used in numpy's masked_array and
00039 //# in the MeasurementSet's FLAG column.
00040 //# But the opposite value sounds somewhat better (same as MaskedArray)
00041 //# because something like DATA[isnan(DATA)] = 0 is much more intuitive.
00042 //#  #define MArrayValid False
00043 //#  #define MArrayInvalid True
00044 
00045 
00046 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00047 
00048   // <summary>
00049   // Base class for an array with an optional mask
00050   // </summary>
00051 
00052   // <use visibility=local>
00053 
00054   // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
00055   // </reviewed>
00056 
00057   // <prerequisite>
00058   //# Classes you should understand before using this one.
00059   //   <li> <linkto class=Array>Array</linkto>
00060   // </prerequisite>
00061 
00062   // <synopsis> 
00063   // This class is the base class of the templated class MArray. It contains
00064   // the functions that are not template dependent.
00065   //
00066   // MArray is developed to make it easier to handle arrays with an
00067   // optional mask. The array is always present, but the mask is optional.
00068   // MArrayMath contains functions to operate on such arrays.
00069   //
00070   // Similar to numpy.masked_array and the MeasurementSet FLAG definition,
00071   // a mask value True means that the corresponding value is masked off,
00072   // thus is not taken into account in reduction functions like <src>sum</src>.
00073   // on a masked array. In operations like addition, masked off values are
00074   // processed because testing the mask value is more expensive than an
00075   // addition (even if the value is a NaN). For an operation with multiple
00076   // operands, the mask of the result is the OR of the operand masks.
00077   //
00078   // MArray can be null meaning that the array is a null value. It can be
00079   // used to indicate that a table cell does not contain an array.
00080   // A null MArray has an empty array and mask. Operations where an operand
00081   // is a null MArray, result in a null MArray.
00082   // </synopsis> 
00083 
00084   class MArrayBase
00085   {
00086   protected:
00087     // The default constructor creates an empty mask.
00088     explicit MArrayBase (Bool isNull)
00089       : itsSize   (0),
00090         itsNValid (0),
00091         itsNull   (isNull)
00092     {}
00093 
00094     // Construct from a given array shape and mask.
00095     MArrayBase (const ArrayBase& arr, const Array<Bool>& mask, Bool isNull);
00096 
00097     // Construct from a given array shape and mask from another MArray.
00098     MArrayBase (const ArrayBase& arr, const MArrayBase& marray);
00099 
00100     // Reference the mask and set the shape.
00101     void setBase (const ArrayBase& arr, const Array<Bool>& mask);
00102 
00103     // Reference another MArray.
00104     void referenceBase (const MArrayBase& other);
00105 
00106     // Set the array shape and resize the mask.
00107     void resizeBase (const ArrayBase& arr, Bool useMask);
00108 
00109   public:
00110     // Is the array null?
00111     Bool isNull() const
00112       { return itsNull; }
00113 
00114     // Remove the mask.
00115     void removeMask()
00116       { itsMask.resize(); itsNValid = itsSize; }
00117 
00118     // Is there a mask?
00119     Bool hasMask() const
00120       { return !itsMask.empty(); }
00121 
00122     // Set the mask. It checks if it matches the array shape.
00123     void setMask (const Array<Bool>& mask);
00124 
00125     // Get the mask. The returned array is empty if there is no mask.
00126     const Array<Bool>& mask() const
00127       { return itsMask; }
00128     Array<Bool>& wmask()
00129       { return itsMask; }
00130 
00131     // Return the number of valid array values, thus unflagged elements.
00132     Int64 nvalid() const
00133     {
00134       if (itsNValid < 0) fillNValid();
00135       return itsNValid;
00136     }
00137 
00138     // Is the array empty?
00139     Bool empty() const
00140       { return itsSize == 0; }
00141 
00142     // Get the dimensionality.
00143     uInt ndim() const
00144       { return itsShape.size(); }
00145 
00146     // Get the shape.
00147     const IPosition& shape() const
00148       { return itsShape; }
00149 
00150     // Get the size.
00151     // <group>
00152     size_t size() const
00153       { return itsSize; }
00154     size_t nelements() const
00155       { return itsSize; }
00156     // </group>
00157 
00158     // Combine this and the other mask.
00159     // One or both MArray-s can be unmasked.
00160     Array<Bool> combineMask (const MArrayBase& other) const;
00161 
00162   private:
00163     // Initialize and check.
00164     void init();
00165 
00166     // Fill the number of valid values.
00167     void fillNValid() const;
00168 
00169     //# Data members.
00170     Array<Bool>   itsMask;
00171     IPosition     itsShape;
00172     size_t        itsSize;
00173     mutable Int64 itsNValid;
00174     Bool          itsNull;   // True = array is null, thus undefined in a column
00175   };
00176 
00177 } //# NAMESPACE CASACORE - END
00178 
00179 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1