Metadata-Version: 2.4
Name: ms-rms-estimator
Version: 0.1.0
Summary: Summarise a Measurement Set and estimate the theoretical image RMS.
Author: ms_rms_estimator
License: Apache-2.0
Project-URL: Homepage, https://example.com/ms-rms-estimator
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy<3,>=2.0
Requires-Dist: dask[array]<2026,>=2023.1.1
Requires-Dist: dask-ms==0.2.32

# 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
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:

```bash
make
```

Or step by step:

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

To remove the environment when no longer needed:

```bash
make clean
```

### After setup

Activate the environment in any future session with:

```bash
conda activate ms-rms-estimator
```

Then run:

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

## Command-Line Options

```text
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

```bash
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

```python
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

```text
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.
