ms.getdata - Function

Read values from the measurement set.

Synopsis
getdata(items, ifraxis, ifraxisgap, increment, average)

Arguments

items	in	Item names
		Allowed:	Vector of strings
		Default:	no default
ifraxis	in	Create interferometer axis if true
		Allowed:	Boolean
		Default:	F
ifraxisgap	in	Gap size on ifr axis when antenna1 changes
		Allowed:	Integer
		Default:	0
increment	in	Row increment for data access
		Allowed:	Integer
		Default:	1
average	in	Average the data in time or over rows
		Allowed:	Boolean
		Default:	F

Returns
record with fields containing arrays of data

Description
This function will read the specified items from the currently selected measurement set and returns them in fields of a record. The main difference between this and direct access of the table, using the table tool, is that this function reads data from the selected measurement set, it provides access to derived quantities like amplitude & flag_sum and it can reorder the data.

The items to read are specified, as with the range function, using a vector of strings. Table 1.355 shows the allowable items. Unrecognized items will result in a warning being sent to the logger. Duplicate items are silently ignored.

The record that is returned contains fields that correspond to each of the specified items. Most fields will contain an array. The array may be one, two or three dimensional depending on whether the corresponding row in the measurement set is a scalar, one or two dimensional. Unless the ifraxis argument is set to T the length of the last axis on these arrays will correspond to the number of rows in the selected measurement set.

If the ifraxis argument is set to T, the row axis is split into an interferometer axis and a time axis. For example a measurement set with 90 rows, in an array with 6 telescopes (so that there are 15 interferometers), may have a data array of shape [4,32,90] if ifraxis is F or [4,32,15,6], if ifraxis is T (assuming there are 4 correlations and 32 channels). If there are missing rows as will happen if not all interferometers where used for all time-slots then a default value will be inserted. This splitting of the row axis may not happen for items where there is only a single value per row. For some items the returned vector will contain only as many values as there are interferometers and it is implicit that the same value should be used for all time slots. The antenna1, antenna2, feed1, feed2 & ifr_number items fall in this category. For other items the returned vector will have as many values as there are time slots and it is implicit that the same value should be used for all interefometers. The field_id, scan_number, data_desc_id & time items fall into this category.

The axis_info item provides data labelling information. It returns a record with the following fields; corr_axis, freq_axis, ifr_axis & time_axis. The latter two fields are not present if ifr_axis is set to F. The corr_axis field contains a string vector with elements like 'RR' or 'XY' that indicates which polarizations where correlated together to produce the data. The length of this vector will always be the same as the length of the first axis of the data array. The freq_axis field contains a record with two fields, chan_freq & resolution. Each of these fields contains vectors which indicate the centre frequency and spectral resolution (FWHM) of each channel. The length of these vectors will be the same as the length of the second axis in the data. The ifr_axis field contains for fields; ifr_number, ifr_name, ifr_shortname & baseline. The ifr_number is the same as returned by the ifr_item, the ifr_name & ifr_shortname are string vecors containing descriptions of the interferometer and the baseline is the Euclidian distance, in meters between the two antennas. All of these vectors have a length equal to the number of interferometers in the selected measurement set ie., to the length of the third axis in the data when ifraxis is T. The time_axis field contains the MJDseconds field and optionally the HA, UT & LAST fields. To include the optional fields you need to add the ha, last or ut strings to the list of requested items. All the fields in the time_axis record contain vectors that indicate the time at the midpoint of the observation and are in seconds. The MJDseconds is since 0 hours on the day having a modified julian day number of zero and the rest are since midnight prior to the start of the observation.

An optional gap size can be specified to visually separate groups of interferometers with the same antenna1 index (handy for identifying antennas in an interferometer vs time display). The default is no gap.

An optional increment can be specified to return data from every row matching the increment only.

When the average flag is set, the data will be averaged over the time axis if the ifraxis is T or the row axis i.e., different interferometers and times may be averaged together. In the latter case, some of the coordinate information, like antenna_id, will no longer make sense.

You need to call selectinit before calling this function. If you haven't then selectinit will be called for you with default arguments.

Items prefixed with either; corrected, model, residual or obs_residual and the imaging_weight item are not available unless your measurement set has been processed either with the imager or calibrator tools.

Example

      include 'ms.g'
      myms := ms("3C273XC1.ms")
      myms.selectinit(datadescid=1)
      d := myms.getdata("amplitude ifr_axis ha")
      include 'pgplotter.g'
      pg := pgplotter()
      tstart := min(z.axis_info.time_axis.HA)
      tstop := max(z.axis_info.time_axis.HA)
      maxamp := max(z.amplitude)
      pg.env(tstart, tstop, 0,  maxamp, 0, 1)
      corr := 1;
      ifr := 1;
      chan := 1;
      pg.pt(d.axis_info.time_axis.HA, d.amplitude[corr, ifr, chan,,], 2)
      title := paste('Frequency', 
                    as_string(d.axis_info.freq_axis.chan_freq[chan]/1E9),'GHz',
                    'Baseline', d.axis_info.ifr_axis.ifr_name[corr],
                    '(', d.axis_info.corr_axis[corr], ')')
      pg.lab('Hour angle (sec)', 'Correlation amplitude', title)

This example selects all the data from the measurement set where the value in the DATA_DESC_ID column is zero. This corresponds to a particular spectral window and polarization setup. It then gets the correlated amplitude, and the axis information from this selected measurement set. This is returned in the Glish variable d. The remainder of the example uses the pgplotter tool to make a plot of correlated amplitude vs hour angle for the first channel, correlation and baseline.

Next: ms.putdata - Function Up: ms - Tool Previous: ms.selectpolarization - Function Contents Index

	Package	general
	Module	ms
	Tool	ms