ms.command - Function

Construct a ms tool using a table query command

Synopsis
command(msfile, command, readonly)

Arguments

msfile	in	name of selected measurement set table
		Allowed:	String
		Default:	no default
command	in	Query string
		Allowed:	Any valid table command
		Default:	no default
readonly	in	prevent changes to the measurement set
		Allowed:	Bool
		Default:	T

Returns
ms tool or fail

Description
Make a new measurement set table and a new ms tool, from a subset of the data in the measurement set the current ms tool is attached to. The subset is selected using the qualification part of the table command as described in note 199. This function will return a new ms tool.

To use this function successfully it helps to have an understanding of the column names used in a measurement set table. These are described in note 229. Any identifiers that are used to refer to rows in a subtable will be zero based ie., the first row is row zero and not row one. This is different to the convention used throught Glish and in other parts of this tool. The example below illustrates this.

The new measurement set must be given a name but it is not written to disk until the close or done functions are performed by the associated tool.

The resulting measurement set is always a reference to the original measurement set, therefore you should not delete the original measurement set from disk unless you also intend to deleted the selected one. However the converse is not true, you may delete the selected measurement set and keep the original one.

Example

      include 'ms.g'
      myms := ms('3C273XC1.ms')
      subms := myms.command('3C273XC1-dd1.ms', 'DATA_DESC_ID == 0')
      print 'The original ms has', myms.nrow(), 'rows.'
      print 'The selected one has', subms.nrow(), 'rows.'
      subms.close()

In this example a new ms tool, called subms, is created that accesses a newly created measurement set called 3C273XC1-dd1.ms. The new tool provides access only to the data where the value in the DATA_DESC_ID column is zero.

This is equivalent to using the selectinit function with an argument of one. This difference in indexing value, between the command and the selectinit functions is illustrative of the difference between zero and one based indexing.

If the measurement set you are using contains data with different spectral windows or polarization setups, then the selected measurement set will have less rows than the original measurement set.

Example

      include 'ms.g'
      myms := ms('3C273XC1.ms')
      subms := myms.command('3C273XC1-a12.ms', 
                            'ANTENNA1 == 0 && ANTENNA2 == 1')
      print 'The original ms has', myms.nrow(), 'rows.'
      print 'The selected one has', subms.nrow(), 'rows.'
      subms.close()

This is identical to the previous example except that a more complex command has been used. In this case all the data from one baseline are selected. The baseline chosen corresponds to data collected from the antennas defined in the first and second rows of the antenna sub-table of the measurement set.

Example

      include 'ms.g'
      myms := ms('3C273XC1.ms')
      subms := myms.command('3C273XC1-a12.ms',
                            'ANTENNA1 == ANTENNA2', readonly=F)
      subms.
      subms.close()

This example selects all the auto-correlations in the measurement set. The resultant ms tool will allow you to modify the data. Because the selected measurement set references the data in the original measurement set modifying the data in the selected measurement set will also change the auto-correlations in original measurement set.

Next: ms.tofits - Function Up: ms - Tool Previous: ms.name - Function Contents Index

	Package	general
	Module	ms
	Tool	ms