casacore
Loading...
Searching...
No Matches
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
55namespace casacore { //# NAMESPACE CASACORE - BEGIN
56
57class MrsEligibility { // Memory Resident Subtable (Mrs) Eligibility (no pun intended)
58
59public:
60
62
63 friend MrsEligibility operator- (const MrsEligibility & a, SubtableId subtableId);
64 friend MrsEligibility operator+ (const MrsEligibility & a, SubtableId subtableId);
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 //
79 static MrsEligibility allButTheseSubtables (SubtableId ineligibleSubtableId, ...);
80
81private:
82
83 typedef std::set<MSMainEnums::PredefinedKeywords> Eligible;
84
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
101class SetupNewTable;
102template <class T> class Block;
103class MDirection;
104class MEpoch;
105class MFrequency;
106class MPosition;
107class Record;
108
109//# forward declared so that the following typedef is up-front
110class MeasurementSet;
111
112// MeasurementSet is too cumbersome for a number of common uses,
113// so we give a typedef here.
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// rownr_t 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
241class MeasurementSet : public MSTable<MSMainEnums>,
242 public MSMainEnums
243{
244
245public:
246 // This constructs an empty MeasurementSet, only useful to assign to
247 // (it is not a valid MS yet).
249
250 // These constructors mirror the Table ones with additional checking
251 // on validity (verifying that the MS will have the required columns
252 // and keywords)
253 // An exception is thrown if the constructed Table is not a valid MS
254 // <thrown>
255 // <li> AipsError
256 // </thrown>
257 // <group name=tableLikeConstructors>
258
262
264 bool doNotLockSubtables, TableOption = Table::Old);
265 // Allows keeping subtables unlocked/read-locked independent of lock
266 // mode of main table.
267
268 MeasurementSet (const String &tableName, const String &tableDescName,
270 MeasurementSet (const String &tableName, const String &tableDescName,
273 Bool initialize = False);
275 rownr_t nrrow = 0, Bool initialize = False);
276 MeasurementSet (const Table &table, const MeasurementSet * otherMs = NULL);
277
278#ifdef HAVE_MPI
279 MeasurementSet (MPI_Comm comm, SetupNewTable &newTab, rownr_t nrrow = 0,
280 Bool initialize = False);
281 MeasurementSet (MPI_Comm comm, SetupNewTable &newTab, const TableLock& lockOptions,
282 rownr_t nrrow = 0, Bool initialize = False);
283#endif // HAVE_MPI
284
286 // </group>
287
288 // As with tables, the destructor writes the table if necessary.
289 // Additional checking is done here to verify that all required
290 // columns are still present.
291 // If it is NOT valid, it will write the table and then throw an exception.
292 // <thrown>
293 // <li> AipsError
294 // </thrown>
296
297 // Assignment operator, reference semantics
299
300 // Make a special copy of this MS which references all columns from
301 // this MS except those mentioned; those are empty and writable.
302 // Each forwarded column has the same writable status as the underlying
303 // column. The mentioned columns all use the AipsIO storage manager.
304 // The main use of this is for the synthesis package where corrected and
305 // model visibilities are stored as new DATA columns in an MS which
306 // references the raw MS for the other columns. Except for these special
307 // cases, the use of this function will be rare.
309 const Block<String>& writableColumns) const;
310
311 // Converts the MS to make the specified set of subtables memory resident.
312 void
314
315 // Return the name of each of the subtables. This should be used by the
316 // filler to create the subtables in the correct location.
317 // <group>
335 // </group>
336
337 // Access functions for the subtables, using the MS-like interface for each
338 // <group>
342 MSFeed& feed() {return feed_p;}
343 MSField& field() {return field_p;}
353 MSState& state() {return state_p;}
356 const MSAntenna& antenna() const {return antenna_p;}
358 const MSDoppler& doppler() const {return doppler_p;}
359 const MSFeed& feed() const {return feed_p;}
360 const MSField& field() const {return field_p;}
361 const MSFlagCmd& flagCmd() const {return flagCmd_p;}
362 const MSFreqOffset& freqOffset() const {return freqOffset_p;}
363 const MSHistory& history() const {return history_p;}
364 const MSObservation& observation() const {return observation_p;}
365 const MSPointing& pointing() const {return pointing_p;}
367 const MSProcessor& processor() const {return processor_p;}
368 const MSSource& source() const {return source_p;}
370 const MSState& state() const {return state_p;}
371 const MSSysCal& sysCal() const {return sysCal_p;}
372 const MSWeather& weather() const {return weather_p;}
373 // </group>
374
376
377 // Initialize the references to the subtables. You need to call
378 // this only if you assign new subtables to the table keywords.
379 // This also checks for validity of the table and its subtables.
380 // Set clear to True to clear the subtable references (used in assignment)
381 void initRefs(Bool clear=False);
382
383 // Create default subtables: fills the required subtable keywords with
384 // tables of the correct type, mainly for testing and as an example of
385 // how to do this for specific fillers. In practice these tables will
386 // often have more things specified, like dimensions of arrays and
387 // storage managers for the various columns.
389#ifdef HAVE_MPI
391#endif // HAVE_MPI
392
393 // Initialize the statics appropriately. This does not need to be
394 // called by users, it is called by the implementation class
395 // MSTableImpl.
397
398 // Create DATA column from existing FLOAT_DATA column. Noop if DATA already
399 // exists or neither exists (returns False in that case).
401
402 // Validate Measure references - check that all Measure columns have their
403 // reference value set, report the ones that don't.
405
406 // Flush all the tables and subtables associated with this
407 // MeasurementSet. This function calls the Table::flush() function on the
408 // main table and all the standard subtables including optional
409 // subtables. See the Table class for a description of the sync argument.
410 void flush(Bool sync=False);
411
412 // Return a record of the indices that the msselection selection selected
413 Record msseltoindex(const String& spw="", const String& field="",
414 const String& baseline="", const String& time="",
415 const String& scan="", const String& uvrange="",
416 const String& observation="", const String& poln="",
417 const String& taql="");
418
419protected:
420
421
422 // Clears all of the subtable components of this object (i.e., set to
423 // value of subtable's default constructor).
425
426 // Assigns one subtable to another if the original subtable (otherSubtable)
427 // is not null and is also memory resident
428 void copySubtable (const Table & otherSubtable, Table & subTable);
429
430 // Copies (assigns) all of the non-null subtables from the other MS into this one.
431 void copySubtables (const MeasurementSet & other);
432
433 // Returns true if the named subtable is eligible for memory residency.
434 Bool isEligibleForMemoryResidency (const String & subtableName) const;
435
436 // Opens all of the eligible subtables in memory resident form
438
439 // The top level name for MRS related CASARC settings
441 {
442 return "MemoryResidentSubtables";
443 }
444
445private:
446
447 // temporary function to add the CATEGORY keyword to the FLAG_CATEGORY
448 // column if it isn't there yet. 2000/08/22
449 // remove this and the calls next MS update
450 void addCat();
451
452 // check that the MS is the latest version (2.0)
454
455 // Creates subtables using an explicit MPI communicator (if MPI support
456 // is enabled)
457 template<typename T>
459
460 // Opens a single subtable as memory resident (if permitted).
461 template <typename Subtable>
462 void
463 openMrSubtable (Subtable & subtable, const String & subtableName);
464
465 // Opens a single subtable if not present in MS object but defined in on-disk MS
466 template <typename Subtable>
467 void
468 openSubtable (Subtable & subtable, const String & subtableName, Bool useLock);
469
470 // keep references to the subtables
483 MSSource source_p; //optional
486 MSSysCal sysCal_p; //optional
488
489 bool doNotLockSubtables_p; // used to prevent subtable locking to allow parallel interprocess sharing
490 int mrsDebugLevel_p; // logging level currently enabled
491 Bool hasBeenDestroyed_p; // required by the need to throw an exception in the destructor
493 Bool memoryResidentSubtables_p; // true if memory resident subtables are enabled
494 MrsEligibility mrsEligibility_p; // subtables which can be made memory resident
495
496};
497
498
499} //# NAMESPACE CASACORE - END
500
501#endif
simple 1-D array
Definition Block.h:200
Enums for the MeasurementSet main table.
Definition MSMainEnums.h:62
PredefinedKeywords
Keywords with a predefined meaning.
A Table intended to hold astronomical data
Definition MSTable.h:147
void openSubtable(Subtable &subtable, const String &subtableName, Bool useLock)
Opens a single subtable if not present in MS object but defined in on-disk MS.
MSAntenna & antenna()
Access functions for the subtables, using the MS-like interface for each.
void createDefaultSubtables(MPI_Comm comm, Table::TableOption option=Table::Scratch)
MeasurementSet(const Table &table, const MeasurementSet *otherMs=NULL)
const MSFreqOffset & freqOffset() const
String fieldTableName() const
MSObservation & observation()
void copySubtables(const MeasurementSet &other)
Copies (assigns) all of the non-null subtables from the other MS into this one.
MrsEligibility getMrsEligibility() const
const MSObservation & observation() const
String stateTableName() const
MSFreqOffset & freqOffset()
const MSAntenna & antenna() const
String freqOffsetTableName() const
String processorTableName() const
const MSSource & source() const
MeasurementSet(const String &tableName, const String &tableDescName, TableOption=Table::Old)
Allows keeping subtables unlocked/read-locked independent of lock mode of main table.
const MSWeather & weather() const
void copySubtable(const Table &otherSubtable, Table &subTable)
Assigns one subtable to another if the original subtable (otherSubtable) is not null and is also memo...
Bool isEligibleForMemoryResidency(const String &subtableName) const
Returns true if the named subtable is eligible for memory residency.
MSDataDescription dataDesc_p
MeasurementSet(const String &tableName, const TableLock &lockOptions, TableOption=Table::Old)
const MSSpectralWindow & spectralWindow() const
const MSSysCal & sysCal() const
const MSHistory & history() const
MeasurementSet()
This constructs an empty MeasurementSet, only useful to assign to (it is not a valid MS yet).
Record msseltoindex(const String &spw="", const String &field="", const String &baseline="", const String &time="", const String &scan="", const String &uvrange="", const String &observation="", const String &poln="", const String &taql="")
Return a record of the indices that the msselection selection selected.
MeasurementSet(MPI_Comm comm, SetupNewTable &newTab, const TableLock &lockOptions, rownr_t nrrow=0, Bool initialize=False)
const MSState & state() const
MSAntenna antenna_p
keep references to the subtables
const MSField & field() const
void createDefaultSubtables(Table::TableOption option=Table::Scratch)
Create default subtables: fills the required subtable keywords with tables of the correct type,...
String flagCmdTableName() const
String spectralWindowTableName() const
String dopplerTableName() const
String historyTableName() const
String feedTableName() const
MSSpectralWindow & spectralWindow()
MeasurementSet(SetupNewTable &newTab, rownr_t nrrow=0, Bool initialize=False)
String sysCalTableName() const
void setMemoryResidentSubtables(const MrsEligibility &mrsEligibility)
Converts the MS to make the specified set of subtables memory resident.
const MSFeed & feed() const
MeasurementSet(const String &tableName, const String &tableDescName, const TableLock &lockOptions, TableOption=Table::Old)
virtual ~MeasurementSet()
As with tables, the destructor writes the table if necessary.
void flush(Bool sync=False)
Flush all the tables and subtables associated with this MeasurementSet.
const MSDataDescription & dataDescription() const
String sourceTableName() const
void openMrSubtables()
Opens all of the eligible subtables in memory resident form.
void createDefaultSubtables_impl(Table::TableOption option, T comm)
Creates subtables using an explicit MPI communicator (if MPI support is enabled)
void openMrSubtable(Subtable &subtable, const String &subtableName)
Opens a single subtable as memory resident (if permitted).
void initRefs(Bool clear=False)
Initialize the references to the subtables.
MSPolarization polarization_p
MSSpectralWindow spectralWindow_p
String observationTableName() const
String dataDescriptionTableName() const
MeasurementSet(const String &tableName, TableOption=Table::Old)
These constructors mirror the Table ones with additional checking on validity (verifying that the MS ...
Bool validateMeasureRefs()
Validate Measure references - check that all Measure columns have their reference value set,...
MeasurementSet(SetupNewTable &newTab, const TableLock &lockOptions, rownr_t nrrow=0, Bool initialize=False)
static String getMrsAipsRcBase()
The top level name for MRS related CASARC settings.
Bool makeComplexData()
Create DATA column from existing FLOAT_DATA column.
const MSFlagCmd & flagCmd() const
static MSTableMaps initMaps()
Initialize the statics appropriately.
String weatherTableName() const
String antennaTableName() const
Return the name of each of the subtables.
void addCat()
temporary function to add the CATEGORY keyword to the FLAG_CATEGORY column if it isn't there yet.
String polarizationTableName() const
MeasurementSet(MPI_Comm comm, SetupNewTable &newTab, rownr_t nrrow=0, Bool initialize=False)
MeasurementSet & operator=(const MeasurementSet &)
Assignment operator, reference semantics.
const MSProcessor & processor() const
const MSPolarization & polarization() const
MeasurementSet(const MeasurementSet &other)
void checkVersion()
check that the MS is the latest version (2.0)
MrsEligibility mrsEligibility_p
MSDataDescription & dataDescription()
const MSPointing & pointing() const
MeasurementSet referenceCopy(const String &newTableName, const Block< String > &writableColumns) const
Make a special copy of this MS which references all columns from this MS except those mentioned; thos...
void clearSubtables()
Clears all of the subtable components of this object (i.e., set to value of subtable's default constr...
MSPolarization & polarization()
String pointingTableName() const
MeasurementSet(const String &tableName, const TableLock &lockOptions, bool doNotLockSubtables, TableOption=Table::Old)
const MSDoppler & doppler() const
std::set< MSMainEnums::PredefinedKeywords > Eligible
Bool isEligible(SubtableId subtableId) const
Returns true if the specified subtable is in the set of subtables eligible for memory residency.
static MrsEligibility noneEligible()
static Bool isSubtable(SubtableId subtableId)
friend MrsEligibility operator+(const MrsEligibility &a, SubtableId subtableId)
static MrsEligibility defaultEligible()
static const MrsEligibility allSubtables_p
static MrsEligibility allEligible()
Factory methods to create MrsEligibility sets.
friend MrsEligibility operator-(const MrsEligibility &a, SubtableId subtableId)
Creates a new MrsEligibilitySet by adding or removing the specified subtable or the specified set of ...
static MrsEligibility eligibleSubtables(SubtableId subtableId,...)
static MrsEligibility allButTheseSubtables(SubtableId ineligibleSubtableId,...)
MSMainEnums::PredefinedKeywords SubtableId
Create a new table - define shapes, data managers, etc.
String: the storage and methods of handling collections of characters.
Definition String.h:225
const TableLock & lockOptions() const
Get the locking options.
Definition Table.h:1110
const String & tableName() const
Get the table name.
Definition Table.h:1187
TableOption
Define the possible options how a table can be opened.
Definition Table.h:172
@ Scratch
new table, which gets marked for delete
Definition Table.h:180
@ Old
existing table
Definition Table.h:174
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:44
TableExprNode time(const TableExprNode &node)
Definition ExprNode.h:1580
LatticeExprNode operator+(const LatticeExprNode &expr)
Global functions operating on a LatticeExprNode.
LatticeExprNode operator-(const LatticeExprNode &expr)
MeasurementSet MS
MeasurementSet is too cumbersome for a number of common uses, so we give a typedef here.
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:46