ms-rms-estimator 0.1.1

Summarise a Measurement Set and estimate the theoretical image RMS.

ms-rms-estimator

ms-rms-estimator summarises radio astronomy Measurement Set (MS) data and estimates the theoretical thermal image RMS from unflagged visibility cells.

What this code does

• Reads antenna metadata from the ANTENNA table.
• Reads spectral window frequency and channel-width information from the SPECTRAL_WINDOW table.
• Scans the main MS table to count flagged and unflagged visibility cells.
• Computes total integration-time × channel-width for unflagged data.
• Estimates the expected thermal image RMS using the radiometer equation and the provided SEFD / efficiency values.
• Reports observing duration, antenna and baseline counts, frequency range, bandwidth, channel width, integration time, and flagging fraction.

Features

• Command-line interface via ms-rms-estimator.
• Python API for programmatic analysis using analyse_ms() and make_report().
• Support for Stokes-I approximation or all correlations.
• Uses Dask and dask-ms for efficient chunked MS table processing.
• Generates a human-readable summary report and writes it to a text file.

Important requirements

• Python 3.10 or newer
• numpy>=2.0,<3
• dask[array]>=2023.1.1,<2026
• dask-ms==0.2.32
• python-casacore (required by dask-ms)

Note: install in a virtual environment or Conda environment. dask-ms is currently compatible with Dask releases before 2026.x, and requires Python 3.10+.

Repository contents

• ms_rms_estimator.py — main module containing the CLI entry point and analysis functions.
• __init__.py — package exports for Python import.
• pyproject.toml — packaging metadata for pip install.
• setup_env.sh — bash script to create and activate the Conda environment.
• Makefile — Make targets for environment creation, installation, and cleanup.
• README.md — usage documentation.

Quick start

Two setup options are provided: a bash script and a Makefile. Both create the same ms-rms-estimator Conda environment.

Option A — bash script

bash setup_env.sh

The script:

1. Creates the ms-rms-estimator Conda environment from environment.yml.
2. Sources Conda's shell integration so conda activate works inside the script.
3. Activates the environment.
4. Installs ms-rms-estimator in editable mode via pip install -e ..

Option B — Makefile

Target	Action
make	Create environment and install package (default)
make env	Create the Conda environment only
make install	Install the package into an existing environment
make clean	Remove the Conda environment
make help	Print available targets

Full setup in one command:

make

Or step by step:

make env      # create the environment
conda activate ms-rms-estimator
make install  # install the package

To remove the environment when no longer needed:

make clean

After setup

Activate the environment in any future session with:

conda activate ms-rms-estimator

Then run:

ms-rms-estimator /path/to/your_measurement_set.ms

Command-Line Options

usage: ms-rms-estimator [-h] [--sefd SEFD] [--eta ETA] [--row-chunks ROW_CHUNKS]
                        [-o OUTPUT] [--corr-mode {all,stokesI}] [--log-level LOG_LEVEL]
                        ms

• ms — Path to the Measurement Set to analyse.
• --sefd — System Equivalent Flux Density in Jy. Default: 420.0.
• --eta — Efficiency factor. Default: 0.9.
• --row-chunks — Dask row chunk size. Default: 100000.
• -o, --output — Output text file path. Default: <measurement-set-name>_rms_summary.txt.
• --corr-mode — all or stokesI. Default: stokesI.
• --log-level — Logging verbosity. Default: INFO.

Typical example

ms-rms-estimator example.ms --sefd 450 --eta 0.85 --corr-mode stokesI -o example_rms_report.txt

This produces a summary report and writes it to example_rms_report.txt.

Python API example

from ms_rms_estimator import analyse_ms, make_report

summary = analyse_ms(
    ms_path="/path/to/example.ms",
    sefd_jy=450.0,
    eta_s=0.85,
    row_chunks=100000,
    corr_mode="stokesI",
)
print(make_report(summary))

Example output

Measurement Set summary
================================================================================
MS path                     : /net/nfs/data3/nadeem/MeerKAT/TRON/msdir/J0240-2309_1spw.ms
Observing start             : 2020-08-29 02:18:47 UTC
Observing end               : 2020-08-29 08:19:34 UTC
On-source span              : 6.013 hr

Antennas in ANTENNA table   : 58
Antennas used in MAIN table : 58
Approx. baselines used      : 1653
Maximum baseline            : 7.698 km

Frequency min               : 880.138 MHz
Frequency max               : 1679.294 MHz
Centre frequency            : 1279.716 MHz
Total nominal bandwidth     : 799.574 MHz
Median channel width        : 417.969 kHz

Mean integration time       : 7.997 s
Total visibility cells      : 6925128868
Unflagged visibility cells  : 154836310
Flagged data                : 97.76 %

SEFD used                   : 420.000 Jy
Efficiency eta              : 0.900
Expected RMS                : 14.505 uJy/beam
Expected RMS                : 1.450542e-05 Jy/beam

Theoretical resolution      : 6.277 arcsec
================================================================================

Notes

• The output report includes both Jy/beam and µJy/beam RMS estimates.
• The estimator assumes the Measurement Set uses CASA-style MJD time values.
• The report is intended for analysis and paper preparation, not for imaging itself.