casa::MeasurementSet Class Reference
[MeasurementSets]

#include <MeasurementSet.h>

Inheritance diagram for casa::MeasurementSet:

[legend]Collaboration diagram for casa::MeasurementSet:

[legend]List of all members.

---

Detailed Description

A Table intended to hold astronomical data (a set of Measurements).

Intended use:

Part of API

Review Status

Reviewed By:

Bob Garwood

Date Reviewed:

1997/02/01

Test programs:

tMeasurementSet

Prerequisite

Tables module MSTable

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 provide one location where the column and keyword names, data types, and table comment strings are found.
• To provide one location where the required table descriptor for the MeasurementSet is found.
• To provide a means of verifying the validity of a MeasurementSet at construction and destruction.
• To allow application programmers to catch name or data type mistakes at compile time rather than at run time.

To Do

• referenceCopy() should be more flexible with the storage managers used for the columns which are not merely references.
• 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().

Definition at line 199 of file MeasurementSet.h.

Public Member Functions
	MeasurementSet ()
	This constructs an empty MeasurementSet, only useful to assign to (it is not a valid MS yet).
	~MeasurementSet ()
	As with tables, the destructor writes the table if necessary.
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.
void	initRefs (Bool clear=False)
	Initialize the references to the subtables.
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.
Bool	makeComplexData ()
	Create DATA column from existing FLOAT_DATA column.
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.
Record	msseltoindex (const String &spw="", const String &field="", const String &baseline="", const String &time="", const String &scan="", const String &uvrange="", const String &taql="")
	Return a record of the indices that the msselection selection selected.
String	antennaTableName () const
	Return the name of each of the subtables.
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 ()
	Access functions for the subtables, using the MS-like interface for each.
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
Static Public Member Functions
static void	init ()
	Initialize the statics appropriately.
Private Member Functions
void	addCat ()
	temporary function to add the CATEGORY keyword to the FLAG_CATEGORY column if it isn't there yet.
void	checkVersion ()
	check that the MS is the latest version (2.0)
Private Attributes
MSAntenna	antenna_p
	keep references to the subtables
MSDataDescription	dataDesc_p
MSDoppler	doppler_p
MSFeed	feed_p
MSField	field_p
MSFlagCmd	flagCmd_p
MSFreqOffset	freqOffset_p
MSHistory	history_p
MSObservation	observation_p
MSPointing	pointing_p
MSPolarization	polarization_p
MSProcessor	processor_p
MSSource	source_p
MSSpectralWindow	spectralWindow_p
MSState	state_p
MSSysCal	sysCal_p
MSWeather	weather_p
Bool	hasBeenDestroyed_p
	required by the need to throw an exception in the destructor
TableLock	mainLock_p

---

Constructor & Destructor Documentation

casa::MeasurementSet::MeasurementSet

(

)

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

casa::MeasurementSet::MeasurementSet	(	const String &	tableName,
		TableOption	= Table::Old
	)

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

• AipsError

casa::MeasurementSet::MeasurementSet	(	const String &	tableName,
		const TableLock &	lockOptions,
		TableOption	= Table::Old
	)

casa::MeasurementSet::MeasurementSet	(	const String &	tableName,
		const String &	tableDescName,
		TableOption	= Table::Old
	)

casa::MeasurementSet::MeasurementSet	(	const String &	tableName,
		const String &	tableDescName,
		const TableLock &	lockOptions,
		TableOption	= Table::Old
	)

casa::MeasurementSet::MeasurementSet	(	SetupNewTable &	newTab,
		uInt	nrrow = 0,
		Bool	initialize = False
	)

casa::MeasurementSet::MeasurementSet	(	SetupNewTable &	newTab,
		const TableLock &	lockOptions,
		uInt	nrrow = 0,
		Bool	initialize = False
	)

casa::MeasurementSet::MeasurementSet

(

const Table &

table

)

casa::MeasurementSet::MeasurementSet

(

const MeasurementSet &

other

)

casa::MeasurementSet::~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

• AipsError

casa::MeasurementSet::MeasurementSet	(	const String &	tableName,
		TableOption	= Table::Old
	)

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

• AipsError

casa::MeasurementSet::MeasurementSet	(	const String &	tableName,
		const TableLock &	lockOptions,
		TableOption	= Table::Old
	)

casa::MeasurementSet::MeasurementSet	(	const String &	tableName,
		const String &	tableDescName,
		TableOption	= Table::Old
	)

casa::MeasurementSet::MeasurementSet	(	const String &	tableName,
		const String &	tableDescName,
		const TableLock &	lockOptions,
		TableOption	= Table::Old
	)

casa::MeasurementSet::MeasurementSet	(	SetupNewTable &	newTab,
		uInt	nrrow = 0,
		Bool	initialize = False
	)

