casacore
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 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward Declarations, more could be if they weren't part of the
43 //# static classes
44 class TableRecord;
45 template <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 
146 template <class MSEnum> class MSTable : public Table
147 {
148 public:
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;
157 
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
187  static const String& columnStandardComment(ColEnum which);
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="");
209  static void addColumnToDesc(MSTableMaps&, ColEnum which,
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.
214  static void addColumnToDesc(MSTableMaps&, ColEnum which,
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);
225  static const String& keywordStandardComment(KeyEnum which);
226 
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
255  static const TableDesc& requiredTableDesc();
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 
268 protected:
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();
294 
295  // Assignment operator, reference semantics
297 
298  // Get the static struct containing all column and keyword mappings.
299  static MSTableMaps& getMaps();
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 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
static const String & columnStandardComment(const MSTableMaps &maps, ColEnum which)
Definition: MSTable.h:334
static KeyEnum keywordType(const String &name)
static const String & keywordStandardComment(KeyEnum which)
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.
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 void keyMapDef(MSTableMaps &maps, KeyEnum key, const String &keyName, DataType keyType, const String &keyComment)
Define an entry in the keyword maps.
static const String & keywordStandardComment(const MSTableMaps &maps, KeyEnum which)
Definition: MSTable.h:359
static const TableDesc & requiredTableDesc()
return the required table description
Bool validate() const
validate self (make sure that this MS is valid)
Definition: MSTable.h:251
static const String & columnName(ColEnum which)
Convert a ColEnum to the actual column name.
static const String & keywordName(KeyEnum which)
KeyEnum convenience functions
Bool isKeyword(KeyEnum which) const
check to see if a keyword exists
static const String & keywordName(const MSTableMaps &maps, KeyEnum which)
Definition: MSTable.h:349
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)
MSTable & operator=(const MSTable< MSEnum > &)
Assignment operator, reference semantics.
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
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 & columnUnit(const MSTableMaps &maps, ColEnum which)
Definition: MSTable.h:339
MSEnum::PredefinedColumns ColEnum
Define the column and keyword enuym types.
Definition: MSTable.h:150
const String & unit(const String &which) const
Return the UNIT keyword value associated with the specified column.
static const String & columnStandardComment(ColEnum which)
return the standard comment for a given ColEnum
MSTable(const String &tableName, TableOption option)
static const String & columnMeasureType(const MSTableMaps &maps, ColEnum which)
Definition: MSTable.h:344
static Bool validate(const TableRecord &tabKeySet)
check that the keyword set is valid
static const String & columnName(const MSTableMaps &maps, ColEnum which)
Convert a ColEnum to the actual column name.
Definition: MSTable.h:324
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
const String & unit(ColEnum which) const
Definition: MSTable.h:176
static const String & columnUnit(ColEnum which)
return the UNIT string for a given ColEnum
static void addKeyToDesc(MSTableMaps &, KeyEnum key)
MSTable()
These constructors mirror the Table ones
static MSTableMaps & getMaps()
Get the static struct containing all column and keyword mappings.
static DataType columnDataType(const MSTableMaps &maps, ColEnum which)
Definition: MSTable.h:329
static const String & columnMeasureType(ColEnum which)
return the MEASURE_TYPE string for a given ColEnum
static DataType keywordDataType(KeyEnum which)
Create a new table - define shapes, data managers, etc.
Definition: SetupNewTab.h:341
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