casacore
MeasurementSet.h
Go to the documentation of this file.
1 //# MeasurementSet.h: A Table to hold astronomical data (a set of Measurements)
2 //# Copyright (C) 1996,1997,1999,2000,2001,2003
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 //#
27 //# $Id$
28 
29 #ifndef MS_MEASUREMENTSET_H
30 #define MS_MEASUREMENTSET_H
31 
32 #include <casacore/casa/aips.h>
33 #include <casacore/ms/MeasurementSets/MSTable.h>
34 #include <casacore/ms/MeasurementSets/MSMainEnums.h>
35 #include <casacore/ms/MeasurementSets/MSAntenna.h>
36 #include <casacore/ms/MeasurementSets/MSDataDescription.h>
37 #include <casacore/ms/MeasurementSets/MSDoppler.h>
38 #include <casacore/ms/MeasurementSets/MSFeed.h>
39 #include <casacore/ms/MeasurementSets/MSField.h>
40 #include <casacore/ms/MeasurementSets/MSFlagCmd.h>
41 #include <casacore/ms/MeasurementSets/MSFreqOffset.h>
42 #include <casacore/ms/MeasurementSets/MSHistory.h>
43 #include <casacore/ms/MeasurementSets/MSObservation.h>
44 #include <casacore/ms/MeasurementSets/MSPointing.h>
45 #include <casacore/ms/MeasurementSets/MSPolarization.h>
46 #include <casacore/ms/MeasurementSets/MSProcessor.h>
47 #include <casacore/ms/MeasurementSets/MSSource.h>
48 #include <casacore/ms/MeasurementSets/MSSpectralWindow.h>
49 #include <casacore/ms/MeasurementSets/MSState.h>
50 #include <casacore/ms/MeasurementSets/MSSysCal.h>
51 #include <casacore/ms/MeasurementSets/MSWeather.h>
52 #include <set>
53 
54 
55 namespace casacore { //# NAMESPACE CASACORE - BEGIN
56 
57 class MrsEligibility { // Memory Resident Subtable (Mrs) Eligibility (no pun intended)
58 
59 public:
60 
62 
63  friend MrsEligibility operator- (const MrsEligibility & a, SubtableId subtableId);
64  friend MrsEligibility operator+ (const MrsEligibility & a, SubtableId subtableId);
65  friend MrsEligibility operator- (const MrsEligibility & a, const MrsEligibility & b);
66  friend MrsEligibility operator+ (const MrsEligibility & a, const MrsEligibility & b);
67 
68  // Returns true if the specified subtable is in the set of subtables
69  // eligible for memory residency.
70  Bool isEligible (SubtableId subtableId) const;
71 
72  // Factory methods to create MrsEligibility sets. The two variable argument methods
73  // require that the list be terminated by using the id MSMainEnums::UNDEFINED_KEYWORD.
74  //
75  static MrsEligibility allEligible ();
77  static MrsEligibility noneEligible ();
78  static MrsEligibility eligibleSubtables (SubtableId subtableId, ...);
79  static MrsEligibility allButTheseSubtables (SubtableId ineligibleSubtableId, ...);
80 
81 private:
82 
83  typedef std::set<MSMainEnums::PredefinedKeywords> Eligible;
84 
85  Eligible eligible_p;
86 
88 
89  static Bool isSubtable (SubtableId subtableId);
90 };
91 
92 // Creates a new MrsEligibilitySet by adding or removing the specified subtable or
93 // the specified set of subtables.
98 
99 //# Forward Declarations, more could be if they weren't part of the
100 //# static classes
101 class SetupNewTable;
102 template <class T> class Block;
103 class MDirection;
104 class MEpoch;
105 class MFrequency;
106 class MPosition;
107 class Record;
108 
109 //# forward declared so that the following typedef is up-front
111 
112 // MeasurementSet is too cumbersome for a number of common uses,
113 // so we give a typedef here.
114 typedef MeasurementSet MS;
115 
116 // <summary>
117 // A Table intended to hold astronomical data (a set of Measurements).
118 // </summary>
119 
120 // <use visibility=export>
121 
122 // <reviewed reviewer="Bob Garwood" date="1997/02/01" tests="tMeasurementSet.cc" demos="">
123 
124 // <prerequisite>
125 // <li> <linkto module="Tables:description">Tables</linkto> module
126 // <li> <linkto class="MSTable">MSTable</linkto>
127 // </prerequisite>
128 //
129 // <etymology>
130 // The MeasurementSet is where all data are ultimately to be found
131 // in Casacore. Since, this is a collection of
132 // measurements (either actual or simulated), the term MeasurementSet
133 // seems appropriate.
134 // </etymology>
135 //
136 // <synopsis>
137 // A MeasurementSet is a Table. Most operations on a MeasurementSet are
138 // Table operations. See the <linkto module="Tables:description">Tables</linkto>
139 // module for a list of those operations. The member functions provided by this
140 // class are primarily convenience functions to help users follow the
141 // agreed upon column and keyword naming conventions. They are useful when
142 // creating a Table following the MeasurementSet conventions from
143 // scratch as well as when creating the column objects to access those
144 // columns.
145 //
146 // The standard way of accessing
147 // table columns is through Strings. Mistakes in typing the column
148 // name will not be caught at compile time (and may not be caught at
149 // run time). We have therefore decided to use an enumeration
150 // to specify columns so that many mistakes will be caught at compile
151 // time. This requires functions to map to and from this enumeration
152 // to the strings that are ultimately used.
153 //
154 // Upon destruction, the table is checked to see that the
155 // MeasurementSet remains valid, i.e., all required columns are present
156 // An exception is thrown if not all required columns are present
157 // Nevertheless, the table will be flushed to disk if it is writable -
158 // preserving its state.
159 //
160 // A MeasurementSet has a number of required subtables. These are stored
161 // as keywords in the Table. Access to these subtables is provided via
162 // member functions (e.g. antenna() for the ANTENNA table). All subtables
163 // have associated MeasurementSet-like classes defined for them (MSAntenna
164 // for the ANTENNA table) which provide analogous column and keyword mapping
165 // as provided here.
166 //
167 // While the class name, MeasurementSet, is descriptive, it is often
168 // too long for many common uses. The typedef MS is provided as
169 // a convenient shorthand for MeasurementSet. The example below uses this
170 // typedef.
171 //
172 // Due to the inheritance scheme, it was necessary to separate the enumerations
173 // used by MeasurementSet into a separate class,
174 // <linkto class=MSMainEnums>MSMainEnums</linkto>.
175 //
176 // </synopsis>
177 //
178 // <example>
179 // This example illustrates a simple use of the MeasurementSet class.
180 // <srcblock>
181 // // create the table descriptor
182 // TableDesc simpleDesc = MS::requiredTableDesc();
183 // // set up a new table
184 // SetupNewTable newTab("simpleTab", simpleDesc, Table::New);
185 // // create the MeasurementSet
186 // MeasurementSet simpleMS(newTab);
187 // // now we need to define all required subtables
188 // // the following call does this for us if we don't need to
189 // // specify details of Storage Managers for columns.
190 // simpleMS.createDefaultSubtables(Table::New);
191 // // fill MeasurementSet via its Table interface
192 // // For example, construct one of the columns
193 // TableColumn feed(simpleMS, MS::columnName(MS::FEED1));
194 // uInt rownr = 0;
195 // // add a row
196 // simpleMS.addRow();
197 // // set the values in that row, e.g. the feed column
198 // feed.putScalar(rownr,1);
199 // // Access a subtable
200 // ArrayColumn<Double> antpos(simpleMS.antenna(),
201 // MSAntenna::columnName(MSAntenna::POSITION));
202 // simpleMS.antenna().addRow();
203 // Array<Double> position(3);
204 // position(0)=1.; position(1)=2.; position(2)=3.;
205 // antpos.put(0,position);
206 // // etc.
207 // </srcblock>
208 //
209 // </example>
210 //
211 // <motivation>
212 // The Table module is more than adequate as a container of data.
213 // However, in order for applications to be useful with data from
214 // different sources, some conventions need to be adopted in the use
215 // of Tables to store data. The MeasurementSet is
216 // where those conventions are defined and, to some extent, enforced.
217 //
218 // There are a number of reasons why MeasurementSet is more
219 // than just a Table.
220 // <ul>
221 // <li> To provide one location where the column and keyword names, data
222 // types, and table comment strings are found.
223 // <li> To provide one location where the required table descriptor for
224 // the MeasurementSet is found.
225 // <li> To provide a means of verifying the validity of a MeasurementSet
226 // at construction and destruction.
227 // <li> To allow application programmers to catch name or data type
228 // mistakes at compile time rather than at run time.
229 // </ul>
230 //
231 // </motivation>
232 //
233 // <todo asof="1996/2/22">
234 // <li> referenceCopy() should be more flexible with the storage managers used
235 // for the columns which are not merely references.
236 // <li> When ForwardColumnEngine is fixed so that it can deal with
237 // tables already in the cache, modify the test program. It may also
238 // be necessary to modify referenceCopy().
239 // </todo>
240 
241 class MeasurementSet : public MSTable<MSMainEnums::PredefinedColumns,
242  MSMainEnums::PredefinedKeywords>,
243  public MSMainEnums
244 {
245 
246 public:
247  // This constructs an empty MeasurementSet, only useful to assign to
248  // (it is not a valid MS yet).
249  MeasurementSet ();
250 
251  // These constructors mirror the Table ones with additional checking
252  // on validity (verifying that the MS will have the required columns
253  // and keywords)
254  // An exception is thrown if the constructed Table is not a valid MS
255  // <thrown>
256  // <li> AipsError
257  // </thrown>
258  // <group name=tableLikeConstructors>
259 
260  MeasurementSet (const String &tableName, TableOption = Table::Old);
261  MeasurementSet (const String &tableName, const TableLock& lockOptions,
263 
264  MeasurementSet (const String &tableName, const TableLock& lockOptions,
265  bool doNotLockSubtables, TableOption = Table::Old);
266  // Allows keeping subtables unlocked/read-locked independent of lock
267  // mode of main table.
268 
269  MeasurementSet (const String &tableName, const String &tableDescName,
271  MeasurementSet (const String &tableName, const String &tableDescName,
272  const TableLock& lockOptions, TableOption = Table::Old);
273  MeasurementSet (SetupNewTable &newTab, uInt nrrow = 0,
274  Bool initialize = False);
275  MeasurementSet (SetupNewTable &newTab, const TableLock& lockOptions,
276  uInt nrrow = 0, Bool initialize = False);
277  MeasurementSet (const Table &table, const MeasurementSet * otherMs = NULL);
278  MeasurementSet (const MeasurementSet &other);
279  // </group>
280 
281  // As with tables, the destructor writes the table if necessary.
282  // Additional checking is done here to verify that all required
283  // columns are still present.
284  // If it is NOT valid, it will write the table and then throw an exception.
285  // <thrown>
286  // <li> AipsError
287  // </thrown>
288  virtual ~MeasurementSet();
289 
290  // Assignment operator, reference semantics
292 
293  // Make a special copy of this MS which references all columns from
294  // this MS except those mentioned; those are empty and writable.
295  // Each forwarded column has the same writable status as the underlying
296  // column. The mentioned columns all use the AipsIO storage manager.
297  // The main use of this is for the synthesis package where corrected and
298  // model visibilities are stored as new DATA columns in an MS which
299  // references the raw MS for the other columns. Except for these special
300  // cases, the use of this function will be rare.
301  MeasurementSet referenceCopy(const String& newTableName,
302  const Block<String>& writableColumns) const;
303 
304  // Converts the MS to make the specified set of subtables memory resident.
305  void
306  setMemoryResidentSubtables (const MrsEligibility & mrsEligibility);
307 
308  // Return the name of each of the subtables. This should be used by the
309  // filler to create the subtables in the correct location.
310  // <group>
311  String antennaTableName() const;
312  String dataDescriptionTableName() const;
313  String dopplerTableName() const;
314  String feedTableName() const;
315  String fieldTableName() const;
316  String flagCmdTableName() const;
317  String freqOffsetTableName() const;
318  String historyTableName() const;
319  String observationTableName() const;
320  String pointingTableName() const;
321  String polarizationTableName() const;
322  String processorTableName() const;
323  String sourceTableName() const;
324  String spectralWindowTableName() const;
325  String stateTableName() const;
326  String sysCalTableName() const;
327  String weatherTableName() const;
328  // </group>
329 
330  // Access functions for the subtables, using the MS-like interface for each
331  // <group>
332  MSAntenna& antenna() {return antenna_p;}
333  MSDataDescription& dataDescription() {return dataDesc_p;}
334  MSDoppler& doppler() {return doppler_p;}
335  MSFeed& feed() {return feed_p;}
336  MSField& field() {return field_p;}
337  MSFlagCmd& flagCmd() {return flagCmd_p;}
338  MSFreqOffset& freqOffset() {return freqOffset_p;}
339  MSHistory& history() {return history_p;}
340  MSObservation& observation() {return observation_p;}
341  MSPointing& pointing() {return pointing_p;}
342  MSPolarization& polarization() {return polarization_p;}
343  MSProcessor& processor() {return processor_p;}
344  MSSource& source() {return source_p;}
345  MSSpectralWindow& spectralWindow() {return spectralWindow_p;}
346  MSState& state() {return state_p;}
347  MSSysCal& sysCal() {return sysCal_p;}
348  MSWeather& weather() {return weather_p;}
349  const MSAntenna& antenna() const {return antenna_p;}
350  const MSDataDescription& dataDescription() const {return dataDesc_p;}
351  const MSDoppler& doppler() const {return doppler_p;}
352  const MSFeed& feed() const {return feed_p;}
353  const MSField& field() const {return field_p;}
354  const MSFlagCmd& flagCmd() const {return flagCmd_p;}
355  const MSFreqOffset& freqOffset() const {return freqOffset_p;}
356  const MSHistory& history() const {return history_p;}
357  const MSObservation& observation() const {return observation_p;}
358  const MSPointing& pointing() const {return pointing_p;}
359  const MSPolarization& polarization() const {return polarization_p;}
360  const MSProcessor& processor() const {return processor_p;}
361  const MSSource& source() const {return source_p;}
362  const MSSpectralWindow& spectralWindow() const {return spectralWindow_p;}
363  const MSState& state() const {return state_p;}
364  const MSSysCal& sysCal() const {return sysCal_p;}
365  const MSWeather& weather() const {return weather_p;}
366  // </group>
367 
368  MrsEligibility getMrsEligibility () const;
369 
370  // Initialize the references to the subtables. You need to call
371  // this only if you assign new subtables to the table keywords.
372  // This also checks for validity of the table and its subtables.
373  // Set clear to True to clear the subtable references (used in assignment)
374  void initRefs(Bool clear=False);
375 
376  // Create default subtables: fills the required subtable keywords with
377  // tables of the correct type, mainly for testing and as an example of
378  // how to do this for specific fillers. In practice these tables will
379  // often have more things specified, like dimensions of arrays and
380  // storage managers for the various columns.
381  void createDefaultSubtables(Table::TableOption option=Table::Scratch);
382 
383  // Initialize the statics appropriately. This does not need to be
384  // called by users, it is called by the implementation class
385  // MSTableImpl.
386  static void init();
387 
388  // Create DATA column from existing FLOAT_DATA column. Noop if DATA already
389  // exists or neither exists (returns False in that case).
390  Bool makeComplexData();
391 
392  // Validate Measure references - check that all Measure columns have their
393  // reference value set, report the ones that don't.
394  Bool validateMeasureRefs();
395 
396  // Flush all the tables and subtables associated with this
397  // MeasurementSet. This function calls the Table::flush() function on the
398  // main table and all the standard subtables including optional
399  // subtables. See the Table class for a description of the sync argument.
400  void flush(Bool sync=False);
401 
402  // Return a record of the indices that the msselection selection selected
403  Record msseltoindex(const String& spw="", const String& field="",
404  const String& baseline="", const String& time="",
405  const String& scan="", const String& uvrange="",
406  const String& observation="", const String& poln="",
407  const String& taql="");
408 
409 protected:
410 
411 
412  // Clears all of the subtable components of this object (i.e., set to
413  // value of subtable's default constructor).
414  void clearSubtables ();
415 
416  // Assigns one subtable to another if the original subtable (otherSubtable)
417  // is not null and is also memory resident
418  void copySubtable (const Table & otherSubtable, Table & subTable);
419 
420  // Copies (assigns) all of the non-null subtables from the other MS into this one.
421  void copySubtables (const MeasurementSet & other);
422 
423  // Returns true if the named subtable is eligible for memory residency.
424  Bool isEligibleForMemoryResidency (const String & subtableName) const;
425 
426  // Opens all of the eligible subtables in memory resident form
427  void openMrSubtables ();
428 
429  // The top level name for MRS related CASARC settings
431  {
432  return "MemoryResidentSubtables";
433  }
434 
435 private:
436 
437  // temporary function to add the CATEGORY keyword to the FLAG_CATEGORY
438  // column if it isn't there yet. 2000/08/22
439  // remove this and the calls next MS update
440  void addCat();
441 
442  // check that the MS is the latest version (2.0)
443  void checkVersion();
444 
445  // Opens a single subtable as memory resident (if permitted).
446  template <typename Subtable>
447  void
448  openMrSubtable (Subtable & subtable, const String & subtableName);
449 
450  // Opens a single subtable if not present in MS object but defined in on-disk MS
451  template <typename Subtable>
452  void
453  openSubtable (Subtable & subtable, const String & subtableName, Bool useLock);
454 
455  // keep references to the subtables
458  MSDoppler doppler_p; //optional
468  MSSource source_p; //optional
471  MSSysCal sysCal_p; //optional
472  MSWeather weather_p; //optional
473 
474  bool doNotLockSubtables_p; // used to prevent subtable locking to allow parallel interprocess sharing
475  int mrsDebugLevel_p; // logging level currently enabled
476  Bool hasBeenDestroyed_p; // required by the need to throw an exception in the destructor
478  Bool memoryResidentSubtables_p; // true if memory resident subtables are enabled
479  MrsEligibility mrsEligibility_p; // subtables which can be made memory resident
480 
481 };
482 
483 
484 } //# NAMESPACE CASACORE - END
485 
486 #endif
A Measure: astronomical direction.
Definition: MDirection.h:174
A Table intended to hold a MeasurementSet OBSERVATIONLOG table.
Definition: MSHistory.h:78
A Table intended to hold a MeasurementSet PROCESSOR table.
Definition: MSProcessor.h:77
A Measure: position on Earth.
Definition: MPosition.h:79
A Table intended to hold a MeasurementSet DOPPLER table.
Definition: MSDoppler.h:79
Create a new table - define shapes, data managers, etc.
Definition: SetupNewTab.h:346
A Table intended to hold a MeasurementSet OBSERVATION table.
Definition: MSObservation.h:78
TableExprNode time(const TableExprNode &node)
Definition: ExprNode.h:1756
const MSObservation & observation() const
Main interface class to a read/write table.
Definition: Table.h:153
MSSpectralWindow & spectralWindow()
new table, which gets marked for delete
Definition: Table.h:176
A Table intended to hold a MeasurementSet POINTING table.
Definition: MSPointing.h:78
A Table intended to hold a MeasurementSet DATADESCRIPTION table.
MSMainEnums::PredefinedKeywords SubtableId
A Table intended to hold a MeasurementSet WEATHER table.
Definition: MSWeather.h:78
const MSSource & source() const
MeasurementSet MS
MeasurementSet is too cumbersome for a number of common uses, so we give a typedef here...
PtrHolder< T > & operator=(const PtrHolder< T > &other)
const MSProcessor & processor() const
const MSHistory & history() const
A Table intended to hold a MeasurementSet FEED table.
Definition: MSFeed.h:78
const MSAntenna & antenna() const
A Table intended to hold a MeasurementSet SYSCAL table.
Definition: MSSysCal.h:78
A Measure: instant in time.
Definition: MEpoch.h:104
const MSPointing & pointing() const
static MrsEligibility eligibleSubtables(SubtableId subtableId,...)
A Table intended to hold a MeasurementSet ANTENNA table.
Definition: MSAntenna.h:79
static MrsEligibility allEligible()
Factory methods to create MrsEligibility sets.
MSObservation & observation()
friend MrsEligibility operator+(const MrsEligibility &a, SubtableId subtableId)
A Measure: wave characteristics.
Definition: MFrequency.h:161
friend MrsEligibility operator-(const MrsEligibility &a, SubtableId subtableId)
Creates a new MrsEligibilitySet by adding or removing the specified subtable or the specified set of ...
A Table intended to hold a MeasurementSet SOURCE table.
Definition: MSSource.h:77
std::set< MSMainEnums::PredefinedKeywords > Eligible
const MSSpectralWindow & spectralWindow() const
existing table
Definition: Table.h:170
A Table intended to hold a MeasurementSet STATE table.
Definition: MSState.h:79
const MSDataDescription & dataDescription() const
static MrsEligibility noneEligible()
MSProcessor & processor()
MSSpectralWindow spectralWindow_p
static Bool isSubtable(SubtableId subtableId)
A Table intended to hold a MeasurementSet POLARIZATION table.
MSPolarization polarization_p
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
MSAntenna & antenna()
Access functions for the subtables, using the MS-like interface for each.
MSDataDescription & dataDescription()
const MSFlagCmd & flagCmd() const
static const MrsEligibility allSubtables_p
const Bool False
Definition: aipstype.h:44
Class to hold table lock options.
Definition: TableLock.h:65
const MSFreqOffset & freqOffset() const
const MSWeather & weather() const
A Table intended to hold a MeasurementSet FIELD table.
Definition: MSField.h:78
A Table intended to hold astronomical data (a set of Measurements).
static MrsEligibility defaultEligible()
const MSField & field() const
simple 1-D array
Definition: ArrayIO.h:47
MSFreqOffset & freqOffset()
const MSFeed & feed() const
const MSDoppler & doppler() const
const MSPolarization & polarization() const
A Table intended to hold astronomical data.
Definition: MSTable.h:112
MSPolarization & polarization()
String: the storage and methods of handling collections of characters.
Definition: String.h:223
A Table intended to hold a MeasurementSet FLAG_CMD table.
Definition: MSFlagCmd.h:78
MrsEligibility mrsEligibility_p
PredefinedKeywords
Keywords with a predefined meaning.
Definition: MSMainEnums.h:252
MSAntenna antenna_p
keep references to the subtables
static String getMrsAipsRcBase()
The top level name for MRS related CASARC settings.
Enums for the MeasurementSet main table.
Definition: MSMainEnums.h:62
const MSState & state() const
this file contains all the compiler specific defines
Definition: mainpage.dox:28
A Table intended to hold a MeasurementSet FREQ_OFFSET table.
Definition: MSFreqOffset.h:78
const MSSysCal & sysCal() const
unsigned int uInt
Definition: aipstype.h:51
static MrsEligibility allButTheseSubtables(SubtableId ineligibleSubtableId,...)
TableOption
Define the possible options how a table can be opened.
Definition: Table.h:168
MSDataDescription dataDesc_p
A Table intended to hold a MeasurementSet SPECTRAL_WINDOW table.
Bool isEligible(SubtableId subtableId) const
Returns true if the specified subtable is in the set of subtables eligible for memory residency...