casacore
MArrayBase.h
Go to the documentation of this file.
1 //# MArrayBase.h: Base class for an array with an optional mask
2 //# Copyright (C) 2012
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id: MArrayBase.h 21399 2013-11-12 07:55:35Z gervandiepen $
27 
28 #ifndef CASA_MARRAYBASE_H
29 #define CASA_MARRAYBASE_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/Array.h>
34 #include <casacore/casa/Arrays/ArrayLogical.h>
35 
36 //# Define the mask value indicating a valid value.
37 //# In this way it is easy to change it to another value (if ever needed).
38 //# The current setting is the same as used in numpy's masked_array and
39 //# in the MeasurementSet's FLAG column.
40 //# But the opposite value sounds somewhat better (same as MaskedArray)
41 //# because something like DATA[isnan(DATA)] = 0 is much more intuitive.
42 //# #define MArrayValid False
43 //# #define MArrayInvalid True
44 
45 
46 namespace casacore { //# NAMESPACE CASACORE - BEGIN
47 
48  // <summary>
49  // Base class for an array with an optional mask
50  // </summary>
51 
52  // <use visibility=local>
53 
54  // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
55  // </reviewed>
56 
57  // <prerequisite>
58  //# Classes you should understand before using this one.
59  // <li> <linkto class=Array>Array</linkto>
60  // </prerequisite>
61 
62  // <synopsis>
63  // This class is the base class of the templated class MArray. It contains
64  // the functions that are not template dependent.
65  //
66  // MArray is developed to make it easier to handle arrays with an
67  // optional mask. The array is always present, but the mask is optional.
68  // MArrayMath contains functions to operate on such arrays.
69  //
70  // Similar to numpy.masked_array and the MeasurementSet FLAG definition,
71  // a mask value True means that the corresponding value is masked off,
72  // thus is not taken into account in reduction functions like <src>sum</src>.
73  // on a masked array. In operations like addition, masked off values are
74  // processed because testing the mask value is more expensive than an
75  // addition (even if the value is a NaN). For an operation with multiple
76  // operands, the mask of the result is the OR of the operand masks.
77  //
78  // MArray can be null meaning that the array is a null value. It can be
79  // used to indicate that a table cell does not contain an array.
80  // A null MArray has an empty array and mask. Operations where an operand
81  // is a null MArray, result in a null MArray.
82  // </synopsis>
83 
84  class MArrayBase
85  {
86  protected:
87  // The default constructor creates an empty mask.
88  explicit MArrayBase (Bool isNull)
89  : itsSize (0),
90  itsNValid (0),
91  itsNull (isNull)
92  {}
93 
94  // Construct from a given array shape and mask.
96 
97  // Construct from a given array shape and mask from another MArray.
98  MArrayBase (const ArrayBase& arr, const MArrayBase& marray);
99 
100  // Reference the mask and set the shape.
101  void setBase (const ArrayBase& arr, const Array<Bool>& mask);
102 
103  // Reference another MArray.
104  void referenceBase (const MArrayBase& other);
105 
106  // Set the array shape and resize the mask.
107  void resizeBase (const ArrayBase& arr, Bool useMask);
108 
109  public:
110  // Is the array null?
111  Bool isNull() const
112  { return itsNull; }
113 
114  // Remove the mask.
115  void removeMask()
116  { itsMask.resize(); itsNValid = itsSize; }
117 
118  // Is there a mask?
119  Bool hasMask() const
120  { return !itsMask.empty(); }
121 
122  // Set the mask. It checks if it matches the array shape.
123  void setMask (const Array<Bool>& mask);
124 
125  // Get the mask. The returned array is empty if there is no mask.
126  const Array<Bool>& mask() const
127  { return itsMask; }
129  { return itsMask; }
130 
131  // Return the number of valid array values, thus unflagged elements.
132  Int64 nvalid() const
133  {
134  if (itsNValid < 0) fillNValid();
135  return itsNValid;
136  }
137 
138  // Is the array empty?
139  Bool empty() const
140  { return itsSize == 0; }
141 
142  // Get the dimensionality.
143  uInt ndim() const
144  { return itsShape.size(); }
145 
146  // Get the shape.
147  const IPosition& shape() const
148  { return itsShape; }
149 
150  // Get the size.
151  // <group>
152  size_t size() const
153  { return itsSize; }
154  size_t nelements() const
155  { return itsSize; }
156  // </group>
157 
158  // Combine this and the other mask.
159  // One or both MArray-s can be unmasked.
160  Array<Bool> combineMask (const MArrayBase& other) const;
161 
162  private:
163  // Initialize and check.
164  void init();
165 
166  // Fill the number of valid values.
167  void fillNValid() const;
168 
169  //# Data members.
172  size_t itsSize;
173  mutable Int64 itsNValid;
174  Bool itsNull; // True = array is null, thus undefined in a column
175  };
176 
177 } //# NAMESPACE CASACORE - END
178 
179 #endif
Non-templated base class for templated Array class.
Definition: ArrayBase.h:73
bool empty() const
Is the array empty (i.e.
Definition: ArrayBase.h:110
void resize()
Make this array a different shape.
size_t size() const
Definition: IPosition.h:572
MArrayBase(Bool isNull)
The default constructor creates an empty mask.
Definition: MArrayBase.h:88
Int64 nvalid() const
Return the number of valid array values, thus unflagged elements.
Definition: MArrayBase.h:132
Bool empty() const
Is the array empty?
Definition: MArrayBase.h:139
Array< Bool > combineMask(const MArrayBase &other) const
Combine this and the other mask.
void setBase(const ArrayBase &arr, const Array< Bool > &mask)
Reference the mask and set the shape.
size_t nelements() const
Definition: MArrayBase.h:154
Bool isNull() const
Is the array null?
Definition: MArrayBase.h:111
MArrayBase(const ArrayBase &arr, const Array< Bool > &mask, Bool isNull)
Construct from a given array shape and mask.
void init()
Initialize and check.
void setMask(const Array< Bool > &mask)
Set the mask.
uInt ndim() const
Get the dimensionality.
Definition: MArrayBase.h:143
Array< Bool > & wmask()
Definition: MArrayBase.h:128
void resizeBase(const ArrayBase &arr, Bool useMask)
Set the array shape and resize the mask.
MArrayBase(const ArrayBase &arr, const MArrayBase &marray)
Construct from a given array shape and mask from another MArray.
Array< Bool > itsMask
Definition: MArrayBase.h:170
const IPosition & shape() const
Get the shape.
Definition: MArrayBase.h:147
void fillNValid() const
Fill the number of valid values.
size_t size() const
Get the size.
Definition: MArrayBase.h:152
const Array< Bool > & mask() const
Get the mask.
Definition: MArrayBase.h:126
void referenceBase(const MArrayBase &other)
Reference another MArray.
void removeMask()
Remove the mask.
Definition: MArrayBase.h:115
Bool hasMask() const
Is there a mask?
Definition: MArrayBase.h:119
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
TableExprNode marray(const TableExprNode &array, const TableExprNode &mask)
Form a masked array.
Definition: ExprNode.h:1935