MSSelection: Class to represent a selection on an MS. More...

#include <MSSelection.h>

Public Types
enum	MSExprType { NO_EXPR, ANTENNA_EXPR, CORR_EXPR, FIELD_EXPR, SPW_EXPR, SCAN_EXPR, ARRAY_EXPR, TIME_EXPR, UVDIST_EXPR, POLN_EXPR, STATE_EXPR, OBSERVATION_EXPR, TAQL_EXPR, MAX_EXPR }
enum	MSSMode { PARSE_NOW, PARSE_LATE }
Public Member Functions
	MSSelection ()
	Default null constructor, and destructor.
virtual	~MSSelection ()
	MSSelection (const MeasurementSet &ms, const MSSMode &mode=PARSE_NOW, const String &timeExpr="", const String &antennaExpr="", const String &fieldExpr="", const String &spwExpr="", const String &uvDistExpr="", const String &taqlExpr="", const String &polnExpr="", const String &scanExpr="", const String &arrayExpr="", const String &stateExpr="", const String &observationExpr="")
	Construct using an MS and the various selection expressions to be applied to the given MS.
	MSSelection (const Record &selectionItem)
	Construct from a record representing a selection item at the CLI or user interface level.
	MSSelection (const MSSelection &other)
	Copy constructor.
MSSelection &	operator= (const MSSelection &other)
	Assignment operator.
Bool	setAntennaExpr (const String &antennaExpr)
	Expression accessors.
Bool	setFieldExpr (const String &fieldExpr)
Bool	setSpwExpr (const String &spwExpr)
Bool	setScanExpr (const String &scanExpr)
Bool	setArrayExpr (const String &ArrayExpr)
Bool	setTimeExpr (const String &timeExpr)
Bool	setUvDistExpr (const String &uvDistExpr)
Bool	setTaQLExpr (const String &taqlExpr)
Bool	setPolnExpr (const String &polnExpr)
Bool	setStateExpr (const String &stateExpr)
Bool	setObservationExpr (const String &obervationExpr)
TableExprNode	getTEN (const MeasurementSet *ms=NULL)
	Accessor for result of parsing all of the selection expressions.
Vector< Int >	getScanList (const MeasurementSet *ms=NULL)
	Accessor for the list of the selected scan IDs.
Vector< Int >	getObservationList (const MeasurementSet *ms=NULL)
	Accessor for the list of the selected observation IDs.
Vector< Int >	getSubArrayList (const MeasurementSet *ms=NULL)
	Accessor for the list of selected sub-array IDs.
Vector< Int >	getAntenna1List (const MeasurementSet *ms=NULL)
	Accessor for the list of antenna-1 of the selected baselines.
Vector< Int >	getAntenna2List (const MeasurementSet *ms=NULL)
	Accessor for the list of antenna-2 of the selected baselines.
Matrix< Int >	getBaselineList (const MeasurementSet *ms=NULL)
	Accessor for the list of selected baselines.
Vector< Int >	getFieldList (const MeasurementSet *ms=NULL)
	Accessor for the list of selected field IDs.
Vector< Int >	getStateObsModeList (const MeasurementSet *ms=NULL)
	Accessor for the list of selected state Obs_Modes.
Matrix< Double >	getTimeList (const MeasurementSet *ms=NULL)
	Accessor for the list of the specified time range(s) as the start and end MJD values.
Matrix< Double >	getUVList (const MeasurementSet *ms=NULL)
	Accessor for the list of the specified uv-range(s) as the start and end values in units used in the MS.
Vector< Bool >	getUVUnitsList (const MeasurementSet *ms=NULL)
	Accessor for the list of user defined units for the uv-range(s).
Vector< Int >	getSpwList (const MeasurementSet *ms=NULL)
	Accessor for the list of the selected Spectral Window IDs.
Matrix< Int >	getChanList (const MeasurementSet *ms=NULL, const Int defaultStep=1, const Bool sorted=False)
	Accessor for the table (as a nx4 Matrix) of the selected Spectral Windows and associated ranges of selected channels.
