fitscube 2.7.0__tar.gz → 2.8.0__tar.gz

{fitscube-2.7.0 → fitscube-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fitscube
-Version: 2.7.0
+Version: 2.8.0
 Summary: A package to produce produce FITS cubes.
 Project-URL: Homepage, https://github.com/AlecThomson/fitscube
 Project-URL: Bug Tracker, https://github.com/AlecThomson/fitscube/issues
@@ -45,7 +45,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: astropy
+Requires-Dist: astropy>=6.0
 Requires-Dist: numpy>=2
 Requires-Dist: radio-beam
 Requires-Dist: tqdm

{fitscube-2.7.0 → fitscube-2.8.0}/fitscube/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.7.0'
-__version_tuple__ = version_tuple = (2, 7, 0)
+__version__ = version = '2.8.0'
+__version_tuple__ = version_tuple = (2, 8, 0)
 
 __commit_id__ = commit_id = None

{fitscube-2.7.0 → fitscube-2.8.0}/fitscube/combine_fits.py

@@ -4,6 +4,8 @@
 Assumes:
 - All files have the same WCS
 - All files have the same shape / pixel grid (checked, see `check_matching_shapes`)
+- All files have the same axes, in the same order, and the same Stokes parameter
+  (checked, see `check_matching_axes`)
 - All the relevant information is in the first header of the first image
 - Frequency is either a WCS axis or in the REFFREQ header keyword OR
 - Time is present in the DATE-OBS header keyword for time-domain-mode
@@ -24,11 +26,12 @@ from typing import IO, Any, Literal, NamedTuple, TypeVar, cast
 
 import astropy.units as u
 import numpy as np
+from astropy.coordinates import StokesCoord
 from astropy.io import fits
 from astropy.io.fits.verify import VerifyWarning
 from astropy.table import Table
 from astropy.time import Time
-from astropy.wcs import WCS
+from astropy.wcs import WCS, WCSSUB_STOKES
 from numpy.typing import ArrayLike, NDArray
 from radio_beam import Beam, Beams
 from radio_beam.beam import NoBeamException
@@ -40,9 +43,11 @@ from fitscube.bounding_box import (
     get_common_bounding_box_coro,
 )
 from fitscube.exceptions import (
+    AxisMismatchException,
     AxisOrderException,
     IrregularSpacingException,
     ShapeMismatchException,
+    StokesMismatchException,
 )
 from fitscube.logging import TQDM_OUT, logger, set_verbosity
 
@@ -134,56 +139,141 @@ async def write_channel_to_cube_coro(
 write_channel_to_cube = sync_wrapper(write_channel_to_cube_coro)
 
 
-async def check_matching_shapes_coro(
+async def read_headers_coro(
     file_list: list[Path],
     max_workers: int | None = None,
-) -> tuple[int, int]:
-    """Confirm every input image shares the same NAXIS1/NAXIS2 pixel grid.
-
-    Planes are written to the cube at a fixed byte offset per channel, so
-    inputs of differing shape would silently slide against each other and
-    produce a scrambled cube with a self-consistent header.
+) -> list[fits.Header]:
+    """Read the primary header of every input image, without its data.
 
     Args:
-        file_list (list[Path]): The FITS images to check
+        file_list (list[Path]): The FITS images to read
         max_workers (int | None, optional): Maximum number of concurrent header reads. Defaults to None.
 
-    Raises:
-        ShapeMismatchException: If any image differs in shape from the first
-
     Returns:
-        tuple[int, int]: The common (NAXIS1, NAXIS2)
+        list[fits.Header]: One header per image, in ``file_list`` order
     """
-    headers = await gather_with_limit(
+    return await gather_with_limit(
         max_workers,
         *(asyncio.to_thread(fits.getheader, fits_path) for fits_path in file_list),
-        desc="Checking shapes",
+        desc="Reading headers",
     )
-    shapes = [(header["NAXIS1"], header["NAXIS2"]) for header in headers]
-    expected = shapes[0]
+
+
+def check_values_match(
+    file_list: list[Path],
+    values: list[T],
+    describe: Callable[[T], str],
+    requirement: str,
+    exception: type[Exception],
+) -> T:
+    """Check that every input has the same value as the first.
+
+    Args:
+        file_list (list[Path]): The FITS images the values came from
+        values (list[T]): One value per image
+        describe (Callable[[T], str]): Describes a value for the error message
+        requirement (str): What the inputs must share, for the error message
+        exception (type[Exception]): Raised when any value differs from the first
+
+    Returns:
+        T: The common value
+    """
+    expected = values[0]
     offenders = [
-        f"{fits_path} has (NAXIS1, NAXIS2)={shape}"
-        for fits_path, shape in zip(file_list, shapes, strict=False)
-        if shape != expected
+        f"{fits_path} has {describe(value)}"
+        for fits_path, value in zip(file_list, values, strict=True)
+        if value != expected
     ]
     if offenders:
         # Keep the message readable when a whole run is mismatched
-        shown = offenders[:10]
+        max_shown = 10
+        shown = offenders[:max_shown]
         if len(offenders) > len(shown):
             shown.append(f"...and {len(offenders) - len(shown)} more")
         listing = "\n".join(shown)
         msg = (
-            "All input images must share the same pixel grid. Expected "
-            f"(NAXIS1, NAXIS2)={expected} from {file_list[0]}, but found:\n{listing}"
+            f"All input images must share {requirement}. Expected "
+            f"{describe(expected)} from {file_list[0]}, but found:\n{listing}"
         )
-        raise ShapeMismatchException(msg)
-
+        raise exception(msg)
     return expected
 
 
+async def check_matching_shapes_coro(
+    file_list: list[Path],
+    max_workers: int | None = None,
+) -> tuple[int, int]:
+    """Confirm every input image shares the same NAXIS1/NAXIS2 pixel grid.
+
+    Planes are written to the cube at a fixed byte offset per channel, so
+    inputs of differing shape would silently slide against each other and
+    produce a scrambled cube with a self-consistent header.
+
+    Args:
+        file_list (list[Path]): The FITS images to check
+        max_workers (int | None, optional): Maximum number of concurrent header reads. Defaults to None.
+
+    Raises:
+        ShapeMismatchException: If any image differs in shape from the first
+
+    Returns:
+        tuple[int, int]: The common (NAXIS1, NAXIS2)
+    """
+    headers = await read_headers_coro(file_list, max_workers=max_workers)
+    return check_values_match(
+        file_list,
+        [(header["NAXIS1"], header["NAXIS2"]) for header in headers],
+        describe=lambda shape: f"(NAXIS1, NAXIS2)={shape}",
+        requirement="the same pixel grid",
+        exception=ShapeMismatchException,
+    )
+
+
 check_matching_shapes = sync_wrapper(check_matching_shapes_coro)
 
 
+async def check_matching_axes_coro(
+    file_list: list[Path],
+    max_workers: int | None = None,
+) -> None:
+    """Confirm every input image has the same axes and Stokes parameter.
+
+    The cube's header is taken from the first input, so an input with other
+    axes (e.g. RA/DEC swapped, or an extra axis) or another Stokes parameter
+    would be silently mislabelled.
+
+    Args:
+        file_list (list[Path]): The FITS images to check
+        max_workers (int | None, optional): Maximum number of concurrent header reads. Defaults to None.
+
+    Raises:
+        AxisMismatchException: If any image's axis types or their order differ from the first
+        StokesMismatchException: If any image differs in Stokes from the first
+    """
+    headers = await read_headers_coro(file_list, max_workers=max_workers)
+    check_values_match(
+        file_list,
+        [get_axis_types(header) for header in headers],
+        describe=lambda ctypes: f"axes {ctypes}",
+        requirement="the same axes, in the same order",
+        exception=AxisMismatchException,
+    )
+    check_values_match(
+        file_list,
+        [get_stokes_codes(header) for header in headers],
+        describe=lambda codes: (
+            "no Stokes axis"
+            if codes is None
+            else f"Stokes {StokesCoord(list(codes)).symbol.tolist()} (codes {codes})"
+        ),
+        requirement="the same Stokes parameter",
+        exception=StokesMismatchException,
+    )
+
+
+check_matching_axes = sync_wrapper(check_matching_axes_coro)
+
+
 # https://stackoverflow.com/a/66082278
 def np_arange_fix(start: float, stop: float, step: float) -> NDArray[np.float64]:
     n = (stop - start) / step + 1
@@ -337,7 +427,7 @@ async def create_cube_from_scratch_coro(
 
     header.tofile(output_file, overwrite=overwrite)
 
-    bytes_per_value = BIT_DICT.get(abs(output_header["BITPIX"]), None)
+    bytes_per_value = BIT_DICT.get(abs(output_header["BITPIX"]))
     msg = f"Header BITPIX={output_header['BITPIX']}, bytes_per_value={bytes_per_value}"
     logger.info(msg)
     if bytes_per_value is None:
@@ -418,7 +508,11 @@ async def create_output_cube_coro(
         diff_time = np.diff(sorted_specs)
         diff_diff_time = np.diff(diff_time)
         running_deviation_from_zero = np.abs(np.cumsum(diff_diff_time))
-        even_spec = np.max(running_deviation_from_zero) < (np.mean(diff_time) * 0.02)
+        # Fewer than three times have no second difference, and are always
+        # evenly spaced
+        even_spec = len(diff_diff_time) == 0 or bool(
+            np.max(running_deviation_from_zero) < (np.mean(diff_time) * 0.02)
+        )
 
         # This is a simpler way where no attempt is made to ensure the total
         # error on the irregular steps accumulates and violates the regular
@@ -814,48 +908,99 @@ def nan_zero_beams(beams: Beams, zero_beam_idx: NDArray[np.bool_]) -> Beams:
     )
 
 
-def get_polarisation(header: fits.Header) -> int:
-    """Get the polarisation axis.
+def _stokes_wcs(header: fits.Header) -> WCS | None:
+    """Get the Stokes axis of an image as a 1D WCS.
 
     Args:
-        header (fits.Header): Primary header
+        header (fits.Header): Primary header of an image
 
     Returns:
-        int: Polarisation axis (in FITS)
+        WCS | None: The Stokes axis alone, or None if there is no Stokes axis
     """
     wcs = WCS(header)
-    array_shape = wcs.array_shape
-    if array_shape is None:
+    if wcs.array_shape is None:
         msg = "WCS does not have an array shape"
         raise ValueError(msg)
 
-    for _, (ctype, naxis, crval) in enumerate(
-        zip(wcs.axis_type_names, array_shape[::-1], wcs.wcs.crval, strict=False)
-    ):
-        if ctype == "STOKES":
-            assert naxis <= 1, (
-                f"Only one polarisation axis is supported - found {naxis}"
-            )
-            # FITS Stokes codes are 1=I, 2=Q, 3=U, 4=V; the BEAMS table POL
-            # column is 0-indexed, so subtract 1.
-            return int(crval - 1)
-    return 0
+    stokes_wcs = wcs.sub([WCSSUB_STOKES])
+    return stokes_wcs if stokes_wcs.naxis else None
 
 
-def make_beam_table(beams: Beams, old_header: fits.Header) -> fits.BinTableHDU:
+def get_polarisation(header: fits.Header) -> NDArray[np.int_]:
+    """Get the 0-based plane indices along the Stokes axis.
+
+    These are the values the CASA beam table expects in its POL column: indices
+    into the cube's Stokes axis, not FITS Stokes codes (see `get_stokes_codes`).
+
+    Args:
+        header (fits.Header): Primary header of the cube
+
+    Returns:
+        NDArray[np.int_]: ``arange(n_stokes)``, or ``[0]`` if there is no Stokes axis
+    """
+    stokes_wcs = _stokes_wcs(header)
+    # CASA counts an image without a Stokes axis as one Stokes plane in its beam set
+    n_stokes = 1 if stokes_wcs is None else stokes_wcs.pixel_shape[0]
+    return np.arange(n_stokes)
+
+
+def get_axis_types(header: fits.Header) -> tuple[str, ...]:
+    """Get the CTYPE of every axis of an image, in FITS axis order.
+
+    Args:
+        header (fits.Header): Primary header of an image
+
+    Returns:
+        tuple[str, ...]: One CTYPE per axis, "" where an axis has none
+    """
+    return tuple(
+        str(header.get(f"CTYPE{axis}", "")).strip()
+        for axis in range(1, header["NAXIS"] + 1)
+    )
+
+
+def get_stokes_codes(header: fits.Header) -> tuple[int, ...] | None:
+    """Get the FITS Stokes code of each plane along the Stokes axis.
+
+    The codes are those of `astropy.coordinates.StokesCoord`, e.g. 1..4 for
+    I, Q, U, V (see ``astropy.coordinates.polarization.FITS_STOKES_VALUE_SYMBOL_MAP``).
+
+    Args:
+        header (fits.Header): Primary header of an image
+
+    Returns:
+        tuple[int, ...] | None: One code per Stokes plane, or None if there is no Stokes axis
+    """
+    stokes_wcs = _stokes_wcs(header)
+    if stokes_wcs is None:
+        return None
+    stokes: StokesCoord = stokes_wcs.pixel_to_world(
+        np.arange(stokes_wcs.pixel_shape[0])
+    )
+    return tuple(int(code) for code in np.round(stokes.value))
+
+
+def make_beam_table(beams: Beams, cube_header: fits.Header) -> fits.BinTableHDU:
     """Make a beam table.
 
+    CHAN and POL are 0-based indices into the cube's frequency and Stokes axes
+    (CASA convention), not FITS Stokes codes.
+
     Args:
-        beams (Beams): Beams object
-        header (fits.Header): Old header to infer polarisation
+        beams (Beams): One beam per output channel
+        cube_header (fits.Header): Header of the output cube, used to find the
+            Stokes axis
 
     Returns:
         fits.BinTableHDU: Beam table
     """
+    stokes_idx = get_polarisation(cube_header)
+    if len(stokes_idx) != 1:
+        msg = f"Only single-Stokes cubes are supported - found {len(stokes_idx)} Stokes planes"
+        raise NotImplementedError(msg)
     nchan = len(beams.major)
     chans = np.arange(nchan)
-    pol = get_polarisation(old_header)
-    pols = np.ones(nchan, dtype=int) * pol
+    pols = np.full(nchan, stokes_idx[0])
     tiny = np.finfo(np.float32).tiny
     # A zero-sized beam is not a valid PSF, and a literal zero is exactly what
     # the sentinel below exists to keep out of the table. NaN them first so they
@@ -880,7 +1025,7 @@ def make_beam_table(beams: Beams, old_header: fits.Header) -> fits.BinTableHDU:
     tab_header = tab_hdu.header
     tab_header["EXTNAME"] = "BEAMS"
     tab_header["NCHAN"] = nchan
-    tab_header["NPOL"] = 1  # Only one pol for now
+    tab_header["NPOL"] = len(stokes_idx)
 
     return tab_hdu
 
@@ -1007,6 +1152,7 @@ async def combine_fits_coro(
     # TODO: Check that all files have the same WCS
 
     await check_matching_shapes_coro(file_list=file_list, max_workers=max_workers)
+    await check_matching_axes_coro(file_list=file_list, max_workers=max_workers)
 
     file_specs, specs, missing_chan_idx = await parse_specs_coro(
         spec_file=spec_file,
@@ -1104,6 +1250,12 @@ async def combine_fits_coro(
         )
         raise ValueError(msg)
 
+    # Build the beam table before writing any data, so an unsupported cube
+    # (e.g. multi-Stokes) fails before the planes are copied in
+    beam_table_hdu = (
+        make_beam_table(beams, new_header) if has_beams and not single_beam else None
+    )
+
     new_channels = np.arange(len(specs))
     old_channels = np.arange(len(file_specs))
 
@@ -1145,9 +1297,7 @@ async def combine_fits_coro(
         await gather_with_limit(max_workers, *coros, desc="Writing channels")
 
     # Handle beams
-    if has_beams and not single_beam:
-        old_header = fits.getheader(file_list[0])
-        beam_table_hdu = make_beam_table(beams, old_header)
+    if beam_table_hdu is not None:
         msg = f"Appending beam table to {out_cube}"
         logger.info(msg)
         fits.append(

{fitscube-2.7.0 → fitscube-2.8.0}/fitscube/exceptions.py

@@ -17,6 +17,14 @@ class ShapeMismatchException(FITSCubeException):
     """Input images do not share a common pixel grid"""
 
 
+class AxisMismatchException(FITSCubeException):
+    """Input images do not share the same axes, in the same order"""
+
+
+class StokesMismatchException(FITSCubeException):
+    """Input images do not share the same Stokes parameter"""
+
+
 class AxisOrderException(FITSCubeException):
     """The spectral axis is not the slowest-varying axis of the cube"""
 

{fitscube-2.7.0 → fitscube-2.8.0}/pyproject.toml

@@ -31,7 +31,7 @@ classifiers = [
 ]
 dynamic = ["version"]
 dependencies = [
-  "astropy",
+  "astropy>=6.0",  # StokesCoord
   "numpy>=2",
   "tqdm",
   "radio_beam",

{fitscube-2.7.0 → fitscube-2.8.0}/tests/test_combine.py

@@ -9,17 +9,40 @@ import numpy as np
 import pytest
 from astropy.io import fits
 from astropy.time import Time
-from fitscube.combine_fits import check_for_any_beam, combine_fits, get_polarisation
+from fitscube.combine_fits import (
+    check_for_any_beam,
+    combine_fits,
+    get_polarisation,
+    make_beam_table,
+)
+from radio_beam import Beams
 
 
 @pytest.mark.filterwarnings("ignore:'datfix' made the change")
-def test_get_polarisation_uses_crval(headers: dict[str, str]) -> None:
-    """POL must track CRVAL4 (the actual Stokes code)"""
+def test_get_polarisation_is_axis_index(headers: dict[str, str]) -> None:
+    """POL values are 0-based indices along the Stokes axis, not Stokes codes"""
     header = fits.Header.fromstring(headers["beams"])
-    assert get_polarisation(header) == 0  # CRVAL4 == 1.0 -> Stokes I
+    header["NAXIS4"] = 1
+    header["CRVAL4"] = 3.0  # Stokes U, but a single plane
+    assert get_polarisation(header).tolist() == [0]
+
+    header["NAXIS4"] = 3
+    assert get_polarisation(header).tolist() == [0, 1, 2]
+
+
+@pytest.mark.filterwarnings("ignore:'datfix' made the change")
+def test_make_beam_table_rejects_multi_stokes(headers: dict[str, str]) -> None:
+    """Multi-Stokes beam tables are not supported yet"""
+    header = fits.Header.fromstring(headers["beams"])
+    header["NAXIS4"] = 3
+    beams = Beams(
+        major=np.ones(4) * u.arcsec,
+        minor=np.ones(4) * u.arcsec,
+        pa=np.zeros(4) * u.deg,
+    )
 
-    header["CRVAL4"] = 2.0  # Stokes Q
-    assert get_polarisation(header) == 1
+    with pytest.raises(NotImplementedError):
+        make_beam_table(beams, header)
 
 
 def test_check_for_any_beams_no_beams(file_list) -> None:
@@ -58,16 +81,15 @@ def test_combine_beam_not_in_first_file(
 
 
 @pytest.mark.parametrize(
-    ("stokes_code", "expected_pol"),
-    [(1, 0), (2, 1), (3, 2), (4, 3)],  # I, Q, U, V
+    "stokes_code",
+    [1, 2, 3, 4],  # I, Q, U, V
 )
-def test_combine_beam_polarisation_matches_stokes(
+def test_combine_beam_pol_is_zero_index_for_single_stokes(
     tmp_path: Path,
     even_specs: u.Quantity,
     stokes_code: int,
-    expected_pol: int,
 ) -> None:
-    """Each Stokes plane's own beam table must carry its own POL, not always 0."""
+    """POL/CHAN are 0-based axis indices, not FITS Stokes codes."""
     image = np.ones((1, 1, 10, 10))
     file_list = []
     for i, spec in enumerate(even_specs):
@@ -103,4 +125,7 @@ def test_combine_beam_polarisation_matches_stokes(
     with fits.open(out_cube) as hdul:
         assert hdul[0].header["CRVAL4"] == stokes_code
         assert hdul[1].name == "BEAMS"
-        assert set(hdul[1].data["POL"].tolist()) == {expected_pol}
+        assert hdul[0].header["NAXIS3"] == len(even_specs)
+        assert hdul[0].header["NAXIS4"] == 1
+        assert np.all(hdul[1].data["POL"] == 0)
+        assert np.array_equal(hdul[1].data["CHAN"], np.arange(len(even_specs)))

{fitscube-2.7.0 → fitscube-2.8.0}/tests/test_combine_guards.py

@@ -9,11 +9,16 @@ import numpy as np
 import pytest
 from astropy.io import fits
 from fitscube.bounding_box import get_common_bounding_box
-from fitscube.combine_fits import check_matching_shapes, combine_fits
+from fitscube.combine_fits import (
+    check_matching_axes,
+    check_matching_shapes,
+    combine_fits,
+)
 from fitscube.exceptions import (
     AxisOrderException,
     IrregularSpacingException,
     ShapeMismatchException,
+    StokesMismatchException,
 )
 
 
@@ -96,6 +101,31 @@ def test_check_matching_shapes(file_list: list[Path]) -> None:
     assert check_matching_shapes(file_list=file_list) == (8, 8)
 
 
+def test_check_matching_axes(file_list: list[Path]) -> None:
+    for path in file_list:
+        fits.setval(path, "CRVAL3", value=3.0)  # Stokes U
+    check_matching_axes(file_list=file_list)
+
+
+def test_check_matching_axes_compares_stokes_codes_not_keywords(
+    file_list: list[Path],
+) -> None:
+    """CRVAL3=2 at CRPIX3=2 is still Stokes I at the (only) first pixel"""
+    fits.setval(file_list[-1], "CRVAL3", value=2.0)
+    fits.setval(file_list[-1], "CRPIX3", value=2.0)
+    check_matching_axes(file_list=file_list)
+
+
+def test_mismatched_stokes_raise(tmp_path: Path, file_list: list[Path]) -> None:
+    """A Q plane among I planes would be mislabelled as I in the cube"""
+    fits.setval(file_list[2], "CRVAL3", value=2.0)  # Stokes Q
+    out_cube = tmp_path / "cube.fits"
+
+    with pytest.raises(StokesMismatchException, match=file_list[2].name):
+        combine_fits(file_list=file_list, out_cube=out_cube, overwrite=True)
+    assert not out_cube.exists()
+
+
 def test_spectral_axis_must_be_slowest(tmp_path: Path, specs: u.Quantity) -> None:
     """A non-degenerate axis above FREQ breaks the per-plane seek."""
     file_list = [

fitscube-2.8.0/tests/test_combine_layouts.py

@@ -0,0 +1,328 @@
+"""End-to-end combines of image pairs across input axis layouts
+
+Each case combines two single-plane images and states the cube it expects in
+the notation ``(RA, DEC, FREQ) + (RA, DEC, FREQ) -> (RA, DEC, FREQ)``, or the
+error it expects. Axes are named by CTYPE. A Stokes symbol (e.g. ``I`` or
+``XX``) is a STOKES axis holding that parameter, and ``FOO`` is an axis type
+fitscube knows nothing about.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+import numpy as np
+import pytest
+from astropy.coordinates import StokesCoord
+from astropy.coordinates.polarization import FITS_STOKES_VALUE_SYMBOL_MAP
+from astropy.io import fits
+from astropy.time import Time
+from fitscube.combine_fits import combine_fits
+from fitscube.exceptions import AxisMismatchException, StokesMismatchException
+
+Axes = tuple[str, ...]
+WritePlane = Callable[[Axes, int], Path]
+
+
+def _is_stokes(axis: str) -> bool:
+    return axis in {stokes.symbol for stokes in FITS_STOKES_VALUE_SYMBOL_MAP.values()}
+
+
+def _axes_id(value: object) -> str:
+    if isinstance(value, bool):
+        return "time" if value else "freq"
+    if isinstance(value, tuple):
+        return f"({','.join(value)})"
+    if isinstance(value, type):
+        return value.__name__
+    return str(value)
+
+
+@pytest.fixture
+def write_plane(tmp_path: Path) -> WritePlane:
+    """Write the ``index``-th single-plane image with the given axes.
+
+    Plane ``index`` holds the value ``index`` and its own beam, is one step
+    later in frequency and time than the plane before, and each non-celestial
+    axis has length one.
+    """
+
+    def _write_plane(axes: Axes, index: int) -> Path:
+        time = Time(60000.0 + index * 10 / 86400, format="mjd")
+        cards = {
+            "RA": {"CTYPE": "RA---SIN", "CRVAL": 0.0, "CDELT": -1e-3, "CRPIX": 5.0},
+            "DEC": {"CTYPE": "DEC--SIN", "CRVAL": 0.0, "CDELT": 1e-3, "CRPIX": 5.0},
+            "FREQ": {
+                "CTYPE": "FREQ",
+                "CRVAL": 1e9 + index * 1e6,
+                "CDELT": 1e6,
+                "CRPIX": 1.0,
+                "CUNIT": "Hz",
+            },
+            "TIME": {
+                "CTYPE": "TIME",
+                "CRVAL": time.mjd * 86400,
+                "CDELT": 10.0,
+                "CRPIX": 1.0,
+                "CUNIT": "s",
+            },
+            "FOO": {"CTYPE": "FOO", "CRVAL": 1.0, "CDELT": 1.0, "CRPIX": 1.0},
+        }
+        header = fits.Header()
+        for fits_axis, axis in enumerate(axes, start=1):
+            axis_cards = (
+                {
+                    "CTYPE": "STOKES",
+                    "CRVAL": float(StokesCoord(axis).value),
+                    "CDELT": 1.0,
+                    "CRPIX": 1.0,
+                }
+                if _is_stokes(axis)
+                else cards[axis]
+            )
+            for key, value in axis_cards.items():
+                header[f"{key}{fits_axis}"] = value
+        header["DATE-OBS"] = time.isot
+        header["MJD-OBS"] = time.mjd
+        if len(axes) == 2:
+            header["REFFREQ"] = 1e9 + index * 1e6
+        # Vary the beam per plane so a beam table is written
+        header["BMAJ"] = 1e-3 * (1 + index)
+        header["BMIN"] = 1e-3
+        header["BPA"] = 0.0
+
+        shape = (1,) * (len(axes) - 2) + (10, 10)
+        path = tmp_path / f"plane_{index}.fits"
+        fits.PrimaryHDU(np.full(shape, float(index)), header=header).writeto(path)
+        return path
+
+    return _write_plane
+
+
+@pytest.fixture
+def out_cube(tmp_path: Path) -> Path:
+    return tmp_path / "cube.fits"
+
+
+@pytest.mark.parametrize(
+    ("time_domain_mode", "first", "second", "expected"),
+    [
+        # Frequency cubes
+        (False, ("RA", "DEC"), ("RA", "DEC"), ("RA", "DEC", "FREQ")),
+        (False, ("RA", "DEC", "FREQ"), ("RA", "DEC", "FREQ"), ("RA", "DEC", "FREQ")),
+        (False, ("DEC", "RA", "FREQ"), ("DEC", "RA", "FREQ"), ("DEC", "RA", "FREQ")),
+        (
+            False,
+            ("RA", "DEC", "FOO", "FREQ"),
+            ("RA", "DEC", "FOO", "FREQ"),
+            ("RA", "DEC", "FOO", "FREQ"),
+        ),
+        (
+            False,
+            ("RA", "DEC", "FREQ", "FOO"),
+            ("RA", "DEC", "FREQ", "FOO"),
+            ("RA", "DEC", "FREQ", "FOO"),
+        ),
+        # wsclean axis order
+        (
+            False,
+            ("RA", "DEC", "FREQ", "I"),
+            ("RA", "DEC", "FREQ", "I"),
+            ("RA", "DEC", "FREQ", "STOKES"),
+        ),
+        # CASA axis order
+        (
+            False,
+            ("RA", "DEC", "U", "FREQ"),
+            ("RA", "DEC", "U", "FREQ"),
+            ("RA", "DEC", "STOKES", "FREQ"),
+        ),
+        (
+            False,
+            ("RA", "DEC", "FREQ", "XX"),
+            ("RA", "DEC", "FREQ", "XX"),
+            ("RA", "DEC", "FREQ", "STOKES"),
+        ),
+        (
+            False,
+            ("RA", "DEC", "TIME", "FREQ"),
+            ("RA", "DEC", "TIME", "FREQ"),
+            ("RA", "DEC", "TIME", "FREQ"),
+        ),
+        (
+            False,
+            ("RA", "DEC", "FREQ", "TIME", "V"),
+            ("RA", "DEC", "FREQ", "TIME", "V"),
+            ("RA", "DEC", "FREQ", "TIME", "STOKES"),
+        ),
+        # Time cubes. A missing TIME axis is appended.
+        (True, ("RA", "DEC"), ("RA", "DEC"), ("RA", "DEC", "TIME")),
+        (True, ("RA", "DEC", "TIME"), ("RA", "DEC", "TIME"), ("RA", "DEC", "TIME")),
+        (
+            True,
+            ("RA", "DEC", "FREQ"),
+            ("RA", "DEC", "FREQ"),
+            ("RA", "DEC", "FREQ", "TIME"),
+        ),
+        (
+            True,
+            ("RA", "DEC", "FREQ", "I"),
+            ("RA", "DEC", "FREQ", "I"),
+            ("RA", "DEC", "FREQ", "STOKES", "TIME"),
+        ),
+        (
+            True,
+            ("RA", "DEC", "Q", "TIME"),
+            ("RA", "DEC", "Q", "TIME"),
+            ("RA", "DEC", "STOKES", "TIME"),
+        ),
+        (
+            True,
+            ("RA", "DEC", "TIME", "FOO"),
+            ("RA", "DEC", "TIME", "FOO"),
+            ("RA", "DEC", "TIME", "FOO"),
+        ),
+    ],
+    ids=_axes_id,
+)
+def test_combine_pair(
+    write_plane: WritePlane,
+    out_cube: Path,
+    time_domain_mode: bool,
+    first: Axes,
+    second: Axes,
+    expected: Axes,
+) -> None:
+    """first + second -> expected, with the planes in order and a valid BEAMS table"""
+    combine_fits(
+        file_list=[write_plane(first, 0), write_plane(second, 1)],
+        out_cube=out_cube,
+        time_domain_mode=time_domain_mode,
+        overwrite=True,
+    )
+
+    with fits.open(out_cube) as hdul:
+        header = hdul[0].header
+        n_axes = header["NAXIS"]
+        ctypes = tuple(
+            header[f"CTYPE{axis}"].split("-")[0] for axis in range(1, n_axes + 1)
+        )
+        assert ctypes == expected
+
+        combine_axis = ctypes.index("TIME" if time_domain_mode else "FREQ") + 1
+        naxes = tuple(header[f"NAXIS{axis}"] for axis in range(1, n_axes + 1))
+        assert naxes == tuple(
+            10 if ctype in ("RA", "DEC") else 2 if axis == combine_axis else 1
+            for axis, ctype in enumerate(ctypes, start=1)
+        )
+        stokes = [axis for axis in first if _is_stokes(axis)]
+        if stokes:
+            stokes_axis = ctypes.index("STOKES") + 1
+            assert header[f"CRVAL{stokes_axis}"] == StokesCoord(stokes[0]).value
+
+        # Plane i along the combine axis holds input i
+        planes = np.moveaxis(hdul[0].data, n_axes - combine_axis, 0)
+        assert np.all(planes[0] == 0)
+        assert np.all(planes[1] == 1)
+
+        beam_table = hdul["BEAMS"]
+        assert beam_table.header["NCHAN"] == 2
+        assert beam_table.header["NPOL"] == 1
+        assert beam_table.data["CHAN"].tolist() == [0, 1]
+        assert beam_table.data["POL"].tolist() == [0, 0]
+
+
+@pytest.mark.parametrize(
+    ("time_domain_mode", "first", "second", "error"),
+    [
+        (
+            False,
+            ("RA", "DEC", "FREQ"),
+            ("DEC", "RA", "FREQ"),
+            AxisMismatchException,
+        ),
+        (False, ("RA", "DEC"), ("RA", "DEC", "FREQ"), AxisMismatchException),
+        (
+            False,
+            ("RA", "DEC", "FREQ"),
+            ("RA", "DEC", "FOO", "FREQ"),
+            AxisMismatchException,
+        ),
+        (
+            False,
+            ("RA", "DEC", "FREQ", "I"),
+            ("RA", "DEC", "I", "FREQ"),
+            AxisMismatchException,
+        ),
+        (
+            False,
+            ("RA", "DEC", "FREQ", "I"),
+            ("RA", "DEC", "FREQ"),
+            AxisMismatchException,
+        ),
+        (
+            False,
+            ("RA", "DEC", "FREQ", "I"),
+            ("RA", "DEC", "FREQ", "Q"),
+            StokesMismatchException,
+        ),
+        (
+            False,
+            ("RA", "DEC", "FREQ", "XX"),
+            ("RA", "DEC", "FREQ", "YY"),
+            StokesMismatchException,
+        ),
+        # Frequency mode needs a FREQ axis, or REFFREQ on a 2D image
+        (False, ("RA", "DEC", "FOO"), ("RA", "DEC", "FOO"), ValueError),
+        (True, ("RA", "DEC", "TIME"), ("RA", "DEC", "FREQ"), AxisMismatchException),
+        (
+            True,
+            ("RA", "DEC", "TIME", "I"),
+            ("RA", "DEC", "TIME", "Q"),
+            StokesMismatchException,
+        ),
+    ],
+    ids=_axes_id,
+)
+def test_combine_pair_raises(
+    write_plane: WritePlane,
+    out_cube: Path,
+    time_domain_mode: bool,
+    first: Axes,
+    second: Axes,
+    error: type[Exception],
+) -> None:
+    """first + second -> error, before any output is written"""
+    with pytest.raises(error):
+        combine_fits(
+            file_list=[write_plane(first, 0), write_plane(second, 1)],
+            out_cube=out_cube,
+            time_domain_mode=time_domain_mode,
+            overwrite=True,
+        )
+    assert not out_cube.exists()
+
+
+def test_combine_rejects_multi_stokes_beams(tmp_path: Path, out_cube: Path) -> None:
+    """A multi-Stokes cube with varying beams fails before any plane is written"""
+    file_list = []
+    for index in range(2):
+        header = fits.Header()
+        header["CTYPE3"], header["CRVAL3"] = "STOKES", 1.0
+        header["CDELT3"], header["CRPIX3"] = 1.0, 1.0
+        header["CTYPE4"], header["CRVAL4"] = "FREQ", 1e9 + index * 1e6
+        header["CDELT4"], header["CRPIX4"], header["CUNIT4"] = 1e6, 1.0, "Hz"
+        header["BMAJ"] = 1e-3 * (1 + index)
+        header["BMIN"], header["BPA"] = 1e-3, 0.0
+        path = tmp_path / f"plane_{index}.fits"
+        fits.PrimaryHDU(np.full((1, 2, 10, 10), 1.0 + index), header=header).writeto(
+            path
+        )
+        file_list.append(path)
+
+    with pytest.raises(NotImplementedError, match="single-Stokes"):
+        combine_fits(file_list=file_list, out_cube=out_cube, overwrite=True)
+
+    # The data were never written: every plane is still the blank fill
+    assert np.all(fits.getdata(out_cube) == 0)

{fitscube-2.7.0 → fitscube-2.8.0}/tests/test_frequencies.py

@@ -44,7 +44,7 @@ def file_list(even_specs: u.Quantity):
 
 
 def test_parse_specs(file_list: list[Path], even_specs: u.Quantity):
-    file_specs, specs, missing_chan_idx = parse_specs(file_list)
+    file_specs, _specs, _missing_chan_idx = parse_specs(file_list)
     assert np.array_equal(file_specs, even_specs)
 
 

{fitscube-2.7.0 → fitscube-2.8.0}/tests/test_times.py

@@ -10,7 +10,9 @@ from fitscube.combine_fits import combine_fits, parse_specs
 
 
 def test_parse_specs(file_list: list[Path], even_specs: u.Quantity):
-    file_specs, specs, missing_chan_idx = parse_specs(file_list, time_domain_mode=True)
+    file_specs, _specs, _missing_chan_idx = parse_specs(
+        file_list, time_domain_mode=True
+    )
     # assert np.array_equal(file_specs, even_specs)
     assert np.allclose(file_specs, even_specs, rtol=1e-10, atol=1e-9)
 

{fitscube-2.7.0 → fitscube-2.8.0}/uv.lock

@@ -446,7 +446,7 @@ uvloop = [
 
 [package.metadata]
 requires-dist = [
-    { name = "astropy" },
+    { name = "astropy", specifier = ">=6.0" },
     { name = "furo", marker = "extra == 'docs'", specifier = ">=2023.8.17" },
     { name = "myst-parser", marker = "extra == 'docs'", specifier = ">=0.13" },
     { name = "numpy", specifier = ">=2" },