MeasurementSet.h

Classes

MeasurementSet -- A Table intended to hold astronomical data (a set of Measurements). (full description)

class MeasurementSet : public MSTable<MSMainEnums::PredefinedColumns, MSMainEnums::PredefinedKeywords>, public MSMainEnums

Interface

Public Members
MeasurementSet ()
MeasurementSet (const String &tableName, TableOption = Table::Old)
MeasurementSet (const String &tableName, const TableLock& lockOptions, TableOption = Table::Old)
MeasurementSet (const String &tableName, const String &tableDescName, TableOption = Table::Old)
MeasurementSet (const String &tableName, const String &tableDescName, const TableLock& lockOptions, TableOption = Table::Old)
MeasurementSet (SetupNewTable &newTab, uInt nrrow = 0, Bool initialize = False)
MeasurementSet (SetupNewTable &newTab, const TableLock& lockOptions, uInt nrrow = 0, Bool initialize = False)
MeasurementSet (const Table &table)
MeasurementSet (const MeasurementSet &other)
~MeasurementSet()
MeasurementSet& operator=(const MeasurementSet&)
MeasurementSet referenceCopy(const String& newTableName, const Block<String>& writableColumns) const
String antennaTableName() const
String dataDescriptionTableName() const
String dopplerTableName() const
String feedTableName() const
String fieldTableName() const
String flagCmdTableName() const
String freqOffsetTableName() const
String historyTableName() const
String observationTableName() const
String pointingTableName() const
String polarizationTableName() const
String processorTableName() const
String sourceTableName() const
String spectralWindowTableName() const
String stateTableName() const
String sysCalTableName() const
String weatherTableName() const
MSAntenna& antenna()
MSDataDescription& dataDescription()
MSDoppler& doppler()
MSFeed& feed()
MSField& field()
MSFlagCmd& flagCmd()
MSFreqOffset& freqOffset()
MSHistory& history()
MSObservation& observation()
MSPointing& pointing()
MSPolarization& polarization()
MSProcessor& processor()
MSSource& source()
MSSpectralWindow& spectralWindow()
MSState& state()
MSSysCal& sysCal()
MSWeather& weather()
const MSAntenna& antenna() const
const MSDataDescription& dataDescription() const
const MSDoppler& doppler() const
const MSFeed& feed() const
const MSField& field() const
const MSFlagCmd& flagCmd() const
const MSFreqOffset& freqOffset() const
const MSHistory& history() const
const MSObservation& observation() const
const MSPointing& pointing() const
const MSPolarization& polarization() const
const MSProcessor& processor() const
const MSSource& source() const
const MSSpectralWindow& spectralWindow() const
const MSState& state() const
const MSSysCal& sysCal() const
const MSWeather& weather() const
void initRefs(Bool clear=False)
void createDefaultSubtables(Table::TableOption option=Table::Scratch)
static void init()
Bool makeComplexData()
Bool validateMeasureRefs()
void flush(Bool sync=False)
Private Members
void addCat()
void checkVersion()

Description

Review Status

Reviewed By:
Bob Garwood
Date Reviewed:
1997/02/01
Programs:
Tests:

Prerequisite

Etymology

The MeasurementSet is where all data are ultimately to be found in AIPS++. Since, this is a collection of measurements (either actual or simulated), the term MeasurementSet seems appropriate.

Synopsis

A MeasurementSet is a Table. Most operations on a MeasurementSet are Table operations. See the Tables 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 MeasurementSet conventions from scratch as well as when creating the column objects to access those columns.

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 the MeasurementSet remains valid, i.e., all required columns are present An exception is thrown if not all required columns are present Nevertheless, the table will be flushed to disk if it is writable - preserving its state.

A MeasurementSet has a number of required subtables. These are stored as keywords in the Table. Access to these subtables is provided via member functions (e.g. antenna() for the ANTENNA table). All subtables have associated MeasurementSet-like classes defined for them (MSAntenna for the ANTENNA table) which provide analogous column and keyword mapping as provided here.

While the class name, MeasurementSet, is descriptive, it is often too long for many common uses. The typedef MS is provided as a convenient shorthand for MeasurementSet. The example below uses this typedef.

Due to the inheritance scheme, it was necessary to separate the enumerations used by MeasurementSet into a separate class, MSMainEnums.

Example

This example illustrates a simple use of the MeasurementSet class.
      // create the table descriptor
      TableDesc simpleDesc = MS::requiredTableDesc()
      // set up a new table
      SetupNewTable newTab("simpleTab", simpleDesc, Table::New);
      // create the MeasurementSet
      MeasurementSet simpleMS(newTab);
      // now we need to define all required subtables
      // the following call does this for us if we don't need to
      // specify details of Storage Managers for columns.
      simpleMS.createDefaultSubtables(Table::New);
      // fill MeasurementSet via its Table interface
      // For example, construct one of the columns
      TableColumn feed(simpleMS, MS::columnName(MS::FEED1));
      uInt rownr = 0;
      // add a row
      simpleMS.addRow();
      // set the values in that row, e.g. the feed column
      feed.putScalar(rownr,1);
      // Access a subtable
      ArrayColumn<Double> antpos(simpleMS.antenna(),
                                 MSAntenna::columnName(MSAntenna::POSITION));
      simpleMS.antenna().addRow();
      Array<Double> position(3); 
      position(0)=1.; position(1)=2.; position(2)=3.;
      antpos.put(0,position);
      // etc.

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 MeasurementSet is where those conventions are defined and, to some extent, enforced.