Matrix< Double >	getChanFreqList (const MeasurementSet *ms=NULL, const Bool sorted=False)
	Same as getChanList, except that the channels and steps are in Hz.
Vector< Int >	getDDIDList (const MeasurementSet *ms=NULL)
	Accessor for the list of the selected Data Description IDs.
OrderedMap< Int, Vector< Int > >	getPolMap (const MeasurementSet *ms=NULL)
	The key in the ordered map returned by getPolMap() is the pol.
OrderedMap< Int, Vector < Vector< Int > > >	getCorrMap (const MeasurementSet *ms=NULL)
void	getChanSlices (Vector< Vector< Slice > > &chanslices, const MeasurementSet *ms=NULL, const Int defaultChanStep=1)
	Methods to convert the maps return by getChanList and getCorrMap to a list of Slice which can be directly used by Table system for in-row selection of frequency channels and polarizations.
void	getCorrSlices (Vector< Vector< Slice > > &corrslices, const MeasurementSet *ms=NULL)
void	clear (const MSExprType type=NO_EXPR)
	Clear sub-expression and reset priority.
Bool	exprIsNull (const MSExprType type=NO_EXPR)
void	deleteNodes ()
	Convey to the various parsers to delete the TENs they hold.
void	deleteErrorHandlers ()
	Delete error handlers (mostly the internally allocated ones).
TableExprNode	toTableExprNode (const MeasurementSet *ms)
	Convert to TableExprNode format (C++ interface to TaQL).
TableExprNode	toTableExprNode (MSSelectableTable *msLike)
	Convert to TableExprNode format (C++ interface to TaQL).
Bool	getSelectedMS (MeasurementSet &selectedMS, const String &outMSName="")
	Return the selected MS.
void	resetMS (const MeasurementSet &ms)
void	resetTEN ()
void	reset (const MeasurementSet &ms, const MSSMode &mode=PARSE_NOW, const String &timeExpr="", const String &antennaExpr="", const String &fieldExpr="", const String &spwExpr="", const String &uvDistExpr="", const String &taqlExpr="", const String &polnExpr="", const String &scanExpr="", const String &arrayExpr="", const String &stateExpr="", const String &observationExpr="")
void	reset (MSSelectableTable &msLike, const MSSMode &mode=PARSE_NOW, const String &timeExpr="", const String &antennaExpr="", const String &fieldExpr="", const String &spwExpr="", const String &uvDistExpr="", const String &taqlExpr="", const String &polnExpr="", const String &scanExpr="", const String &arrayExpr="", const String &stateExpr="", const String &observationExpr="")
void	setMaxScans (const Int &n)
void	setMaxObs (const Int &n)
void	setErrorHandler (const MSExprType type, MSSelectionErrorHandler *mssEH, const Bool overRide=False)
void	runErrorHandler ()
const MeasurementSet *	getMS (MSSelectableTable *msLike)
Static Public Member Functions
static String	indexExprStr (Vector< Int > index)
	Helper method for converting index vectors to expression strings.
static String	nameExprStr (Vector< String > name)
	Helper method for converting name vectors to expression strings.
Private Member Functions
Bool	setOrder (MSSelection::MSExprType type)
	Set into the order of the selection expression.
void	fromSelectionItem (const Record &selectionItem)
	Initialize from a Record representing a selection item from the user interface or CLI.
Bool	definedAndSet (const Record &inpRec, const String &fieldName)
	Check if record field exists and is not unset.
Private Attributes
TableExprNode	fullTEN_p
	Convert an MS select string to TaQL const String msToTaQL(const String& msSelect) {};.
const MeasurementSet *	ms_p
String	antennaExpr_p
	Selection expressions.
String	fieldExpr_p
String	spwExpr_p
String	scanExpr_p
String	arrayExpr_p
String	timeExpr_p
String	uvDistExpr_p
String	polnExpr_p
String	taqlExpr_p
String	stateExpr_p
String	observationExpr_p
Vector< Int >	exprOrder_p
	Priority.
