MeasurementSet

class MeasurementSet(name: str, session: str | None = None)

Bases: object

A logical representation of a MeasurementSet (MS).

The MeasurementSet class represents the metadata and relationships held in a measurement set on disk, acting as an in-memory representation so that metadata and relationships can be quickly queried without additional disk I/O.

MeasurementSet does not cache binary data or offer functions to facilitate processing of binary data held in the measurement set. For general reading of binary data, see the MSWrapper class.

name

Name of MeasurementSet, equivalent to file path to MeasurementSet.

session

Name of session associated with MS.

exclude_num_chans

Tuple containing spectral window sizes (in number of channels) used to filter out non-science-spectral-windows.

filesize

Disk size of MS.

acs_software_build_version

ALMA Common Software build version used to create this MS (None if not ALMA).

acs_software_version

ALMA Common Software version used to create this MS (None if not ALMA).

antenna_array

Antenna array information.

array_name

Name of array configuration.

correlator_name

The name of the correlator, populated from the PROCESSOR table. Example values: ALMA_ACA, ALMA_BASELINE.

data_column

A dictionary to store data type (key) and corresponding data column (value).

data_descriptions

A list of DataDescription objects associated with MS.

data_types_per_source_and_spw

A dictionary to store a list of available data types (values) in this MS per (source,spw) tuples (keys).

execblock_id

Execution Block ID for this MS (only for ALMA, VLA).

fields

A list of Field objects associated with MS.

observer

The name of the observer, as listed in the OBSERVATIONS table.

observing_modes

The name(s) of the Observing Mode(s) used for this MS, populated from the ASDM_SBSUMMARY table (empty list if not ALMA).

polarizations

A list of Polarization objects associated with the MS.

project_id

Project ID associated with this MS, as listed in the OBSERVATIONS table.

representative_target

A tuple of the name of representative source, frequency and bandwidth.

representative_window

A representative spectral window name.

scans

A list of Scan objects associated with MS.

schedblock_id

Scheduling Block ID for this MS (only for ALMA, VLA).

science_goals

A science goal information consists of min/max acceptable angular resolution, max allowed beam ratio, sensitivity, dynamic range, spectral dynamic range bandwidth (Cycle 10+), and SB name.

sources

A list of Source objects associated with MS.

spectral_windows

A list of SpectralWindow objects associated with MS.

spectralspec_spwmap

A dictionary to map each SpectralSpec to a list of corresponding spectral window IDs.

states

A list of State objects associated with MS.

derived_fluxes

Calibrated visibility based flux measurements derived during pipeline run, used in subsequent imaging stages.

fluxscale_fluxes

Flux measurements derived by CASA's fluxscale during the hifa_gfluxscale task, for use by a subsequent hifa_polcal task (ALMA interferometry polarisation calibration only).

origin_ms

A path to the first generation MeasurementSet from which the current MS is generated. This is typically set by tasks such as h_mssplit, hif_mstransform, hifv_mstransform, hif_transformimagedata.

phase_calapps_for_check_sources

List of CalApplications for the phase calibration of the check source(s) generated during hifa_gfluxscale. These are used in a subsequent hifa_timegaincal task to overplot the phase calibration for check source in its Diagnostic Phase Vs. Time plots.

phasecal_mapping

A dictionary mapping phase calibrator fields to corresponding fields with TARGET or CHECK intent; typically populated by the hifa_spwphaseup task (ALMA-only).

phaseup_caltable_for_phase_rms

The bandpass phase-up caltable created during the hifa_bandpass task (prior to deriving the bandpass solution), for use in subsequent phase RMS stability assessment during the hifa_spwphaseup task (ALMA-interferometry-only).

reference_antenna_locked

If True, reference antenna is locked to prevent modification. Typically used in polarization calibration stages / recipes.

reference_spwmap