casa::MeasurementSet::MeasurementSet	(	SetupNewTable &	newTab,
		const TableLock &	lockOptions,
		uInt	nrrow = 0,
		Bool	initialize = False
	)

casa::MeasurementSet::MeasurementSet

(

const Table &

table

)

casa::MeasurementSet::MeasurementSet

(

const MeasurementSet &

other

)

---

Member Function Documentation

MeasurementSet& casa::MeasurementSet::operator=

(

const MeasurementSet &

)

Assignment operator, reference semantics.

MeasurementSet casa::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.

Reimplemented from casa::MSTable< ColEnum, KeyEnum >.

String casa::MeasurementSet::antennaTableName

(

)

const

Return the name of each of the subtables.

This should be used by the filler to create the subtables in the correct location.

String casa::MeasurementSet::dataDescriptionTableName

(

)

const

String casa::MeasurementSet::dopplerTableName

(

)

const

String casa::MeasurementSet::feedTableName

(

)

const

String casa::MeasurementSet::fieldTableName

(

)

const

String casa::MeasurementSet::flagCmdTableName

(

)

const

String casa::MeasurementSet::freqOffsetTableName

(

)

const

String casa::MeasurementSet::historyTableName

(

)

const

String casa::MeasurementSet::observationTableName

(

)

const

String casa::MeasurementSet::pointingTableName

(

)

const

String casa::MeasurementSet::polarizationTableName

(

)

const

String casa::MeasurementSet::processorTableName

(

)

const

String casa::MeasurementSet::sourceTableName

(

)

const

String casa::MeasurementSet::spectralWindowTableName

(

)

const

String casa::MeasurementSet::stateTableName

(

)

const

String casa::MeasurementSet::sysCalTableName

(

)

const

String casa::MeasurementSet::weatherTableName

(

)

const

MSAntenna& casa::MeasurementSet::antenna

(

)

[inline]

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

Definition at line 279 of file MeasurementSet.h.

References antenna_p.

MSDataDescription& casa::MeasurementSet::dataDescription

(

)

[inline]

Definition at line 280 of file MeasurementSet.h.

References dataDesc_p.

Referenced by casa::MSPlotMainMSCallBack::printlocateinfo(), and casa::MSPlotUVWCallBack::printlocateinfo().

MSDoppler& casa::MeasurementSet::doppler

(

)

[inline]

Definition at line 281 of file MeasurementSet.h.

References doppler_p.

MSFeed& casa::MeasurementSet::feed

(

)

[inline]

Definition at line 282 of file MeasurementSet.h.

References feed_p.

MSField& casa::MeasurementSet::field

(

)

[inline]

Definition at line 283 of file MeasurementSet.h.

References field_p.

MSFlagCmd& casa::MeasurementSet::flagCmd

(

)

[inline]

Definition at line 284 of file MeasurementSet.h.

References flagCmd_p.

MSFreqOffset& casa::MeasurementSet::freqOffset

(

)

[inline]

Definition at line 285 of file MeasurementSet.h.

References freqOffset_p.

MSHistory& casa::MeasurementSet::history

(

)

[inline]

Definition at line 286 of file MeasurementSet.h.

References history_p.

MSObservation& casa::MeasurementSet::observation

(

)

[inline]

Definition at line 287 of file MeasurementSet.h.

References observation_p.

MSPointing& casa::MeasurementSet::pointing

(

)

[inline]

Definition at line 288 of file MeasurementSet.h.

References pointing_p.

MSPolarization& casa::MeasurementSet::polarization

(

)

[inline]

Definition at line 289 of file MeasurementSet.h.

References polarization_p.

MSProcessor& casa::MeasurementSet::processor

(

)

[inline]

Definition at line 290 of file MeasurementSet.h.

References processor_p.

MSSource& casa::MeasurementSet::source

(

)

[inline]

Definition at line 291 of file MeasurementSet.h.

References source_p.

MSSpectralWindow& casa::MeasurementSet::spectralWindow

(

)

[inline]

Definition at line 292 of file MeasurementSet.h.

References spectralWindow_p.

MSState& casa::MeasurementSet::state

(

)

[inline]

Definition at line 293 of file MeasurementSet.h.

References state_p.

MSSysCal& casa::MeasurementSet::sysCal

(

)

[inline]

Definition at line 294 of file MeasurementSet.h.

References sysCal_p.

MSWeather& casa::MeasurementSet::weather

(

)

[inline]

Definition at line 295 of file MeasurementSet.h.

References weather_p.

const MSAntenna& casa::MeasurementSet::antenna

(

)

const [inline]

Definition at line 296 of file MeasurementSet.h.

References antenna_p.

const MSDataDescription& casa::MeasurementSet::dataDescription

(

)

const [inline]

Definition at line 297 of file MeasurementSet.h.

References dataDesc_p.