Vector< Int >	antenna1IDs_p
Vector< Int >	antenna2IDs_p
Vector< Int >	fieldIDs_p
Vector< Int >	spwIDs_p
Vector< Int >	scanIDs_p
Vector< Int >	arrayIDs_p
Vector< Int >	ddIDs_p
Vector< Int >	stateObsModeIDs_p
Vector< Int >	observationIDs_p
Matrix< Int >	chanIDs_p
Matrix< Int >	baselineIDs_p
Matrix< Double >	selectedTimesList_p
Matrix< Double >	selectedUVRange_p
Vector< Bool >	selectedUVUnits_p
OrderedMap< Int, Vector< Int > >	selectedPolMap_p
OrderedMap< Int, Vector < Vector< Int > > >	selectedSetupMap_p
Int	maxScans_p
Int	maxObs_p
Int	maxArray_p
MSSelectionErrorHandler *	mssErrHandler_p
Bool	isMS_p
Bool	toTENCalled_p

Detailed Description

MSSelection: Class to represent a selection on an MS.

Intended use:

Public interface

Prerequisite

MeasurementSet module

Etymology

From "MeasurementSet" and "selection".

Synopsis

The MSSelection class represents a selection on a MeasurementSet (MS). This class is used in translating MS selections represented as selection items in the user interface, and for converting between MS selection and pure TaQL selection.

The purpose of this class is to provides a simple expression based selection mechanism to both the end-user and developer wishing to perform query operations over a measurement set. This is accomplished by abstracting the TaQL interface through an adapter/translation interface which converts STaQL (Simple Table Query Language) expressions into the equivalent table expression form, reducing the knowledge necessary to perform powerful query operations directly in TaQL. It is also possible to supply pure TaQL expression(s) as sub-expressions if required. For a complete list of the STaQL interface refer to: Data Selection

The sub-expressions are interpreted in the order which they were set. The order however in not important - any dependency on the order in which the expressions are evaluated is handled internally. The result of parsing the expressions is TableExprNode (TEN). All TENs from sub-expressions are finally ANDed and the resultant TEN is used to select the rows of the MS table.

Example

    // Create a MS and a MS selection
    MeasurementSet ms(msName);
    MSSelection select;
    // Setup any sub-expressions of interest directly
    // (or optionally send this information through a Record)
    select.setFieldExpr("0,1");
    select.setSpwExpr(">0");
    // Create a table expression over a MS representing the selection
    TableExprNode node = select.toTableExprNode(&ms);
    // Optionally create a table and new MS based on this node
    Table tablesel(ms.tableName(), Table::Update);
    MeasurementSet mssel(tablesel(node, node.nrow()));

Motivation

This class is used by the MS access classes.

Definition at line 118 of file MSSelection.h.

Member Enumeration Documentation

enum casa::MSSelection::MSExprType

Enumerator:

NO_EXPR
ANTENNA_EXPR
CORR_EXPR
FIELD_EXPR
SPW_EXPR
SCAN_EXPR
ARRAY_EXPR
TIME_EXPR
UVDIST_EXPR
POLN_EXPR
STATE_EXPR
OBSERVATION_EXPR
TAQL_EXPR
MAX_EXPR

Definition at line 121 of file MSSelection.h.

enum casa::MSSelection::MSSMode

Enumerator:

PARSE_NOW
PARSE_LATE

Definition at line 135 of file MSSelection.h.

Constructor & Destructor Documentation

casa::MSSelection::MSSelection ( )

Default null constructor, and destructor.

virtual casa::MSSelection::~MSSelection ( ) [virtual]

casa::MSSelection::MSSelection	(	const MeasurementSet &	ms,
		const MSSMode &	mode = `PARSE_NOW`,
		const String &	timeExpr = `""`,
		const String &	antennaExpr = `""`,
		const String &	fieldExpr = `""`,
		const String &	spwExpr = `""`,
		const String &	uvDistExpr = `""`,
		const String &	taqlExpr = `""`,
		const String &	polnExpr = `""`,
		const String &	scanExpr = `""`,
		const String &	arrayExpr = `""`,
		const String &	stateExpr = `""`,
		const String &	observationExpr = `""`
	)

Construct using an MS and the various selection expressions to be applied to the given MS.