Vector of spectral window IDs, enabling flux scaling across spectral windows. Typically populated by the hifa_fluxcalflag task, and used by a subsequent hifa_gfluxscale task in its call to CASA fluxscale task (ALMA-interferometry-only).

spwmaps

Dictionary mapping (intent, field) keys to corresponding phase-up spectral window mapping to use for combining/mapping spectral windows; used in subsequent calibration tasks (ALMA-interferometry-only).

Attributes Summary

antennas	Return list of Antenna objects for all antennas in the measurement set.
basename	Return base path to the measurement set.
end_time	Return end time for this measurement set as CASA 'epoch' measure dictionary.
intents	Return unique intents in the measurement set.
is_band_to_band	Return whether this MS is for band-to-band interferometry.
reference_antenna	Get the reference antenna list for this MS.
session	Return name of session associated with this measurement set.
start_time	Return start time for this measurement set as CASA 'epoch' measure dictionary.

Methods Summary

all_colnames()	Return all available column names for this MS.
compute_az_el_for_ms(func)	Computes overall azimuth and elevation values across POINTING, SIDEBAND, ATMOSPHERE scans.
compute_az_el_to_field([field, epoch])	Computes azimuth and elevation of a field at a given epoch.
data_colnames()	Return all data column names for this MS.
get_all_spectral_windows([task_arg, ...])	Return spectral windows corresponding to the given CASA-style spw argument.
get_alma_corrstring()	Get correlation string for ALMA for the science spectral windows.
get_alma_cycle_number()	Get the ALMA cycle number from the observation start time.
get_antenna([search_term])	Return Antenna(s) for given antenna selection in CASA format.
get_data_column(dtype[, source, spw])	Return the column name associated with a DataType in an MS domain object for given source and spectral window.
get_data_description([spw, id])	Return the DataDescription in the MeasurementSet that matches the given criteria (spectral window or ID).
get_data_type(column[, source, spw])	Return the DataType associated with a column in an MS domain object for given source and spectral window.
get_diffgain_mode()	Determine if the intents and SpW setup in this measurement set are consistent with an observing mode that uses a differential gain calibrator: BandToBand (B2B) or BandwidthSwitching (BWSW).
get_fields([task_arg, field_id, name, intent])	Get Fields from this MeasurementSet matching the given criteria.
get_integration_time_stats([intent, spw, ...])	Get the given statistcs of integration time.
get_original_intent(intent)	Get the original obs_modes that correspond to the given pipeline observing intent(s).
get_representative_source_spw([source_name, ...])	Get the representative target source object.
get_scans([scan_id, scan_intent, field, spw])	Return Scan(s) in MeasurementSet matching the given criteria (ID, intent, field, and/or spectral window).
get_spectral_specs()	Return list of all spectral specs used in the MS.
get_spectral_window(spw_id)	Return the SpectralWindow object matching the given identifier.
get_spectral_windows([task_arg, ...])	Return spectral windows matching given criteria.
get_state([state_id])	Return State in MeasurementSet matching the given identifier.
get_times_on_source_per_field_id(field, intent)	Return on-source time for given field ID(s) and intent(s).
get_vla_baseband_spws([...])	Get the SPW information from individual VLA band/baseband.
get_vla_corrlist_from_spw([spw])	Get all VLA correlation labels as a list of string from selected spw(s).
get_vla_corrstring()	Get correlation string for VLA.
get_vla_critfrac()	Identify bands/basebands/spws.
get_vla_field_spws([spwlist])	Find field spws for VLA
get_vla_numchan()	Get number of channels for VLA.
get_vla_spw2band()	Find spectral windows id-to-band mapping for VLA.
get_vla_tst_bpass_spw([spwlist])	Get VLA test bandpass or delay spws.
set_data_column(dtype, column[, source, ...])	Assign a data type to a column in the MS domain object.
set_data_type_dicts(data_type_per_column, ...)	Set the data type lookup dictionaries directly without writing new MS HISTORY entries as they would already exist when calling this method.
update_reference_antennas([ants_to_demote, ...])	Update the reference antenna list for this MS to demote/remove specified antennas.

