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