By default, the expressions will be parsed immediately. With mode=PARSE_LATE, the parsing will be done with a call to toTableExprNode().

casa::MSSelection::MSSelection ( const Record & selectionItem )

Construct from a record representing a selection item at the CLI or user interface level.

This is functionally same as the constructor above with mode=PARSE_LATE.

casa::MSSelection::MSSelection ( const MSSelection & other )

Copy constructor.

Member Function Documentation

void casa::MSSelection::clear ( const MSExprType type = NO_EXPR )

Clear sub-expression and reset priority.

Default behavior is to reset all sub-expressions.

Bool casa::MSSelection::definedAndSet	(	const Record &	inpRec,
		const String &	fieldName
	)		`[private]`

Check if record field exists and is not unset.

void casa::MSSelection::deleteErrorHandlers ( )

Delete error handlers (mostly the internally allocated ones).

void casa::MSSelection::deleteNodes ( )

Convey to the various parsers to delete the TENs they hold.

Bool casa::MSSelection::exprIsNull ( const MSExprType type = NO_EXPR )

void casa::MSSelection::fromSelectionItem ( const Record & selectionItem ) [private]

Initialize from a Record representing a selection item from the user interface or CLI.

Vector<Int> casa::MSSelection::getAntenna1List ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of antenna-1 of the selected baselines.

Antennas affected by the baseline negation operator have the antenna IDs multiplied by -1.

Definition at line 211 of file MSSelection.h.

References antenna1IDs_p, and getTEN().

Vector<Int> casa::MSSelection::getAntenna2List ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of antenna-2 of the selected baselines.

Antennas affected by the baseline negation operator have the antenna IDs multiplied by -1.

Definition at line 218 of file MSSelection.h.

References antenna2IDs_p, and getTEN().

Matrix<Int> casa::MSSelection::getBaselineList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of selected baselines.

The list is a Nx2 Matrix with one row per baseline containing the antenna IDs of the two antenna associated with the baseline.

Baselines affected by the negation operator in the baseline selection expression are reported with one or both the antenna IDs multiplied by -1. E.g. a baseline selection expression "!1" will result in a baseline list

[-1, 2], [-1, 3], [-1, 4], ....

The expression "!1&10" will result in a baseline list [-1, -10]. Etc...

Definition at line 239 of file MSSelection.h.

References baselineIDs_p, and getTEN().

Matrix<Double> casa::MSSelection::getChanFreqList	(	const MeasurementSet *	ms = `NULL`,
		const Bool	sorted = `False`
	)

Same as getChanList, except that the channels and steps are in Hz.

Matrix<Int> casa::MSSelection::getChanList	(	const MeasurementSet *	ms = `NULL`,
		const Int	defaultStep = `1`,
		const Bool	sorted = `False`
	)

Accessor for the table (as a nx4 Matrix) of the selected Spectral Windows and associated ranges of selected channels.

Each row of the Matrix has the following elements:

SpwID StartCh StopCh Step

where StartCh, StopCh and Step are the first and the last selected channels and step is the step size. If no step size was supplied as part of the expression, the value of Step is replaced with the value of the defaultStep parameter. Multiple channel specifications for the same Spectral Window selection, results in multiple rows in the Matrix. If sorted is True, the rows of the output Matrix will be sorted by the SPW IDs (the entries in the first column).

void casa::MSSelection::getChanSlices	(	Vector< Vector< Slice > > &	chanslices,
		const MeasurementSet *	ms = `NULL`,
		const Int	defaultChanStep = `1`
	)

Methods to convert the maps return by getChanList and getCorrMap to a list of Slice which can be directly used by Table system for in-row selection of frequency channels and polarizations.

OrderedMap<Int, Vector<Vector<Int> > > casa::MSSelection::getCorrMap ( const MeasurementSet * ms = NULL ) [inline]

Definition at line 313 of file MSSelection.h.

References getTEN(), and selectedSetupMap_p.

void casa::MSSelection::getCorrSlices	(	Vector< Vector< Slice > > &	corrslices,
		const MeasurementSet *	ms = `NULL`
	)