Attributes Documentation

antennas

Return list of Antenna objects for all antennas in the measurement set.

basename

Return base path to the measurement set.

end_time

Return end time for this measurement set as CASA 'epoch' measure dictionary.

intents

Return unique intents in the measurement set.

is_band_to_band

Return whether this MS is for band-to-band interferometry.

Criteria adopted from PIPE-2084: an MS is deemed to be for band-to-band interferometry if either the observing mode declares it as band-to-band, or if the diffgain intent + SpW setup are consistent with band-to-band. The latter covers datasets that don't have correct observing mode set in their metadata.

reference_antenna

Get the reference antenna list for this MS. The refant value is a comma-separated string.

Example: 'DV01,DV02,DV03'

session: str | None

Return name of session associated with this measurement set.

start_time

Return start time for this measurement set as CASA 'epoch' measure dictionary.

Methods Documentation

all_colnames() → list[str]

Return all available column names for this MS.

compute_az_el_for_ms(func: Callable) → tuple[float, float]

Computes overall azimuth and elevation values across POINTING, SIDEBAND, ATMOSPHERE scans.

Applies the given aggregation function (e.g. min, max, mean) to azimuth and elevation values computed at the start and end of each field in science scans.

Parameters:

func -- A function that takes a list of floats and returns a single float. Common examples include min, max, or np.mean.

Returns:

A tuple containing the aggregated azimuth and elevation values.

compute_az_el_to_field(field: Field | None = None, epoch: dict | None = None) → list[float]

Computes azimuth and elevation of a field at a given epoch.

This method uses the CASA measures tool to convert the direction of a field to azimuth and elevation (AZELGEO frame) at the time specified by the epoch and location of the observatory.

Parameters:

• field -- Field domain object or None.

• epoch -- A dictionary representing the time epoch.

Returns:

A list containing azimuth (degrees) and elevation (degrees), in that order.

data_colnames() → list[str]

Return all data column names for this MS.

get_all_spectral_windows(task_arg: int | str = '', with_channels: bool = False) → list[SpectralWindow | SpectralWindowWithChannelSelection]

Return spectral windows corresponding to the given CASA-style spw argument.

By default, this returns a list of SpectralWindow objects; if with_channels is True, this will instead return the spectral windows as a list of SpectralWindowWithChannelSelection objects.

Parameters:

• task_arg -- Spectral window selection to match, as either single integer ID, or one-or-more IDs in CASA-style string format.

• with_channels -- If True, return spectral window with channel selection.

Returns:

List of SpectralWindow or SpectralWindowWithChannelSelection objects for given CASA-style search criteria.

get_alma_corrstring() → str

Get correlation string for ALMA for the science spectral windows.

Returns:

corrstring -- string value of correlation

get_alma_cycle_number() → int | None

Get the ALMA cycle number from the observation start time.

Returns:

Cycle number or None if not found or not an ALMA dataset.

get_antenna(search_term: str = '') → list[Antenna]

Return Antenna(s) for given antenna selection in CASA format.

If the search_term is omitted or an empty string, this will return all antennas in the measurement set.

Parameters:

search_term -- Antenna selection string in CASA format.

Returns:

List of Antenna objects matching search term.

get_data_column(dtype: DataType, source: str | None = None, spw: str | None = None) → str | None

Return the column name associated with a DataType in an MS domain object for given source and spectral window.

If source and spw are both unset, the method will just look at the MS data type and column information. If one or both parameters are set, it will require all (source,spw) combinations to have data of the requested data type.

Parameters:

• dtype -- DataType to fetch column name for

• source -- Source names (comma separated name selection string) to filter for. If unset, all sources will be used.

• spw -- Spectral windows (comma separated real spw ID selection string) to filter for. If unset, all real spw IDs will be used.

