casacore
ScaledArrayEngine.h
Go to the documentation of this file.
1 //# ScaledArrayEngine.h: Templated virtual column engine to scale a table array
2 //# Copyright (C) 1994,1995,1996,1999,2001
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$
27 
28 #ifndef TABLES_SCALEDARRAYENGINE_H
29 #define TABLES_SCALEDARRAYENGINE_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/DataMan/BaseMappedArrayEngine.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 //# Forward Declarations
38 template<class T> class ScalarColumn;
39 
40 
41 
42 // <summary>
43 // Templated virtual column engine to scale a table array
44 // </summary>
45 
46 // <use visibility=export>
47 
48 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
49 // </reviewed>
50 
51 // <prerequisite>
52 //# Classes you should understand before using this one.
53 // <li> VirtualColumnEngine
54 // <li> VirtualArrayColumn
55 // </prerequisite>
56 
57 // <synopsis>
58 // ScaledArrayEngine is a virtual column engine which scales an array
59 // of one type to another type to save disk storage.
60 // This resembles the classic AIPS compress method which scales the
61 // data from float to short.
62 // The scale factor and offset value can be given in two ways:
63 // <ul>
64 // <li> As a fixed value which is used for all arrays in the column.
65 // <li> As the name of a column. In this way each array in a
66 // column can have its own scale and offset value.
67 // The scale and offset value in a row must be put before
68 // the array is put and should not be changed anymore.
69 // </ul>
70 // It is also possible to have a variable scale factor with a fixed offset
71 // value.
72 // As in FITS the scale and offset values are used as:
73 // <br><src> True_value = Stored_value * scale + offset; </src>
74 //
75 // An engine object should be used for one column only, because the stored
76 // column name is part of the engine. If it would be used for more than
77 // one column, they would all share the same stored column.
78 // When the engine is bound to a column, it is checked if the name
79 // of that column matches the given virtual column name.
80 //
81 // The engine can be used for a column containing any kind of array
82 // (thus direct or indirect, fixed or variable shaped)) as long as the
83 // virtual array can be stored in the stored array. Thus a fixed shaped
84 // virtual can use a variable shaped stored, but not vice versa.
85 // A fixed shape indirect virtual can use a stored with direct arrays.
86 //
87 // This class can also serve as an example of how to implement
88 // a virtual column engine.
89 // </synopsis>
90 
91 // <motivation>
92 // This class allows to store data in a smaller representation.
93 // It is needed to resemble the classic AIPS compress option.
94 // It adds the scale and offset value on a per row basis.
95 //
96 // Because the engine can serve only one column, it was possible to
97 // combine the engine and the column functionality in one class.
98 // This has been achieved using multiple inheritance.
99 // The advantage of this is that only one templated class is used,
100 // so less template instantiations are needed.
101 // </motivation>
102 
103 // <example>
104 // <srcblock>
105 // // Create the table description and 2 columns with indirect arrays in it.
106 // // The Int column will be stored, while the double will be
107 // // used as virtual.
108 // TableDesc tableDesc ("", TableDesc::Scratch);
109 // tableDesc.addColumn (ArrayColumnDesc<Int> ("storedArray"));
110 // tableDesc.addColumn (ArrayColumnDesc<double> ("virtualArray"));
111 //
112 // // Create a new table using the table description.
113 // SetupNewTable newtab (tableDesc, "tab.data", Table::New);
114 //
115 // // Create the array scaling engine to scale from double to Int
116 // // and bind it to the double column.
117 // // Create the table.
118 // ScaledArrayEngine<double,Int> scalingEngine("virtualArray",
119 // "storedArray", 10);
120 // newtab.bindColumn ("virtualArray", scalingEngine);
121 // Table table (newtab);
122 //
123 // // Store a 3-D array (with dim. 2,3,4) into each row of the column.
124 // // The shape of each array in the column is implicitly set by the put
125 // // function. This will also set the shape of the underlying Int array.
126 // ArrayColumn data (table, "virtualArray");
127 // Array<double> someArray(IPosition(4,2,3,4));
128 // someArray = 0;
129 // for (rownr_t i=0, i<10; i++) { // table will have 10 rows
130 // table.addRow();
131 // data.put (i, someArray)
132 // }
133 // </srcblock>
134 // </example>
135 
136 // <templating arg=VirtualType>
137 // <li> only suited for built-in numerics data types
138 // </templating>
139 // <templating arg=StoredType>
140 // <li> only suited for built-in numerics data types
141 // </templating>
142 
143 template<class VirtualType, class StoredType> class ScaledArrayEngine : public BaseMappedArrayEngine<VirtualType, StoredType>
144 {
145  //# Make members of parent class known.
146 public:
148 protected:
153 
154 public:
155  // Construct an engine to scale all arrays in a column with
156  // the given offset and scale factor.
157  // StoredColumnName is the name of the column where the scaled
158  // data will be put and must have data type StoredType.
159  // The virtual column using this engine must have data type VirtualType.
160  ScaledArrayEngine (const String& virtualColumnName,
161  const String& storedColumnName,
162  VirtualType scale,
163  VirtualType offset = 0);
164 
165  // Construct an engine to scale the arrays in a column.
166  // The scale and offset values are taken from a column with
167  // the given names. In that way each array has its own scale factor
168  // and offset value.
169  // An exception is thrown if these columns do not exist.
170  // VirtualColumnName is the name of the virtual column and is used to
171  // check if the engine gets bound to the correct column.
172  // StoredColumnName is the name of the column where the scaled
173  // data will be put and must have data type StoredType.
174  // The virtual column using this engine must have data type VirtualType.
175  // <group>
176  ScaledArrayEngine (const String& virtualColumnName,
177  const String& storedColumnName,
178  const String& scaleColumnName,
179  VirtualType offset = 0);
180  ScaledArrayEngine (const String& virtualColumnName,
181  const String& storedColumnName,
182  const String& scaleColumnName,
183  const String& offsetColumnName);
184  // </group>
185 
186  // Construct from a record specification as created by getmanagerSpec().
187  ScaledArrayEngine (const Record& spec);
188 
189  // Destructor is mandatory.
191 
192  // Return the type name of the engine (i.e. its class name).
193  virtual String dataManagerType() const;
194 
195  // Get the name given to the engine (is the virtual column name).
196  virtual String dataManagerName() const;
197 
198  // Record a record containing data manager specifications.
199  virtual Record dataManagerSpec() const;
200 
201  // Return the name of the class.
202  // This includes the names of the template arguments.
203  static String className();
204 
205  // Register the class name and the static makeObject "constructor".
206  // This will make the engine known to the table system.
207  // The automatically invoked registration function in DataManReg.cc
208  // contains ScaledArrayEngine<double,Int>.
209  // Any other instantiation of this class must be registered "manually"
210  // (or added to DataManReg.cc).
211  static void registerClass();
212 
213 private:
214  // Copy constructor is only used by clone().
215  // (so it is made private).
217 
218  // Assignment is not needed and therefore forbidden
219  // (so it is made private and not implemented).
222 
223  // Clone the engine object.
224  DataManager* clone() const;
225 
226  // Initialize the object for a new table.
227  // It defines the keywords containing the engine parameters.
228  void create64 (rownr_t initialNrrow);
229 
230  // Preparing consists of setting the writable switch and
231  // adding the initial number of rows in case of create.
232  // Furthermore it reads the keywords containing the engine parameters.
233  void prepare();
234 
235  // Get an array in the given row.
236  // This will scale and offset from the underlying array.
238 
239  // Put an array in the given row.
240  // This will scale and offset to the underlying array.
241  void putArray (rownr_t rownr, const Array<VirtualType>& array);
242 
243  // Get a section of the array in the given row.
244  // This will scale and offset from the underlying array.
245  void getSlice (rownr_t rownr, const Slicer& slicer, Array<VirtualType>& array);
246 
247  // Put into a section of the array in the given row.
248  // This will scale and offset to the underlying array.
249  void putSlice (rownr_t rownr, const Slicer& slicer,
250  const Array<VirtualType>& array);
251 
252  // Get an entire column.
253  // This will scale and offset from the underlying array.
255 
256  // Put an entire column.
257  // This will scale and offset to the underlying array.
259 
260  // Get a section of all arrays in the column.
261  // This will scale and offset from the underlying array.
263 
264  // Put a section of all arrays in the column.
265  // This will scale and offset to the underlying array.
266  void putColumnSlice (const Slicer& slicer, const Array<VirtualType>& array);
267 
268  // Scale and/or offset stored to array.
269  // This is meant when reading an array from the stored column.
270  // It optimizes for scale=1 and/or offset=0.
271  void scaleOnGet (VirtualType scale, VirtualType offset,
273  const Array<StoredType>& stored);
274 
275  // Scale and/or offset array to stored.
276  // This is meant when writing an array into the stored column.
277  // It optimizes for scale=1 and/or offset=0.
278  void scaleOnPut (VirtualType scale, VirtualType offset,
279  const Array<VirtualType>& array,
280  Array<StoredType>& stored);
281 
282  // Scale and/or offset stored to array for the entire column.
283  // When the scale and offset are fixed, it will do the entire array.
284  // Otherwise it iterates through the array and applies the scale
285  // and offset per row.
287  const Array<StoredType>& stored);
288 
289  // Scale and/or offset array to stored for the entire column.
290  // When the scale and offset are fixed, it will do the entire array.
291  // Otherwise it iterates through the array and applies the scale
292  // and offset per row.
294  Array<StoredType>& stored);
295 
296 
297  //# Now define the data members.
298  String scaleName_p; //# name of scale column
299  String offsetName_p; //# name of offset column
300  VirtualType scale_p; //# scale factor
301  VirtualType offset_p; //# offset value
302  Bool fixedScale_p; //# scale is a fixed column
303  Bool fixedOffset_p; //# scale is a fixed column
304  ScalarColumn<VirtualType>* scaleColumn_p; //# column with scale value
305  ScalarColumn<VirtualType>* offsetColumn_p; //# column with offset value
306 
307  // Get the scale value for this row.
308  VirtualType getScale (rownr_t rownr);
309 
310  // Get the offset value for this row.
311  VirtualType getOffset (rownr_t rownr);
312 
313 public:
314  //*display 4
315  // Define the "constructor" to construct this engine when a
316  // table is read back.
317  // This "constructor" has to be registered by the user of the engine.
318  // If the engine is commonly used, its registration can be added
319  // to the registerAllCtor function in DataManReg.cc.
320  // That function gets automatically invoked by the table system.
322  const Record& spec);
323 };
324 
325 
326 
327 } //# NAMESPACE CASACORE - END
328 
329 #ifndef CASACORE_NO_AUTO_TEMPLATES
330 #include <casacore/tables/DataMan/ScaledArrayEngine.tcc>
331 #endif //# CASACORE_NO_AUTO_TEMPLATES
332 #endif
Abstract base class for a data manager.
Definition: DataManager.h:221
static String className()
Return the name of the class.
void getArray(rownr_t rownr, Array< VirtualType > &array)
Get an array in the given row.
virtual String dataManagerName() const
Get the name given to the engine (is the virtual column name).
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
VirtualType getOffset(rownr_t rownr)
Get the offset value for this row.
virtual Record dataManagerSpec() const
Record a record containing data manager specifications.
DataManager * clone() const
Clone the engine object.
void putArrayColumn(const Array< VirtualType > &array)
Put an entire column.
void scaleOnPut(VirtualType scale, VirtualType offset, const Array< VirtualType > &array, Array< StoredType > &stored)
Scale and/or offset array to stored.
ScaledArrayEngine(const ScaledArrayEngine< VirtualType, StoredType > &)
Copy constructor is only used by clone().
void putColumnSlice(const Slicer &slicer, const Array< VirtualType > &array)
Put a section of all arrays in the column.
ScaledArrayEngine(const String &virtualColumnName, const String &storedColumnName, VirtualType scale, VirtualType offset=0)
Construct an engine to scale all arrays in a column with the given offset and scale factor.
void scaleColumnOnGet(Array< VirtualType > &array, const Array< StoredType > &stored)
Scale and/or offset stored to array for the entire column.
void scaleColumnOnPut(const Array< VirtualType > &array, Array< StoredType > &stored)
Scale and/or offset array to stored for the entire column.
void scaleOnGet(VirtualType scale, VirtualType offset, Array< VirtualType > &array, const Array< StoredType > &stored)
Scale and/or offset stored to array.
void getColumnSlice(const Slicer &slicer, Array< VirtualType > &array)
Get a section of all arrays in the column.
ScaledArrayEngine(const Record &spec)
Construct from a record specification as created by getmanagerSpec().
VirtualType getScale(rownr_t rownr)
Get the scale value for this row.
void putSlice(rownr_t rownr, const Slicer &slicer, const Array< VirtualType > &array)
Put into a section of the array in the given row.
virtual String dataManagerType() const
Return the type name of the engine (i.e.
~ScaledArrayEngine()
Destructor is mandatory.
static void registerClass()
Register the class name and the static makeObject "constructor".
void getArrayColumn(Array< VirtualType > &array)
Get an entire column.
ScaledArrayEngine(const String &virtualColumnName, const String &storedColumnName, const String &scaleColumnName, VirtualType offset=0)
Construct an engine to scale the arrays in a column.
ScaledArrayEngine(const String &virtualColumnName, const String &storedColumnName, const String &scaleColumnName, const String &offsetColumnName)
ScalarColumn< VirtualType > * offsetColumn_p
void create64(rownr_t initialNrrow)
Initialize the object for a new table.
void prepare()
Preparing consists of setting the writable switch and adding the initial number of rows in case of cr...
void getSlice(rownr_t rownr, const Slicer &slicer, Array< VirtualType > &array)
Get a section of the array in the given row.
ScalarColumn< VirtualType > * scaleColumn_p
void putArray(rownr_t rownr, const Array< VirtualType > &array)
Put an array in the given row.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition: ExprNode.h:1929
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46