casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
MeasurementSets.h
Go to the documentation of this file.
00001 //# MeasurementSets.h:  Handle storage and access of the telescope data
00002 //# Copyright (C) 1996,1997
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: MeasurementSets.h 20691 2009-07-14 03:13:54Z Malte.Marquarding $
00027 
00028 #ifndef MS_MEASUREMENTSETS_H
00029 #define MS_MEASUREMENTSETS_H
00030 
00031 #include <ms/MeasurementSets/MeasurementSet.h>
00032 #include <ms/MeasurementSets/MSColumns.h>
00033 
00034 namespace casa { //# NAMESPACE CASA - BEGIN
00035 
00036 // <module>
00037 //
00038 // <summary>
00039 // Handle storage and access of telescope data
00040 // </summary>
00041 
00042 // <prerequisite>
00043 //   <li> <linkto module="Tables:description">Tables</linkto> module
00044 //   <li> <a href="../notes/229.html">Note 229</a>
00045 // </prerequisite>
00046 //
00047 //
00048 // <reviewed reviewer="Bob Garwood" date="1997/02/01" demos="">
00049 // </reviewed>
00050 
00051 // <etymology>
00052 // The MeasurementSet is where all data are ultimately to be found
00053 // in AIPS++.  Since, this is a collection of 
00054 // measurements (either actual or simulated), the term MeasurementSet
00055 // seems appropriate. Often we use the abbreviation (and typedef) MS for
00056 // MeasurementSet.
00057 // </etymology>
00058 //
00059 // <synopsis>
00060 // The MeasurementSets module handles storage of telescope data and access
00061 // to it. The MeasurementSet is the class that gives access to the data.
00062 //
00063 // A <linkto class=MeasurementSet>MeasurementSet</linkto> (MS) 
00064 // is a Table with subtables stored as keywords. 
00065 // For each of these tables there is a separate class: the main table is
00066 // MeasurementSet, the subtables are MSAntenna, 
00067 // MSArray, MSFeed, MSField, MSObsLog, MSObservation, MSSource, 
00068 // MSSpectralWindow, MSSysCal, MSWeather. 
00069 //
00070 // <h4> Class hierarchy and Table layout </h4>
00071 // Each table has a number
00072 // of predefined columns and keywords, a subset of which is required to be
00073 // present. The column and keyword layout of each table is described in
00074 // <a href="../notes/229.html">Note 229</a>
00075 // and in a separate class which contains two enum definitions.
00076 // The enum classes, e.g., 
00077 // <linkto class=MSMainEnums>MSMainEnums</linkto> and 
00078 // <linkto class=MSAntennaEnums>MSAntennaEnums</linkto>, just contain a
00079 // PredefinedColumn (PDC) enum and a PredefinedKeyword (PDK) enum. These enum 
00080 // definitions are used as template arguments for the generic class
00081 // <linkto class=MSTable><src>MSTable<PDC,PDK></src></linkto> from which MeasurementSet 
00082 // and all the subtable classes are derived. 
00083 // Thus, e.g., the class MSAntenna is derived from <src>
00084 // MSTable<MSAntennaEnums::PredefinedColumns, MSAntennaEnums::PredefinedKeywords></src>. 
00085 // 
00086 // The MSTable class
00087 // provides a large number of common column and keyword helper functions.
00088 // They are useful when creating a Table following the MeasurementSet  
00089 // conventions from scratch and assist in following the agreed upon 
00090 // column and keyword naming conventions.
00091 // 
00092 // MSTable in turn is derived from Table, thus all the MS table classes are
00093 // Tables. Many operations on a MeasurementSet are Table operations. See the 
00094 // <linkto module="Tables:description">Tables</linkto> module for a list of 
00095 // those operations.
00096 //
00097 // The reason for this class hierarchy is to provide each of the table classes
00098 // with a separate namespace for its column and keyword enums, so that
00099 // e.g., they can all have a column named TIME, while sharing as much code
00100 // as possible. The MSTable class forwards any substantial work
00101 // to the MSTableImpl class which does the actual work, it is a purely
00102 // implementation class with static functions not of interest to the user.
00103 // 
00104 // <h4> Access to columns </h4>
00105 // To simplify the access of columns, and catch type errors in
00106 // the column declarations for column access objects (TableColumns) at
00107 // compile time, there is a helper class for each (sub)table (e.g., 
00108 // MSFieldColumns). The helper class for the MeasurementSet, 
00109 // MSColumns gives access to the main table columns and the helper objects 
00110 // for all subtables. A read-only version of these classes is also
00111 // provided (e.g., ROMSFieldColumns).
00112 //
00113 // At present these classes are separate from the Table classes, mainly
00114 // to ensure that the member functions are only called on valid, completely
00115 // constructed MeasurementSet Tables. They also represent a large amount
00116 // of 'state' in the form of TableColumn objects of which only a couple
00117 // may actually be used.
00118 // 
00119 // <h4> Units and Measures </h4>
00120 // Columns in the MeasurementSet and its subtables can have several 
00121 // keywords attached to describe the contents of the column.
00122 // The UNIT keyword contains an ASCII string describing the unit of
00123 // the values in the column. The unit member function (in MSTable) will
00124 // return this unit string, it can be used to construct a 
00125 // <linkto class=Unit>Unit</linkto> object for a particular column.
00126 //
00127 // The MEASURE_TYPE keyword gives the AIPS++ Measure that applies to the
00128 // column (if any). See the 
00129 //  <linkto module="Measures:description">Measures</linkto> module for a 
00130 // list of available Measures and their use.
00131 //
00132 // The MEASURE_REFERENCE keyword gives (part of) the reference frame needed
00133 // to interpret the values in a column. An example is J2000 for the POSITION
00134 // column. A number of static functions in MeasurementSet are available to
00135 // create a 'template' Measure for a column, which has the MEASURE_TYPE filled
00136 // in. Currently the following functions exist: directionMeasure, 
00137 // positionMeasure, epochMeasure and frequencyMeasure. They return a 
00138 // Measure which can then be filled with a value from a particular row from
00139 // the column to obtain, e.g., a proper MDirection Measure for the phase
00140 // center. 
00141 //
00142 // <h4> Reference Tables </h4>
00143 // Each of the MS classes has a member function
00144 // referenceCopy which takes the name of a new Table and a list (Block) of
00145 // column names to create a Table which references all columns in the
00146 // original table, except for those listed. The listed columns are 
00147 // new columns which can be written to without affecting the original Table.
00148 // The main use of this is for the synthesis package where corrected and
00149 // model visibilities are stored as new DATA columns in an MS which 
00150 // references the raw MS for the other columns. Except for these special
00151 // cases, the use of this function will be rare.
00152 //
00153 // <h4> DATA and FLOAT_DATA columns </h4>
00154 // To accommodate both synthesis and single dish data efficiently, it was 
00155 // decided that a MeasurementSet can have a Complex DATA column,
00156 // a float FLOAT_DATA column or both. If it has only a FLOAT_DATA column, the
00157 // corresponding DATA column can be created with the makeComplexData()
00158 // member function. In special cases, both columns could be present but
00159 // filled for different rows, with an extra index defined indicating in
00160 // which column to look (e.g., multi-feed single dish with cross correlations).
00161 // The details of this last scheme are yet to be worked out. 
00162 // The table consistency checks (isValid()) do not require the presence 
00163 // of either column.
00164 //
00165 // <h4> Unset values in MeasurementSet Tables </h4>
00166 // For ID columns, the rule is that a value of -1 indicates that there is
00167 // no corresponding subtable in which to look up details. An example is
00168 // the PULSAR_ID column, which should be set to -1 if the optional 
00169 // PULSAR subtable does not exist.
00170 //
00171 // The rules for non integer unset values in MS tables have not 
00172 // settled down yet.
00173 // For Floating point and Complex values the recommended practice is
00174 // to set the values to the FITS and IEEE value NaN, 
00175 // with a bit pattern of all 1's.
00176 // In much of the present filler code unused values are filled with 0 instead.
00177 //
00178 // <h4> Table destruction </h4>
00179 // Upon destruction, the table and all subtables are checked to see that the
00180 // MeasurementSet remains valid, i.e., all required columns are present.
00181 // An exception is thrown if not all required columns are present
00182 // Nevertheless, the table will be flushed to disk if it is writable -
00183 // preserving its state.
00184 //
00185 //
00186 // <h4> MS shorthand </h4>
00187 // While the class name, MeasurementSet, is descriptive, it is often
00188 // too long for many common uses.  The typedef MS is provided as
00189 // a convenient shorthand for MeasurementSet.  The example below uses this
00190 // typedef.
00191 // 
00192 //
00193 // </synopsis> 
00194 //
00195 // <example>
00196 // This example illustrates creation and filling of the MeasurementSet.
00197 // <srcblock>
00198 //      // create the table descriptor
00199 //      TableDesc simpleDesc = MS::requiredTableDesc()
00200 //      // set up a new table
00201 //      SetupNewTable newTab("simpleTab", simpleDesc, Table::New);
00202 //      // create the MeasurementSet
00203 //      MeasurementSet simpleMS(newTab);
00204 //      // now we need to define all required subtables
00205 //      // the following call does this for us if we don't need to
00206 //      // specify details of Storage Managers or non-standard columns.
00207 //      simpleMS.createDummySubtables(Table::New);
00208 //      // fill MeasurementSet via its Table interface
00209 //      // For example, construct one of the column access objects.
00210 //      TableColumn feed(simpleMS, MS::columnName(MS::FEED1));
00211 //      uInt rownr = 0;
00212 //      // add a row
00213 //      simpleMS.addRow();
00214 //      // set the values in that row, e.g. the feed column
00215 //      feed.putScalar(rownr,1);
00216 //      // Access the position column in the ANTENNA subtable
00217 //      ArrayColumn<Double> antpos(simpleMS.antenna(),
00218 //                                 MSAntenna::columnName(MSAntenna::POSITION));
00219 //      // Add a row to it and fill in the position
00220 //      simpleMS.antenna().addRow();
00221 //      Array<Double> position(3); 
00222 //      position(0)=1.; position(1)=2.; position(2)=3.;
00223 //      antpos.put(0,position);
00224 //      // .
00225 //      // For standard columns the above can be done more easily using 
00226 //      // the MSColumns object.
00227 //      // Create the MSColumns
00228 //      MSColumns msc(simpleMS);
00229 //      // and fill in the position
00230 //      msc.antenna().position().put(0,position);
00231 // </srcblock>
00232 //
00233 // </example>
00234 
00235 // <example>
00236 // This example illustrates read only access to an existing MeasurementSet
00237 // and creation of an MDirection Measure for the phase center.
00238 // <srcblock>
00239 //      // Create the MeasurementSet from an existing Table on disk
00240 //      MeasurementSet ms("myMS"); 
00241 //      // Create the RO column access objects for main table and subtables
00242 //      ROMSColumns msc(ms);
00243 //      // show data from row 5
00244 //      cout << msc.data()(5) << endl;
00245 //      // show phase center for row 3 in field table
00246 //      Vector<double> phaseCtr=msc.field().phaseCenter()(3);
00247 //      cout << phaseCtr<<endl;
00248 //      // now create a Measure for the phaseCenter
00249 //      MDirection phaseCenterMeasure =
00250 //         MS::directionMeasure(msc.field().phaseCenter());
00251 //      // put the value from row 3 in the Measure and print it
00252 //      phaseCenterMeasure.set(MVPosition(phaseCtr));
00253 //      cout <<"phase center:"<< phaseCenterMeasure<<endl;
00254 //
00255 // </srcblock>
00256 //
00257 // </example>
00258 //
00259 // <motivation>
00260 // The attempt is to define a single, extensible, Table format that will
00261 // be able to cope with all, or at least most, radio telescope data.
00262 // Having a single MeasurementSet should make it easier to combine data
00263 // from different instruments. The format of the MeasurementSet,
00264 // table with subtables, was chosen to be able to cope with items
00265 // varying at different rates more efficiently than a 'flat' Table layout
00266 // would allow.
00267 // </motivation>
00268 
00269 // <todo asof="1997/02/01">
00270 //   <li> Incorporate the MSColumn classes in the MeasurementSet classes?
00271 //   <li> Variable (row to row) ReferenceFrame (e.g., J2000 mixed with
00272 //      galactic, different Frequency reference frames mixed in the
00273 //      same MS, etc.). This could be done with a column named
00274 //     "column_name"_MEASURE_REFERENCE for each column with varying
00275 //     Measure reference frames.
00276 // </todo>
00277 
00278 // </module>
00279 
00280 
00281 } //# NAMESPACE CASA - END
00282 
00283 #endif
00284 
00285 
00286 
00287