B Appendix: API Note - Using the MSSelection module for other MS-like Tables

The MSSelection module was originally written to provide a higher-level, simpler language called STaQL (Simpler TaQL) specifically for applying selection on Measurement Sets. Parsers in the MSSelection module compile the various STaQL expressions and emit the equivalent tree of Table Expression Nodes (TEN), which is then used by the MeasurementSet class to generate a selected Table containing rows from the original Table for which the supplied TEN evaluates to True.

The information required to compile the STaQL expressions is derived from various sub-tables of the Measurement Set format (e.g. the ANTENNA sub-table, SPECTRAL_WINDOW sub-table, etc.). Since the MeasurementSet class is a specialization of the Table class and uses the services of the Table class to do the selection, in principle, STaQL can be used for any database that follows the general Table structure of the Measurement Set format. We refer to classes/objects which provide such a view of the underlying data as MS-like objects/classes. To use the MSSelection module for selection, the basic requirement is that the MS-like formats be organized as pseudo-relational database (like the Measurement Set) where most of the main-table entries are references to the rows of sub-tables. The information that these main-table entries represent resides in these much smaller sub-tables.

Since there may be minor differences in the details of the target databases (e.g. names of the sub-tables, or even absence of some required sub-tables which can be generated on-the-fly), the MSSelection module provides an interface to the database via a translation class inherited from the pure-virtual base-class of type MSSelectableTable14 . The MSSelectableTable class provides a uniform interface for the MSSelection class(es) and does any required translation to interface with the database classes. This also allows the client database related classes to exist outside the CASACore package. The inheritance tree of the MSSelectableTable line of classes is shown in Fig. 3.


Figure 3: Class diagram of the implementations of the MSSelectableTable pure-virtual base-class.

For using the MSSelection module on the Measurement Sets, the MSInterface object can be constructed from the MeasurementSet object and passed to the MSSelection object as shown in Listing 2.

Listing 2: Code snippet showing usage of MSSelection for Measurement Sets.
1      MS ms(MSName,TableLock(TableLock::AutoNoReadLocking)); 
2      // 
3      // Setup the MSSelection thingi 
4      // 
5      MSInterface msLike(ms); 
6      MSSelection msSelection; 
7      MSSelectionLogError mssLE; 
8      msSelection.setErrorHandler(MSSelection::ANTENNA_EXPR,&mssLE); 
9      msSelection.reset(msLike,MSSelection::PARSE_NOW, 
10                        timeStr,baselineStr,fieldStr,spwStr, 
11                        uvdistStr,taqlStr,polnStr,scanStr,arrayStr, 
12                        stateObsModeStr,observationStr);

Another method of using the MSSelection class is to set the individual expressions, get the TEN via the MSSelection::toTableExprNode() method and finally use the global method getSelectedTable() to apply the selection. This style of usage is shown in Listing 3. While for Measurement Sets the MSSelection::reset() method also works with MeasurementSet object, for future compatibility reasons it is recommended that the MSInterface be used instead.

B.1 Using MSSelection for CalTables

The MSSelection module can be used for selection on CalTables15  , which are implemented in the synthesis module of the CASA package, via the interface object of type CTInterface.

To use the MSSelection module for selection on (New)CalTable object, the only difference from the code snippet above, is that a CTInterface object needs to be constructed (instead of the MSInterface object) from the (New)CalTable class of the synthesis module. The CTInterface object can be supplied to the MSSelection object via the reset() method. Alternatively, various expressions can be set in the MSSelection object and the CTInterface object supplied via the MSSelection::toTableExprNode() method which returns the tree of TENs. The tree can then be used to get a selected CalTable as shown in Listing 3.

Listing 3: Code snippet showing usage of MSSelection for (New)CalTables.
1  NewCalTable calTab(CalName), selectedCalTable(calTab); 
2  CTInterface msLike(calTab); 
3  MSSelection mss; 
4  MSSelectionLogError mssLE; 
5  mss.setErrorHandler(MSSelection::ANTENNA_EXPR,&mssLE); 
7  mss.setFieldExpr(fieldStr); 
8  mss.setAntennaExpr(antennaStr); 
9  mss.setSpwExpr(spwStr); 
11  TableExprNode ten=mss.toTableExprNode(&msLike); 
12  // 
13  // Now use the global method getSelectedTable() to apply the TEN on the calTab 
14  // parameter and return the selected table in selectedCalTable parameter. 
15  // 
16  getSelectedTable(selectedCalTable, calTab, ten, "");