fitscube 2.3.2__tar.gz → 2.4.0__tar.gz

{fitscube-2.3.2 → fitscube-2.4.0}/.github/workflows/cd.yml

@@ -25,11 +25,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
-      - uses: hynek/build-and-inspect-python-package@v2
+      - uses: hynek/build-and-inspect-python-package@v2.18.0
 
   publish:
     needs: [dist]
@@ -43,13 +43,13 @@ jobs:
     if: github.event_name == 'release' && github.event.action == 'published'
 
     steps:
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@v8
         with:
           name: Packages
           path: dist
 
       - name: Generate artifact attestation for sdist and wheel
-        uses: actions/attest-build-provenance@v2.4.0
+        uses: actions/attest-build-provenance@v4.1.1
         with:
           subject-path: "dist/*"
 

{fitscube-2.3.2 → fitscube-2.4.0}/.github/workflows/ci.yml

@@ -21,10 +21,10 @@ jobs:
     name: Format
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.x"
       - uses: pre-commit/action@v3.0.1
@@ -42,11 +42,11 @@ jobs:
         runs-on: [ubuntu-latest]
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
@@ -62,6 +62,6 @@ jobs:
           --durations=20
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v5.5.0
+        uses: codecov/codecov-action@v7.0.0
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

{fitscube-2.3.2 → fitscube-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fitscube
-Version: 2.3.2
+Version: 2.4.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

{fitscube-2.3.2 → fitscube-2.4.0}/fitscube/__init__.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
+from fitscube.bounding_box import BoundingBox, get_common_bounding_box
 from fitscube.combine_fits import combine_fits
 
 from ._version import version as __version__
 
-__all__ = ["__version__", "combine_fits"]
+__all__ = ["BoundingBox", "__version__", "combine_fits", "get_common_bounding_box"]

{fitscube-2.3.2 → fitscube-2.4.0}/fitscube/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.3.2'
-__version_tuple__ = version_tuple = (2, 3, 2)
+__version__ = version = '2.4.0'
+__version_tuple__ = version_tuple = (2, 4, 0)
 
 __commit_id__ = commit_id = None

{fitscube-2.3.2 → fitscube-2.4.0}/fitscube/bounding_box.py

@@ -10,28 +10,43 @@ from pathlib import Path
 import numpy as np
 from astropy.io import fits
 
+from fitscube.asyncio import gather_with_limit, sync_wrapper
 from fitscube.logging import logger
 
 
 @dataclass(frozen=True)
 class BoundingBox:
-    """Simple container to represent a bounding box. Maximum values can be
-    used as is when slicing."""
+    """Simple container to represent a bounding box.
+
+    .. warning::
+        ``x`` and ``y`` here are the *numpy* axes, which are the reverse of the
+        FITS ``NAXIS`` convention:
+
+        - ``x`` is axis ``-2`` -- image rows -- which is ``NAXIS2`` (declination)
+        - ``y`` is axis ``-1`` -- image columns -- which is ``NAXIS1`` (right ascension)
+
+        So a plane is sliced as ``data[..., xmin:xmax, ymin:ymax]`` and the
+        trimmed header takes ``NAXIS1 = y_span``, ``NAXIS2 = x_span``.
+
+    Minimum values are inclusive and maximum values are exclusive, so both can
+    be used as is when slicing. Note that ``xmax``/``ymax`` were *inclusive*
+    prior to ``v2.3.2``.
+    """
 
     xmin: int
-    """Minimum x pixel"""
+    """Minimum row pixel (numpy axis -2, FITS NAXIS2). Inclusive."""
     xmax: int
-    """Maximum x pixel"""
+    """Maximum row pixel (numpy axis -2, FITS NAXIS2). Can be used as is in a slice (e.g. is exclusive)."""
     ymin: int
-    """Minimum y pixel. Can be used as is in slice (e.g. is exclusive). """
+    """Minimum column pixel (numpy axis -1, FITS NAXIS1). Inclusive."""
     ymax: int
-    """Maximum y pixel Can be used as is in slice (e.g. is exclusive)."""
+    """Maximum column pixel (numpy axis -1, FITS NAXIS1). Can be used as is in a slice (e.g. is exclusive)."""
     original_shape: tuple[int, int]
     """The original shape of the image. If constructed against a cube this is the shape of a single plane."""
     y_span: int
-    """The span between ymax and ymin"""
+    """The span between ymax and ymin (i.e. the trimmed NAXIS1)"""
     x_span: int
-    """The span between xmax and xmin"""
+    """The span between xmax and xmin (i.e. the trimmed NAXIS2)"""
 
 
 def create_bound_box_plane(image_data: np.ndarray) -> BoundingBox | None:
@@ -151,3 +166,40 @@ async def get_bounding_box_for_fits_coro(
         data[data == 0.0] = np.nan
 
     return await asyncio.to_thread(create_bound_box_plane, image_data=data)
+
+
+async def get_common_bounding_box_coro(
+    file_list: list[Path],
+    invalidate_zeros: bool = False,
+    max_workers: int | None = None,
+) -> BoundingBox:
+    """Compute the single bounding box that encompasses the valid data of every
+    image in ``file_list``.
+
+    This is the box that ``combine_fits`` computes internally when
+    ``bounding_box=True``. Compute it once with this function and pass the
+    result to ``combine_fits(bounding_box=...)`` when several cubes (e.g. an
+    image cube and its weights cube) must land on an identical pixel grid.
+
+    Args:
+        file_list (list[Path]): The FITS images to consider
+        invalidate_zeros (bool, optional): Mark pixels that are exactly 0.0 as invalid (NaN them). Defaults to False.
+        max_workers (int | None, optional): Maximum number of concurrent reads. Defaults to None.
+
+    Returns:
+        BoundingBox: The smallest bounding box that contains all valid data
+    """
+    boxes = await gather_with_limit(
+        max_workers,
+        *(
+            get_bounding_box_for_fits_coro(
+                fits_path=fits_path, invalidate_zeros=invalidate_zeros
+            )
+            for fits_path in file_list
+        ),
+        desc="Bounding boxes",
+    )
+    return extract_common_bounding_box(bounding_boxes=boxes)
+
+
+get_common_bounding_box = sync_wrapper(get_common_bounding_box_coro)

{fitscube-2.3.2 → fitscube-2.4.0}/fitscube/combine_fits.py

@@ -3,7 +3,7 @@
 
 Assumes:
 - All files have the same WCS
-- All files have the same shape / pixel grid
+- All files have the same shape / pixel grid (checked, see `check_matching_shapes`)
 - 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
@@ -16,7 +16,7 @@ import asyncio
 import warnings
 from io import BufferedRandom
 from pathlib import Path
-from typing import Literal, NamedTuple, TypeVar
+from typing import Any, Literal, NamedTuple, TypeVar
 
 import astropy.units as u
 import numpy as np
@@ -25,7 +25,7 @@ from astropy.io.fits.verify import VerifyWarning
 from astropy.table import Table
 from astropy.time import Time
 from astropy.wcs import WCS
-from numpy.typing import ArrayLike
+from numpy.typing import ArrayLike, NDArray
 from radio_beam import Beam, Beams
 from radio_beam.beam import NoBeamException
 from tqdm.asyncio import tqdm
@@ -33,9 +33,9 @@ from tqdm.asyncio import tqdm
 from fitscube.asyncio import gather_with_limit, sync_wrapper
 from fitscube.bounding_box import (
     BoundingBox,
-    extract_common_bounding_box,
-    get_bounding_box_for_fits_coro,
+    get_common_bounding_box_coro,
 )
+from fitscube.exceptions import AxisOrderException, ShapeMismatchException
 from fitscube.logging import TQDM_OUT, logger, set_verbosity
 
 T = TypeVar("T")
@@ -73,7 +73,7 @@ class SpequencyInfo(NamedTuple):
 
     specs: u.Quantity
     """Frequencies/Times"""
-    missing_chan_idx: ArrayLike
+    missing_chan_idx: NDArray[np.bool_]
     """Missing channel indices"""
 
 
@@ -84,13 +84,19 @@ class FileSpequencyInfo(NamedTuple):
     """Frequencies or times matching each file"""
     specs: u.Quantity
     """Frequency/time in Hz or s"""
-    missing_chan_idx: ArrayLike
+    missing_chan_idx: NDArray[np.bool_]
     """Missing channel/time indices"""
 
 
 async def write_channel_to_cube_coro(
-    file_handle: BufferedRandom, plane: ArrayLike, chan: int, header: fits.Header
+    file_handle: BufferedRandom,
+    plane: NDArray[np.floating[Any]],
+    chan: int,
+    header: fits.Header,
 ) -> None:
+    # Seeking by whole planes is only valid when every plane is the same size
+    # (enforced by check_matching_shapes_coro) and the spectral axis is the
+    # slowest-varying one (enforced by create_output_cube_coro).
     msg = f"Writing channel {chan} to cube"
     logger.info(msg)
     seek_length = len(header.tostring()) + (plane.nbytes * chan)
@@ -101,8 +107,58 @@ async def write_channel_to_cube_coro(
 write_channel_to_cube = sync_wrapper(write_channel_to_cube_coro)
 
 
+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 gather_with_limit(
+        max_workers,
+        *(asyncio.to_thread(fits.getheader, fits_path) for fits_path in file_list),
+        desc="Checking shapes",
+    )
+    shapes = [(header["NAXIS1"], header["NAXIS2"]) for header in headers]
+    expected = shapes[0]
+    offenders = [
+        f"{fits_path} has (NAXIS1, NAXIS2)={shape}"
+        for fits_path, shape in zip(file_list, shapes)
+        if shape != expected
+    ]
+    if offenders:
+        # Keep the message readable when a whole run is mismatched
+        shown = offenders[:10]
+        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}"
+        )
+        raise ShapeMismatchException(msg)
+
+    return expected
+
+
+check_matching_shapes = sync_wrapper(check_matching_shapes_coro)
+
+
 # https://stackoverflow.com/a/66082278
-def np_arange_fix(start: float, stop: float, step: float) -> ArrayLike:
+def np_arange_fix(start: float, stop: float, step: float) -> NDArray[np.float64]:
     n = (stop - start) / step + 1
     x = n - int(n)
     stop += step * max(0.1, x) if x < 0.5 else 0
@@ -110,16 +166,18 @@ def np_arange_fix(start: float, stop: float, step: float) -> ArrayLike:
 
 
 def isin_close(
-    element: ArrayLike, test_element: ArrayLike, time_domain_mode: bool = False
-) -> ArrayLike:
+    element: NDArray[np.floating[Any]],
+    test_element: ArrayLike,
+    time_domain_mode: bool = False,
+) -> NDArray[np.bool_]:
     """Check if element is in test_element, within a tolerance.
 
     Args:
-        element (ArrayLike): Element to check
+        element (NDArray[np.floating[Any]]): Element to check
         test_element (ArrayLike): Element to check against
 
     Returns:
-        ArrayLike: Boolean array
+        NDArray[np.bool_]: Boolean array
     """
     if time_domain_mode:
         # the following should be sufficient to test integration times to ~5ms accuracy
