mstool — MeasurementSet utilities¶

mstool provides utilities for inspecting and manipulating MeasurementSets directly via casacore TAQL: inspecting metadata, column arithmetic, concatenating in time, and extracting an LST range.

info — inspect a MeasurementSet¶

Prints a summary of the columns, time range, and frequency range of a MeasurementSet.

Usage¶

mstool info obs.MS

Example output:

MS: obs.MS

Columns:
  UVW                      double      71280 x (3,)
  FLAG                     bool        71280 x (3072,)
  DATA                     complex     71280 x (3072,)
  CORRECTED_DATA           complex     71280 x (3072,)
  ...

Time:
  start: 2023-12-08T06:12:00.000
  end:   2023-12-08T10:07:05.000
  duration: 3.92 h
  integration: 1.00 s

Frequency:
  range: 16.99 – 87.89 MHz
  channel width: 3.05 kHz
  total channels: 3072

Reference¶

mstool info¶

List columns, time and frequency range.

Usage

mstool info [OPTIONS] MS

Arguments

MS¶: Required argument

add / sub — column arithmetic¶

add and sub perform element-wise arithmetic between two visibility columns using casacore TAQL. Both commands operate on complex data, so they work correctly on visibility data regardless of polarisation shape.

Usage¶

mstool add obs.MS CORRECTED_DATA MODEL_DATA

Adds in place — equivalent to the TAQL UPDATE obs.MS SET CORRECTED_DATA = CORRECTED_DATA + MODEL_DATA. With --out_col the result goes to a separate column instead (created if needed):

mstool add obs.MS DATA MODEL_DATA --out_col CORRECTED_DATA

sub works identically with subtraction, e.g. mstool sub obs.MS CORRECTED_DATA MODEL_DATA --out_col RESIDUAL_DATA.

Notes¶

When --out_col is omitted the first column (COL1) must already exist; the operation is performed in place.
When --out_col is specified and the column does not yet exist, it is created with the same shape and data manager as DATA, then zero-initialised before the arithmetic is applied.

Reference¶

mstool add¶

Addition: COL1 = COL1 + COL2, or OUT = COL1 + COL2 with –out_col.

Usage

mstool add [OPTIONS] MS COL1 COL2

Options

--out_col <outcol>¶: If set: write OUT = COL1 + COL2 (OUT created if missing).

Arguments

MS¶: Required argument

COL1¶: Required argument

COL2¶: Required argument

mstool sub¶

Subtraction: COL1 = COL1 - COL2, or OUT = COL1 - COL2 with –out_col.

Usage

mstool sub [OPTIONS] MS COL1 COL2

Options

--out_col <outcol>¶: If set: write OUT = COL1 - COL2 (OUT created if missing).

Arguments

MS¶: Required argument

COL1¶: Required argument

COL2¶: Required argument

concat — concatenate MeasurementSets in time¶

Concatenates two or more MeasurementSets along the time axis into a single output MS using a casacore TAQL select … giving … AS PLAIN query. The input MSs are assumed to be from the same observation (same spectral window and antenna layout) but observed at consecutive times.

Usage¶

mstool concat /net/node101/.../SW03_T001.MS /net/node102/.../SW03_T002.MS out_concat.MS

The last positional argument is always the output path, so any number of inputs (e.g. from a glob) can precede it:

mstool concat $(ls -d /data/SW03_T*.MS) out_concat.MS

Notes¶

At least two input MSs are required.
The output directory is created automatically if it does not exist.
The concatenation is a physical copy — the output MS is self-contained and does not reference the input MSs.

Reference¶

mstool concat¶

Concatenate MeasurementSets in time using casacore TAQL.

MS_INS: one or more input MeasurementSets (directories). MS_OUT: output MeasurementSet (path to new directory).

Usage

mstool concat [OPTIONS] [MS_INS]... MS_OUT

Arguments

MS_INS¶: Optional argument(s)

MS_OUT¶: Required argument

extract_lst — extract an LST range¶

Extracts a Local Sidereal Time (LST) window from a set of MeasurementSets and writes the selected rows to a new MS. This is used to cut a fixed nightly LST bin (e.g. 1–3 h) from each observation so that all nights cover the same region of the sky.

The input MSs are first concatenated in memory using a TAQL virtual concatenation, then a TIME selection is derived from the requested LST range and applied.

Algorithm¶

Concatenate all input MSs virtually (in memory, no disk copy).
Read the TIME of the first and last row to determine the observed LST range.
Linearly interpolate between those endpoints to find the TIME boundaries that correspond to the requested LST window.
Select rows whose TIME falls in that window and copy them to the output MS.

Usage¶

mstool extract_lst obs.MS \
    --ms_out lst_2h.MS \
    --lst_start 2.0 --lst_end 4.0 \
    --longitude 6.57

Extracts the 2–4 h LST window from a night. Multiple consecutive MSs (e.g. time chunks on different nodes) can be passed at once:

mstool extract_lst /net/node101/...T001.MS /net/node102/...T002.MS \
    --ms_out lst_window.MS --lst_start 2.0 --lst_end 4.0 --longitude 6.57

--data_column CORRECTED_DATA selects which column is copied into the output DATA column, and --overwrite replaces an existing output MS.

Options¶

Option	Default	Description
`--ms_out`	(required)	Output MS path
`--lst_start`	(required)	Start of LST window in hours
`--lst_end`	(required)	End of LST window in hours (exclusive)
`--longitude`	(required)	Observatory east longitude in degrees
`--data_column`	`DATA`	Column copied into the output `DATA` column
`--overwrite`	false	Remove and overwrite the output MS if it exists
`--min_fraction`	`0.8`	Minimum fraction of the requested LST duration that must be present; raises an error if below this threshold

Notes¶

LST values are in hours (0–24).
The LST-to-TIME mapping assumes a linear drift, which is accurate for continuous observations of a few hours but may introduce small errors for very long baselines or highly fragmented data.
The NenuFAR longitude is 6.57°E.
--min_fraction guards against edge effects when the requested LST window extends slightly outside the observed range: a value of 0.8 means at least 80 % of the requested window must be covered.

Reference¶

mstool extract_lst¶

Extract an LST range from a continuous set of MeasurementSets using casacore TAQL.

MS_INS: one or more input MeasurementSets (directories), assumed to form a continuous observation.

Usage

mstool extract_lst [OPTIONS] [MS_INS]...

Options

--ms_out <ms_out>¶: Required Output MeasurementSet (path to new directory).

--lst_start <lst_start>¶: Required Start LST in hours.

--lst_end <lst_end>¶: Required End LST in hours.

--longitude <longitude>¶: Required Longitude in degrees.

--data_column <data_column>¶

Data column to copy into the output DATA column.

Default:: 'DATA'

--overwrite¶: Overwrite output MS if it already exists.

--min_fraction <min_fraction>¶

Minimum fraction of the requested LST bin duration required to create the output MS.

Default:: 0.8

Arguments

MS_INS¶: Optional argument(s)