Measurement Set¶

class oskar.MeasurementSet¶

This class provides a Python interface to a CASA Measurement Set.

The oskar.MeasurementSet class can be used to read data from and write data to a CASA Measurement Set. The casacore library is used for this interface, so it must be available when OSKAR is compiled for this to work.

The Measurement Set format is extremely flexible, and casacore provides a complete and comprehensive interface to use it fully. However, in many cases a simpler interface is sufficient and may be easier to use. This class can be used to read and write Measurement Sets containing only a single spectral window (but potentially multiple channels) and a single field - this includes all Measurement Sets written by OSKAR.

Create or open a Measurement Set using the create() and open() methods, respectively. Both return a new oskar.MeasurementSet object.

Once opened, to read data from the Measurement Set:

the read_column() method can be used to read any named column of data from the main table;
the read_vis() convenience method can be used to read visibility data from one of the data columns in the main table;
the read_coords() convenience method can be used to read baseline (u,v,w) coordinates from the main table.

Once created, to write data to a Measurement Set:

the write_vis() method can be used to write visibility data to the DATA column;
the write_coords() method can be used to write time and baseline coordinates to the main table. (The baseline order is implicit, so the antenna indices will be written automatically.)

Examples

To write a Measurement Set from Python:

import numpy

filename = "test1.ms"

# Define data dimensions.
num_pols = 4
num_channels = 2
num_stations = 3
num_times = 4
num_baselines = num_stations * (num_stations - 1) // 2
ref_freq_hz = 100e6
freq_inc_hz = 100e3
exposure_sec = 1.0
interval_sec = 1.0

# Data to write are stored as numpy arrays.
uu = numpy.zeros([num_baselines])
vv = numpy.zeros_like(uu)
ww = numpy.zeros_like(uu)
vis = numpy.zeros([num_times, num_channels,
                   num_baselines, num_pols], dtype='c8')

# Create the empty Measurement Set.
ms = oskar.MeasurementSet.create(filename, num_stations,
                                 num_channels, num_pols,
                                 ref_freq_hz, freq_inc_hz)

# Set phase centre.
ra_rad = numpy.pi / 4
dec_rad = -numpy.pi / 4
ms.set_phase_centre(ra_rad, dec_rad)

# Write data one block at a time.
for t in range(num_times):
    # Dummy data to write.
    time_stamp = 51544.5 * 86400.0 + t
    uu[:] = 1e0 * t + 1
    vv[:] = 1e1 * t + 2
    ww[:] = 1e2 * t + 3
    for c in range(num_channels):
        for b in range(num_baselines):
            vis[t, c, b, :] = (t * 10 + b) + 1j * (c + 1)

    # Write coordinates and visibilities.
    start_row = t * num_baselines
    ms.write_coords(start_row, num_baselines, uu, vv, ww,
                    exposure_sec, interval_sec, time_stamp)
    ms.write_vis(start_row, 0, num_channels, num_baselines, vis[t, ...])

__init__()¶: The default constructor does nothing. Use create() or open().

classmethod create(file_name, num_stations, num_channels, num_pols, ref_freq_hz, freq_inc_hz, write_autocorr=False, write_crosscorr=True)¶

Creates a new, empty Measurement Set with the given name.

Parameters:

file_name (str) – File name of the new Measurement Set.
num_stations (int) – The number of antennas/stations.
num_channels (int) – The number of channels in the band.
num_pols (int) – The number of polarisations (1, 2 or 4).
ref_freq_hz (float) – The frequency at the centre of channel 0, in Hz.
freq_inc_hz (float) – The increment between channels, in Hz.
write_autocorr (Optional[bool]) – If set, allow for write of auto-correlation data.
write_crosscorr (Optional[bool]) – If set, allow for write of cross-correlation data.

ensure_num_rows(num)¶

Ensures the specified number of rows exist in the Measurement Set.

Note that rows will not be removed if the total number is already larger than the value given.

Parameters:	num (int) – Ensure at least this many rows are present.

classmethod open(file_name, readonly=False)¶

Opens an existing Measurement Set with the given name.

