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

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1