Returns:

A name of column of a dtype. Returns None if dtype is not defined in the MS.

get_data_description(spw: int | spectralwindow.SpectralWindow | None = None, id: int | None = None) → DataDescription | None

Return the DataDescription in the MeasurementSet that matches the given criteria (spectral window or ID). If no criteria are given, this will return None. If both spw and id are given, this will match by id only.

Parameters:

• spw -- Spectral window to match (as ID or SpectralWindow object).

• id -- Data description numerical identifier to match.

Returns:

DataDescription matching the given criteria, or None if no match was found.

get_data_type(column: str, source: str | None = None, spw: str | None = None) → DataType | None

Return the DataType associated with a column in an MS domain object for given source and spectral window.

If source and spw are both unset, the method will just look at the MS data type and column information. If one or both parameters are set, it will require all (source,spw) combinations to have data of the requested data type.

Parameters:

• column -- Name of column in MS

• source -- Source names (comma separated name selection string) to filter for. If unset, all sources will be used.

• spw -- Spectral windows (comma separated real spw ID selection string) to filter for. If unset, all real spw IDs will be used.

Returns:

The DataType associated with the column name. Returns None if dtype is not defined in the MS or in the source/spw selection.

get_diffgain_mode() → str | None

Determine if the intents and SpW setup in this measurement set are consistent with an observing mode that uses a differential gain calibrator: BandToBand (B2B) or BandwidthSwitching (BWSW).

Returns:

• 'B2B' if the ratio of frequencies between on-source and reference spws is above 1.661;

• 'BWSW' if the ratio of bandwidths between reference and on-source is above 1.5;

• None if there are no DIFFGAIN* intents in this MS.

Raises:

• ValueError if the DIFFGAIN* intents are present in the MS, but either --

• a. the MS is missing diffgain reference or on-source SpWs, or --

• b. the SpW setup does not match either BandToBand or BandwidthSwitching. --

get_fields(task_arg: int | str | None = None, field_id: int | Sequence[int] | None = None, name: str | Sequence[str] | None = None, intent: str | Sequence[str] | None = None) → list[Field]

Get Fields from this MeasurementSet matching the given criteria. If no criteria are given, all Fields in the MeasurementSet will be returned.

Arguments can be given as either single items of the expected type, sequences of the expected type, or as comma separated strings in the case of name and/or intent. For instance, name could be 'HOIX', 'HOIX,0841+708' or ('HOIX','0841+708').

Parameters:

• task_arg -- A field selection in CASA format to match.

• field_id -- Field ID(s) to match.

• name -- Field name(s) to match.

• intent -- Select fields that are associated with these intents. If set to an empty string or '*', this is the equivalent to all intents in the measurement set.

Returns:

List of Field objects for fields in MS matching the given criteria.

get_integration_time_stats(intent: str | None = None, spw: str | None = None, science_windows_only: bool = False, stat_type: str = 'max', band: str | None = None) → float

Get the given statistcs of integration time.

Parameters:

• intent -- The intent of the data of interest.

• spw -- spw string list - '1,7,11,18'.

• science_windows_only -- Use integration time of science spws only to compute the given statistics.

• stat_type -- Type of the statistics.

• band -- return maximum integration time for the given VLA band. Ignored for non-VLA datasets; has no effect in that case. Default is None.default None

Returns

Computed statistics value.

get_original_intent(intent: str) → set[str]

Get the original obs_modes that correspond to the given pipeline observing intent(s).

Parameters:

intent -- Pipeline intent(s) to convert.

Returns:

Set of original CASA intent(s) (obs_modes) corresponding to given Pipeline intent(s).

get_representative_source_spw(source_name: str | None = None, source_spwid: int | None = None) → tuple[str | None, int | None]

Get the representative target source object.

• Use user name if source_name is supplied by user and it has TARGET intent.

