casacore
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
this file contains all the compiler specific defines
Definition: mainpage.dox:28