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