msmetadata

class msmetadata

Operations to retrieve metadata from a measurment set

The msmd tool provides methods to retrieve metadata from measurement sets.

Attaching to a Measurement Set

The simplest and most common way to attach an msmd tool to a measurement set is to use the msmd.open method which requires that you specify the name of the measurement set table.

NOTE: Any modifications to an MS while an associated msmd tool is open will not be reflected in the msmd tool. You must close and reopen the tool if you want to capture changes made to metadata of an MS if such a change occurs.

Methods Summary

almaspws	Get a list of spectral window IDs with ALMA-specific attributes.
antennadiameter	Get the diameter for the specified antenna. The antenna can be specified either by
antennaids	Get the zero-based antenna ID for the specfied antenna name.
antennanames	Get the names of the antennas for the specfied zero-based antenna IDs.
antennaoffset	Get the offset position of the specified antenna relative to the array reference position. Antenna may
antennaposition	Get the position of the specified antenna. The returned record represents a position measure,
antennasforscan	Get an array of the unique antenna IDs for the specified scan, obsservation ID, and array ID.
antennastations	Get the station names of the specified antennas. If a specified antenna name is listed multiple
bandwidths	Get the bandwidths in Hz for the specified spectral windows.
baseband	Get the baseband for the specified spectral window.
baselines	Get a two dimensional boolean array representing baselines for data recorded in the MS. A value of True means
chanavgspws	Get an array of spectral window IDs used for channel averages.
chaneffbws	Get an array of channel effective bandwidths for the specified spectral window. The parameter
chanfreqs	Get an array of channel frequencies for the specified spectral window.
chanres	Get an array of channel resolutions for the specified spectral window. The parameter
chanwidths	Get an array of channel widths for the specified spectral window.
close	Close this tool and reclaim system resources associated with it.
corrprodsforpol	Get the correlation products associated with the specified polarization ID.
corrtypesforpol	Get the correlation types associated with the specified polarization ID.
datadescids	Get the data description IDs associated with the specified spectral window and/or polarization ID
done	Close this tool and reclaim system resources associated with it.
effexposuretime	Get the effective exposure (on-source integration time)
exposuretime	Get the exposure time for the specified scan, spwid, polarization ID, array ID, and observation ID.
fdmspws	Get an array of spectral window IDs used for FDM.
fieldnames	Get an array of field names as they appear in the FIELD table.
fieldsforintent	Get an array of the unique fields for the specified intent.
fieldsforname	Get an array of the unique, zero-based field IDs for the specified field name. If the field name is the
fieldsforscan	Get an array of the unique fields for the specified scan number, observation ID, and array ID.
fieldsforscans	Get an array or dictionary of the unique fields for the specified scan numbers, observationID, and array ID.
fieldsforsource	Get an array of the unique fields for the specified source ID.
fieldsforsources	Get a map of source IDs to fields.
fieldsforspw	Get an array of the unique fields for the specified spectral window.
fieldsfortimes	Get an array of the unique, zero-based, field IDs for the specified time range (time-tol to time+tol).
intents	Get an array of the unique intents associated with the MS.
intentsforfield	Get an array of the unique intents for the specified field.
intentsforscan	Get an array of the unique intents for the specified scan, obsservation ID, and array ID.
intentsforspw	Get an array of the unique intents for the specified spectral window ID.
meanfreq	Get the mean frequency for the specified spectral window.
msmetadata
name	Get the name of the attached MS.
namesforfields	Get the name of the specified field.
namesforspws	Get the name of the specified spws.
nantennas	Get the number of antennas associated with the MS.
narrays	Get the number of arrays associated with the MS from the ARRAY table.
nbaselines	Get the number of baselines represented in the main MS table.
nchan	Get the number of channels associated with the specified spectral window.
ncorrforpol	Get the number of correlations for the specified polarization ID. If the specified polarization ID
nfields	Get the number of fields associated with the MS.
nobservations	Get the number of observations associated with the MS from the OBSERVATIONS table.
nrows	Get the number of visibilities (from the main table) associated with the MS.
nscans	Get the number of scans associated with the MS.
nsources	Get the number of unique values from the SOURCE_ID column in the SOURCE table. The number of rows in the
nspw	Get the number of spectral windows associated with the MS.
nstates	Get the number of states (from the STATE table) associated with the MS.
observatorynames	Get an array of MS telescope (observatory) names as they are listed in the OBSERVATIONS table.
observatoryposition	Get the position of the specified telescope.
observers	Get an array observers as they are listed in the OBSERVATIONS table.
open	Attach the MS metadata tool to the specified MS
phasecenter	Get the phasecenter direction from a field ID and time if necessary
pointingdirection	Get the pointing direction for antennas at the specified row number in the main MS table. Returns a record
polidfordatadesc	Get the polarization ID associated with the specified data description ID. If the specified data description ID
projects	Get an array projects as they are listed in the OBSERVATIONS table.
propermotions	Get the values of the PROPER_MOTION column from the SOURCE table.
refdir	Get the reference direction from a field ID and time if necessary
reffreq	Get the reference frequency of the specified spectral window. The returned frequency is in
restfreqs	Get the rest frequencies from the SOURCE table for the specified source and spectral window.
scannumbers	Get an array of the unique scan numbers associated with the MS for the specified observation ID and array ID.
scansforfield	Get an array of the unique scan numbers associated with the specified field, observation ID, and array ID.
scansforfields	Get a dictionary of which maps field ID to scan numbers for the specified observation ID and array ID.
scansforintent	Get an array of the unique scan numbers associated with the specified intent, observation ID, and arrayID.
scansforspw	Get an array of the unique scan numbers associated with the specified zero-based spectral window ID, observation ID, and array ID.
scansforspws	Get a dictionary of which maps spw ID to scan numbers for the specified observation ID and array ID.
scansforstate	Get an array of the unique scan numbers for the specified state, observation ID, and array ID.
scansfortimes	Get an array of the unique scan numbers for the specified time range (time-tol to time+tol), observation ID, and array ID.
schedule	Get the schedule information for the specified observation ID.
sideband	Get the sideband for the specified spectral window.
sourcedirs	Get the values of the DIRECTION column from the SOURCE table. Returns a dictionary in which the
sourceidforfield	Get the source ID from the field table for the specified field ID.
sourceidsfromsourcetable	Get the values of the SOURCE_ID column from the SOURCE table. It is unfortunate that the SOURCE
sourcenames	Get the values of the SOURCE_NAME column from the SOURCE table.
sourcetimes	Get the values of the TIME column from the SOURCE table. Returns a dictionary in which the
spwfordatadesc	Get the spectral window ID associated with the specified data description ID. If the specified data description ID
spwsforbaseband	Get the spws associated with the specified baseband or dictionary that maps baseband to spws.
spwsforfield	Get an array of the unique spectral window IDs for the specified field.
spwsforfields	Get a dictionary which maps field IDs to spectral window IDs. The field IDs are keys in the
spwsforintent	Get an array of the unique spectral window IDs for the specified intent.
spwsfornames	Get the IDs of the specified spw names.
spwsforscan	Get an array of the unique spectral window IDs for the specified scan number, observation ID, and array ID.
spwsforscans	Get a dictionary of which maps scan number to spectral windows for the specified observation ID and array ID. The keys (scan
statesforscan	Get an array of the unique state IDs for the specified scan number, observation ID, and array ID.
statesforscans	Get a dictionary which maps scan numbers to state IDs for the specified array and observation IDs. The returned dictionary
summary	Get dictionary summarizing the MS.
tdmspws	Get an array of spectral window IDs used for TDM.
timerangeforobs	Get the time range for the specified observation ID. The return value is a dictionary containing
timesforfield	Get an array of the unique times for the specified field.
timesforintent	Get an array of the unique times for the specified intent.
timesforscan	Get the unique times for the specified scan number, observation ID, and array ID. If perspw=True, the returned data structure is
timesforscans	Get an array of the unique times for the specified scan numbers, observation ID, and array ID.
timesforspws	Get the unique times corresponding to the specified spectral window(s). The input indicates the
transitions	Get the spectral transitions from the SOURCE table for the specified source and spectral window.
wvrspws	Get an array of spectral window IDs used for WVR. These are windows that have 4 channels.

almaspws(chavg=False, fdm=False, sqld=False, tdm=False, wvr=False, complement=False)

Get a list of spectral window IDs with ALMA-specific attributes.

Get spectral window IDs based on ALMA-specific criteria. The inputs are or’ed together

to form the returned list. If complement=True, then the complement of the selection is returned.

If the SPECTRAL_WINDOW table has the optional BBC_NO column and if the name of the spectral window matches the regular expression “BB_[0-9]#SQLD”, where [0-9] indicates that a single integer matches, the window is classified as a square law detector spectral window.

The following algorithm is used to identify WVR spwectral windows: 1. check for water vapor radiometer (WVR) spectral windows using the spectral window

name “WVR#NOMINAL” and report these.

2. If no SPWs match that string, then the names are checked for “WVR” and are reported instead. If the window is not found to be a WVR window, it is then checked if

The window is classified as a channel average spectral window if it is not a WVR window, if the number of channels is one, and the spectral window name does not contain the string “FULL_RES”

The window is classifed as an FDM window if it is neither a WVR window nor a channel average window and if either 1. its bandwidth is less than 2 GHz, or 2. the number of channels it contains is greater than or equal to 15 but not

equal to 256, 128, 64, 32, 16, 248, 124, 62, or 31.

The window is classified as a TDM spectral window if it is neither a WVR window, a channel average window, nor an FDM window.

Parameters

• chavg (bool=False) - Get channel average spectral windows?

• fdm (bool=False) - Get FDM spectral windows?

• sqld (bool=False) - Get square law (i.e. total power) detector spectral windows?

• tdm (bool=False) - Get TDM spectral windows?

• wvr (bool=False) - Get WVR spectral windows?

• complement (bool=False) - Return the complement of the selected set?

antennadiameter(antenna='-1')

Get the diameter for the specified antenna. The antenna can be specified either by

its zero-based ID from the ANTENNA table or by its name in that table. The returned dictionary is a valid quantity. If a negative integer is provided for the antenna, then all atenna diameters will be returned in a dictionary that has keys that are the antenna IDs and values that are dictionaries, each being a valid quantity representing the diameter for that antenna ID.

Parameters

• antenna ({string, int}='-1') - Zero-based antenna in the ANTENNA table, or antenna name. A negative integer will cause all antenna diameters to be returned.

antennaids(name='', mindiameter='0m', maxdiameter='1pc', obsid=- 1)

Get the zero-based antenna ID for the specfied antenna name.

Get the zero-based antenna IDs for the specfied antenna names and the specified diameter

range for the specified observation ID. An array of unique IDs in order of the specified names is returned. Note that if a specified name is listed mulitple times in the ANTENNA table, the largest ID is returned, unless the observation ID is specified to be non-negative, in which case, the returned IDs are filtered based on the specified observation ID. If no names and no diameter range is specified, all IDs are returned.

Parameters

• name ({string, stringArray}='') - Antenna names (string or string array) for which to get the corresponding IDs. Note that * matches any number of characters of all character classes.

• mindiameter (variant='0m') - Minimum antenna diameter, expressed as a quantity.

• maxdiameter (variant='1pc') - Maximum antenna diameter, expressed as a quantity.

• obsid (int=-1) - Observation ID. If negative, all observation IDs are considered.

antennanames(antennaids=- 1)

Get the names of the antennas for the specfied zero-based antenna IDs.

Get the name of the antenna for the specfied zero-based antenna ID. If antennaids is not specified,

all antenna names are returned.

Parameters

• antennaids ({int, intArray}=-1) - Zero-based antenna IDs (int or int array) for which to get the antenna names.

antennaoffset(which='0')

Get the offset position of the specified antenna relative to the array reference position. Antenna may

be specified as a zero-based integer (row number in the ANTENNA table) or a string representing a valid antenna name. The returned record contains the longitude, latitude, and elevation offsets as quantity records. The reported longitude and latitude offsets are measured along the surface of a sphere whose center is coincident with the center of the earth and whose surface contains the observatory reference position.

Parameters

• which ({string, int}='0') - Zero-based antenna in the ANTENNA table, or antenna name.

antennaposition(which='0')

Get the position of the specified antenna. The returned record represents a position measure,

and can be used as such by the measures (me) tool.

Parameters

• which ({int, string}='0') - Zero-based antenna ID in the ANTENNA table or antenna name.

antennasforscan(scan=- 1, obsid=- 1, arrayid=- 1)

Get an array of the unique antenna IDs for the specified scan, obsservation ID, and array ID.

Get an array of the unique antennaIDs for the specified scan, observation ID, and array ID.

Parameters

• scan (int=-1) - Scan number for which to return the intents.

• obsid (int=-1) - Observation ID. If less than 0, all observation IDs are used.

• arrayid (int=-1) - Array ID. If less than 0, all array IDs are used.

antennastations(which='-1', obsid=- 1)

Get the station names of the specified antennas. If a specified antenna name is listed multiple

times in the ANTENNA table, obsid is negative, and which is specified as an array of names, then the station associated with the largest ID for that antenna is returned. If obsid is nonnegative, returned stations are filtered based on that. If which is specified as a string (antenna name), then all the stations associated with that antenna are returned.

Parameters

• which ({int, string, intArray, stringArray}='-1') - Zero-based antenna ID(s) in the ANTENNA table or antenna name(s). Single numeric id less than zero retrieves all station names.

• obsid (int=-1) - Observation ID. If negative, all observation IDs are considered.

bandwidths(spw=- 1)

Get the bandwidths in Hz for the specified spectral windows. If spw less than zero, return bandwidths for all spectral windows.

Parameters

• spw ({int, intArray}=-1) - Spectral window IDs, if integer less than zero, return bandwidths for all spectral windows.

baseband(spw='')

Get the baseband for the specified spectral window.

Parameters

• spw (int='') - Spectral window ID.

baselines()

Get a two dimensional boolean array representing baselines for data recorded in the MS. A value of True means

there is at least one row in the MS main table for that baseline, False means no rows for that baseline. Autocorrelation “baseline” information is also present via the values along the diagonal.

chanavgspws()

Get an array of spectral window IDs used for channel averages. These are windows that do have 1 channel.

chaneffbws(spw='', unit='', asvel=False)

Get an array of channel effective bandwidths for the specified spectral window. The parameter

asvel indicates if velocity widths (True) or frequency widths (False) should be returned. The unit parameter specifies the units that the returned values should have. If empty (default), “Hz” will be used if asvel=False, or “km/s” will be used if asvel=True.

Parameters

• spw (int='') - Spectral window ID.

• unit (string='') - Desired unit of returned quantities. Empty means “Hz” if asvel=False, “km/s” if asvel=True.

• asvel (bool=False) - Should return values be equivalent velocity widths?

chanfreqs(spw='', unit='Hz')

Get an array of channel frequencies for the specified spectral window.

Parameters

• spw (int='') - Spectral window ID.

• unit (string='Hz') - Convert frequencies to this unit.

chanres(spw='', unit='', asvel=False)

Get an array of channel resolutions for the specified spectral window. The parameter

asvel indicates if velocity widths (True) or frequency widths (False) should be returned. The unit parameter specifies the units that the returned values should have. If empty (default), “Hz” will be used if asvel=False, or “km/s” will be used if asvel=True.

Parameters

• spw (int='') - Spectral window ID.

• unit (string='') - Desired unit of returned quantities. Empty means “Hz” if asvel=False, “km/s” if asvel=True.

• asvel (bool=False) - Should return values be equivalent velocity resolutions?

chanwidths(spw='', unit='Hz')

Get an array of channel widths for the specified spectral window.

Parameters

• spw (int='') - Spectral window ID.

• unit (string='Hz') - Convert frequencies to this unit.

close()

Close this tool and reclaim system resources associated with it.

This method will close the tool and reclaim system resources it has been using. Returns true if successful.

corrprodsforpol(pol=- 1)

Get the correlation products associated with the specified polarization ID.

Parameters

• pol (int=-1) - Polarization ID. Must be nonnegative.

corrtypesforpol(pol=- 1)

Get the correlation types associated with the specified polarization ID.

Parameters

• pol (int=-1) - Polarization ID. Must be nonnegative.

datadescids(spw=- 1, pol=- 1)

Get the data description IDs associated with the specified spectral window and/or polarization ID

Get a list of data description IDs associated with the specified spectral window ID

and/or polarization ID. Values of less than zero for either means all IDs should be used in the selection.

Parameters

• spw (int=-1) - Spectral window ID. Less than zero implies any,

• pol (int=-1) - Polarization ID. Less than zero implies any.

done()

Close this tool and reclaim system resources associated with it.

This method will close the tool and reclaim system resources it has been using. Returns true if successful.

effexposuretime()

Get the effective exposure (on-source integration time)

Get the effective exposure time (equivalent to what might be more commonly known as total integration

time or total sample time) is calculated by summing over all rows in the main MS table, excluding autocorrelations or rows where FLAG_ROW is false, thusly:

sum[over i] (exposure[i]*sum[over j](UFBW[i, j])/ncorrelations[i] )/ nmaxbaselines

where exposure[i] is the value of EXPOSURE for the ith row, the inner sum is performed over each correlation for that row, UFBW is the unflagged fractional bandwidth is determined by summing all the widths of the unflagged channels for that correlation and dividing by the total bandwidth of all spectral windows observed at the timestamp of row i, ncorrelations is the number of correlations determined by the number of rows in the FLAG matrix for MS row i, and nmaxbaselines is the maximum number of antenna pairs, nantennas*(nantennas-1)/2, where nantennas is the number of antennas in the ANTENNA table. This method returns a quantity (a dictionary having a numerical value and a string unit).

exposuretime(scan=0, spwid=0, polid=- 1, obsid=0, arrayid=0)

Get the exposure time for the specified scan, spwid, polarization ID, array ID, and observation ID.

This is the exposure time of the record with the lowest time stamp of the records associated with these parameters. Returns a quantity dictionary. If polid is not specified (or specified and negative) and there is only one polarization ID in for the specified combination of scan, spwid, obsID, and arrayID, then that polarization ID is used. If there are multiple polarization IDs for the combination of other parameters, a list of these is logged and an empty dictionary is returned.

Parameters

• scan (int=0) - Scan number.

• spwid (int=0) - Spectral window ID.

• polid (int=-1) - Polarization ID.

• obsid (int=0) - Observation ID.

• arrayid (int=0) - Array ID.

fdmspws()

Get an array of spectral window IDs used for FDM. These are windows that do not have 64, 128, or 256 channels.

fieldnames()

Get an array of field names as they appear in the FIELD table.

fieldsforintent(intent='', asnames=False)

Get an array of the unique fields for the specified intent. Note that * matches any number of characters of all character classes.

Parameters

• intent (string='') - Intent (case sensitive) for which to return the fields.

• asnames (bool=False) - If true, return the field names. If false, return the zero-based field IDs.

fieldsforname(name='')

Get an array of the unique, zero-based field IDs for the specified field name. If the field name is the

empty string (the default), a list of all unique field IDs in the main table of the MS will be returned.

Parameters

• name (string='') - Field name (case sensitive) for which to return the fields.

fieldsforscan(scan=- 1, asnames=False, obsid=- 1, arrayid=- 1)

Get an array of the unique fields for the specified scan number, observation ID, and array ID.

Parameters

• scan (int=-1) - Scan number for which to return the fields.

• asnames (bool=False) - If true, return the field names. If false, return the zero-based field IDs.

• obsid (int=-1) - Observation ID. A negative value means use all observation IDs.

• arrayid (int=-1) - Array ID. A negative value means use all array IDs.

fieldsforscans(scans=[''], asnames=False, obsid=- 1, arrayid=- 1, asmap=False)

Get an array or dictionary of the unique fields for the specified scan numbers, observationID, and array ID.

Get an array or dictionary of the unique fields for the specified scan numbers, observation ID, and array ID.

If asnames=True, the values returned will be the field names, if False, they will be field IDs. If asmap=True, the structure returned will be a dictionary which maps scan number (as a string) to fields. In this case, both obsid and arrayid must be nonnegative. If asmap=False, a single array of fields is returned that matches the query. In this case, if obsid and/or arrayid are negative, then it indicates that all fields matching any obsid and/or arrayid should be returned. An empty array specified for scans means that all scans for the selected obsid and arrayid should be included.

Parameters

• scans (intArray=['']) - Scan numbers for which to return the fields.

• asnames (bool=False) - If true, return the field names. If false, return the zero-based field IDs.

• obsid (int=-1) - Observation ID. A negative value means use all observation IDs.

• arrayid (int=-1) - Array ID. A negative value means use all array IDs.

• asmap (bool=False) - Return a dictionary mapping scan numbers to fields?

fieldsforsource(source=- 1, asnames=False)

Get an array of the unique fields for the specified source ID.

Get an array of the unique fields for the specified source.

Parameters

• source (int=-1) - Zero-based source ID for which to return the fields.

• asnames (bool=False) - If true, return the field names. If false, return the zero-based field IDs.

fieldsforsources(asnames=False)

Get a map of source IDs to fields. The keys (source IDs) will be strings.

Parameters

• asnames (bool=False) - If true, return the field names. If false, return the zero-based field IDs.

fieldsforspw(spw=- 1, asnames=False)

Get an array of the unique fields for the specified spectral window.

Parameters

• spw (int=-1) - Zero-based spectral window ID for which to return the fields.

• asnames (bool=False) - If true, return the field names. If false, return the zero-based field IDs.

fieldsfortimes(time=- 1, tol=0)

Get an array of the unique, zero-based, field IDs for the specified time range (time-tol to time+tol).

Get an array of the unique, zero-based, fieldIDs for the specified time range (time-tol to time+tol).

Parameters

• time (double=-1) - Time at center of time range.

• tol (double=0) - Time on either side of center for specifying range.

intents()

Get an array of the unique intents associated with the MS.

intentsforfield(field='-1')

Get an array of the unique intents for the specified field.

Parameters

• field ({int, string}='-1') - Field ID or name for which to return the intents.

intentsforscan(scan=- 1, obsid=- 1, arrayid=- 1)

Get an array of the unique intents for the specified scan, obsservation ID, and array ID.

Get an array of the unique intents for the specified scan, observation ID, and array ID.

Parameters

• scan (int=-1) - Scan number for which to return the intents.

• obsid (int=-1) - Observation ID. A negative value means use all observation IDs.

• arrayid (int=-1) - Array ID. A negative value means use all array IDs.

intentsforspw(spw=- 1)

Get an array of the unique intents for the specified spectral window ID.

Parameters

• spw (int=-1) - Spectral window ID (>=0) for which to return the intents.

meanfreq(spw='', unit='Hz')

Get the mean frequency for the specified spectral window.

Parameters

• spw (int='') - Spectral window ID.

• unit (string='Hz') - Convert frequencies to this unit.

msmetadata()

name()

Get the name of the attached MS.

namesforfields(fieldids='')

Get the name of the specified field.

Parameters

• fieldids ({string, int, intArray}='') - Zero-based field IDs for which to get the names (integer or interger array). Unspecified will return all field names.

namesforspws(spwids='')

Get the name of the specified spws.

Get the name of the specified spw(s).

Parameters

• spwids ({string, int, intArray}='') - Zero-based spw ID(s) for which to get the names (integer or interger array). Unspecified will return all spw names.

nantennas()

Get the number of antennas associated with the MS.

narrays()

Get the number of arrays associated with the MS from the ARRAY table.

nbaselines(ac=False)

Get the number of baselines represented in the main MS table.

Get the number of unique baselines (antenna pairs) represented in the main MS table. This can, in theory, be less than

n*(n-1)/2 (n being the number of antennas in the ANTENNA table), if data for certain baselines are not included in the main MS table. Autocorrelation “baselines” are included in this count if ac=True.

Parameters

• ac (bool=False) - Include auto-correlation “baselines”?

nchan(spw='')

Get the number of channels associated with the specified spectral window.

Parameters

• spw (int='') - Zero-based spw ID for which to get the number of channels.

ncorrforpol(polid=- 1)

Get the number of correlations for the specified polarization ID. If the specified polarization ID

is negative, an array of numbers of correlations is returned. The indices of that array represent polarization IDs.

Parameters

• polid (int=-1) - Zero-based polarization ID. A negative number will cause all the numbers of correlations to be returned.

nfields()

Get the number of fields associated with the MS.

nobservations()

Get the number of observations associated with the MS from the OBSERVATIONS table.

nrows(autoc=True, flagged=True)

Get the number of visibilities (from the main table) associated with the MS.

Parameters

• autoc (bool=True) - Include autocorrelation data? If False, only cross correlation rows will be summed.

• flagged (bool=True) - Include flagged data? If False, only unflagged or patially flagged rows will be summed.

nscans()

Get the number of scans associated with the MS.

nsources()

Get the number of unique values from the SOURCE_ID column in the SOURCE table. The number of rows in the

SOURCE table may be greater than this value.

nspw(includewvr=True)

Get the number of spectral windows associated with the MS.

This method will return the number of spectral windows in the associated MS.

Parameters

• includewvr (bool=True) - Include wvr spectral windows? If false, exclude wvr windows from count.

nstates()

Get the number of states (from the STATE table) associated with the MS.

This method will return the number of states (number of rows in the STATES table) in the associated MS.

observatorynames()

Get an array of MS telescope (observatory) names as they are listed in the OBSERVATIONS table.

observatoryposition(which=0)

Get the position of the specified telescope.

Parameters

• which (int=0) - Zero-based telescope position in the OBSERVATIONS table (see msmd.telescopenames()).

observers()

Get an array observers as they are listed in the OBSERVATIONS table.

Get an array of observers as they are listed in the OBSERVATIONS table.

open(msfile='', maxcache=50)

Attach the MS metadata tool to the specified MS

Attach this tool to the specified MS. This method runs a few basic MS validation tests, and if any of these

fail (which indicates that the MS is invalid), an error occurs and the tool is not attached to the MS. Note that it is ultimately the user’s responsibility to ensure that the MS is valid. Running the methods of this tool on an invalid MS may result in incorrect results or even a crash of CASA. Such invalidities include any MS subtable not having appropriate information (eg, an OBSERVATION subtable not having enough rows to account for all the OBSERVATION_IDs in the main table).

Parameters

• msfile (string='') - Name of the existing measurement set

• maxcache (float=50) - Maximum cache size, in megabytes, to use.

phasecenter(fieldid=0, epoch='')

Get the phasecenter direction from a field ID and time if necessary

Get a direction measures for the phasecenter of the field id and time specified

Parameters

• fieldid (int=0) - Zero-based field ID for which to get the phasecenter; default fieldid=0

• epoch (record='') - Optional time, expressed as a measures epoch dictionary, if field id has a polynomial in time phasecenter or an ephemerides table attached to the ID. Default value means evaluate at the origin TIME in the FIELD table

pointingdirection(rownum=0, interpolate=False, initialrow=0)

Get the pointing direction for antennas at the specified row number in the main MS table. Returns a record

containing the time, antenna IDs and corresponding pointing directions.

Parameters

• rownum (int=0) - Row number in the main MS table.

• interpolate (bool=False) - Interpolate pointings in case the interval in the main table is shorter than that in the pointing table (often the case in fast-scanning in single dish observaitions)

• initialrow (int=0) - Initial guess of row index in pointing table to start search.

polidfordatadesc(ddid=- 1)

Get the polarization ID associated with the specified data description ID. If the specified data description ID

is negative, an array of polarization IDs is returned. The indices of that array represent data description IDs.

Parameters

• ddid (int=-1) - Zero-based data description ID. A negative number will cause all the polarization IDs to be returned.

projects()

Get an array projects as they are listed in the OBSERVATIONS table.

Get an array of projects as they are listed in the OBSERVATIONS table.

propermotions()

Get the values of the PROPER_MOTION column from the SOURCE table.

Get the values of the DIRECTION column from the SOURCE table. Returns a dictionary in which the

keys are the associated zero-based row numbers, represented as strings, in the SOURCE table. The associated values are two element dictionaries, with keys “longitude” and “latitude”, containing the longitudinal and latidinal components of the proper motion, which are valid quantity dictionaries.

refdir(field='0', epoch='')

Get the reference direction from a field ID and time if necessary

Get a direction measure for the reference direction of the field and time specified

Parameters

• field ({string, int}='0') - Zero-based field ID or field name for which to get the reference direction; default field=0

• epoch (record='') - Optional time, expressed as a measures epoch dictionary, if associated field has a polynomial in time reference direction or an ephemerides table attached it. Default value means evaluate at the origin TIME in the FIELD table

reffreq(spw=- 1)

Get the reference frequency of the specified spectral window. The returned frequency is in

the form of a valid measures dictionary.

Parameters

• spw (int=-1) - Zero-based spectral window ID.

restfreqs(sourceid=0, spw=0)

Get the rest frequencies from the SOURCE table for the specified source and spectral window.

The return value will be a dictionary of frequency measures if the rest frequencies are defined for the specified inputs, or False if they do not.

Parameters

• sourceid (int=0) - Zero-based source ID (from the SOURCE::SOURCE_ID column).

• spw (int=0) - Zero-based spectral window ID.

scannumbers(obsid=- 1, arrayid=- 1)

Get an array of the unique scan numbers associated with the MS for the specified observation ID and array ID.

This method will return an array of unique scan numbers in the associated MS for the specified observation ID and array ID.

Parameters

• obsid (int=-1) - Observation ID. A negative value indicates all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value indicates all array IDs should be used.

scansforfield(field='', obsid=- 1, arrayid=- 1)

Get an array of the unique scan numbers associated with the specified field, observation ID, and array ID.

Parameters

• field ({string, int}='') - Field ID or field name (case sensitive) for which to return the scan numbers.

• obsid (int=-1) - Observation ID. A negative value indicates all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value indicates all array IDs should be used.

scansforfields(obsid=0, arrayid=0)

Get a dictionary of which maps field ID to scan numbers for the specified observation ID and array ID.

Get a dictionary of which maps field ID to scan numbers for the specified observation ID

and array ID. The keys (field IDs) will be strings. obsid and arrayid must both be non-negative.

Parameters

• obsid (int=0) - Observation ID. Must be non-negative.

• arrayid (int=0) - Array ID. Must be non-negative.

scansforintent(intent='', obsid=- 1, arrayid=- 1)

Get an array of the unique scan numbers associated with the specified intent, observation ID, and arrayID.

The “*” character matches any number of characters from all character classes.

Parameters

• intent (string='') - Intent (case-sensitive) for which to return the scan numbers.

• obsid (int=-1) - Observation ID. A negative value indicates all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value indicates all array IDs should be used.

scansforspw(spw=- 1, obsid=- 1, arrayid=- 1)

Get an array of the unique scan numbers associated with the specified zero-based spectral window ID, observation ID, and array ID.

Parameters

• spw (int=-1) - Zero-based spectral window ID for which to return the scan numbers.

• obsid (int=-1) - Observation ID. A negative value indicates all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value indicates all array IDs should be used.

scansforspws(obsid=0, arrayid=0)

Get a dictionary of which maps spw ID to scan numbers for the specified observation ID and array ID.

Get a dictionary of which maps spw ID to scan numbers for the specified observation ID

and array ID. The keys (spectral window IDs) will be strings. obsid and arrayid must both be non-negative.

Parameters

• obsid (int=0) - Observation ID. Must be non-negative.

• arrayid (int=0) - Array ID. Must be non-negative.

scansforstate(state=- 1, obsid=- 1, arrayid=- 1)

Get an array of the unique scan numbers for the specified state, observation ID, and array ID.

Parameters

• state (int=-1) - ID of state for which to return the scan numbers.

• obsid (int=-1) - Observation ID. A negative value indicates all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value indicates all array IDs should be used.

scansfortimes(time=- 1, tol=0, obsid=- 1, arrayid=- 1)

Get an array of the unique scan numbers for the specified time range (time-tol to time+tol), observation ID, and array ID.

Parameters

• time (double=-1) - Time at center of time range.

• tol (double=0) - Time difference on either side of center for specifying range.

• obsid (int=-1) - Observation ID. A negative value indicates all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value indicates all array IDs should be used.

schedule(obsid=- 1)

Get the schedule information for the specified observation ID.

Parameters

• obsid (int=-1) - Observation ID.

sideband(spw='')

Get the sideband for the specified spectral window.

Parameters

• spw (int='') - Spectral window ID.

sourcedirs()

Get the values of the DIRECTION column from the SOURCE table. Returns a dictionary in which the

keys are the associated row numbers, represented as strings, in the SOURCE table. Each value in the returned dictionary is a valid direction measure.

sourceidforfield(field=- 1)

Get the source ID from the field table for the specified field ID.

Parameters

• field (int=-1) - Zero-based field ID for which to return the source ID from the field table.

sourceidsfromsourcetable()

Get the values of the SOURCE_ID column from the SOURCE table. It is unfortunate that the SOURCE

table has a column named SOURCE_ID, because implicitly the “ID” of a row in an MS subtable is generally meant to reflect a row number in that table, but that is not the case for the SOURCE table.

sourcenames()

Get the values of the SOURCE_NAME column from the SOURCE table.

sourcetimes()

Get the values of the TIME column from the SOURCE table. Returns a dictionary in which the

keys are the associated row numbers, represented as strings, in the SOURCE table. Each value in the returned dictionary is a valid time quantity.

spwfordatadesc(ddid=- 1)

Get the spectral window ID associated with the specified data description ID. If the specified data description ID

is negative, an array of spectral window IDs is returned. The indices of that array represent data description IDs.

Parameters

• ddid (int=-1) - Zero-based data description ID. A negative number will cause all the spectral window IDs to be returned.

spwsforbaseband(baseband=- 1, sqldmode='include')

Get the spws associated with the specified baseband or dictionary that maps baseband to spws.

Get the spectral windows associated with the specified baseband or dictionary that maps baseband to spectral windows.

Parameters

• baseband (int=-1) - Baseband number. If <0, return a dictionary mapping basebands to spws.

• sqldmode (string='include') - If “include”, include SQLD windows, if “exclude”, exclude SQLD windows, if “only”, include only SQLD windows. Case insenstive, inimum match honored.

spwsforfield(field='')

Get an array of the unique spectral window IDs for the specified field.

Parameters

• field ({string, int}='') - Field (case sensitive string or zero-based integer ID) for which to return the spectral window IDs.

spwsforfields()

Get a dictionary which maps field IDs to spectral window IDs. The field IDs are keys in the

returned dictionary. To access a particular element, one must ensure the key is a string.

spwsforintent(intent='')

Get an array of the unique spectral window IDs for the specified intent. The “*” character matches any number of characters from all character classes.

Parameters

• intent (string='') - Intent (case sensitive) for which to return the spectral window IDs.

spwsfornames(spwids='')

Get the IDs of the specified spw names.

Get the IDs of the specified spw(s). Returns a dictionary where the keys

are the requested spectral window names that are present in the data set and the values are arrays of the spectral window IDs corresponding to the name. If a specified name is not present, a warning message is logged and that name is not included in the returned dictionary. Specifying no names results in a dictionary containing the name to spw ID mapping for the entire data set.

Parameters

• spwids ({string, stringArray}='') - Names of the spws for which IDs are needed (string or string array). Unspecified will return all spw names.

spwsforscan(scan=- 1, obsid=- 1, arrayid=- 1)

Get an array of the unique spectral window IDs for the specified scan number, observation ID, and array ID.

Parameters

• scan (int=-1) - Scan number for which to return the spectral window IDs.

• obsid (int=-1) - Observation ID. A negative value means that all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value means that all array IDs should be used.

spwsforscans(obsid=0, arrayid=0)

Get a dictionary of which maps scan number to spectral windows for the specified observation ID and array ID. The keys (scan

numbers) will be strings. obsid and arrayid must both be non-negative.

Parameters

• obsid (int=0) - Observation ID. Must be non-negative.

• arrayid (int=0) - Array ID. Must be non-negative.

statesforscan(scan=- 1, obsid=- 1, arrayid=- 1)

Get an array of the unique state IDs for the specified scan number, observation ID, and array ID.

Parameters

• scan (int=-1) - Scan number for which to return the state IDs.

• obsid (int=-1) - Observation ID. A negative value means that all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value means that all array IDs should be used.

statesforscans(obsid=0, arrayid=0)

Get a dictionary which maps scan numbers to state IDs for the specified array and observation IDs. The returned dictionary

will have scan numbers, as strings, as keys.

Parameters

• obsid (int=0) - Observation ID, must be nonnegative.

• arrayid (int=0) - Array ID, must be nonnegative.

summary()

Get dictionary summarizing the MS.

tdmspws()

Get an array of spectral window IDs used for TDM. These are windows that have 64, 128, or 256 channels.

timerangeforobs(obsid=- 1)

Get the time range for the specified observation ID. The return value is a dictionary containing

keys “begin” and “end”. Each of the associated value are dictionaries representing epochs which are valid measure records. The values are taken directly from the OBSERVATION subtable; no half-intervals are added or subtracted.

Parameters

• obsid (int=-1) - Zero-based observation ID for which to get the time range.

timesforfield(field=- 1)

Get an array of the unique times for the specified field.

Parameters

• field (int=-1) - Zero-based field ID for which to return the times.

timesforintent(intent='')

Get an array of the unique times for the specified intent.

Parameters

• intent (string='') - Intent for which to return the times.

timesforscan(scan=- 1, obsid=- 1, arrayid=- 1, perspw=False)

Get the unique times for the specified scan number, observation ID, and array ID. If perspw=True, the returned data structure is

a dictionary that has keys representing zero-based spectral window IDs and values representing the unique values of the TIME column corrsponding to the specified scan and that corresponding spectral window ID. If False, an array of unique values from the TIME column for the specified scan is returned; there is no separation into spectral window IDs.

Parameters

• scan (int=-1) - Scan number for which to return the times.

• obsid (int=-1) - Observation ID. A negative value indicates all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value indicates all array IDs should be used.

• perspw (bool=False) - Return output dictionary with keys representing spectral window IDs (True), or an array of all times (False).

timesforscans(scans=- 1, obsid=- 1, arrayid=- 1)

Get an array of the unique times for the specified scan numbers, observation ID, and array ID.

Parameters

• scans ({int, intArray}=-1) - Scan number(s) for which to return the times.

• obsid (int=-1) - Observation ID. A negative value indicates all observation IDs should be used.

• arrayid (int=-1) - Array ID. A negative value indicates all array IDs should be used.

timesforspws(spw=- 1)

Get the unique times corresponding to the specified spectral window(s). The input indicates the

spws for which times are to be retrieved, and can be a single integer or an array of integers. If a single, non-negative integer, an array of unique times associated with that spectral window are returned. Otherwise, a dictionary of times associated with the specified spectral windows are returned, with the spws (as strings) as the keys and the times as the values. A negative integer will cause a dictionary of all spws and their associated times to be returned.

Parameters

• spw ({int, intArray}=-1) - Zero-based spectral window ID(s). A negative integer will cause the all the times for all spws to be returned.

transitions(sourceid=0, spw=0)

Get the spectral transitions from the SOURCE table for the specified source and spectral window.

The return value will be an array of transitions if the transitions are defined for the specified inputs, or False if they do not.

Parameters

• sourceid (int=0) - Zero-based source ID (from the SOURCE::SOURCE_ID column).

• spw (int=0) - Zero-based spectral window ID.

wvrspws(complement=False)

Get an array of spectral window IDs used for WVR. These are windows that have 4 channels.

If complement is True, return the complement set instead (all non-wvr spw IDs). WVR windows are identified using the algorithm 1. check for water vapor radiometer (WVR) spectral windows using the spectral window

name “WVR#NOMINAL” and report these.

2. If no SPWs match that string, then the names are checked for “WVR” and are reported instead.

Parameters

• complement (bool=False) - If True, return all non-wvr spws.