@@ -210,23 +268,7 @@ async def create_cube_from_scratch_coro(
     msg = f"Creating a new FITS file with shape {output_shape}"
     logger.info(msg)
 
-    # If the output shape is less than 1801, we can create a blank array
-    # in memory and write it to disk
-    if np.prod(output_shape) < 1801:
-        msg = "Output cube is small enough to create in memory"
-        logger.warning(msg)
-        out_arr = np.zeros(output_shape)
-        fits.writeto(output_file, out_arr, output_header, overwrite=overwrite)
-        with fits.open(output_file, mode="denywrite", memmap=True) as hdu_list:
-            hdu = hdu_list[0]
-            data = hdu.data
-            on_disk_shape = data.shape
-            assert data.shape == output_shape, (
-                f"Output shape {on_disk_shape} does not match header {output_shape}!"
-            )
-        return fits.getheader(output_file)
-
-    logger.info("Output cube is too large to create in memory. Creating a blank file.")
+    logger.info("Creating a blank file.")
 
     small_size = [1 for _ in output_shape]
     data = np.zeros(small_size)
@@ -387,7 +429,7 @@ async def create_output_cube_coro(
 
     if ignore_spec or not even_spec:
         logger.info(
-            f"Ignore the specrency information, {ignore_spec=} or {not even_spec=}"
+            f"Ignore the spequency information, {ignore_spec=} or {not even_spec=}"
         )
         new_header[f"CDELT{fits_idx}"] = 1
         del new_header[f"CUNIT{fits_idx}"]
@@ -402,15 +444,17 @@ async def create_output_cube_coro(
             "Full beam information is stored in the second FITS extension."
         )
         new_header["COMMENT"] = (
-            f"The value '{tiny}' repsenents a NaN PSF in the beamtable."
+            f"The value '{tiny}' represents a NaN PSF in the beamtable."
         )
-        del new_header["BMAJ"], new_header["BMIN"], new_header["BPA"]
+        for k in ("BMAJ", "BMIN", "BPA"):
+            new_header.pop(k, None)
 
     if bounding_box:
         logger.info("Updating CRPIX1 and CRPIX2 header values to reflect bounding box")
+        # NOTE: BoundingBox x/y are numpy axes, so x -> NAXIS2 and y -> NAXIS1
         new_header["CRPIX1"] -= bounding_box.ymin
         new_header["CRPIX2"] -= bounding_box.xmin
-        logger.info("Updating NAXIS1 and NAXIS2 ro reflect bounding box")
+        logger.info("Updating NAXIS1 and NAXIS2 to reflect bounding box")
         new_header["NAXIS1"] = bounding_box.y_span
         new_header["NAXIS2"] = bounding_box.x_span
 
@@ -421,7 +465,7 @@ async def create_output_cube_coro(
     else:
         cube_shape[idx] = n_chan
 
-    logger.critical(f"{float_length=} {new_header['BITPIX']=}")
+    logger.debug(f"{float_length=} {new_header['BITPIX']=}")
     if float_length is not None:
         # Per astropy docs
         # bITPIX    numpy data type
@@ -438,6 +482,21 @@ async def create_output_cube_coro(
         logger.info(f"Specified {float_length=}, corresponding to {bit_pix=}")
         new_header["BITPIX"] = -abs(bit_pix)
 
+    # Planes are written at an offset of (plane bytes * channel), which only
+    # lands on the right plane when the spectral axis is the slowest-varying
+    # one - i.e. every axis above it in the cube is degenerate.
+    trailing_axes = {
+        f"NAXIS{axis}": new_header[f"NAXIS{axis}"]
+        for axis in range(fits_idx + 1, new_header["NAXIS"] + 1)
+    }
+    if any(naxis != 1 for naxis in trailing_axes.values()):
+        msg = (
+            f"The {ctype} axis (NAXIS{fits_idx}) must be the slowest-varying axis of "
+            f"the output cube, but non-degenerate axes sit above it: {trailing_axes}. "
+            "Reorder the axes of the input images before combining."
+        )
+        raise AxisOrderException(msg)
+
     output_header = await create_cube_from_scratch_coro(
         output_file=out_cube, output_header=new_header, overwrite=overwrite
     )
@@ -685,26 +744,14 @@ def make_beam_table(beams: Beams, old_header: fits.Header) -> fits.BinTableHDU:
     return tab_hdu
 
 
-async def process_channel(
-    file_handle: BufferedRandom,
-    new_header: fits.Header,
-    new_channel: int,
-    old_channel: int,
-    is_missing: bool,
-    file_list: list[Path],
+def load_and_preprocess_fits_data(
+    file_path: Path,
     bounding_box: BoundingBox | None = None,
     invalidate_zeros: bool = False,
-) -> None:
-    msg = f"Processing channel {new_channel}"
-    logger.info(msg)
+    wipe_with_nan: bool = False,
+) -> NDArray[np.floating[Any]]:
     # Use memmap=False to force the data to be read into memory - gives a speedup
-    if is_missing:
-        plane = await asyncio.to_thread(fits.getdata, file_list[0], memamp=False)
-        plane *= np.nan
-    else:
-        plane = await asyncio.to_thread(
-            fits.getdata, file_list[old_channel], memmap=False
-        )
+    plane: NDArray[np.floating[Any]] = fits.getdata(filename=file_path, memmap=False)
 
     if bounding_box is not None:
         plane = plane[
@@ -712,9 +759,39 @@ async def process_channel(
             bounding_box.xmin : bounding_box.xmax,
             bounding_box.ymin : bounding_box.ymax,
         ]
+
+    # Bail out early if we need to replace with nans
+    if wipe_with_nan:
+        plane *= np.nan
+        return plane
+
     if invalidate_zeros:
         plane[plane == 0.0] = np.nan
 
+    return plane
+
+
+async def process_channel(
+    file_handle: BufferedRandom,
+    new_header: fits.Header,
+    new_channel: int,
+    old_channel: int,
+    is_missing: bool,
+    file_list: list[Path],
+    bounding_box: BoundingBox | None = None,
+    invalidate_zeros: bool = False,
+) -> None:
+    msg = f"Processing channel {new_channel}"
+    logger.info(msg)
+    file_to_load = file_list[0] if is_missing else file_list[old_channel]
+    plane = await asyncio.to_thread(
+        load_and_preprocess_fits_data,
+        file_to_load,
+        bounding_box=bounding_box,
+        invalidate_zeros=invalidate_zeros,
+        wipe_with_nan=is_missing,
+    )
+
     if "BITPIX" in new_header:
         bit_pix = abs(new_header["BITPIX"])
         float_type = FLOAT_TYPE[bit_pix]
@@ -729,6 +806,30 @@ async def process_channel(
     del plane
 
 
+def check_for_any_beam(file_list: list[Path]) -> bool:
+    """Check to see if any input files have a beam encoded in the header
+
+    Args:
+        file_list (list[Path]): The collection of files to examine
+
+    Returns:
+        bool: Whether beam properties were found in any of the files
+    """
+    # This is the same as any(), but avoids reading un-necessary headers
+    # TODO: Should we ever do a test for consistent WCSs up front this should be
+    # moved over to that check
+    for file in file_list:
+        logger.debug(f"Examining {file=} for beam properties")
+        file_header = fits.getheader(file)
+        if "BMAJ" in file_header:
+            logger.info(f"Found beam properties in {file}")
+            return True
+
+    # No beams were found among any of the inputs, so no beam information
+    # can be recorded in the output
+    return False
+
+
 async def combine_fits_coro(
     file_list: list[Path],
     out_cube: Path,
@@ -739,7 +840,7 @@ async def combine_fits_coro(
     overwrite: bool = False,
     max_workers: int | None = None,
     time_domain_mode: bool = False,
-    bounding_box: bool = False,
+    bounding_box: bool | BoundingBox = False,
     invalidate_zeros: bool = False,
     float_length: FLOAT_LENGTH | None = None,
 ) -> u.Quantity:
@@ -752,15 +853,20 @@ async def combine_fits_coro(
         ignore_spec (bool, optional): Ignore frequency/time information. Defaults to False.
         create_blanks (bool, optional): Attempt to create even frequency spacing. Defaults to False.
         time_domain_mode (bool, optional): Work in time domain mode - make a time-cube. Default = False.
-        bounding_box (bool, optional): Clip invalid/padded pixels when crafting the fits cube. When True an extra read of the input daata is needed, but output cube is smaller. Defaults to False.
+        bounding_box (bool | BoundingBox, optional): Clip invalid/padded pixels when crafting the fits cube. When True an extra read of the input data is needed, but output cube is smaller. A BoundingBox may be supplied directly (see `get_common_bounding_box`) to force several cubes onto an identical pixel grid. Defaults to False.
         invalidate_zeros (bool, optionals): Set pixels whose values are exactly zero to NaNs. Defaults to False.
         float_length (Literal[16, 32, 64] | None, optional): The floating point precision in bits to use when creating the output cube. If None the size of the input data are used. Defaults to None.
 
+    Raises:
+        ShapeMismatchException: If the input images do not share a pixel grid
+
     Returns:
         tuple[fits.HDUList, u.Quantity]: The combined FITS cube and frequencies
     """
     # TODO: Check that all files have the same WCS
 
+    await check_matching_shapes_coro(file_list=file_list, max_workers=max_workers)
+
     file_specs, specs, missing_chan_idx = await parse_specs_coro(
         spec_file=spec_file,
         spec_list=spec_list,
@@ -769,10 +875,8 @@ async def combine_fits_coro(
         create_blanks=create_blanks,
         time_domain_mode=time_domain_mode,
     )
-    has_beams = "BMAJ" in fits.getheader(file_list[0])
+    has_beams = check_for_any_beam(file_list=file_list)
     if has_beams:
-        msg = f"Found beam in {file_list[0]} - assuming all files have beams"
-        logger.info(msg)
         beams = parse_beams(file_list)
         for beam in beams:
             logger.info(f"{beams[0]==beam=}")
@@ -784,7 +888,7 @@ async def combine_fits_coro(
             & np.isclose(beams[0].minor, beams.minor)
             & np.isclose(beams[0].pa, beams.pa)
         )
-        single_beam = np.all(same_beam)
+        single_beam = bool(np.all(same_beam))
 
         if single_beam:
             logger.info("All beams are the same")
@@ -799,19 +903,16 @@ async def combine_fits_coro(
     specs = specs[new_sort_idx]
     missing_chan_idx = missing_chan_idx[new_sort_idx]
 
-    # Get the bounding box, if requested
-    final_bounding_box = None
-    if bounding_box:
-        boxes_futures = [
-            get_bounding_box_for_fits_coro(
-                fits_path=fits_path, invalidate_zeros=invalidate_zeros
-            )
-            for fits_path in file_list
-        ]
-        boxes = await gather_with_limit(
-            max_workers, *boxes_futures, desc="Bounding boxes"
+    # Get the bounding box, if requested. A caller supplied box is used as is,
+    # so that separate cubes can be forced onto a common pixel grid.
+    final_bounding_box = bounding_box if isinstance(bounding_box, BoundingBox) else None
+    if bounding_box is True:
+        final_bounding_box = await get_common_bounding_box_coro(
+            file_list=file_list,
+            invalidate_zeros=invalidate_zeros,
+            max_workers=max_workers,
         )
-        final_bounding_box = extract_common_bounding_box(bounding_boxes=boxes)
+    if final_bounding_box is not None:
         logger.info(f"The final bounding box is: {final_bounding_box=}")
 
     # Initialize the data cube
@@ -835,7 +936,7 @@ async def combine_fits_coro(
 
     coros = []
     with out_cube.open("rb+") as file_handle:
-        for new_channel in new_channels:
+        for new_channel in range(len(new_channels)):
             is_missing = missing_chan_idx[new_channel]
             msg = f"Channel {new_channel} missing == {is_missing}"
             logger.info(msg)

{fitscube-2.3.2 → fitscube-2.4.0}/fitscube/exceptions.py

@@ -11,3 +11,11 @@ class TargetAxisMissingException(FITSCubeException):
 
 class ChannelMissingException(FITSCubeException):
     """Raised when a channel can not be accessed"""
+
+
+class ShapeMismatchException(FITSCubeException):
+    """Input images do not share a common pixel grid"""
+
+
+class AxisOrderException(FITSCubeException):
+    """The spectral axis is not the slowest-varying axis of the cube"""

{fitscube-2.3.2 → fitscube-2.4.0}/tests/conftest.py

@@ -3,8 +3,11 @@ from __future__ import annotations
 from pathlib import Path
 from shutil import unpack_archive
 
+import astropy.units as u
+import numpy as np
 import pytest
 from astropy.io import fits
+from astropy.time import Time
 
 EXAMPLE_HEADER = "SIMPLE  =                    T / conforms to FITS standard                      BITPIX  =                  -32 / array data type                                NAXIS   =                    4 / number of array dimensions                     NAXIS1  =                 6192                                                  NAXIS2  =                 6192                                                  NAXIS3  =                    1                                                  NAXIS4  =                   72                                                  EXTEND  =                    T                                                  BSCALE  =                  1.0                                                  BZERO   =                  0.0                                                  BUNIT   = 'JY/BEAM '                                                            BMAJ    =  0.00398184964207042                                                  BMIN    =  0.00332268385509243                                                  BPA     =     77.3858939868987                                                  EQUINOX =               2000.0                                                  LONPOLE =                180.0                                                  BTYPE   = 'Intensity'                                                           TELESCOP= 'ASKAP   '                                                            OBJECT  = 'EMU_1141-55'                                                         ORIGIN  = 'WSClean '                                                            CTYPE1  = 'RA---SIN'                                                            CRPIX1  =               3097.0                                                  CRVAL1  =     173.522555019647                                                  CDELT1  =            -0.000625                                                  CUNIT1  = 'deg     '                                                            CTYPE2  = 'DEC--SIN'                                                            CRPIX2  =               3097.0                                                  CRVAL2  =    -55.3190947400628                                                  CDELT2  =             0.000625                                                  CUNIT2  = 'deg     '                                                            CTYPE3  = 'STOKES  '                                                            CRPIX3  =                  1.0                                                  CRVAL3  =                  1.0                                                  CDELT3  =                  1.0                                                  CUNIT3  = ''                                                                    CTYPE4  = 'FREQ    '                                                            CRPIX4  =                    1                                                  CRVAL4  =     801490740.740741                                                  CDELT4  =            4000000.0                                                  CUNIT4  = 'Hz      '                                                            SPECSYS = 'TOPOCENT'                                                            DATE-OBS= '2023-01-08T15:36:40.9'                                               WSCDATAC= 'DATA    '                                                            WSCVDATE= '2022-10-21'                                                          WSCVERSI= '3.2     '                                                            WSCWEIGH= 'Briggs''(-0)'                                                        WSCENVIS=     1026544.24656423                                                  WSCFIELD=                  0.0                                                  WSCGAIN =                  0.1                                                  WSCGKRNL=                  7.0                                                  WSCIMGWG=     4052355.35920529                                                  WSCMAJOR=                  9.0                                                  WSCMGAIN=                  0.9                                                  WSCMINOR=              62860.0                                                  WSCNEGCM=                  1.0                                                  WSCNEGST=                  0.0                                                  WSCNITER=            5000000.0                                                  WSCNORMF=     4052355.35920529                                                  WSCNVIS =            7648518.0                                                  WSCNWLAY=                  1.0                                                  WSCTHRES=                  0.0                                                  WSCVWSUM=           30594072.0                                                  COMMENT   FITS (Flexible Image Transport System) format is defined in 'AstronomyCOMMENT   and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H HISTORY wsclean -abs-mem 200 -local-rms-window 20 -size 6192 6192 -local-rms -foHISTORY rce-mask-rounds 4 -auto-mask 8.0 -auto-threshold 3.0 -channels-out 72 -mHISTORY gain 0.9 -nmiter 10 -niter 5000000 -multiscale-scale-bias 0.8 -multiscalHISTORY e-scales 0,4,8,16,24,32,48,64,92,128,196,512,796,1025 -fit-spectral-pol HISTORY 4 -weight briggs -0 -data-column DATA -scale 2.25asec -gridder wgridder HISTORY -wgridder-accuracy 0.0001 -join-channels -minuv-l 50.0 -beam-fitting-sizHISTORY e 1.25 -deconvolution-channels 8 -parallel-gridding 18 -temp-dir /dev/shHISTORY m/gal16b.8974844 -pol i -save-source-list -name /dev/shm/gal16b.8974844/HISTORY SB47138.EMU_1141-55.beam19.i /scratch3/gal16b/emu_download/flint_jollytrHISTORY actor/47138/SB47138.EMU_1141-55.beam19.ms                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               END                                                                             "
 
@@ -94,3 +97,70 @@ def time_image_paths_withzeroborder(tmpdir) -> list[Path]:
             output_paths.append(image_output)
 
     return output_paths
+
+
+@pytest.fixture
+def even_specs() -> u.Quantity:
+    rng = np.random.default_rng()
+    # mjd 60000 to 60000.2
+    start = rng.integers(5184000000, 5184017280)
+    end = rng.integers(5184025920, 5184043200)
+    # start = rng.integers(0, 17280)
+    # end = rng.integers(25920, 43200)
+    num = rng.integers(6, 10)
+    # num=6
+    return np.linspace(start, end, num) * u.s
+
+
+@pytest.fixture
+def output_file():
+    yield Path("test.fits")
+    Path("test.fits").unlink()
+
+
+@pytest.fixture
+def file_list(even_specs: u.Quantity):
+    image = np.ones((1, 10, 10))
+    for i, spec in enumerate(even_specs):
+        header = fits.Header()
+        header["CRVAL3"] = spec.to(u.s).value
+        header["CDELT3"] = 9.98
+        header["CRPIX3"] = 1
+        header["CTYPE3"] = "TIME"
+        header["CUNIT3"] = "s"
+        header["DATE-OBS"] = Time(spec.to(u.d).value, format="mjd").isot
+        header["MJD-OBS"] = Time(spec.to(u.d).value, format="mjd").mjd
+        hdu = fits.PrimaryHDU(image * i, header=header)
+        hdu.writeto(f"plane_{i}.fits", overwrite=True)
+
+    yield [Path(f"plane_{i}.fits") for i in range(len(even_specs))]
+
+    for i in range(len(even_specs)):
+        Path(f"plane_{i}.fits").unlink()
+
+
+@pytest.fixture
+def file_list_onebeam(even_specs: u.Quantity):
+    """Same as above but one file with have a beam"""
+    image = np.ones((1, 10, 10))
+    for i, spec in enumerate(even_specs):
+        header = fits.Header()
+        header["CRVAL3"] = spec.to(u.s).value
+        header["CDELT3"] = 9.98
+        header["CRPIX3"] = 1
+        header["CTYPE3"] = "TIME"
+        header["CUNIT3"] = "s"
+        header["DATE-OBS"] = Time(spec.to(u.d).value, format="mjd").isot
+        header["MJD-OBS"] = Time(spec.to(u.d).value, format="mjd").mjd
+        if i == 3:
+            header["BMAJ"] = 1
+            header["BMIN"] = 1
+            header["BPA"] = 1
+
+        hdu = fits.PrimaryHDU(image * i, header=header)
+        hdu.writeto(f"plane_{i}.fits", overwrite=True)
+
+    yield [Path(f"plane_{i}.fits") for i in range(len(even_specs))]
+
+    for i in range(len(even_specs)):
+        Path(f"plane_{i}.fits").unlink()

fitscube-2.4.0/tests/test_combine.py

@@ -0,0 +1,44 @@
+"""Tests related to specific combine functionality"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+from astropy.io import fits
+from fitscube.combine_fits import check_for_any_beam, combine_fits
+
+
+def test_check_for_any_beams_no_beams(file_list) -> None:
+    """See if we can confirm is all beams are in fits files"""
+    # file_list returns fits files without beam information
+    assert not check_for_any_beam(file_list=file_list)
+
+
+def test_check_for_any_beam_real_images(time_image_paths) -> None:
+    """See if beam is in any of these images"""
+    assert check_for_any_beam(file_list=time_image_paths)
+
+
+def test_check_for_any_beam_one_beam(file_list_onebeam) -> None:
+    """See if beam is in any of these images. Only one of the files should have the beamn properties"""
+    assert check_for_any_beam(file_list=file_list_onebeam)
+
+
+def test_combine_beam_not_in_first_file(
+    file_list_onebeam: list[Path], output_file: Path
+) -> None:
+    """A beam only on the fourth input should still reach the output cube"""
+    combine_fits(
+        file_list=file_list_onebeam,
+        out_cube=output_file,
+        time_domain_mode=True,
+        overwrite=True,
+    )
+
+    with fits.open(output_file) as hdul:
+        assert hdul[1].name == "BEAMS"
+        bmaj = hdul[1].data["BMAJ"]
+        # Only plane 3 carries a beam; the rest are the NaN sentinel
+        assert np.isclose(bmaj[3], 3600.0)
+        assert np.all(bmaj[np.arange(len(bmaj)) != 3] < 1e-30)

fitscube-2.4.0/tests/test_combine_guards.py

@@ -0,0 +1,209 @@
+# Regression tests for the cube-scrambling and blank-channel bugs
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import astropy.units as u
+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.exceptions import AxisOrderException, ShapeMismatchException
+
+
+def make_plane(
+    path: Path,
+    spec: u.Quantity,
+    shape: tuple[int, ...] = (1, 1, 8, 8),
+    value: float = 1.0,
+    pol_outer: bool = False,
+) -> Path:
+    """Write a single-channel image with a FREQ axis at ``spec``.
+
+    By default the axes are (FREQ, STOKES, DEC, RA), the usual ASKAP ordering.
+    With ``pol_outer`` they are (STOKES, FREQ, DEC, RA), which puts a
+    non-degenerate STOKES axis above FREQ in the output cube.
+    """
+    header = fits.Header()
+    header["CTYPE1"] = "RA---SIN"
+    header["CRPIX1"] = 1.0
+    header["CRVAL1"] = 0.0
+    header["CDELT1"] = -1e-3
+    header["CUNIT1"] = "deg"
+    header["CTYPE2"] = "DEC--SIN"
+    header["CRPIX2"] = 1.0
+    header["CRVAL2"] = 0.0
+    header["CDELT2"] = 1e-3
+    header["CUNIT2"] = "deg"
+    spec_axis, pol_axis = (4, 3) if not pol_outer else (3, 4)
+    header[f"CTYPE{spec_axis}"] = "FREQ"
+    header[f"CRPIX{spec_axis}"] = 1.0
+    header[f"CRVAL{spec_axis}"] = spec.to(u.Hz).value
+    header[f"CDELT{spec_axis}"] = 1e6
+    header[f"CUNIT{spec_axis}"] = "Hz"
+    header[f"CTYPE{pol_axis}"] = "STOKES"
+    header[f"CRPIX{pol_axis}"] = 1.0
+    header[f"CRVAL{pol_axis}"] = 1.0
+    header[f"CDELT{pol_axis}"] = 1.0
+    fits.PrimaryHDU(np.full(shape, value, dtype=np.float32), header=header).writeto(
+        path, overwrite=True
+    )
+    return path
+
+
+@pytest.fixture
+def specs() -> u.Quantity:
+    return np.arange(4) * 1e6 * u.Hz + 1e9 * u.Hz
+
+
+@pytest.fixture
+def file_list(tmp_path: Path, specs: u.Quantity) -> list[Path]:
+    return [
+        make_plane(tmp_path / f"plane_{i}.fits", spec, value=float(i))
+        for i, spec in enumerate(specs)
+    ]
+
+
+def test_mismatched_shapes_raise(
+    tmp_path: Path, file_list: list[Path], specs: u.Quantity
+) -> None:
+    """Differing NAXIS1/NAXIS2 used to slide the planes against each other."""
+    odd_one_out = make_plane(
+        tmp_path / "plane_odd.fits", specs[-1] + 1e6 * u.Hz, shape=(1, 1, 6, 6)
+    )
+
+    with pytest.raises(ShapeMismatchException, match="plane_odd"):
+        combine_fits(
+            file_list=[*file_list, odd_one_out],
+            out_cube=tmp_path / "cube.fits",
+            overwrite=True,
+        )
+
+
+def test_check_matching_shapes(file_list: list[Path]) -> None:
+    assert check_matching_shapes(file_list=file_list) == (8, 8)
+
+
+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 = [
+        make_plane(tmp_path / f"pol_{i}.fits", spec, shape=(2, 1, 8, 8), pol_outer=True)
+        for i, spec in enumerate(specs)
+    ]
+
+    with pytest.raises(AxisOrderException, match="NAXIS4"):
+        combine_fits(
+            file_list=file_list, out_cube=tmp_path / "cube.fits", overwrite=True
+        )
+
+
+def test_small_cube_keeps_input_precision(
+    tmp_path: Path, file_list: list[Path]
+) -> None:
+    """The small-cube path used to promote the output to float64."""
+    out_cube = tmp_path / "cube.fits"
+    combine_fits(file_list=file_list, out_cube=out_cube, overwrite=True)
+
+    header = fits.getheader(out_cube)
+    assert header["BITPIX"] == -32
+    cube = fits.getdata(out_cube)
+    assert cube.dtype.itemsize == 4
+    assert cube.shape == (len(file_list), 1, 8, 8)
+    for chan in range(len(file_list)):
+        assert np.allclose(cube[chan], fits.getdata(file_list[chan]))
+
+
+def test_float_length_is_respected(tmp_path: Path, file_list: list[Path]) -> None:
+    out_cube = tmp_path / "cube.fits"
+    combine_fits(
+        file_list=file_list, out_cube=out_cube, overwrite=True, float_length=64
+    )
+
+    assert fits.getheader(out_cube)["BITPIX"] == -64
+    assert fits.getdata(out_cube).dtype.itemsize == 8
+
+
+def test_blank_channels_are_created(
+    tmp_path: Path, specs: u.Quantity, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """create_blanks used to hit `fits.getdata(..., memamp=False)`.
+
+    Some astropy versions swallow the unknown keyword, so reject it explicitly
+    here the way a strict astropy does.
+    """
+    real_getdata = fits.getdata
+
+    def strict_getdata(*args: Any, **kwargs: Any) -> Any:
+        unexpected = set(kwargs) - {
+            "filename",
+            "header",
+            "memmap",
+            "lazy_load_hdus",
+            "ext",
+        }
+        if unexpected:
+            msg = f"getdata() got unexpected keyword arguments {unexpected}"
+            raise TypeError(msg)
+        return real_getdata(*args, **kwargs)
+
+    monkeypatch.setattr(fits, "getdata", strict_getdata)
+
+    # Drop the second channel to leave a gap in the frequency grid
+    gapped = [specs[0], specs[2], specs[3]]
+    file_list = [
+        make_plane(tmp_path / f"gap_{i}.fits", spec, value=float(i))
+        for i, spec in enumerate(gapped)
+    ]
+
+    out_cube = tmp_path / "cube.fits"
+    out_specs = combine_fits(
+        file_list=file_list,
+        out_cube=out_cube,
+        create_blanks=True,
+        overwrite=True,
+    )
+
+    assert len(out_specs) == 4
+    cube = fits.getdata(out_cube)
+    assert np.isnan(cube[1]).all()
+    assert np.allclose(cube[0], 0.0)
+    assert np.allclose(cube[2], 1.0)
+    assert np.allclose(cube[3], 2.0)
+
+
+def test_bounding_box_can_be_supplied(tmp_path: Path, specs: u.Quantity) -> None:
+    """A caller-supplied box is used as is, so two cubes can share a grid."""
+    # Images blanked to different extents, as per-channel linmos mosaics are
+    images = []
+    weights = []
+    for i, spec in enumerate(specs):
+        image = make_plane(tmp_path / f"image_{i}.fits", spec, value=float(i))
+        with fits.open(image, mode="update") as hdu_list:
+            hdu_list[0].data[..., : i + 1, :] = np.nan
+        images.append(image)
+        weights.append(make_plane(tmp_path / f"weight_{i}.fits", spec, value=1.0))
+
+    common_box = get_common_bounding_box(file_list=images)
+    assert common_box.x_span == 8 - 1  # first row blanked in every image
+
+    image_cube = tmp_path / "image_cube.fits"
+    weight_cube = tmp_path / "weight_cube.fits"
+    for file_list, out_cube in ((images, image_cube), (weights, weight_cube)):
+        combine_fits(
+            file_list=file_list,
+            out_cube=out_cube,
+            overwrite=True,
+            bounding_box=common_box,
+        )
+
+    image_header = fits.getheader(image_cube)
+    weight_header = fits.getheader(weight_cube)
+    assert fits.getdata(image_cube).shape == fits.getdata(weight_cube).shape
+    for key in ("NAXIS1", "NAXIS2", "CRPIX1", "CRPIX2"):
+        assert image_header[key] == weight_header[key]
+    assert image_header["NAXIS2"] == common_box.x_span
+
+    # The weights alone would have given the full, untrimmed grid
+    assert get_common_bounding_box(file_list=weights).x_span == 8

{fitscube-2.3.2 → fitscube-2.4.0}/tests/test_times.py

@@ -6,50 +6,9 @@ import astropy.units as u
 import numpy as np
 import pytest
 from astropy.io import fits
-from astropy.time import Time
 from fitscube.combine_fits import combine_fits, parse_specs
 
 
-@pytest.fixture
-def even_specs() -> u.Quantity:
-    rng = np.random.default_rng()
-    # mjd 60000 to 60000.2
-    start = rng.integers(5184000000, 5184017280)
-    end = rng.integers(5184025920, 5184043200)
-    # start = rng.integers(0, 17280)
-    # end = rng.integers(25920, 43200)
-    num = rng.integers(6, 10)
-    # num=6
-    return np.linspace(start, end, num) * u.s
-
-
-@pytest.fixture
-def output_file():
-    yield Path("test.fits")
-    Path("test.fits").unlink()
-
-
-@pytest.fixture
-def file_list(even_specs: u.Quantity):
-    image = np.ones((1, 10, 10))
-    for i, spec in enumerate(even_specs):
-        header = fits.Header()
-        header["CRVAL3"] = spec.to(u.s).value
-        header["CDELT3"] = 9.98
-        header["CRPIX3"] = 1
-        header["CTYPE3"] = "TIME"
-        header["CUNIT3"] = "s"
-        header["DATE-OBS"] = Time(spec.to(u.d).value, format="mjd").isot
-        header["MJD-OBS"] = Time(spec.to(u.d).value, format="mjd").mjd
-        hdu = fits.PrimaryHDU(image * i, header=header)
-        hdu.writeto(f"plane_{i}.fits", overwrite=True)
-
-    yield [Path(f"plane_{i}.fits") for i in range(len(even_specs))]
-
-    for i in range(len(even_specs)):
-        Path(f"plane_{i}.fits").unlink()
-
-
 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)
     # assert np.array_equal(file_specs, even_specs)