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/Containers/SimOrdMap.h>
36 #include <casacore/casa/Utilities/CountedPtr.h>
37 #include <casacore/casa/BasicSL/String.h>
38 #include <casacore/tables/Tables/ColumnDesc.h>
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 // <summary>
48 // A Table intended to hold astronomical data
49 // </summary>
50 
51 // <use visibility=export>
52 
53 // <reviewed reviewer="Bob Garwood" date="1997/02/01" tests="" demos="">
54 
55 // <prerequisite>
56 // <li> <linkto module="Tables:description">Tables</linkto> module
57 // </prerequisite>
58 //
59 // <etymology>
60 // The MSTable is the base class for all MeasurementSet Tables, hence the
61 // name.
62 // </etymology>
63 //
64 // <synopsis>
65 // A MSTable is a Table. Most operations on a MSTable are
66 // Table operations. See the <linkto module="Tables:description">Tables</linkto>
67 // module for a list of those operations. The member functions provided by this
68 // class are primarily convenience functions to help users follow the
69 // agreed upon column and keyword naming conventions. They are useful when
70 // creating a Table following the MSTable conventions from
71 // scratch as well as when creating the column objects to access those
72 // columns. All actual MeasurementSet Tables will be derived from this class.
73 //
74 // The standard way of accessing
75 // table columns is through Strings. Mistakes in typing the column
76 // name will not be caught at compile time (and may not be caught at
77 // run time). We have therefore decided to use an enumeration
78 // to specify columns so that many mistakes will be caught at compile
79 // time. This requires functions to map to and from this enumeration
80 // to the strings that are ultimately used.
81 //
82 // Upon destruction, the table is checked to see that all
83 // required columns and keywords are still present.
84 // If not an exception is thrown. (Not a good idea!) Nevertheless,
85 // the table will be flushed to disk if it is writable -
86 // preserving its state.
87 //
88 // </synopsis>
89 //
90 // <example>
91 // For examples of use, see the MeasurementSet class.
92 // </example>
93 //
94 // <motivation>
95 // The Table module is more than adequate as a container of data.
96 // However, in order for applications to be useful with data from
97 // different sources, some conventions need to be adopted in the use
98 // of Tables to store data. The MSTable provides the framework for
99 // these conventions and conversion functions. The actual definitions
100 // of columns and keywords are found in the derived classes and their
101 // "enum" base class (e.g. MSAntenna and MSAntennaEnums).
102 // </motivation>
103 //
104 // <todo asof="1996/2/22">
105 // <li> referenceCopy() should be more flexible with the storage managers used
106 // for the columns which are not merely references.
107 // <li> When ForwardColumnEngine is fixed so that it can deal with
108 // tables already in the cache, modify the test program. It may also
109 // be necessary to modify referenceCopy().
110 // </todo>
111 
112 template <class ColEnum, class KeyEnum> class MSTable : public Table
113 {
114 public:
115  // ColEnum convenience functions
116  // <group name=columns>
117  // check to see if a column exists
118  Bool isColumn(ColEnum which) const;
119 
120  // check to see if a column is writable
121  // <group>
122  Bool isColumnWritable(ColEnum which) const;
124  { return Table::isColumnWritable(columnName); }
125  Bool isColumnWritable (uInt columnIndex) const
126  { return Table::isColumnWritable(columnIndex); }
127  // </group>
128 
129  // Information about scalar vs array of a column
130  // <group>
131  Bool isScalar(ColEnum which) const;
132  Bool isArray(ColEnum which) const;
133  // </group>
134 
135  // Return the UNIT keyword value associated with the specified column
136  // <group>
137  const String& unit(const String& which) const;
138  const String& unit(ColEnum which) const
139  { return unit(columnName(which)); }
140  // </group>
141 
142  // Convert a ColEnum to the actual column name.
143  static const String& columnName(ColEnum which);
144  // Convert a name to a ColEnum
145  static ColEnum columnType(const String &name);
146  // return the data type for a given ColEnum
147  static DataType columnDataType(ColEnum which);
148  // return the standard comment for a given ColEnum
149  static const String& columnStandardComment(ColEnum which);
150  // return the UNIT string for a given ColEnum
151  static const String& columnUnit(ColEnum which);
152  // return the MEASURE_TYPE string for a given ColEnum
153  static const String& columnMeasureType(ColEnum which);
154 
155  // add a column to a TableDesc
156  // An exception is thrown for an invalid data type. This indicates a
157  // programming error in this class when this occurs.
158  // For Array columns you can optionally define the dimension here.
159  // For Measure columns you can define a variable reference column.
160  // <thrown>
161  // <li> AipsError
162  // </thrown>
163  static void addColumnToDesc(TableDesc & tabDesc, ColEnum which,
164  Int ndim=-1,const String& refCol="");
165  // add a column to a TableDesc, defining the shape and setting
166  // the ColumnDesc option (Fixed, Undefined, Direct)
167  // For Measure columns you can define a variable reference column.
168  static void addColumnToDesc(TableDesc & tabDesc, ColEnum which,
169  const IPosition& shape, ColumnDesc::Option option,
170  const String& refCol="");
171 
172  // </group>
173 
174  // KeyEnum convenience functions
175  // <group name=keywords>
176  static const String& keywordName(KeyEnum which);
177  static KeyEnum keywordType(const String &name);
178  static DataType keywordDataType(KeyEnum which);
179  static const String& keywordStandardComment(KeyEnum which);
180 
181  // check to see if a keyword exists
182  Bool isKeyword(KeyEnum which) const;
183 
184  // add a keyword to a TableDesc
185  // An exception is thrown for an invalid data type. This indicates a
186  // missing data type in the code..
187  // <thrown>
188  // <li> AipsError
189  // </thrown>
190  static void addKeyToDesc(TableDesc & tabDesc, KeyEnum key);
191 
192  // </group>
193 
194  // tableDesc convenience functions
195  // <group>
196 
197  // check that a TableDesc is valid
198  static Bool validate(const TableDesc& tabDesc);
199 
200  // check that the keyword set is valid
201  static Bool validate(const TableRecord& tabKeySet);
202 
203  // validate self (make sure that this MS is valid)
204  Bool validate() const
205  { return this->isNull() ? False : validate(this->tableDesc());}
206 
207  // return the required table description
208  static const TableDesc& requiredTableDesc();
209 
210  // Add the compress option for the given column to the TableDesc.
211  // It can only be used for a Float or a Complex column.
212  // For complex columns the type determines which CompressComplex
213  // engine is used. "SD" means that CompressComplexSD is used; otherwise
214  // CompressComplex is used.
215  static void addColumnCompression (TableDesc& td, ColEnum which,
216  Bool autoScale = True,
217  const String& type = String());
218 
219  // </group>
220 
221  // Remove a column from a table
222  // No exception is thrown if this invalidates the table
223  // in order to permit more complex operations with invalid
224  // intermediate states
225  void removeColumn(const String & columnName)
226  {
227  Table::removeColumn(columnName);
228  }
229 
230  // Remove columns from a table
231  void removeColumn(const Vector<String>& columnNames)
232  {
233  Table::removeColumn(columnNames);
234  }
235 
236  // Rename a column
237  // No exception is thrown if this invalidates the table
238  // in order to permit more complex operations with invalid
239  // intermediate states
240  void renameColumn(const String & newName,
241  const String & oldName)
242  {
243  Table::renameColumn(newName, oldName);
244  }
245 
246 protected:
247  // These constructors mirror the Table ones
248  // <group name=tableLikeConstructors>
249  // Default constructor for use by derived classes
250  MSTable ();
251  MSTable (const String &tableName, TableOption option);
252  MSTable (const String &tableName, const TableLock& lockOptions,
253  TableOption option);
254  MSTable (const String &tableName, const String &tableDescName,
255  TableOption option);
256  MSTable (const String &tableName, const String &tableDescName,
257  const TableLock& lockOptions, TableOption option);
258  MSTable (SetupNewTable &newTab, uInt nrrow,
259  Bool initialize);
260  MSTable (SetupNewTable &newTab, const TableLock& lockOptions, uInt nrrow,
261  Bool initialize);
262  MSTable (const Table &table);
263  MSTable (const MSTable<ColEnum,KeyEnum> &other);
264  // </group>
265  ~MSTable();
266 
267  // Assignment operator, reference semantics
269 
270  // These are the static ordered maps which contain the above info
271  // ColEnum -> name
273  // ColEnum -> DataType
275  // ColEnum -> comment string
277  // ColEnum -> UNIT string
279  // ColEnum -> MEASURE_TYPE string
281 
282 
283  // KeyEnum -> name
285  // KeyEnum -> DataType
287  // KeyEnum -> comment string
289 
290  // The required TableDesc
291  //# following fails in static initialization (segm. fault).
292  // static TableDesc requiredTD_p;
294 
295  // Define an entry in the column maps
296  static void colMapDef(ColEnum col,
297  const String& colName,
298  DataType colType,
299  const String& colComment,
300  const String& colUnit="",
301  const String& colMeasureType="");
302 
303  // Define an entry in the keyword maps
304  static void keyMapDef(KeyEnum key,
305  const String& keyName,
306  DataType keyType,
307  const String& keyComment);
308 
309  // Return a table that references all columns in this table except for
310  // those given in writableColumns, those are empty and writable.
311  Table referenceCopy(const String& newTableName,
312  const Block<String>& writableColumns) const;
313 
314 };
315 
316 
317 } //# NAMESPACE CASACORE - END
318 
319 //# #ifndef CASACORE_NO_AUTO_TEMPLATES
320 //# #include <casacore/ms/MeasurementSets/MSTable.tcc>
321 //# #endif //# CASACORE_NO_AUTO_TEMPLATES
322 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
int Int
Definition: aipstype.h:50
static SimpleOrderedMap< Int, String > columnMap_p
These are the static ordered maps which contain the above info ColEnum -> name.
Definition: MSTable.h:272
void removeColumn(const String &columnName)
Remove columns.
Bool isKeyword(KeyEnum which) const
check to see if a keyword exists
void renameColumn(const String &newName, const String &oldName)
Rename a column.
Definition: Table.h:1234
static ColEnum columnType(const String &name)
Convert a name to a ColEnum.
static const String & columnMeasureType(ColEnum which)
return the MEASURE_TYPE string for a given ColEnum
Create a new table - define shapes, data managers, etc.
Definition: SetupNewTab.h:346
static KeyEnum keywordType(const String &name)
Main interface class to a read/write table.
Definition: Table.h:149
const String & unit(const String &which) const
Return the UNIT keyword value associated with the specified column.
Bool isColumnWritable(const String &columnName) const
Test if the given column is writable.
Definition: Table.h:1140
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...
Bool isScalar(ColEnum which) const
Information about scalar vs array of a column.
Bool isColumn(ColEnum which) const
ColEnum convenience functions.
static SimpleOrderedMap< Int, String > colMeasureTypeMap_p
ColEnum -> MEASURE_TYPE string.
Definition: MSTable.h:280
void removeColumn(const String &columnName)
Remove a column from a table No exception is thrown if this invalidates the table in order to permit ...
Definition: MSTable.h:225
const TableDesc & tableDesc() const
Get the table description.
Definition: Table.h:1182
Bool isColumnWritable(const String &columnName) const
Definition: MSTable.h:123
static DataType keywordDataType(KeyEnum which)
TableExprNode key(const String &keywordName) const
Create a TableExprNode object for a column or for a keyword in the table keyword set.
static const String & columnUnit(ColEnum which)
return the UNIT string for a given ColEnum
static const String & columnName(ColEnum which)
Convert a ColEnum to the actual column name.
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.
static SimpleOrderedMap< Int, String > keywordMap_p
KeyEnum -> name.
Definition: MSTable.h:284
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.
static const String & keywordName(KeyEnum which)
KeyEnum convenience functions.
Bool isArray(ColEnum which) const
static DataType columnDataType(ColEnum which)
return the data type for a given ColEnum
Simple map with keys ordered.
Definition: SimOrdMap.h:69
Referenced counted pointer for constant data.
Definition: CountedPtr.h:86
static void addKeyToDesc(TableDesc &tabDesc, KeyEnum key)
add a keyword to a TableDesc An exception is thrown for an invalid data type.
const TableLock & lockOptions() const
Get the locking options.
Definition: Table.h:1117
static void colMapDef(ColEnum col, const String &colName, DataType colType, const String &colComment, const String &colUnit="", const String &colMeasureType="")
Define an entry in the column maps.
Bool validate() const
validate self (make sure that this MS is valid)
Definition: MSTable.h:204
LatticeExprNode ndim(const LatticeExprNode &expr)
1-argument function to get the dimensionality of a lattice.
static SimpleOrderedMap< Int, Int > keyDTypeMap_p
KeyEnum -> DataType.
Definition: MSTable.h:286
static const String & columnStandardComment(ColEnum which)
return the standard comment for a given ColEnum
static const TableDesc & requiredTableDesc()
return the required table description
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
MSTable & operator=(const MSTable< ColEnum, KeyEnum > &)
Assignment operator, reference semantics.
const Bool False
Definition: aipstype.h:44
Class to hold table lock options.
Definition: TableLock.h:65
Bool isColumnWritable(uInt columnIndex) const
Definition: MSTable.h:125
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:2151
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:182
Bool isColumnWritable(ColEnum which) const
check to see if a column is writable
void removeColumn(const Vector< String > &columnNames)
Remove columns from a table.
Definition: MSTable.h:231
simple 1-D array
Definition: ArrayIO.h:47
static CountedPtr< TableDesc > requiredTD_p
The required TableDesc.
Definition: MSTable.h:293
TableExprNode col(const String &columnName) const
static SimpleOrderedMap< Int, Int > colDTypeMap_p
ColEnum -> DataType.
Definition: MSTable.h:274
static SimpleOrderedMap< Int, String > colUnitMap_p
ColEnum -> UNIT string.
Definition: MSTable.h:278
const String & unit(ColEnum which) const
Definition: MSTable.h:138
A Table intended to hold astronomical data.
Definition: MSTable.h:112
static void keyMapDef(KeyEnum key, const String &keyName, DataType keyType, const String &keyComment)
Define an entry in the keyword maps.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
MSTable()
These constructors mirror the Table ones.
static SimpleOrderedMap< Int, String > keyCommentMap_p
KeyEnum -> comment string.
Definition: MSTable.h:288
Define the structure of a Casacore table.
Definition: TableDesc.h:186
const String & tableName() const
Get the table name.
Definition: Table.h:1196
Bool isNull() const
Test if the object is null, i.e.
Definition: Table.h:503
const Bool True
Definition: aipstype.h:43
void renameColumn(const String &newName, const String &oldName)
Rename a column No exception is thrown if this invalidates the table in order to permit more complex ...
Definition: MSTable.h:240
this file contains all the compiler specific defines
Definition: mainpage.dox:28
Option
Enumerate the possible column options.
Definition: ColumnDesc.h:141
static const String & keywordStandardComment(KeyEnum which)
unsigned int uInt
Definition: aipstype.h:51
TableOption
Define the possible options how a table can be opened.
Definition: Table.h:164
static SimpleOrderedMap< Int, String > colCommentMap_p
ColEnum -> comment string.
Definition: MSTable.h:276