casacore
MArray.h
Go to the documentation of this file.
1 //# MArray.h: Class to handle 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: MArray.h 21399 2013-11-12 07:55:35Z gervandiepen $
27 
28 #ifndef CASA_MARRAY_H
29 #define CASA_MARRAY_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/TaQL/MArrayBase.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37  // <summary>
38  // Class to handle an Array with an optional mask
39  // </summary>
40 
41  // <use visibility=local>
42 
43  // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
44  // </reviewed>
45 
46  // <prerequisite>
47  //# Classes you should understand before using this one.
48  // <li> <linkto class=Array>Array</linkto>
49  // <li> <linkto class=MArrayBase>MArrayBase</linkto>
50  // </prerequisite>
51 
52  // <synopsis>
53  // This class makes it easier to handle arrays with ot without mask.
54  // The array is always present, but the mask is optional. The mask is
55  // contained in the non-templated base class MArrayBase and functions
56  // to operate on the mask are defined there.
57  // <br> The class is primarily developed for TaQL masked arrays, but
58  // could be used elsewhere as well.
59  //
60  // A mask value True means that the corresponding value is masked off, thus
61  // not taken into account in reduction functions like <src>sum</src>. This
62  // is the same as the numpy masked array.
63  //
64  // MArrayMath.h contains many functions to operate on MArray objects
65  // (addition, sin, etc.).
66  // </synopsis>
67 
68  template <typename T>
69  class MArray: public MArrayBase
70  {
71  public:
72  // Default constructor creates a null array.
74  : MArrayBase (True)
75  {}
76 
77  // Construct from an array without a mask.
78  // It references the given array.
79  explicit MArray (const Array<T>& array)
80  : MArrayBase (False),
81  itsArray (array)
82  {
84  }
85 
86  // Construct from an array and a mask.
87  // It references the given arrays.
88  // <src>isNull=True</src> requires the arrays to be empty.
91  itsArray (array)
92  {}
93 
94  // Construct from an array with the mask and null from another MArray.
95  // It references the given arrays.
96  // The shapes of both arrays must match.
98  : MArrayBase (array, marray),
99  itsArray (array)
100  {}
101 
102  // Construct from two MArrays, one the array, the other the mask.
103  // If one of them is null, the constructed MArray is null.
105  : MArrayBase (array.isNull() || mask.isNull())
106  {
107  if (! isNull()) {
108  itsArray.reference (array.array());
109  setBase (itsArray, mask.array());
110  }
111  }
112 
113  // Reference another array.
114  void reference (const MArray<T>& other)
115  {
116  itsArray.reference (other.itsArray);
117  referenceBase (other);
118  }
119 
120  // Resize the array and optionally the mask.
121  // It always sets the MArray to non-null.
122  void resize (const IPosition& shape, Bool useMask)
123  {
125  resizeBase (itsArray, useMask);
126  }
127 
128  // Copy the array data and possible mask from another one.
129  // The shapes do not need to match.
130  // The array data is copied, but the new mask references the possible
131  // mask in <src>from</src>.
132  template <typename U>
133  void fill (const MArray<U>& from)
134  {
135  itsArray.resize (from.shape());
136  convertArray (itsArray, from.array());
137  setBase (itsArray, from.mask());
138  }
139 
140  // Copy the array from a normal Array. The possible mask is removed.
141  // The shapes do not need to match.
142  // The array data is always copied.
143  template <typename U>
144  void fill (const Array<U>& from)
145  {
146  itsArray.resize (from.shape());
147  convertArray (itsArray, from);
149  }
150 
151  // Get access to the array.
152  // <group>
153  const Array<T>& array() const
154  { return itsArray; }
156  { return itsArray; }
157  // </group>
158 
159  // Flatten the unmasked elements of the array to a vector.
161  // Copy the unmasked elements to the out. The argument <src>size</src>
162  // gives the size of the output buffer which should be at least the
163  // size of the array. It returns the nr of unmasked elements.
164  size_t flatten (T* out, size_t size) const;
165 
166  // Get a subset of the array.
167  MArray<T> operator() (const IPosition& start, const IPosition& end,
168  const IPosition& stride)
169  {
170  if (hasMask()) {
171  return MArray<T> (itsArray(start, end, stride),
172  mask()(start, end, stride));
173  }
174  return MArray<T> (itsArray(start, end, stride));
175  }
176 
177  private:
179  };
180 
181 
182  //# Implement functions.
183  template<typename T>
185  {
186  Vector<T> vec(nvalid());
187  // We lie about the size, because we know the buffer has the right size.
188  flatten (vec.data(), itsArray.size());
189  return vec;
190  }
191 
192  template<typename T>
193  size_t MArray<T>::flatten (T* out, size_t size) const
194  {
195  if (size < itsArray.size()) {
196  throw ArrayError ("MArray::flatten - size " + std::to_string(size) +
197  " of output buffer is too small");
198  }
199  size_t nr = 0;
200  if (!hasMask()) {
201  // No mask, so copy all elements.
202  Array<T> arr(itsArray.shape(), out, SHARE);
203  arr = itsArray;
204  nr = arr.size();
205  } else {
206  // Copy only the valid elements.
207  if (itsArray.contiguousStorage() && mask().contiguousStorage()) {
208  typename Array<Bool>::const_contiter miter = mask().cbegin();
209  typename Array<T>::const_contiter iterEnd = itsArray.cend();
210  for (typename Array<T>::const_contiter iter=itsArray.cbegin();
211  iter!=iterEnd; ++iter, ++miter) {
212  if (!*miter) out[nr++] = *iter;
213  }
214  } else {
215  typename Array<Bool>::const_iterator miter = mask().begin();
216  typename Array<T>::const_iterator iterEnd = itsArray.end();
217  for (typename Array<T>::const_iterator iter=itsArray.begin();
218  iter!=iterEnd; ++iter, ++miter) {
219  if (!*miter) out[nr++] = *iter;
220  }
221  }
222  }
223  return nr;
224  }
225 
226 
227 } //# NAMESPACE CASACORE - END
228 
229 #endif
const IPosition & shape() const
The length of each axis.
Definition: ArrayBase.h:125
size_t size() const
Definition: ArrayBase.h:105
virtual void reference(const Array< T, Alloc > &other)
After invocation, this array and other reference the same storage.
void resize()
Make this array a different shape.
contiter cbegin()
Get the begin iterator object for a contiguous array.
Definition: Array.h:871
contiter cend()
Definition: Array.h:875
iterator begin()
Get the begin iterator object for any array.
Definition: Array.h:859
T * data()
Get a pointer to the beginning of the array.
Definition: Array.h:604
iterator end()
Definition: Array.h:863
void setBase(const ArrayBase &arr, const Array< Bool > &mask)
Reference the mask and set the shape.
Bool isNull() const
Is the array null?
Definition: MArrayBase.h:111
void resizeBase(const ArrayBase &arr, Bool useMask)
Set the array shape and resize the mask.
const IPosition & shape() const
Get the shape.
Definition: MArrayBase.h:147
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.
Bool hasMask() const
Is there a mask?
Definition: MArrayBase.h:119
MArray(const MArray< T > &array, const MArray< Bool > &mask)
Construct from two MArrays, one the array, the other the mask.
Definition: MArray.h:104
Vector< T > flatten() const
Flatten the unmasked elements of the array to a vector.
Definition: MArray.h:184
MArray(const Array< T > &array, const MArrayBase &marray)
Construct from an array with the mask and null from another MArray.
Definition: MArray.h:97
void reference(const MArray< T > &other)
Reference another array.
Definition: MArray.h:114
size_t flatten(T *out, size_t size) const
Copy the unmasked elements to the out.
Definition: MArray.h:193
void fill(const Array< U > &from)
Copy the array from a normal Array.
Definition: MArray.h:144
void fill(const MArray< U > &from)
Copy the array data and possible mask from another one.
Definition: MArray.h:133
Array< T > itsArray
Definition: MArray.h:178
MArray(const Array< T > &array)
Construct from an array without a mask.
Definition: MArray.h:79
void resize(const IPosition &shape, Bool useMask)
Resize the array and optionally the mask.
Definition: MArray.h:122
Array< T > & array()
Definition: MArray.h:155
MArray()
Default constructor creates a null array.
Definition: MArray.h:73
const Array< T > & array() const
Get access to the array.
Definition: MArray.h:153
MArray< T > operator()(const IPosition &start, const IPosition &end, const IPosition &stride)
Get a subset of the array.
Definition: MArray.h:167
MArray(const Array< T > &array, const Array< Bool > &mask, Bool isNull=False)
Construct from an array and a mask.
Definition: MArray.h:89
@ SHARE
Share means that the Array will just use the pointer (no copy), however the Array will NOT delete it ...
Definition: ArrayBase.h:62
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
std::string to_string(const IPosition &ip)
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
const Bool True
Definition: aipstype.h:43