casacore
Loading...
Searching...
No Matches
MeasurementSets.h
Go to the documentation of this file.
1//# MeasurementSets.h: Handle storage and access of the telescope data
2//# Copyright (C) 1996,1997
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//# $Id$
27
28#ifndef MS_MEASUREMENTSETS_H
29#define MS_MEASUREMENTSETS_H
30
31#include <casacore/casa/aips.h>
32#include <casacore/ms/MeasurementSets/MeasurementSet.h>
33#include <casacore/ms/MeasurementSets/MSColumns.h>
34
35namespace casacore { //# NAMESPACE CASACORE - BEGIN
36
37// <module>
38//
39// <summary>
40// Handle storage and access of telescope data
41// </summary>
42
43// <prerequisite>
44// <li> <linkto module="Tables:description">Tables</linkto> module
45// <li> <a href="../notes/229.html">Note 229</a>
46// </prerequisite>
47//
48//
49// <reviewed reviewer="Bob Garwood" date="1997/02/01" demos="">
50// </reviewed>
51
52// <etymology>
53// The MeasurementSet is where all data are ultimately to be found
54// in Casacore. Since, this is a collection of
55// measurements (either actual or simulated), the term MeasurementSet
56// seems appropriate. Often we use the abbreviation (and typedef) MS for
57// MeasurementSet.
58// </etymology>
59//
60// <synopsis>
61// The MeasurementSets module handles storage of telescope data and access
62// to it. The MeasurementSet is the class that gives access to the data.
63//
64// A <linkto class=MeasurementSet>MeasurementSet</linkto> (MS)
65// is a Table with subtables stored as keywords.
66// For each of these tables there is a separate class: the main table is
67// MeasurementSet, the subtables are MSAntenna,
68// MSArray, MSFeed, MSField, MSObsLog, MSObservation, MSSource,
69// MSSpectralWindow, MSSysCal, MSWeather.
70//
71// <h4> Class hierarchy and Table layout </h4>
72// Each table has a number
73// of predefined columns and keywords, a subset of which is required to be
74// present. The column and keyword layout of each table is described in
75// <a href="../notes/229.html">Note 229</a>
76// and in a separate class which contains two enum definitions.
77// The enum classes, e.g.,
78// <linkto class=MSMainEnums>MSMainEnums</linkto> and
79// <linkto class=MSAntennaEnums>MSAntennaEnums</linkto>, just contain a
80// PredefinedColumn (PDC) enum and a PredefinedKeyword (PDK) enum. These enum
81// definitions are used as template arguments for the generic class
82// <linkto class=MSTable><src>MSTable<PDC,PDK></src></linkto> from which MeasurementSet
83// and all the subtable classes are derived.
84// Thus, e.g., the class MSAntenna is derived from <src>
85// MSTable<MSAntennaEnums::PredefinedColumns, MSAntennaEnums::PredefinedKeywords></src>.
86//
87// The MSTable class
88// provides a large number of common column and keyword helper functions.
89// They are useful when creating a Table following the MeasurementSet
90// conventions from scratch and assist in following the agreed upon
91// column and keyword naming conventions.
92//
93// MSTable in turn is derived from Table, thus all the MS table classes are
94// Tables. Many operations on a MeasurementSet are Table operations. See the
95// <linkto module="Tables:description">Tables</linkto> module for a list of
96// those operations.
97//
98// The reason for this class hierarchy is to provide each of the table classes
99// with a separate namespace for its column and keyword enums, so that
100// e.g., they can all have a column named TIME, while sharing as much code
101// as possible. The MSTable class forwards any substantial work
102// to the MSTableImpl class which does the actual work, it is a purely
103// implementation class with static functions not of interest to the user.
104//
105// <h4> Access to columns </h4>
106// To simplify the access of columns, and catch type errors in
107// the column declarations for column access objects (TableColumns) at
108// compile time, there is a helper class for each (sub)table (e.g.,
109// MSFieldColumns). The helper class for the MeasurementSet,
110// MSColumns gives access to the main table columns and the helper objects
111// for all subtables.
112//
113// At present these classes are separate from the Table classes, mainly
114// to ensure that the member functions are only called on valid, completely
115// constructed MeasurementSet Tables. They also represent a large amount
116// of 'state' in the form of TableColumn objects of which only a couple
117// may actually be used.
118//
119// <h4> Units and Measures </h4>
120// Columns in the MeasurementSet and its subtables can have several
121// keywords attached to describe the contents of the column.
122// The UNIT keyword contains an ASCII string describing the unit of
123// the values in the column. The unit member function (in MSTable) will
124// return this unit string, it can be used to construct a
125// <linkto class=Unit>Unit</linkto> object for a particular column.
126//
127// The MEASURE_TYPE keyword gives the Casacore Measure that applies to the
128// column (if any). See the
129// <linkto module="Measures:description">Measures</linkto> module for a
130// list of available Measures and their use.
131//
132// The MEASURE_REFERENCE keyword gives (part of) the reference frame needed
133// to interpret the values in a column. An example is J2000 for the POSITION
134// column. A number of static functions in MeasurementSet are available to
135// create a 'template' Measure for a column, which has the MEASURE_TYPE filled
136// in. Currently the following functions exist: directionMeasure,
137// positionMeasure, epochMeasure and frequencyMeasure. They return a
138// Measure which can then be filled with a value from a particular row from
139// the column to obtain, e.g., a proper MDirection Measure for the phase
140// center.
141//
142// <h4> Reference Tables </h4>
143// Each of the MS classes has a member function
144// referenceCopy which takes the name of a new Table and a list (Block) of
145// column names to create a Table which references all columns in the
146// original table, except for those listed. The listed columns are
147// new columns which can be written to without affecting the original Table.
148// The main use of this is for the synthesis package where corrected and
149// model visibilities are stored as new DATA columns in an MS which
150// references the raw MS for the other columns. Except for these special
151// cases, the use of this function will be rare.
152//
153// <h4> DATA and FLOAT_DATA columns </h4>
154// To accommodate both synthesis and single dish data efficiently, it was
155// decided that a MeasurementSet can have a Complex DATA column,
156// a float FLOAT_DATA column or both. If it has only a FLOAT_DATA column, the
157// corresponding DATA column can be created with the makeComplexData()
158// member function. In special cases, both columns could be present but
159// filled for different rows, with an extra index defined indicating in
160// which column to look (e.g., multi-feed single dish with cross correlations).
161// The details of this last scheme are yet to be worked out.
162// The table consistency checks (isValid()) do not require the presence
163// of either column.
164//
165// <h4> Unset values in MeasurementSet Tables </h4>
166// For ID columns, the rule is that a value of -1 indicates that there is
167// no corresponding subtable in which to look up details. An example is
168// the PULSAR_ID column, which should be set to -1 if the optional
169// PULSAR subtable does not exist.
170//
171// The rules for non integer unset values in MS tables have not
172// settled down yet.
173// For Floating point and Complex values the recommended practice is
174// to set the values to the FITS and IEEE value NaN,
175// with a bit pattern of all 1's.
176// In much of the present filler code unused values are filled with 0 instead.
177//
178// <h4> Table destruction </h4>
179// Upon destruction, the table and all subtables are checked to see that the
180// MeasurementSet remains valid, i.e., all required columns are present.
181// An exception is thrown if not all required columns are present
182// Nevertheless, the table will be flushed to disk if it is writable -
183// preserving its state.
184//
185//
186// <h4> MS shorthand </h4>
187// While the class name, MeasurementSet, is descriptive, it is often
188// too long for many common uses. The typedef MS is provided as
189// a convenient shorthand for MeasurementSet. The example below uses this
190// typedef.
191//
192//
193// </synopsis>
194//
195// <example>
196// This example illustrates creation and filling of the MeasurementSet.
197// <srcblock>
198// // create the table descriptor
199// TableDesc simpleDesc = MS::requiredTableDesc()
200// // set up a new table
201// SetupNewTable newTab("simpleTab", simpleDesc, Table::New);
202// // create the MeasurementSet
203// MeasurementSet simpleMS(newTab);
204// // now we need to define all required subtables
205// // the following call does this for us if we don't need to
206// // specify details of Storage Managers or non-standard columns.
207// simpleMS.createDummySubtables(Table::New);
208// // fill MeasurementSet via its Table interface
209// // For example, construct one of the column access objects.
210// TableColumn feed(simpleMS, MS::columnName(MS::FEED1));
211// uInt rownr = 0;
212// // add a row
213// simpleMS.addRow();
214// // set the values in that row, e.g. the feed column
215// feed.putScalar(rownr,1);
216// // Access the position column in the ANTENNA subtable
217// ArrayColumn<Double> antpos(simpleMS.antenna(),
218// MSAntenna::columnName(MSAntenna::POSITION));
219// // Add a row to it and fill in the position
220// simpleMS.antenna().addRow();
221// Array<Double> position(3);
222// position(0)=1.; position(1)=2.; position(2)=3.;
223// antpos.put(0,position);
224// // .
225// // For standard columns the above can be done more easily using
226// // the MSColumns object.
227// // Create the MSColumns
228// MSColumns msc(simpleMS);
229// // and fill in the position
230// msc.antenna().position().put(0,position);
231// </srcblock>
232//
233// </example>
234
235// <example>
236// This example illustrates read only access to an existing MeasurementSet
237// and creation of an MDirection Measure for the phase center.
238// <srcblock>
239// // Create the MeasurementSet from an existing Table on disk
240// MeasurementSet ms("myMS");
241// // Create the RO column access objects for main table and subtables
242// MSColumns msc(ms);
243// // show data from row 5
244// cout << msc.data()(5) << endl;
245// // show phase center for row 3 in field table
246// Vector<double> phaseCtr=msc.field().phaseCenter()(3);
247// cout << phaseCtr<<endl;
248// // now create a Measure for the phaseCenter
249// MDirection phaseCenterMeasure =
250// MS::directionMeasure(msc.field().phaseCenter());
251// // put the value from row 3 in the Measure and print it
252// phaseCenterMeasure.set(MVPosition(phaseCtr));
253// cout <<"phase center:"<< phaseCenterMeasure<<endl;
254//
255// </srcblock>
256//
257// </example>
258//
259// <motivation>
260// The attempt is to define a single, extensible, Table format that will
261// be able to cope with all, or at least most, radio telescope data.
262// Having a single MeasurementSet should make it easier to combine data
263// from different instruments. The format of the MeasurementSet,
264// table with subtables, was chosen to be able to cope with items
265// varying at different rates more efficiently than a 'flat' Table layout
266// would allow.
267// </motivation>
268
269// <todo asof="1997/02/01">
270// <li> Incorporate the MSColumn classes in the MeasurementSet classes?
271// <li> Variable (row to row) ReferenceFrame (e.g., J2000 mixed with
272// galactic, different Frequency reference frames mixed in the
273// same MS, etc.). This could be done with a column named
274// "column_name"_MEASURE_REFERENCE for each column with varying
275// Measure reference frames.
276// </todo>
277
278// </module>
279
280
281} //# NAMESPACE CASACORE - END
282
283#endif
this file contains all the compiler specific defines
Definition mainpage.dox:28