• Otherwise, use the source defined in the ASDM SBSummary table if it has TARGET intent.

• Otherwise, use the first source in the source list with TARGET intent.

Parameters:

• source_name -- A string with the source name, or None for an automatic selection.

• source_spwid -- An int with the spw id, or None for an automatic selection.

Returns:

a tuple with representative source name and spw id; if such a source cannot be identified, return (None, None), and if a spw cannot be determined, return (name, None).

get_scans(scan_id: int | Sequence[int] | None = None, scan_intent: str | Sequence[str] | None = None, field: int | str | None = None, spw: int | str | Sequence[int] | Sequence[str] | None = None) → list[Scan]

Return Scan(s) in MeasurementSet matching the given criteria (ID, intent, field, and/or spectral window). If no criteria are given, all Scans in the MeasurementSet will be returned.

Criteria arguments can be given as either single items of the expected type, sequences of the expected type, or in the case of intent or spw, as a comma-separated values string. For example, intent could be 'ATMOSPHERE', 'ATMOSPHERE,BANDPASS', or ('ATMOSPHERE', 'BANDPASS').

Parameters:

• scan_id -- Scan ID(s) to match.

• scan_intent -- Intent(s) to match.

• field -- Field(s) to match, as field selection in CASA format.

• spw -- Spectral window(s) to match.

Returns:

List of Scan objects for scans in MS matching the given criteria.

get_spectral_specs() → list[str]

Return list of all spectral specs used in the MS.

get_spectral_window(spw_id: int | str) → SpectralWindow

Return the SpectralWindow object matching the given identifier. The identifier can be provided as an integer or string of integer.

Parameters:

spw_id -- Numerical identifier of spectral window to match.

Returns:

SpectralWindow object for spectral window matching the identifier.

Raises:

KeyError if no matching spectral window is found for given identifier. --

get_spectral_windows(task_arg: int | str = '', with_channels: bool = False, num_channels: list | None = None, science_windows_only: bool = True, spectralspecs: list | None = None, intent: str | None = None) → list[SpectralWindow | SpectralWindowWithChannelSelection]

Return spectral windows matching given criteria.

This returns spectral windows that correspond to the given CASA-style spw argument (specified as task_arg), filtering out windows for a number of criteria: number of channels, science spectral windows, spectral specs, intents.

By default, this returns a list of SpectralWindow objects; if with_channels is True, this will instead return the spectral windows as a list of SpectralWindowWithChannelSelection objects.

Parameters:

• task_arg -- Spectral window selection to match, as either single integer ID, or one-or-more IDs in CASA-style string format.

• with_channels -- If True, return spectral window with channel selection.

• num_channels -- Optional list of spectral window sizes in number of channels; if set, only return spectral windows whose number of channels matches any of the given sizes.

• science_windows_only -- If True, only return "science" spectral windows, aka spectral windows associated with science intents.

• spectralspecs -- Optional list of spectral specs; if set, only return spectral windows associated with given spectral specs.

• intent -- Optional string of comma-separated intents; if set, only return spectral windows that observed given intent(s).

Returns:

List of SpectralWindow or SpectralWindowWithChannelSelection objects for given search criteria.

get_state(state_id: int | None = None) → State | None

Return State in MeasurementSet matching the given identifier.

Parameters:

state_id -- Numerical identifier of state to search for.

Returns:

State object associated with matched identifier, or None if no match was found.

get_times_on_source_per_field_id(field: str, intent: str) → dict[int, floating]

Return on-source time for given field ID(s) and intent(s).

Parameters:

• field -- Field name(s) to return times for.

• intent -- Intent(s) to filter for.

Returns:

Dictionary of on-source times for selected field ID(s) and intent(s).

get_vla_baseband_spws(science_windows_only: bool = True, return_select_list: bool = True, warning: bool = True) → dict | list[list[int]]

Get the SPW information from individual VLA band/baseband.