There are a number of reasons why MeasurementSet is more than just a Table.

To Do

Member Description

MeasurementSet ()

This constructs an empty MeasurementSet, only useful to assign to (it is not a valid MS yet).

MeasurementSet (const String &tableName, TableOption = Table::Old)
MeasurementSet (const String &tableName, const TableLock& lockOptions, TableOption = Table::Old)
MeasurementSet (const String &tableName, const String &tableDescName, TableOption = Table::Old)
MeasurementSet (const String &tableName, const String &tableDescName, const TableLock& lockOptions, TableOption = Table::Old)
MeasurementSet (SetupNewTable &newTab, uInt nrrow = 0, Bool initialize = False)
MeasurementSet (SetupNewTable &newTab, const TableLock& lockOptions, uInt nrrow = 0, Bool initialize = False)
MeasurementSet (const Table &table)
MeasurementSet (const MeasurementSet &other)

These constructors mirror the Table ones with additional checking on validity (verifying that the MS will have the required columns and keywords) An exception is thrown if the constructed Table is not a valid MS

Thrown Exceptions

~MeasurementSet()

As with tables, the destructor writes the table if necessary. Additional checking is done here to verify that all required columns are still present. If it is NOT valid, it will write the table and then throw an exception.

Thrown Exceptions

MeasurementSet& operator=(const MeasurementSet&)

Assignment operator, reference semantics

MeasurementSet referenceCopy(const String& newTableName, const Block<String>& writableColumns) const

Make a special copy of this MS which references all columns from this MS except those mentioned; those are empty and writable. Each forwarded column has the same writable status as the underlying column. The mentioned columns all use the AipsIO storage manager. The main use of this is for the synthesis package where corrected and model visibilities are stored as new DATA columns in an MS which references the raw MS for the other columns. Except for these special cases, the use of this function will be rare.

String antennaTableName() const
String dataDescriptionTableName() const
String dopplerTableName() const
String feedTableName() const
String fieldTableName() const
String flagCmdTableName() const
String freqOffsetTableName() const
String historyTableName() const
String observationTableName() const
String pointingTableName() const
String polarizationTableName() const
String processorTableName() const
String sourceTableName() const
String spectralWindowTableName() const
String stateTableName() const
String sysCalTableName() const
String weatherTableName() const

Return the name of each of the subtables. This should be used by the filler to create the subtables in the correct location.

MSAntenna& antenna()
MSDataDescription& dataDescription()
MSDoppler& doppler()
MSFeed& feed()
MSField& field()
MSFlagCmd& flagCmd()
MSFreqOffset& freqOffset()
MSHistory& history()
MSObservation& observation()
MSPointing& pointing()
MSPolarization& polarization()
MSProcessor& processor()
MSSource& source()
MSSpectralWindow& spectralWindow()
MSState& state()
MSSysCal& sysCal()
MSWeather& weather()
const MSAntenna& antenna() const
const MSDataDescription& dataDescription() const
const MSDoppler& doppler() const
const MSFeed& feed() const
const MSField& field() const
const MSFlagCmd& flagCmd() const
const MSFreqOffset& freqOffset() const
const MSHistory& history() const
const MSObservation& observation() const
const MSPointing& pointing() const
const MSPolarization& polarization() const
const MSProcessor& processor() const
const MSSource& source() const
const MSSpectralWindow& spectralWindow() const
const MSState& state() const
const MSSysCal& sysCal() const
const MSWeather& weather() const

Access functions for the subtables, using the MS-like interface for each

void initRefs(Bool clear=False)

Initialize the references to the subtables. You need to call this only if you assign new subtables to the table keywords. This also checks for validity of the table and its subtables. Set clear to True to clear the subtable references (used in assignment)

void createDefaultSubtables(Table::TableOption option=Table::Scratch)

Create default subtables: fills the required subtable keywords with tables of the correct type, mainly for testing and as an example of how to do this for specific fillers. In practice these tables will often have more things specified, like dimensions of arrays and storage managers for the various columns.

static void init()

Initialize the statics appropriately. This does not need to be called by users, it is called by the implementation class MSTableImpl.

Bool makeComplexData()

Create DATA column from existing FLOAT_DATA column. Noop if DATA already exists or neither exists (returns False in that case).

Bool validateMeasureRefs()

Validate Measure references - check that all Measure columns have their reference value set, report the ones that don't.

void flush(Bool sync=False)

Flush all the tables and subtables associated with this MeasurementSet. This function calls the Table::flush() function on the main table and all the standard subtables including optional subtables. See the Table class for a description of the sync argument.

void addCat()

temporary function to add the CATEGORY keyword to the FLAG_CATEGORY column if it isn't there yet. 2000/08/22 remove this and the calls next MS update

void checkVersion()

check that the MS is the latest version (2.0)