Vector<Int> casa::MSSelection::getDDIDList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of the selected Data Description IDs.

Definition at line 298 of file MSSelection.h.

References ddIDs_p, getTEN(), and casa::ArrayBase::nelements().

Vector<Int> casa::MSSelection::getFieldList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of selected field IDs.

Definition at line 243 of file MSSelection.h.

References fieldIDs_p, and getTEN().

const MeasurementSet* casa::MSSelection::getMS ( MSSelectableTable * msLike )

Vector<Int> casa::MSSelection::getObservationList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of the selected observation IDs.

Definition at line 201 of file MSSelection.h.

References getTEN(), and observationIDs_p.

OrderedMap<Int, Vector<Int> > casa::MSSelection::getPolMap ( const MeasurementSet * ms = NULL ) [inline]

The key in the ordered map returned by getPolMap() is the pol.

ID. The value is a vector containing the list of in-row indices to pick out the selected polarizations (or equivalently, the list of indices for the vector in the corrType column of the POLARIZATION sub-table). These are also what the user intended (i.e., e.g. not all DD IDs due to user POL expression might be selected due to SPW expressions).

Definition at line 310 of file MSSelection.h.

References getTEN(), and selectedPolMap_p.

Vector<Int> casa::MSSelection::getScanList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of the selected scan IDs.

Definition at line 197 of file MSSelection.h.

References getTEN(), and scanIDs_p.

Bool casa::MSSelection::getSelectedMS	(	MeasurementSet &	selectedMS,
		const String &	outMSName = `""`
	)

Return the selected MS.

The selected MS reflects only row selections (as against in-row selections). If outMSName != "", the selected MS is also written to the disk (a shallow copy).

For in-row selection, use the appropriate global function mssSetData() MSSelectionTools.h which also returns the in-row (corr/chan) slices that can be supplied to the VisIter object for on-the-fly in-row selection.

Vector<Int> casa::MSSelection::getSpwList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of the selected Spectral Window IDs.

Definition at line 269 of file MSSelection.h.

References getTEN(), and spwIDs_p.

Vector<Int> casa::MSSelection::getStateObsModeList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of selected state Obs_Modes.

Definition at line 248 of file MSSelection.h.

References getTEN(), casa::ArrayBase::nelements(), and stateObsModeIDs_p.

Vector<Int> casa::MSSelection::getSubArrayList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of selected sub-array IDs.

Definition at line 205 of file MSSelection.h.

References arrayIDs_p, and getTEN().

TableExprNode casa::MSSelection::getTEN ( const MeasurementSet * ms = NULL )

Accessor for result of parsing all of the selection expressions.

The final TableExprNode (TEN) is the result of ANDing the TENs for the individual expressions.

Referenced by getAntenna1List(), getAntenna2List(), getBaselineList(), getCorrMap(), getDDIDList(), getFieldList(), getObservationList(), getPolMap(), getScanList(), getSpwList(), getStateObsModeList(), getSubArrayList(), getTimeList(), getUVList(), and getUVUnitsList().

Matrix<Double> casa::MSSelection::getTimeList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of the specified time range(s) as the start and end MJD values.

The time ranges are stored as columns, i.e. the output Matrix is 2 x n_ranges.

Definition at line 254 of file MSSelection.h.

References getTEN(), and selectedTimesList_p.

Matrix<Double> casa::MSSelection::getUVList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of the specified uv-range(s) as the start and end values in units used in the MS.

Definition at line 259 of file MSSelection.h.

References getTEN(), and selectedUVRange_p.

Vector<Bool> casa::MSSelection::getUVUnitsList ( const MeasurementSet * ms = NULL ) [inline]

Accessor for the list of user defined units for the uv-range(s).

The uv-range(s) return by getUVList is always in the units used in the MS.

Definition at line 265 of file MSSelection.h.

References getTEN(), and selectedUVUnits_p.

static String casa::MSSelection::indexExprStr ( Vector< Int > index ) [static]

Helper method for converting index vectors to expression strings.

static String casa::MSSelection::nameExprStr ( Vector< String > name ) [static]

Helper method for converting name vectors to expression strings.

