casacore
Loading...
Searching...
No Matches
MSTable.h
Go to the documentation of this file.
1//# MSTable.h: A Table to hold astronomical data (a set of Measurements)
2//# Copyright (C) 1996,1997,2000,2001,2002
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//#
27//# $Id: MSTable.h 21451 2014-06-10 07:48:08Z gervandiepen $
28
29#ifndef MS_MSTABLE_H
30#define MS_MSTABLE_H
31
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Utilities/DataType.h>
34#include <casacore/tables/Tables/Table.h>
35#include <casacore/casa/Utilities/CountedPtr.h>
36#include <casacore/casa/BasicSL/String.h>
37#include <casacore/tables/Tables/ColumnDesc.h>
38#include <map>
39
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42//# Forward Declarations, more could be if they weren't part of the
43//# static classes
44class TableRecord;
45template <class T> class Block;
46
47
48// <summary>
49// A struct holding the maps used in MSTable.
50// </summary>
52{
53 // ColEnum -> name
54 std::map<Int, String> columnMap_p;
55 // ColEnum -> DataType
56 std::map<Int, Int> colDTypeMap_p;
57 // ColEnum -> comment string
58 std::map<Int, String> colCommentMap_p;
59 // ColEnum -> UNIT string
60 std::map<Int, String> colUnitMap_p;
61 // ColEnum -> MEASURE_TYPE string
62 std::map<Int, String> colMeasureTypeMap_p;
63 // KeyEnum -> name
64 std::map<Int, String> keywordMap_p;
65 // KeyEnum -> DataType
66 std::map<Int, Int> keyDTypeMap_p;
67 // KeyEnum -> comment string
68 std::map<Int, String> keyCommentMap_p;
69 // The required TableDesc
71
72 // Convert a name to a ColEnum or KeyEnum.
73 Int columnType (const String& name) const
74 { return mapType (columnMap_p, name); }
75 Int keywordType (const String& name) const
76 { return mapType (keywordMap_p, name); }
77 Int mapType (const std::map<Int,String>&, const String& name) const;
78};
79
80
81// <summary>
82// A Table intended to hold astronomical data
83// </summary>
84
85// <use visibility=export>
86
87// <reviewed reviewer="Bob Garwood" date="1997/02/01" tests="" demos="">
88
89// <prerequisite>
90// <li> <linkto module="Tables:description">Tables</linkto> module
91// </prerequisite>
92//
93// <etymology>
94// The MSTable is the base class for all MeasurementSet Tables, hence the
95// name.
96// </etymology>
97//
98// <synopsis>
99// A MSTable is a Table. Most operations on a MSTable are
100// Table operations. See the <linkto module="Tables:description">Tables</linkto>
101// module for a list of those operations. The member functions provided by this
102// class are primarily convenience functions to help users follow the
103// agreed upon column and keyword naming conventions. They are useful when
104// creating a Table following the MSTable conventions from
105// scratch as well as when creating the column objects to access those
106// columns. All actual MeasurementSet Tables will be derived from this class.
107//
108// The standard way of accessing
109// table columns is through Strings. Mistakes in typing the column
110// name will not be caught at compile time (and may not be caught at
111// run time). We have therefore decided to use an enumeration
112// to specify columns so that many mistakes will be caught at compile
113// time. This requires functions to map to and from this enumeration
114// to the strings that are ultimately used.
115//
116// Upon destruction, the table is checked to see that all
117// required columns and keywords are still present.
118// If not an exception is thrown. (Not a good idea!) Nevertheless,
119// the table will be flushed to disk if it is writable -
120// preserving its state.
121//
122// </synopsis>
123//
124// <example>
125// For examples of use, see the MeasurementSet class.
126// </example>
127//
128// <motivation>
129// The Table module is more than adequate as a container of data.
130// However, in order for applications to be useful with data from
131// different sources, some conventions need to be adopted in the use
132// of Tables to store data. The MSTable provides the framework for
133// these conventions and conversion functions. The actual definitions
134// of columns and keywords are found in the derived classes and their
135// "enum" base class (e.g. MSAntenna and MSAntennaEnums).
136// </motivation>
137//
138// <todo asof="1996/2/22">
139// <li> referenceCopy() should be more flexible with the storage managers used
140// for the columns which are not merely references.
141// <li> When ForwardColumnEngine is fixed so that it can deal with
142// tables already in the cache, modify the test program. It may also
143// be necessary to modify referenceCopy().
144// </todo>
145
146template <class MSEnum> class MSTable : public Table
147{
148public:
149 // Define the column and keyword enuym types.
150 typedef typename MSEnum::PredefinedColumns ColEnum;
151 typedef typename MSEnum::PredefinedKeywords KeyEnum;
152
153 // ColEnum convenience functions
154 // <group name=columns>
155 // check to see if a column exists
156 Bool isColumn(ColEnum which) const;
158 // check to see if a column is writable
159 // <group>
163 Bool isColumnWritable (uInt columnIndex) const
164 { return Table::isColumnWritable(columnIndex); }
165 // </group>
166
167 // Information about scalar vs array of a column
168 // <group>
169 Bool isScalar(ColEnum which) const;
170 Bool isArray(ColEnum which) const;
171 // </group>
172
173 // Return the UNIT keyword value associated with the specified column
174 // <group>
175 const String& unit(const String& which) const;
176 const String& unit(ColEnum which) const
177 { return unit(columnName(which)); }
178 // </group>
179
180 // Convert a ColEnum to the actual column name.
181 static const String& columnName(ColEnum which);
182 // Convert a name to a ColEnum
183 static ColEnum columnType(const String &name);
184 // return the data type for a given ColEnum
185 static DataType columnDataType(ColEnum which);
186 // return the standard comment for a given ColEnum
188 // return the UNIT string for a given ColEnum
189 static const String& columnUnit(ColEnum which);
190 // return the MEASURE_TYPE string for a given ColEnum
191 static const String& columnMeasureType(ColEnum which);
192
193 // add a column to a TableDesc
194 // An exception is thrown for an invalid data type. This indicates a
195 // programming error in this class when this occurs.
196 // For Array columns you can optionally define the dimension here.
197 // For Measure columns you can define a variable reference column.
198 // <thrown>
199 // <li> AipsError
200 // </thrown>
201 static void addColumnToDesc(TableDesc & tabDesc, ColEnum which,
202 Int ndim=-1,const String& refCol="");
203 // add a column to a TableDesc, defining the shape and setting
204 // the ColumnDesc option (Fixed, Undefined, Direct)
205 // For Measure columns you can define a variable reference column.
206 static void addColumnToDesc(TableDesc & tabDesc, ColEnum which,
207 const IPosition& shape, ColumnDesc::Option option,
208 const String& refCol="");
210 Int ndim=-1,const String& refCol="");
211 // add a column to a TableDesc, defining the shape and setting
212 // the ColumnDesc option (Fixed, Undefined, Direct)
213 // For Measure columns you can define a variable reference column.
215 const IPosition& shape, ColumnDesc::Option option,
216 const String& refCol="");
217
218 // </group>
219
220 // KeyEnum convenience functions
221 // <group name=keywords>
222 static const String& keywordName(KeyEnum which);
223 static KeyEnum keywordType(const String &name);
224 static DataType keywordDataType(KeyEnum which);
227 // check to see if a keyword exists
228 Bool isKeyword(KeyEnum which) const;
229
230 // add a keyword to a TableDesc
231 // An exception is thrown for an invalid data type. This indicates a
232 // missing data type in the code..
233 // <thrown>
234 // <li> AipsError
235 // </thrown>
238
239 // </group>
240
241 // tableDesc convenience functions
242 // <group>
243
244 // check that a TableDesc is valid
245 static Bool validate(const TableDesc& tabDesc);
246
247 // check that the keyword set is valid
248 static Bool validate(const TableRecord& tabKeySet);
249
250 // validate self (make sure that this MS is valid)
251 Bool validate() const
252 { return this->isNull() ? False : validate(this->tableDesc());}
253
254 // return the required table description
256
257 // Add the compress option for the given column to the TableDesc.
258 // It can only be used for a Float or a Complex column.
259 // For complex columns the type determines which CompressComplex
260 // engine is used. "SD" means that CompressComplexSD is used; otherwise
261 // CompressComplex is used.
262 static void addColumnCompression (TableDesc& td, ColEnum which,
263 Bool autoScale = True,
264 const String& type = String());
265
266 // </group>
267
268protected:
269 // These constructors mirror the Table ones
270 // <group name=tableLikeConstructors>
271 // Default constructor for use by derived classes
272 MSTable ();
275 TableOption option);
276 MSTable (const String &tableName, const String &tableDescName,
277 TableOption option);
278 MSTable (const String &tableName, const String &tableDescName,
280 MSTable (SetupNewTable &newTab, rownr_t nrrow,
281 Bool initialize);
282 MSTable (SetupNewTable &newTab, const TableLock& lockOptions, rownr_t nrrow,
283 Bool initialize);
284#ifdef HAVE_MPI
285 MSTable (MPI_Comm comm, SetupNewTable &newTab, rownr_t nrrow,
286 Bool initialize);
287 MSTable (MPI_Comm comm, SetupNewTable &newTab, const TableLock& lockOptions,
288 rownr_t nrrow, Bool initialize);
289#endif // HAVE_MPI
290 MSTable (const Table &table);
291 MSTable (const MSTable<MSEnum> &other);
292 // </group>
293 ~MSTable();
295 // Assignment operator, reference semantics
297
298 // Get the static struct containing all column and keyword mappings.
300
301 // Define an entry in the column maps
302 static void colMapDef(MSTableMaps& maps,
303 ColEnum col,
304 const String& colName,
305 DataType colType,
306 const String& colComment,
307 const String& colUnit="",
308 const String& colMeasureType="");
309
310 // Define an entry in the keyword maps
311 static void keyMapDef(MSTableMaps& maps,
312 KeyEnum key,
313 const String& keyName,
314 DataType keyType,
315 const String& keyComment);
316
317 // Return a table that references all columns in this table except for
318 // those given in writableColumns, those are empty and writable.
319 Table referenceCopy(const String& newTableName,
320 const Block<String>& writableColumns) const;
321
322 // Convert a ColEnum to the actual column name.
323 inline static
324 const String& columnName(const MSTableMaps& maps,
325 ColEnum which)
326 { return maps.columnMap_p.at(which); }
327
328 inline static
329 DataType columnDataType(const MSTableMaps& maps,
330 ColEnum which)
331 { return DataType(maps.colDTypeMap_p.at(which)); }
332
333 inline static
335 ColEnum which)
336 { return maps.colCommentMap_p.at(which); }
337
338 inline static
339 const String& columnUnit(const MSTableMaps& maps,
340 ColEnum which)
341 { return maps.colUnitMap_p.at(which); }
342
343 inline static
345 ColEnum which)
346 { return maps.colMeasureTypeMap_p.at(which); }
347
348 inline static
349 const String& keywordName(const MSTableMaps& maps,
350 KeyEnum which)
351 { return maps.keywordMap_p.at(which); }
352
353 inline static
354 DataType keywordDataType(const MSTableMaps& maps,
355 KeyEnum which)
356 { return DataType(maps.keyDTypeMap_p.at(which)); }
357
358 inline static
360 KeyEnum which)
361 { return maps.keyCommentMap_p.at(which); }
362
363};
364
365
366} //# NAMESPACE CASACORE - END
367
368
369//# Do not instantiate the templates automatically, because it means that the static
370//# in function getMaps() might be instantiated in many compilation units.
371//# The templates are instantiated in MSTable.cc.
372//#ifndef CASACORE_NO_AUTO_TEMPLATES
373//#include <casacore/ms/MeasurementSets/MSTable.tcc>
374//#endif //# CASACORE_NO_AUTO_TEMPLATES
375#endif
simple 1-D array
Definition Block.h:200
Option
Enumerate the possible column options.
Definition ColumnDesc.h:142
A Table intended to hold astronomical data
Definition MSTable.h:147
static const String & columnUnit(ColEnum which)
return the UNIT string for a given ColEnum
static void addColumnToDesc(TableDesc &tabDesc, ColEnum which, Int ndim=-1, const String &refCol="")
add a column to a TableDesc An exception is thrown for an invalid data type.
MSEnum::PredefinedKeywords KeyEnum
Definition MSTable.h:151
static DataType columnDataType(ColEnum which)
return the data type for a given ColEnum
MSTable(const String &tableName, const String &tableDescName, TableOption option)
static KeyEnum keywordType(const String &name)
static MSTableMaps & getMaps()
Get the static struct containing all column and keyword mappings.
MSTable(SetupNewTable &newTab, rownr_t nrrow, Bool initialize)
static void addColumnCompression(TableDesc &td, ColEnum which, Bool autoScale=True, const String &type=String())
Add the compress option for the given column to the TableDesc.
Bool isScalar(ColEnum which) const
Information about scalar vs array of a column.
MSTable & operator=(const MSTable< MSEnum > &)
Assignment operator, reference semantics.
static void addColumnToDesc(TableDesc &tabDesc, ColEnum which, const IPosition &shape, ColumnDesc::Option option, const String &refCol="")
add a column to a TableDesc, defining the shape and setting the ColumnDesc option (Fixed,...
static const TableDesc & requiredTableDesc()
return the required table description
const String & unit(const String &which) const
Return the UNIT keyword value associated with the specified column.
static void keyMapDef(MSTableMaps &maps, KeyEnum key, const String &keyName, DataType keyType, const String &keyComment)
Define an entry in the keyword maps.
MSTable(MPI_Comm comm, SetupNewTable &newTab, rownr_t nrrow, Bool initialize)
MSTable(MPI_Comm comm, SetupNewTable &newTab, const TableLock &lockOptions, rownr_t nrrow, Bool initialize)
MSTable(SetupNewTable &newTab, const TableLock &lockOptions, rownr_t nrrow, Bool initialize)
static const String & columnUnit(const MSTableMaps &maps, ColEnum which)
Definition MSTable.h:339
MSTable(const String &tableName, const TableLock &lockOptions, TableOption option)
Bool validate() const
validate self (make sure that this MS is valid)
Definition MSTable.h:251
static const String & columnStandardComment(ColEnum which)
return the standard comment for a given ColEnum
Bool isKeyword(KeyEnum which) const
check to see if a keyword exists
const String & unit(ColEnum which) const
Definition MSTable.h:176
static const String & columnStandardComment(const MSTableMaps &maps, ColEnum which)
Definition MSTable.h:334
static DataType keywordDataType(const MSTableMaps &maps, KeyEnum which)
Definition MSTable.h:354
static void addKeyToDesc(TableDesc &, KeyEnum key)
add a keyword to a TableDesc An exception is thrown for an invalid data type.
Bool isColumnWritable(ColEnum which) const
check to see if a column is writable
MSTable(const Table &table)
static ColEnum columnType(const String &name)
Convert a name to a ColEnum.
static void colMapDef(MSTableMaps &maps, ColEnum col, const String &colName, DataType colType, const String &colComment, const String &colUnit="", const String &colMeasureType="")
Define an entry in the column maps.
Bool isColumnWritable(const String &columnName) const
Definition MSTable.h:161
static const String & keywordStandardComment(KeyEnum which)
Bool isColumn(ColEnum which) const
ColEnum convenience functions
static void addColumnToDesc(MSTableMaps &, ColEnum which, Int ndim=-1, const String &refCol="")
Table referenceCopy(const String &newTableName, const Block< String > &writableColumns) const
Return a table that references all columns in this table except for those given in writableColumns,...
static const String & keywordStandardComment(const MSTableMaps &maps, KeyEnum which)
Definition MSTable.h:359
MSTable(const MSTable< MSEnum > &other)
static const String & columnMeasureType(const MSTableMaps &maps, ColEnum which)
Definition MSTable.h:344
static const String & keywordName(const MSTableMaps &maps, KeyEnum which)
Definition MSTable.h:349
MSEnum::PredefinedColumns ColEnum
Define the column and keyword enuym types.
Definition MSTable.h:150
static const String & columnName(ColEnum which)
Convert a ColEnum to the actual column name.
static const String & keywordName(KeyEnum which)
KeyEnum convenience functions
MSTable(const String &tableName, TableOption option)
static const String & columnMeasureType(ColEnum which)
return the MEASURE_TYPE string for a given ColEnum
static Bool validate(const TableRecord &tabKeySet)
check that the keyword set is valid
Bool isColumnWritable(uInt columnIndex) const
Definition MSTable.h:163
static void addColumnToDesc(MSTableMaps &, ColEnum which, const IPosition &shape, ColumnDesc::Option option, const String &refCol="")
add a column to a TableDesc, defining the shape and setting the ColumnDesc option (Fixed,...
static Bool validate(const TableDesc &tabDesc)
tableDesc convenience functions
Bool isArray(ColEnum which) const
static void addKeyToDesc(MSTableMaps &, KeyEnum key)
MSTable()
These constructors mirror the Table ones
static const String & columnName(const MSTableMaps &maps, ColEnum which)
Convert a ColEnum to the actual column name.
Definition MSTable.h:324
static DataType columnDataType(const MSTableMaps &maps, ColEnum which)
Definition MSTable.h:329
static DataType keywordDataType(KeyEnum which)
MSTable(const String &tableName, const String &tableDescName, const TableLock &lockOptions, TableOption option)
Create a new table - define shapes, data managers, etc.
String: the storage and methods of handling collections of characters.
Definition String.h:225
const TableLock & lockOptions() const
Get the locking options.
Definition Table.h:1110
Bool isNull() const
Test if the object is null, i.e.
Definition Table.h:477
Bool isColumnWritable(const String &columnName) const
Test if the given column is writable.
Definition Table.h:1133
const TableDesc & tableDesc() const
Get the table description.
Definition Table.h:1175
const String & tableName() const
Get the table name.
Definition Table.h:1187
TableOption
Define the possible options how a table can be opened.
Definition Table.h:172
TableExprNode key(const String &keywordName) const
Create a TableExprNode object for a column or for a keyword in the table keyword set.
TableExprNode col(const String &columnName) const
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:44
LatticeExprNode ndim(const LatticeExprNode &expr)
1-argument function to get the dimensionality of a lattice.
unsigned int uInt
Definition aipstype.h:51
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition ExprNode.h:1987
int Int
Definition aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
const Bool True
Definition aipstype.h:43
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:46
Int keywordType(const String &name) const
Definition MSTable.h:75
TableDesc requiredTD_p
The required TableDesc.
Definition MSTable.h:70
std::map< Int, String > keyCommentMap_p
KeyEnum -> comment string.
Definition MSTable.h:68
std::map< Int, Int > keyDTypeMap_p
KeyEnum -> DataType.
Definition MSTable.h:66
std::map< Int, Int > colDTypeMap_p
ColEnum -> DataType.
Definition MSTable.h:56
std::map< Int, String > keywordMap_p
KeyEnum -> name.
Definition MSTable.h:64
std::map< Int, String > colMeasureTypeMap_p
ColEnum -> MEASURE_TYPE string.
Definition MSTable.h:62
std::map< Int, String > colCommentMap_p
ColEnum -> comment string.
Definition MSTable.h:58
std::map< Int, String > colUnitMap_p
ColEnum -> UNIT string.
Definition MSTable.h:60
Int mapType(const std::map< Int, String > &, const String &name) const
Int columnType(const String &name) const
Convert a name to a ColEnum or KeyEnum.
Definition MSTable.h:73
std::map< Int, String > columnMap_p
ColEnum -> name.
Definition MSTable.h:54