Parameters:	file_name (str) – File name of the Measurement Set to open. readonly (bool) – Open the Measurement Set in read-only mode.

read_column(column, start_row, num_rows)¶

Reads a column of data from the main table.

Parameters:	column (str) – Name of the column to read. start_row (int) – The start row index to read (zero-based). num_rows (int) – Number of rows to read.
Returns:	A numpy array containing the contents of the column.
Return type:	numpy.array

read_coords(start_row, num_baselines)¶

Reads baseline coordinate data from the main table.

This function reads a list of baseline coordinates from the main table of the Measurement Set. The coordinates are returned as a tuple of numpy arrays (uu, vv, ww).

Parameters:	start_row (int) – The start row index to read (zero-based). num_baselines (int) – Number of baselines (rows) to read.
Returns:	(uu, vv, ww) baseline coordinates, in metres.
Return type:	tuple

read_vis(start_row, start_channel, num_channels, num_baselines, column='DATA')¶

Reads visibility data from the main table.

This function reads a block of visibility data from the specified column of the main table of the Measurement Set.

The dimensionality of the returned data block is: (num_channels * num_baselines * num_pols), with num_pols the fastest varying dimension, then num_baselines, and num_channels the slowest.

Parameters:	start_row (int) – The start row index to read (zero-based). start_channel (int) – Start channel index to read. num_channels (int) – Number of channels to read. num_baselines (int) – Number of baselines to read. column (Optional[str]) – Name of the data column to read.
Returns:	visibility data block.
Return type:	array

set_phase_centre(longitude_rad, latitude_rad)¶

Sets the phase centre.

Parameters:	longitude_rad (float) – Right Ascension of phase centre. latitude_rad (float) – Declination of phase centre.

write_coords(start_row, num_baselines, uu, vv, ww, exposure_sec, interval_sec, time_stamp)¶

Writes baseline coordinate data to the main table.

This function writes the supplied list of baseline coordinates to the main table of the Measurement Set, extending it if necessary.

Baseline antenna-pair ordering is implicit: a0-a1, a0-a2, a0-a3… a1-a2, a1-a3… a2-a3 etc. The supplied number of baselines must be compatible with the number of stations in the Measurement Set. Auto-correlations are allowed.

This function should be called for each time step to write out the baseline coordinate data.

The time stamp is given in units of (MJD) * 86400, i.e. seconds since Julian date 2400000.5.

Parameters:

start_row (int) – The start row index to write (zero-based).
num_baselines (int) – Number of rows to add to the main table.
uu (float, array-like) – Baseline u-coordinates, in metres.
vv (float, array-like) – Baseline v-coordinates, in metres.
ww (float, array-like) – Baseline w-coordinates, in metres.
exposure_sec (float) – Exposure length per visibility, in seconds.
interval_sec (float) – Interval length per visibility, in seconds.
time_stamp (float) – Time stamp of visibility block.

write_vis(start_row, start_channel, num_channels, num_baselines, vis)¶

Writes visibility data to the main table.

This function writes the given block of visibility data to the data column of the Measurement Set, extending it if necessary.

The dimensionality of the complex vis data block is: (num_channels * num_baselines * num_pols), with num_pols the fastest varying dimension, then num_baselines, and num_channels the slowest.

Parameters:	start_row (int) – The start row index to write (zero-based). start_channel (int) – Start channel index of the visibility block. num_channels (int) – Number of channels in the visibility block. num_baselines (int) – Number of baselines in the visibility block. vis (complex float, array-like) – Pointer to visibility block.

freq_inc_hz¶: Returns the frequency increment between channels.

freq_start_hz¶: Returns the frequency at the centre of the first channel.

num_channels¶: Returns the number of frequency channels in the Measurement Set.

num_pols¶: Returns the number of polarisations in the Measurement Set.

num_rows¶: Returns the number of rows in the Measurement Set main table.

num_stations¶: Returns the number of stations in the Measurement Set.

phase_centre_ra_rad¶: Returns the Right Ascension of the phase centre in radians.

phase_centre_dec_rad¶: Returns the Declination of the phase centre in radians.