const MSDoppler& casa::MeasurementSet::doppler

(

)

const [inline]

Definition at line 298 of file MeasurementSet.h.

References doppler_p.

const MSFeed& casa::MeasurementSet::feed

(

)

const [inline]

Definition at line 299 of file MeasurementSet.h.

References feed_p.

const MSField& casa::MeasurementSet::field

(

)

const [inline]

Definition at line 300 of file MeasurementSet.h.

References field_p.

const MSFlagCmd& casa::MeasurementSet::flagCmd

(

)

const [inline]

Definition at line 301 of file MeasurementSet.h.

References flagCmd_p.

const MSFreqOffset& casa::MeasurementSet::freqOffset

(

)

const [inline]

Definition at line 302 of file MeasurementSet.h.

References freqOffset_p.

const MSHistory& casa::MeasurementSet::history

(

)

const [inline]

Definition at line 303 of file MeasurementSet.h.

References history_p.

const MSObservation& casa::MeasurementSet::observation

(

)

const [inline]

Definition at line 304 of file MeasurementSet.h.

References observation_p.

const MSPointing& casa::MeasurementSet::pointing

(

)

const [inline]

Definition at line 305 of file MeasurementSet.h.

References pointing_p.

const MSPolarization& casa::MeasurementSet::polarization

(

)

const [inline]

Definition at line 306 of file MeasurementSet.h.

References polarization_p.

const MSProcessor& casa::MeasurementSet::processor

(

)

const [inline]

Definition at line 307 of file MeasurementSet.h.

References processor_p.

const MSSource& casa::MeasurementSet::source

(

)

const [inline]

Definition at line 308 of file MeasurementSet.h.

References source_p.

const MSSpectralWindow& casa::MeasurementSet::spectralWindow

(

)

const [inline]

Definition at line 309 of file MeasurementSet.h.

References spectralWindow_p.

const MSState& casa::MeasurementSet::state

(

)

const [inline]

Definition at line 310 of file MeasurementSet.h.

References state_p.

const MSSysCal& casa::MeasurementSet::sysCal

(

)

const [inline]

Definition at line 311 of file MeasurementSet.h.

References sysCal_p.

const MSWeather& casa::MeasurementSet::weather

(

)

const [inline]

Definition at line 312 of file MeasurementSet.h.

References weather_p.

void casa::MeasurementSet::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 casa::MeasurementSet::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 casa::MeasurementSet::init

(

)

[static]

Initialize the statics appropriately.

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

Bool casa::MeasurementSet::makeComplexData

(

)

Create DATA column from existing FLOAT_DATA column.

Noop if DATA already exists or neither exists (returns False in that case).

Bool casa::MeasurementSet::validateMeasureRefs

(

)

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

void casa::MeasurementSet::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.

Record casa::MeasurementSet::msseltoindex	(	const String &	spw = "",
		const String &	field = "",
		const String &	baseline = "",
		const String &	time = "",
		const String &	scan = "",
		const String &	uvrange = "",
		const String &	taql = ""
	)

Return a record of the indices that the msselection selection selected.

void casa::MeasurementSet::addCat

(

)

[private]

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 casa::MeasurementSet::checkVersion

(

)

[private]

check that the MS is the latest version (2.0)

---

Member Data Documentation

MSAntenna casa::MeasurementSet::antenna_p [private]

keep references to the subtables

Definition at line 364 of file MeasurementSet.h.

Referenced by antenna().

MSDataDescription casa::MeasurementSet::dataDesc_p [private]

Definition at line 365 of file MeasurementSet.h.

Referenced by dataDescription().

MSDoppler casa::MeasurementSet::doppler_p [private]

Definition at line 366 of file MeasurementSet.h.

Referenced by doppler().

MSFeed casa::MeasurementSet::feed_p [private]

Definition at line 367 of file MeasurementSet.h.

Referenced by feed().

MSField casa::MeasurementSet::field_p [private]

Definition at line 368 of file MeasurementSet.h.

Referenced by field().

MSFlagCmd casa::MeasurementSet::flagCmd_p [private]

Definition at line 369 of file MeasurementSet.h.

Referenced by flagCmd().

MSFreqOffset casa::MeasurementSet::freqOffset_p [private]

Definition at line 370 of file MeasurementSet.h.

Referenced by freqOffset().

MSHistory casa::MeasurementSet::history_p [private]

Definition at line 371 of file MeasurementSet.h.

Referenced by history().

MSObservation casa::MeasurementSet::observation_p [private]

Definition at line 372 of file MeasurementSet.h.

Referenced by observation().

MSPointing casa::MeasurementSet::pointing_p [private]

Definition at line 373 of file MeasurementSet.h.

Referenced by pointing().

MSPolarization casa::MeasurementSet::polarization_p [private]

Definition at line 374 of file MeasurementSet.h.