Loading...
Searching...
No Matches
MSTable.h
Go to the documentation of this file.
//# MSTable.h: A Table to hold astronomical data (a set of Measurements)
//# Copyright (C) 1996,1997,2000,2001,2002
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef MS_MSTABLE_H
#define MS_MSTABLE_H
#include <casacore/casa/aips.h>
#include <casacore/casa/Utilities/DataType.h>
#include <casacore/tables/Tables/Table.h>
#include <casacore/casa/BasicSL/String.h>
#include <casacore/tables/Tables/ColumnDesc.h>
#include <map>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward Declarations, more could be if they weren't part of the
//# static classes
class TableRecord;
template <class T> class Block;
// <summary>
// A struct holding the maps used in MSTable.
// </summary>
struct MSTableMaps
{
// ColEnum -> name
std::map<Int, String> columnMap_p;
// ColEnum -> DataType
std::map<Int, Int> colDTypeMap_p;
// ColEnum -> comment string
std::map<Int, String> colCommentMap_p;
// ColEnum -> UNIT string
std::map<Int, String> colUnitMap_p;
// ColEnum -> MEASURE_TYPE string
std::map<Int, String> colMeasureTypeMap_p;
// KeyEnum -> name
std::map<Int, String> keywordMap_p;
// KeyEnum -> DataType
std::map<Int, Int> keyDTypeMap_p;
// KeyEnum -> comment string
std::map<Int, String> keyCommentMap_p;
// The required TableDesc
TableDesc requiredTD_p;
// Convert a name to a ColEnum or KeyEnum.
Int columnType (const String& name) const
{ return mapType (columnMap_p, name); }
Int keywordType (const String& name) const
{ return mapType (keywordMap_p, name); }
Int mapType (const std::map<Int,String>&, const String& name) const;
};
// <summary>
// A Table intended to hold astronomical data
// </summary>
// <use visibility=export>
// <reviewed reviewer="Bob Garwood" date="1997/02/01" tests="" demos="">
// <prerequisite>
// <li> <linkto module="Tables:description">Tables</linkto> module
// </prerequisite>
//
// <etymology>
// The MSTable is the base class for all MeasurementSet Tables, hence the
// name.
// </etymology>
//
// <synopsis>
// A MSTable is a Table. Most operations on a MSTable are
// Table operations. See the <linkto module="Tables:description">Tables</linkto>
// module for a list of those operations. The member functions provided by this
// class are primarily convenience functions to help users follow the
// agreed upon column and keyword naming conventions. They are useful when
// creating a Table following the MSTable conventions from
// scratch as well as when creating the column objects to access those
// columns. All actual MeasurementSet Tables will be derived from this class.
//
// The standard way of accessing
// table columns is through Strings. Mistakes in typing the column
// name will not be caught at compile time (and may not be caught at
// run time). We have therefore decided to use an enumeration
// to specify columns so that many mistakes will be caught at compile
// time. This requires functions to map to and from this enumeration
// to the strings that are ultimately used.
//
// Upon destruction, the table is checked to see that all
// required columns and keywords are still present.
// If not an exception is thrown. (Not a good idea!) Nevertheless,
// the table will be flushed to disk if it is writable -
// preserving its state.
//
// </synopsis>
//
// <example>
// For examples of use, see the MeasurementSet class.
// </example>
//
// <motivation>
// The Table module is more than adequate as a container of data.
// However, in order for applications to be useful with data from
// different sources, some conventions need to be adopted in the use
// of Tables to store data. The MSTable provides the framework for
// these conventions and conversion functions. The actual definitions
// of columns and keywords are found in the derived classes and their
// "enum" base class (e.g. MSAntenna and MSAntennaEnums).
// </motivation>
//
// <todo asof="1996/2/22">
// <li> referenceCopy() should be more flexible with the storage managers used
// for the columns which are not merely references.
// <li> When ForwardColumnEngine is fixed so that it can deal with
// tables already in the cache, modify the test program. It may also
// be necessary to modify referenceCopy().
// </todo>
template <class MSEnum> class MSTable : public Table
{
public:
// Define the column and keyword enuym types.
typedef typename MSEnum::PredefinedColumns ColEnum;
typedef typename MSEnum::PredefinedKeywords KeyEnum;
// ColEnum convenience functions
// <group name=columns>
// check to see if a column exists
Bool isColumn(ColEnum which) const;
// check to see if a column is writable
// <group>
Bool isColumnWritable(ColEnum which) const;
Bool isColumnWritable (const String& columnName) const
{ return Table::isColumnWritable(columnName); }
Bool isColumnWritable (uInt columnIndex) const
{ return Table::isColumnWritable(columnIndex); }
// </group>
// Information about scalar vs array of a column
// <group>
Bool isScalar(ColEnum which) const;
Bool isArray(ColEnum which) const;
// </group>
// Return the UNIT keyword value associated with the specified column
// <group>
const String& unit(const String& which) const;
const String& unit(ColEnum which) const
{ return unit(columnName(which)); }
// </group>
// Convert a ColEnum to the actual column name.
static const String& columnName(ColEnum which);
// Convert a name to a ColEnum
static ColEnum columnType(const String &name);
// return the data type for a given ColEnum
static DataType columnDataType(ColEnum which);
// return the standard comment for a given ColEnum
static const String& columnStandardComment(ColEnum which);
// return the UNIT string for a given ColEnum
static const String& columnUnit(ColEnum which);
// return the MEASURE_TYPE string for a given ColEnum
static const String& columnMeasureType(ColEnum which);
// add a column to a TableDesc
// An exception is thrown for an invalid data type. This indicates a
// programming error in this class when this occurs.
// For Array columns you can optionally define the dimension here.
// For Measure columns you can define a variable reference column.
// <thrown>
// <li> AipsError
// </thrown>
static void addColumnToDesc(TableDesc & tabDesc, ColEnum which,
Int ndim=-1,const String& refCol="");
// add a column to a TableDesc, defining the shape and setting
// the ColumnDesc option (Fixed, Undefined, Direct)
// For Measure columns you can define a variable reference column.
static void addColumnToDesc(TableDesc & tabDesc, ColEnum which,
const IPosition& shape, ColumnDesc::Option option,
const String& refCol="");
static void addColumnToDesc(MSTableMaps&, ColEnum which,
Int ndim=-1,const String& refCol="");
// add a column to a TableDesc, defining the shape and setting
// the ColumnDesc option (Fixed, Undefined, Direct)
// For Measure columns you can define a variable reference column.
static void addColumnToDesc(MSTableMaps&, ColEnum which,
const IPosition& shape, ColumnDesc::Option option,
const String& refCol="");
// </group>
// KeyEnum convenience functions
// <group name=keywords>
static const String& keywordName(KeyEnum which);
static KeyEnum keywordType(const String &name);
static DataType keywordDataType(KeyEnum which);
static const String& keywordStandardComment(KeyEnum which);
// check to see if a keyword exists
Bool isKeyword(KeyEnum which) const;
// add a keyword to a TableDesc
// An exception is thrown for an invalid data type. This indicates a
// missing data type in the code..
// <thrown>
// <li> AipsError
// </thrown>
static void addKeyToDesc(TableDesc&, KeyEnum key);
static void addKeyToDesc(MSTableMaps&, KeyEnum key);
// </group>
// tableDesc convenience functions
// <group>
// check that a TableDesc is valid
static Bool validate(const TableDesc& tabDesc);
// check that the keyword set is valid
static Bool validate(const TableRecord& tabKeySet);
// validate self (make sure that this MS is valid)
Bool validate() const
{ return this->isNull() ? False : validate(this->tableDesc());}
// return the required table description
static const TableDesc& requiredTableDesc();
// Add the compress option for the given column to the TableDesc.
// It can only be used for a Float or a Complex column.
// For complex columns the type determines which CompressComplex
// engine is used. "SD" means that CompressComplexSD is used; otherwise
// CompressComplex is used.
static void addColumnCompression (TableDesc& td, ColEnum which,
Bool autoScale = True,
const String& type = String());
// </group>
protected:
// These constructors mirror the Table ones
// <group name=tableLikeConstructors>
// Default constructor for use by derived classes
MSTable ();
MSTable (const String &tableName, TableOption option);
MSTable (const String &tableName, const TableLock& lockOptions,
TableOption option);
MSTable (const String &tableName, const String &tableDescName,
TableOption option);
MSTable (const String &tableName, const String &tableDescName,
const TableLock& lockOptions, TableOption option);
MSTable (SetupNewTable &newTab, rownr_t nrrow,
Bool initialize);
MSTable (SetupNewTable &newTab, const TableLock& lockOptions, rownr_t nrrow,
Bool initialize);
#ifdef HAVE_MPI
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);
#endif // HAVE_MPI
MSTable (const Table &table);
MSTable (const MSTable<MSEnum> &other);
// </group>
~MSTable();
// Assignment operator, reference semantics
MSTable& operator=(const MSTable<MSEnum>&);
// Get the static struct containing all column and keyword mappings.
static MSTableMaps& getMaps();
// Define an entry in the column maps
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 keyword maps
static void keyMapDef(MSTableMaps& maps,
KeyEnum key,
const String& keyName,
DataType keyType,
const String& keyComment);
// Return a table that references all columns in this table except for
// those given in writableColumns, those are empty and writable.
Table referenceCopy(const String& newTableName,
const Block<String>& writableColumns) const;
// Convert a ColEnum to the actual column name.
inline static
const String& columnName(const MSTableMaps& maps,
ColEnum which)
{ return maps.columnMap_p.at(which); }
inline static
DataType columnDataType(const MSTableMaps& maps,
ColEnum which)
{ return DataType(maps.colDTypeMap_p.at(which)); }
inline static
const String& columnStandardComment(const MSTableMaps& maps,
ColEnum which)
{ return maps.colCommentMap_p.at(which); }
inline static
const String& columnUnit(const MSTableMaps& maps,
ColEnum which)
{ return maps.colUnitMap_p.at(which); }
inline static
const String& columnMeasureType(const MSTableMaps& maps,
ColEnum which)
{ return maps.colMeasureTypeMap_p.at(which); }
inline static
const String& keywordName(const MSTableMaps& maps,
KeyEnum which)
{ return maps.keywordMap_p.at(which); }
inline static
DataType keywordDataType(const MSTableMaps& maps,
KeyEnum which)
{ return DataType(maps.keyDTypeMap_p.at(which)); }
inline static
const String& keywordStandardComment(const MSTableMaps& maps,
KeyEnum which)
{ return maps.keyCommentMap_p.at(which); }
};
} //# NAMESPACE CASACORE - END
//# Do not instantiate the templates automatically, because it means that the static
//# in function getMaps() might be instantiated in many compilation units.
//# The templates are instantiated in MSTable.cc.
//#ifndef CASACORE_NO_AUTO_TEMPLATES
//#include <casacore/ms/MeasurementSets/MSTable.tcc>
//#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
casacore::type
casacore::Block
simple 1-D array
Definition Block.h:198
casacore::ColumnDesc::Option
Option
Enumerate the possible column options.
Definition ColumnDesc.h:140
casacore::IPosition
Definition IPosition.h:117
casacore::MSTable::columnUnit
static const String & columnUnit(ColEnum which)
return the UNIT string for a given ColEnum
casacore::MSTable::addColumnToDesc
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.
casacore::MSTable::KeyEnum
MSEnum::PredefinedKeywords KeyEnum
Definition MSTable.h:147
casacore::MSTable::columnDataType
static DataType columnDataType(ColEnum which)
return the data type for a given ColEnum
casacore::MSTable::MSTable
MSTable(const String &tableName, const String &tableDescName, TableOption option)
casacore::MSTable::keywordType
static KeyEnum keywordType(const String &name)
casacore::MSTable::getMaps
static MSTableMaps & getMaps()
Get the static struct containing all column and keyword mappings.
casacore::MSTable::MSTable
MSTable(SetupNewTable &newTab, rownr_t nrrow, Bool initialize)
casacore::MSTable::addColumnCompression
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.
casacore::MSTable::isScalar
Bool isScalar(ColEnum which) const
Information about scalar vs array of a column.
casacore::MSTable::operator=
MSTable & operator=(const MSTable< MSEnum > &)
Assignment operator, reference semantics.
casacore::MSTable::addColumnToDesc
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,...
casacore::MSTable::requiredTableDesc
static const TableDesc & requiredTableDesc()
return the required table description
casacore::MSTable::unit
const String & unit(const String &which) const
Return the UNIT keyword value associated with the specified column.
casacore::MSTable::keyMapDef
static void keyMapDef(MSTableMaps &maps, KeyEnum key, const String &keyName, DataType keyType, const String &keyComment)
Define an entry in the keyword maps.
casacore::MSTable::MSTable
MSTable(MPI_Comm comm, SetupNewTable &newTab, rownr_t nrrow, Bool initialize)
casacore::MSTable::MSTable
MSTable(MPI_Comm comm, SetupNewTable &newTab, const TableLock &lockOptions, rownr_t nrrow, Bool initialize)
casacore::MSTable::MSTable
MSTable(SetupNewTable &newTab, const TableLock &lockOptions, rownr_t nrrow, Bool initialize)
casacore::MSTable::columnUnit
static const String & columnUnit(const MSTableMaps &maps, ColEnum which)
Definition MSTable.h:335
casacore::MSTable::MSTable
MSTable(const String &tableName, const TableLock &lockOptions, TableOption option)
casacore::MSTable::validate
Bool validate() const
validate self (make sure that this MS is valid)
Definition MSTable.h:247
casacore::MSTable::columnStandardComment
static const String & columnStandardComment(ColEnum which)
return the standard comment for a given ColEnum
casacore::MSTable::isKeyword
Bool isKeyword(KeyEnum which) const
check to see if a keyword exists
casacore::MSTable::unit
const String & unit(ColEnum which) const
Definition MSTable.h:172
casacore::MSTable::columnStandardComment
static const String & columnStandardComment(const MSTableMaps &maps, ColEnum which)
Definition MSTable.h:330
casacore::MSTable::keywordDataType
static DataType keywordDataType(const MSTableMaps &maps, KeyEnum which)
Definition MSTable.h:350
casacore::MSTable::addKeyToDesc
static void addKeyToDesc(TableDesc &, KeyEnum key)
add a keyword to a TableDesc An exception is thrown for an invalid data type.
casacore::MSTable::isColumnWritable
Bool isColumnWritable(ColEnum which) const
check to see if a column is writable
casacore::MSTable::MSTable
MSTable(const Table &table)
casacore::MSTable::columnType
static ColEnum columnType(const String &name)
Convert a name to a ColEnum.
casacore::MSTable::colMapDef
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.
casacore::MSTable::isColumnWritable
Bool isColumnWritable(const String &columnName) const
Definition MSTable.h:157
casacore::MSTable::keywordStandardComment
static const String & keywordStandardComment(KeyEnum which)
casacore::MSTable::isColumn
Bool isColumn(ColEnum which) const
ColEnum convenience functions .
casacore::MSTable::addColumnToDesc
static void addColumnToDesc(MSTableMaps &, ColEnum which, Int ndim=-1, const String &refCol="")
casacore::MSTable::referenceCopy
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,...
casacore::MSTable::keywordStandardComment
static const String & keywordStandardComment(const MSTableMaps &maps, KeyEnum which)
Definition MSTable.h:355
casacore::MSTable::MSTable
MSTable(const MSTable< MSEnum > &other)
casacore::MSTable::columnMeasureType
static const String & columnMeasureType(const MSTableMaps &maps, ColEnum which)
Definition MSTable.h:340
casacore::MSTable::keywordName
static const String & keywordName(const MSTableMaps &maps, KeyEnum which)
Definition MSTable.h:345
casacore::MSTable::~MSTable
~MSTable()
casacore::MSTable::ColEnum
MSEnum::PredefinedColumns ColEnum
Define the column and keyword enuym types.
Definition MSTable.h:146
casacore::MSTable::columnName
static const String & columnName(ColEnum which)
Convert a ColEnum to the actual column name.
casacore::MSTable::keywordName
static const String & keywordName(KeyEnum which)
KeyEnum convenience functions .
casacore::MSTable::MSTable
MSTable(const String &tableName, TableOption option)
casacore::MSTable::columnMeasureType
static const String & columnMeasureType(ColEnum which)
return the MEASURE_TYPE string for a given ColEnum
casacore::MSTable::validate
static Bool validate(const TableRecord &tabKeySet)
check that the keyword set is valid
casacore::MSTable::isColumnWritable
Bool isColumnWritable(uInt columnIndex) const
Definition MSTable.h:159
casacore::MSTable::addColumnToDesc
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,...
casacore::MSTable::validate
static Bool validate(const TableDesc &tabDesc)
tableDesc convenience functions
casacore::MSTable::isArray
Bool isArray(ColEnum which) const
casacore::MSTable::addKeyToDesc
static void addKeyToDesc(MSTableMaps &, KeyEnum key)
casacore::MSTable::MSTable
MSTable()
These constructors mirror the Table ones .
casacore::MSTable::columnName
static const String & columnName(const MSTableMaps &maps, ColEnum which)
Convert a ColEnum to the actual column name.
Definition MSTable.h:320
casacore::MSTable::columnDataType
static DataType columnDataType(const MSTableMaps &maps, ColEnum which)
Definition MSTable.h:325
casacore::MSTable::keywordDataType
static DataType keywordDataType(KeyEnum which)
casacore::MSTable::MSTable
MSTable(const String &tableName, const String &tableDescName, const TableLock &lockOptions, TableOption option)
casacore::SetupNewTable
Create a new table - define shapes, data managers, etc.
Definition SetupNewTab.h:337
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::TableDesc
Definition TableDesc.h:189
casacore::TableLock
Definition TableLock.h:67
casacore::TableRecord
Definition TableRecord.h:183
casacore::Table::lockOptions
const TableLock & lockOptions() const
Get the locking options.
Definition Table.h:1126
casacore::Table::isNull
Bool isNull() const
Test if the object is null, i.e.
Definition Table.h:489
casacore::Table::isColumnWritable
Bool isColumnWritable(const String &columnName) const
Test if the given column is writable.
Definition Table.h:1149
casacore::Table::tableDesc
const TableDesc & tableDesc() const
Get the table description.
Definition Table.h:1191
casacore::Table::tableName
const String & tableName() const
Get the table name.
Definition Table.h:1203
casacore::Table::TableOption
TableOption
Define the possible options how a table can be opened.
Definition Table.h:171
casacore::Table::key
TableExprNode key(const String &keywordName) const
Create a TableExprNode object for a column or for a keyword in the table keyword set.
casacore::Table::col
TableExprNode col(const String &columnName) const
casacore::Table::Table
Table()
Create a null Table object (i.e.
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::False
const Bool False
Definition aipstype.h:42
casacore::ndim
LatticeExprNode ndim(const LatticeExprNode &expr)
1-argument function to get the dimensionality of a lattice.
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::shape
IPosition shape(const RecordFieldId &) const
Get the actual shape of this field.
casacore::name
String name() const
Return the name of the field.
Definition RecordField.h:163
casacore::Int
int Int
Definition aipstype.h:48
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::True
const Bool True
Definition aipstype.h:41
casacore::rownr_t
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:44
casacore::MSTableMaps
Definition MSTable.h:48
casacore::MSTableMaps::keywordType
Int keywordType(const String &name) const
Definition MSTable.h:71
casacore::MSTableMaps::requiredTD_p
TableDesc requiredTD_p
The required TableDesc.
Definition MSTable.h:66
casacore::MSTableMaps::keyCommentMap_p
std::map< Int, String > keyCommentMap_p
KeyEnum -> comment string.
Definition MSTable.h:64
casacore::MSTableMaps::keyDTypeMap_p
std::map< Int, Int > keyDTypeMap_p
KeyEnum -> DataType.
Definition MSTable.h:62
casacore::MSTableMaps::colDTypeMap_p
std::map< Int, Int > colDTypeMap_p
ColEnum -> DataType.
Definition MSTable.h:52
casacore::MSTableMaps::keywordMap_p
std::map< Int, String > keywordMap_p
KeyEnum -> name.
Definition MSTable.h:60
casacore::MSTableMaps::colMeasureTypeMap_p
std::map< Int, String > colMeasureTypeMap_p
ColEnum -> MEASURE_TYPE string.
Definition MSTable.h:58
casacore::MSTableMaps::colCommentMap_p
std::map< Int, String > colCommentMap_p
ColEnum -> comment string.
Definition MSTable.h:54
casacore::MSTableMaps::colUnitMap_p
std::map< Int, String > colUnitMap_p
ColEnum -> UNIT string.
Definition MSTable.h:56
casacore::MSTableMaps::mapType
Int mapType(const std::map< Int, String > &, const String &name) const
casacore::MSTableMaps::columnType
Int columnType(const String &name) const
Convert a name to a ColEnum or KeyEnum.
Definition MSTable.h:69
casacore::MSTableMaps::columnMap_p
std::map< Int, String > columnMap_p
ColEnum -> name.
Definition MSTable.h:50