msutils 1.2.0__tar.gz → 2.0.0b1__tar.gz

msutils-2.0.0b1/.gitignore

@@ -0,0 +1,18 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Python
+__pycache__/
+*.py[cod]
+*.so
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/

msutils-2.0.0b1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: msutils
+Version: 2.0.0b1
+Summary: Tools for playing with Measurement sets.
+Project-URL: Homepage, https://github.com/SpheMakh/msutils
+Project-URL: Repository, https://github.com/SpheMakh/msutils
+Project-URL: Issues, https://github.com/SpheMakh/msutils/issues
+Author-email: Sphesihle Makhathini <sphemakh@gmail.com>
+License-Expression: GPL-2.0-or-later
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: click>=8.0
+Requires-Dist: numpy
+Requires-Dist: python-casacore
+Provides-Extra: all
+Requires-Dist: dask-ms; extra == 'all'
+Requires-Dist: matplotlib; extra == 'all'
+Requires-Dist: scipy; extra == 'all'
+Provides-Extra: flagstats
+Requires-Dist: dask-ms; extra == 'flagstats'
+Requires-Dist: matplotlib; extra == 'flagstats'
+Provides-Extra: plots
+Requires-Dist: matplotlib; extra == 'plots'
+Requires-Dist: scipy; extra == 'plots'
+Description-Content-Type: text/markdown
+
+# msutils
+
+Tools for manipulating CASA Measurement Sets (MS), for radio-astronomy pipelines.
+
+[![Python package](https://github.com/sphemakh/msutils/actions/workflows/installation.yml/badge.svg)](https://github.com/sphemakh/msutils/actions/workflows/installation.yml)
+[![PyPI](https://img.shields.io/pypi/v/msutils.svg)](https://pypi.org/project/msutils/)
+
+## Features
+
+- Summarise an MS — fields, spectral windows, antennas, scans, correlations — to a dict / JSON.
+- Add, copy, and sum/subtract visibility columns, chunked by spectral window.
+- Add Gaussian noise to a column (from a stddev, or computed from an SEFD).
+- Verify / fix antenna Y-position sign conventions.
+- Flag statistics per antenna / scan / field / correlation, with a matplotlib summary plot (`flagstats` extra).
+- Per-channel visibility weight estimation from an SEFD profile (`plots` extra).
+- A `msutils` command-line tool wrapping the above.
+
+## Install
+
+Requires Python >= 3.8. `python-casacore` is pulled in automatically (its wheels bundle the casacore libraries).
+
+```bash
+pip install msutils                 # core column operations + CLI
+pip install "msutils[flagstats]"    # + flag statistics & plots (dask-ms, matplotlib)
+pip install "msutils[plots]"        # + weight estimation (matplotlib, scipy)
+pip install "msutils[all]"          # everything
+```
+
+## Python API
+
+The core operations are exposed directly on the package:
+
+```python
+import msutils
+
+# Metadata summary (returns a JSON-serialisable dict)
+info = msutils.summary("obs.ms")
+
+# Column operations
+msutils.addcol("obs.ms", "MODEL_DATA", clone="DATA")
+msutils.copycol("obs.ms", "DATA", "CORRECTED_DATA")
+msutils.sumcols("obs.ms", cols=["DATA", "MODEL_DATA"], outcol="CORRECTED_DATA")
+
+# Add noise (computed from an SEFD, or a fixed stddev)
+msutils.addnoise("obs.ms", column="MODEL_DATA", sefd=551)
+```
+
+Flag statistics and weight estimation live in optional submodules:
+
+```python
+from msutils import flagstats                 # needs msutils[flagstats]
+flagstats.plot_statistics("obs.ms", plotfile="flags.png", outfile="flags.json")
+
+from msutils.weights import MSNoise           # needs msutils[plots]
+```
+
+## Command line
+
+```bash
+msutils summary  obs.ms --json summary.json
+msutils addcol   obs.ms MODEL_DATA --clone DATA
+msutils copycol  obs.ms DATA CORRECTED_DATA
+msutils sumcols  obs.ms DATA MODEL_DATA --out CORRECTED_DATA
+msutils addnoise obs.ms --column MODEL_DATA --sefd 551
+msutils flagstats obs.ms --plot flags.png --json flags.json   # needs msutils[flagstats]
+```
+
+Run `msutils --help` or `msutils <command> --help` for all options.
+
+## Migrating from 1.x / `MSUtils`
+
+- The import package is now lowercase **`msutils`** (the capitalised `MSUtils` still works, with a deprecation warning).
+- The core functions are on the package root — use `msutils.summary(...)` instead of `from msutils import msutils`.
+- Modules renamed: `flag_stats` → `flagstats`, `ClassESW` → `weights` (old names still importable, deprecated).
+- `imp_plotter` (gain/calibration-table plotting) was removed — use [ragavi](https://github.com/ratt-ru/ragavi) (`ragavi-gains`) instead.
+- The defunct `prep()` and its external-binary dependencies were removed.
+
+## License
+
+GNU GPL v2 or later. See [LICENSE](LICENSE).

msutils-2.0.0b1/README.md

@@ -0,0 +1,80 @@
+# msutils
+
+Tools for manipulating CASA Measurement Sets (MS), for radio-astronomy pipelines.
+
+[![Python package](https://github.com/sphemakh/msutils/actions/workflows/installation.yml/badge.svg)](https://github.com/sphemakh/msutils/actions/workflows/installation.yml)
+[![PyPI](https://img.shields.io/pypi/v/msutils.svg)](https://pypi.org/project/msutils/)
+
+## Features
+
+- Summarise an MS — fields, spectral windows, antennas, scans, correlations — to a dict / JSON.
+- Add, copy, and sum/subtract visibility columns, chunked by spectral window.
+- Add Gaussian noise to a column (from a stddev, or computed from an SEFD).
+- Verify / fix antenna Y-position sign conventions.
+- Flag statistics per antenna / scan / field / correlation, with a matplotlib summary plot (`flagstats` extra).
+- Per-channel visibility weight estimation from an SEFD profile (`plots` extra).
+- A `msutils` command-line tool wrapping the above.
+
+## Install
+
+Requires Python >= 3.8. `python-casacore` is pulled in automatically (its wheels bundle the casacore libraries).
+
+```bash
+pip install msutils                 # core column operations + CLI
+pip install "msutils[flagstats]"    # + flag statistics & plots (dask-ms, matplotlib)
+pip install "msutils[plots]"        # + weight estimation (matplotlib, scipy)
+pip install "msutils[all]"          # everything
+```
+
+## Python API
+
+The core operations are exposed directly on the package:
+
+```python
+import msutils
+
+# Metadata summary (returns a JSON-serialisable dict)
+info = msutils.summary("obs.ms")
+
+# Column operations
+msutils.addcol("obs.ms", "MODEL_DATA", clone="DATA")
+msutils.copycol("obs.ms", "DATA", "CORRECTED_DATA")
+msutils.sumcols("obs.ms", cols=["DATA", "MODEL_DATA"], outcol="CORRECTED_DATA")
+
+# Add noise (computed from an SEFD, or a fixed stddev)
+msutils.addnoise("obs.ms", column="MODEL_DATA", sefd=551)
+```
+
+Flag statistics and weight estimation live in optional submodules:
+
+```python
+from msutils import flagstats                 # needs msutils[flagstats]
+flagstats.plot_statistics("obs.ms", plotfile="flags.png", outfile="flags.json")
+
+from msutils.weights import MSNoise           # needs msutils[plots]
+```
+
+## Command line
+
+```bash
+msutils summary  obs.ms --json summary.json
+msutils addcol   obs.ms MODEL_DATA --clone DATA
+msutils copycol  obs.ms DATA CORRECTED_DATA
+msutils sumcols  obs.ms DATA MODEL_DATA --out CORRECTED_DATA
+msutils addnoise obs.ms --column MODEL_DATA --sefd 551
+msutils flagstats obs.ms --plot flags.png --json flags.json   # needs msutils[flagstats]
+```
+
+Run `msutils --help` or `msutils <command> --help` for all options.
+
+## Migrating from 1.x / `MSUtils`
+
+- The import package is now lowercase **`msutils`** (the capitalised `MSUtils` still works, with a deprecation warning).
+- The core functions are on the package root — use `msutils.summary(...)` instead of `from msutils import msutils`.
+- Modules renamed: `flag_stats` → `flagstats`, `ClassESW` → `weights` (old names still importable, deprecated).
+- `imp_plotter` (gain/calibration-table plotting) was removed — use [ragavi](https://github.com/ratt-ru/ragavi) (`ragavi-gains`) instead.
+- The defunct `prep()` and its external-binary dependencies were removed.
+
+## License
+
+GNU GPL v2 or later. See [LICENSE](LICENSE).

msutils-2.0.0b1/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "msutils"
+version = "2.0.0b1"
+description = "Tools for playing with Measurement sets."
+readme = "README.md"
+license = "GPL-2.0-or-later"
+requires-python = ">=3.8"
+authors = [
+    { name = "Sphesihle Makhathini", email = "sphemakh@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+# Base install covers the core column operations in msutils.msutils only.
+# Heavier, feature-specific stacks live in optional extras below.
+dependencies = [
+    "numpy",
+    "python-casacore",
+    "click>=8.0",
+]
+
+[project.scripts]
+msutils = "msutils.cli:cli"
+
+[project.optional-dependencies]
+# msutils.flagstats: out-of-core flag statistics + matplotlib summary plots
+flagstats = [
+    "dask-ms",
+    "matplotlib",
+]
+# msutils.weights: matplotlib/scipy noise-weight estimation + diagnostic plot
+plots = [
+    "matplotlib",
+    "scipy",
+]
+all = [
+    "msutils[flagstats,plots]",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.5",
+]
+# `simms` generates the synthetic MS used by the behavioural tests. It is a
+# heavy, git-installed dependency (kept out of the published package metadata);
+# MS-backed tests skip when it is not importable.
+test = [
+    "pytest>=8.0",
+    "simms @ git+https://github.com/wits-cfa/simms.git",
+]
+
+[project.urls]
+Homepage = "https://github.com/SpheMakh/msutils"
+Repository = "https://github.com/SpheMakh/msutils"
+Issues = "https://github.com/SpheMakh/msutils/issues"
+
+[tool.hatch.build.targets.wheel]
+# `MSUtils` is a deprecated alias shim that re-exports `msutils`.
+packages = ["src/msutils", "src/MSUtils"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/msutils",
+    "/src/MSUtils",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "--import-mode=importlib"
+consider_namespace_packages = true
+
+[tool.ruff]
+line-length = 180
+
+[tool.ruff.lint]
+# Mirror the pre-refactor flake8 hard-fail gate: syntax errors and
+# undefined names only. `# noqa: F821` markers in the source are load-bearing.
+select = ["E9", "F63", "F7", "F82"]

msutils-2.0.0b1/src/MSUtils/__init__.py

@@ -0,0 +1,25 @@
+"""Deprecated import alias for :mod:`msutils`.
+
+``MSUtils`` was renamed to the lowercase ``msutils``. This shim keeps
+``import MSUtils`` / ``from MSUtils import msutils`` working while emitting a
+:class:`FutureWarning` (shown by default, unlike ``DeprecationWarning``), then
+aliases itself to the real package so that attribute and submodule access
+transparently resolve to ``msutils``.
+"""
+import sys
+import warnings
+
+warnings.warn(
+    "The 'MSUtils' package has been renamed to 'msutils'. Importing 'MSUtils' "
+    "is deprecated and will be removed in a future release; use 'msutils' "
+    "(e.g. 'from msutils import msutils') instead.",
+    FutureWarning,
+    stacklevel=2,
+)
+
+import msutils as _msutils
+
+# Replace this shim module with the real package so that any subsequent
+# attribute or submodule access (e.g. ``from MSUtils import msutils``) resolves
+# against ``msutils`` rather than this empty stub.
+sys.modules[__name__] = _msutils

msutils-2.0.0b1/src/msutils/ClassESW.py

@@ -0,0 +1,12 @@
+"""Deprecated module alias: use :mod:`msutils.weights` instead."""
+import warnings
+
+warnings.warn(
+    "`msutils.ClassESW` has been renamed to `msutils.weights`; the old name is "
+    "deprecated and will be removed in a future release.",
+    FutureWarning,
+    stacklevel=2,
+)
+
+from .weights import *  # noqa: E402,F401,F403  (re-export the public API)
+from .weights import __all__  # noqa: E402,F401

msutils-2.0.0b1/src/msutils/__init__.py

@@ -0,0 +1,43 @@
+"""msutils: CASA Measurement Set manipulation utilities.
+
+The core column operations are exposed directly on the package, e.g.::
+
+    import msutils
+    msutils.summary(msname)
+    msutils.addcol(msname, "MODEL_DATA")
+
+Feature-specific modules (``flagstats``, ``weights``) require optional
+extras -- ``pip install msutils[flagstats]`` / ``msutils[plots]``.
+"""
+from ._ms import (
+    STOKES_TYPES,
+    summary,
+    addcol,
+    sumcols,
+    copycol,
+    compute_vis_noise,
+    verify_antpos,
+    addnoise,
+)
+
+__all__ = [
+    "STOKES_TYPES",
+    "summary",
+    "addcol",
+    "sumcols",
+    "copycol",
+    "compute_vis_noise",
+    "verify_antpos",
+    "addnoise",
+]
+
+
+def __getattr__(name):
+    # Lazily expose the deprecated `msutils.msutils` alias (emits a warning on
+    # import) without pulling it in on every package import. Import via
+    # importlib rather than `from . import msutils` to avoid recursing back
+    # through this __getattr__.
+    if name == "msutils":
+        import importlib
+        return importlib.import_module(__name__ + ".msutils")
+    raise AttributeError("module {0!r} has no attribute {1!r}".format(__name__, name))

msutils-2.0.0b1/src/msutils/_log.py

@@ -0,0 +1,15 @@
+"""Shared logging helper for the msutils package."""
+import logging
+
+
+def create_logger(name):
+    """Return a console logger, attaching a handler only once per logger."""
+    log = logging.getLogger(name)
+    if not log.handlers:
+        cfmt = logging.Formatter("%(name)s - %(asctime)s %(levelname)s - %(message)s")
+        log.setLevel(logging.DEBUG)
+        console = logging.StreamHandler()
+        console.setLevel(logging.INFO)
+        console.setFormatter(cfmt)
+        log.addHandler(console)
+    return log