MSSelection& casa::MSSelection::operator= ( const MSSelection & other )

Assignment operator.

void casa::MSSelection::reset	(	const MeasurementSet &	ms,
		const MSSMode &	mode = `PARSE_NOW`,
		const String &	timeExpr = `""`,
		const String &	antennaExpr = `""`,
		const String &	fieldExpr = `""`,
		const String &	spwExpr = `""`,
		const String &	uvDistExpr = `""`,
		const String &	taqlExpr = `""`,
		const String &	polnExpr = `""`,
		const String &	scanExpr = `""`,
		const String &	arrayExpr = `""`,
		const String &	stateExpr = `""`,
		const String &	observationExpr = `""`
	)

void casa::MSSelection::reset	(	MSSelectableTable &	msLike,
		const MSSMode &	mode = `PARSE_NOW`,
		const String &	timeExpr = `""`,
		const String &	antennaExpr = `""`,
		const String &	fieldExpr = `""`,
		const String &	spwExpr = `""`,
		const String &	uvDistExpr = `""`,
		const String &	taqlExpr = `""`,
		const String &	polnExpr = `""`,
		const String &	scanExpr = `""`,
		const String &	arrayExpr = `""`,
		const String &	stateExpr = `""`,
		const String &	observationExpr = `""`
	)

void casa::MSSelection::resetMS ( const MeasurementSet & ms ) [inline]

Definition at line 367 of file MSSelection.h.

References ms_p, and resetTEN().

void casa::MSSelection::resetTEN ( ) [inline]

Definition at line 368 of file MSSelection.h.

References fullTEN_p.

Referenced by resetMS().

void casa::MSSelection::runErrorHandler ( )

Bool casa::MSSelection::setAntennaExpr ( const String & antennaExpr )

Expression accessors.

The following set*Expr() methods only set the expressions. Parsing is done with a call to toTableExprNode().

Bool casa::MSSelection::setArrayExpr ( const String & ArrayExpr )

void casa::MSSelection::setErrorHandler	(	const MSExprType	type,
		MSSelectionErrorHandler *	mssEH,
		const Bool	overRide = `False`
	)

Bool casa::MSSelection::setFieldExpr ( const String & fieldExpr )

void casa::MSSelection::setMaxObs ( const Int & n ) [inline]

Definition at line 398 of file MSSelection.h.

References maxObs_p.

void casa::MSSelection::setMaxScans ( const Int & n ) [inline]

Definition at line 397 of file MSSelection.h.

References maxScans_p.

Bool casa::MSSelection::setObservationExpr ( const String & obervationExpr )

Bool casa::MSSelection::setOrder ( MSSelection::MSExprType type ) [private]

Set into the order of the selection expression.

Bool casa::MSSelection::setPolnExpr ( const String & polnExpr )

Bool casa::MSSelection::setScanExpr ( const String & scanExpr )

Bool casa::MSSelection::setSpwExpr ( const String & spwExpr )

Bool casa::MSSelection::setStateExpr ( const String & stateExpr )

Bool casa::MSSelection::setTaQLExpr ( const String & taqlExpr )

Bool casa::MSSelection::setTimeExpr ( const String & timeExpr )

Bool casa::MSSelection::setUvDistExpr ( const String & uvDistExpr )

TableExprNode casa::MSSelection::toTableExprNode ( const MeasurementSet * ms )

Convert to TableExprNode format (C++ interface to TaQL).

This is now for purely backwards compatibility and ease of use. It internally constructs the MSSelectableTable from the supplied MS and calls the generic version of toTableExprNode below (which works with MSSelectableTable object).

TableExprNode casa::MSSelection::toTableExprNode ( MSSelectableTable * msLike )

Convert to TableExprNode format (C++ interface to TaQL).

The MSSelectableTable is a pure-virtual base class which provides a generic interface both to MeasurementSet and CalTable (in the synthesis module) services used in MSSelection. The actual objects used for supplying MeasurementSet or CalTable to MSSelection are MSInterface and CTInterface classes respectively. With this, MSSelection module can be used for selection on MeasurementSet or CalTable.