Parameters:

• science_windows_only -- Whether to include only science spectral windows.

• return_select_list -- Whether to return SPW list of each baseband instead of full band/subband info.

• warning -- Whether to log warnings for parsing errors.

Returns:

If return_select_list is False -- Dictionary with SPW info organized as baseband_spws[band][baseband], where each

entry contains a list of spw info as {spwid, (min_freq, max_freq, mean_freq, chan_width)}.

If return_select_list is True:

List of SPW ID lists for each band.baseband, e.g., [[0,1,2,3], [4,5,6,7]].

get_vla_corrlist_from_spw(spw: str | None = None) → list

Get all VLA correlation labels as a list of string from selected spw(s).

Parameters:

spw -- a spw selection string or None. Defaults to None.

Returns:

list -- a list of correlation labels.

get_vla_corrstring() → str

Get correlation string for VLA.

Returns:

corrstring -- string value of correlation

get_vla_critfrac() → float

Identify bands/basebands/spws.

Returns:

critical fraction

get_vla_field_spws(spwlist=[])

Find field spws for VLA

Parameters:

spwlist (List, optional) -- list of string spws ['1', '2', '3']

Returns:

field_spws -- List of dictionaries

get_vla_numchan()

Get number of channels for VLA.

Returns:

channels -- NUM_CHAN column from spectral window table

get_vla_spw2band() → dict[int, str]

Find spectral windows id-to-band mapping for VLA.

Creat spw id-to-band mapping from spw names or derives it from reference frequency when name parsing fails. Handles special cases for KU and KA band naming conventions.

Returns:

Dictionary mapping spectral window IDs to single-letter band codes (e.g., '4', 'P', 'L', 'S', 'C', 'X', 'U', 'K', 'A', 'Q').

get_vla_tst_bpass_spw(spwlist=[])

Get VLA test bandpass or delay spws.

This function replaced functionality for get_vla_tst_delay_spw - PIPE-1325

Parameters:

spwlist (List, optional) -- list of string spws ['1', '2', '3']

Returns:

tst_bpass_spws -- CASA argument format of spws:channels '0:10~80, 1:15~60, 2:30~70'

set_data_column(dtype: DataType, column: str, source: str | None = None, spw: str | None = None, overwrite: bool = False, save_to_ms: bool = True) → None

Assign a data type to a column in the MS domain object.

Set data type and column to MS domain object and record the available data types per (source,spw) tuple. If source or spw are unset, they will be expanded to all available values.

Parameters:

• dtype -- data type to set

• column -- name of column in MS associated with the data type

• source -- source name selection string (comma separated names). If unset, all sources will be used.

• spw -- real spectral window selection string (string of comma separated IDs). If unset, all real spw IDs will be used.

• overwrite -- if True existing data colum is overwritten by the new column. If False and if type is already associated with other column, the function raises ValueError.

• save_to_ms (bool, optional) -- If True, persists the datatype-to-column mapping to the MS history subtable. Defaults to True.

Raises:

ValueError -- An error raised when the column does not exist or the type is already associated with a column or the column is already assigned to a type and would not be overwritten.

set_data_type_dicts(data_type_per_column: dict, data_types_per_source_and_spw: dict) → None

Set the data type lookup dictionaries directly without writing new MS HISTORY entries as they would already exist when calling this method. Also do not auto-generate the per source and spw lookup dictionary from the per column information since it might have a sparse structure (e.g. selfcal use case).

Parameters:

• data_type_per_column -- Data type per column lookup dictionary

• data_types_per_source_and_spw -- Data type per source and spw lookup dictionary.

update_reference_antennas(ants_to_demote: set[str] | None = None, ants_to_remove: set[str] | None = None) → None

Update the reference antenna list for this MS to demote/remove specified antennas.

Parameters:

• ants_to_demote -- Set of antenna names to demote.

• ants_to_remove -- Set of antenna names to remove.