casacore
ms
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
35
namespace
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
casacore
this file contains all the compiler specific defines
Definition:
mainpage.dox:28
Generated by
1.8.17