dkist-processing-math 2.2.2__tar.gz → 3.0.0rc1__tar.gz

{dkist_processing_math-2.2.2 → dkist_processing_math-3.0.0rc1}/CHANGELOG.rst

@@ -1,3 +1,12 @@
+v2.2.3 (2026-06-15)
+===================
+
+Features
+--------
+
+- Add new method to find the closest datetime in a list to a target datetime. (`#26 <https://bitbucket.org/dkistdc/dkist-processing-math/pull-requests/26>`__)
+
+
 v2.2.2 (2026-04-16)
 ===================
 

{dkist_processing_math-2.2.2 → dkist_processing_math-3.0.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dkist-processing-math
-Version: 2.2.2
+Version: 3.0.0rc1
 Summary: Common math functionality used in the DKIST calibrations suite
 Author-email: NSO / AURA <dkistdc@nso.edu>
 License: BSD-3-Clause

dkist_processing_math-3.0.0rc1/changelog/27.feature.rst

@@ -0,0 +1 @@
+Add ``apply_affine_transform`` which applies a combined center-preserving rotation and shift to an iterable of 2D arrays in a single interpolation pass. The rotation is specified as a scalar ``angle`` in radians. Also add ``affine_inverse_transform_matrix`` for callers that need the underlying homogeneous-coordinates matrix directly.

dkist_processing_math-3.0.0rc1/changelog/27.removal.rst

@@ -0,0 +1 @@
+Remove ``affine_transform_arrays``, ``translate_arrays``, ``rotate_arrays_about_point``, ``scale_matrix``, ``rotation_matrix``, ``shear_matrix``, and ``translation_matrix`` from ``dkist_processing_math.transform``. These were superseded by ``apply_affine_transform`` (and, for callers that need the raw matrix, ``affine_inverse_transform_matrix``).

{dkist_processing_math-2.2.2 → dkist_processing_math-3.0.0rc1}/dkist_processing_math/arithmetic.py

@@ -1,5 +1,6 @@
 """Arithmetic."""
 
+from datetime import datetime
 from typing import Generator
 from typing import Iterable
 from typing import Union
@@ -124,3 +125,21 @@ def divide_fits_access_by_array(
     for obj in access_objs:
         obj.data = next(divide_arrays_by_array(obj.data, array_to_divide_by))
         yield obj
+
+
+def closest_datetime(
+    target_datetime: str | datetime, datetimes: list[str | datetime] | str | datetime
+) -> str | datetime:
+    """Find the closest datetime to a target datetime. Return type is of the same type as the datetimes list."""
+    if isinstance(target_datetime, str):
+        target_datetime = datetime.fromisoformat(target_datetime)
+    if isinstance(datetimes, str) or isinstance(datetimes, datetime):
+        datetimes = [datetimes]
+    converted_datetimes = [
+        datetime.fromisoformat(d) if isinstance(d, str) else d for d in datetimes
+    ]
+    closest_index, _ = min(
+        enumerate(converted_datetimes),
+        key=lambda dt: abs(dt[1] - target_datetime),
+    )
+    return datetimes[closest_index]

{dkist_processing_math-2.2.2 → dkist_processing_math-3.0.0rc1}/dkist_processing_math/tests/test_arithmetic.py

@@ -1,3 +1,4 @@
+from datetime import datetime
 from typing import Generator
 
 import numpy as np
@@ -5,6 +6,7 @@ import pytest
 from astropy.io import fits
 from dkist_processing_common.models.fits_access import FitsAccessBase
 
+from dkist_processing_math.arithmetic import closest_datetime
 from dkist_processing_math.arithmetic import divide_arrays_by_array
 from dkist_processing_math.arithmetic import divide_fits_access_by_array
 from dkist_processing_math.arithmetic import subtract_array_from_arrays
@@ -18,7 +20,7 @@ def multiple_test_fits_access(request, numpy_arrays):
     for i, array in enumerate(numpy_arrays):
         hdu = fits.PrimaryHDU(data=array)
         hdu.header["TEST"] = i
-        access_list.append(FitsAccessBase(hdu=hdu))
+        access_list.append(FitsAccessBase(header=hdu.header, data=array))
     if request.param == "multiple":
         return access_list
     return access_list[0]
@@ -126,3 +128,54 @@ def test_divide_arrays_by_array_wrong_shape(numpy_arrays_wrong_shape, numpy_arra
     """
     with pytest.raises(ValueError):
         list(divide_arrays_by_array(numpy_arrays_wrong_shape, numpy_array))
+
+
+@pytest.mark.parametrize(
+    "datetimes, expected_result",
+    [
+        pytest.param(
+            ["2025-12-31T00:00:00", "2026-01-07T00:00:00"],
+            "2025-12-31T00:00:00",
+            id="multiple solar gain ops",
+        ),
+        pytest.param("2025-12-31T00:00:00", "2025-12-31T00:00:00", id="single solar gain op"),
+    ],
+)
+def test_closest_datetime_with_strings(datetimes, expected_result):
+    """
+    Given: a target datetime and a list of string datetimes
+    When: running the closest_datetime method
+    Then: the closest datetime from the list of datetimes is returned
+    """
+    result = closest_datetime(
+        target_datetime="2026-01-01T00:00:00",
+        datetimes=datetimes,
+    )
+    assert result == expected_result
+
+
+@pytest.mark.parametrize(
+    "datetimes, expected_result",
+    [
+        pytest.param(
+            [
+                datetime(2025, 12, 31),
+                datetime(2026, 1, 7),
+            ],
+            datetime(2025, 12, 31),
+            id="multiple solar gain ops",
+        ),
+        pytest.param(datetime(2025, 12, 31), datetime(2025, 12, 31), id="single solar gain op"),
+    ],
+)
+def test_closest_datetime_with_datetimes(datetimes, expected_result):
+    """
+    Given: a target datetime and a list of datetimes
+    When: running the closest_datetime method
+    Then: the closest datetime from the list of datetimes is returned
+    """
+    result = closest_datetime(
+        target_datetime=datetime(2026, 1, 1),
+        datetimes=datetimes,
+    )
+    assert result == expected_result

dkist_processing_math-3.0.0rc1/dkist_processing_math/tests/test_transform.py

@@ -0,0 +1,452 @@
+import numpy as np
+import pytest
+from skimage import transform as transform
+
+from dkist_processing_math.transform import affine_inverse_transform_matrix
+from dkist_processing_math.transform import apply_affine_transform
+from dkist_processing_math.transform import bin_arrays
+from dkist_processing_math.transform import do_hough
+from dkist_processing_math.transform import make_binary
+from dkist_processing_math.transform.binning import resize_arrays
+from dkist_processing_math.transform.binning import resize_arrays_local_mean
+
+
+@pytest.fixture()
+def binned_arrays(numpy_arrays):
+    """
+    Create a list of binned arrays from numpy_arrays
+
+    Parameters
+    ----------
+    numpy_arrays: List[np.ndarray]
+        A list of arrays to be binned
+
+    Returns
+    -------
+    List[np.ndarray]
+        A list of 2x2 binned versions of the input arrays
+
+    """
+
+    temp_arrays = np.zeros((2, 2, 2), dtype=numpy_arrays[0].dtype)
+    for array, temp_array in zip(numpy_arrays, temp_arrays):
+        for row in range(temp_array.shape[1]):
+            for column in range(temp_array.shape[0]):
+                temp_array[column, row] = array[
+                    column * 5 : (column + 1) * 5, row * 5 : (row + 1) * 5
+                ].mean()
+    return temp_arrays
+
+
+@pytest.fixture()
+def binned_array(numpy_array, binned_arrays):
+    """
+    Create a binned array from numpy_array
+
+    Parameters
+    ----------
+    numpy_array: np.ndarray
+        The array to be binned
+
+    Returns
+    -------
+    np.ndarray
+        A 2x2 binned version of the input array
+
+    """
+    return binned_arrays[0]
+
+
+@pytest.fixture()
+def resized_arrays(numpy_arrays):
+    temp_arrays = np.zeros((2, 20, 100), dtype=numpy_arrays[0].dtype)
+    for array, temp_array in zip(numpy_arrays, temp_arrays):
+        temp_array[:, :] = transform.resize_local_mean(array, (20, 100), preserve_range=True)
+    return temp_arrays
+
+
+@pytest.fixture()
+def resized_array(resized_arrays):
+    return resized_arrays[0]
+
+
+def test_bin_arrays(numpy_arrays, binned_arrays):
+    """
+    Given: an iterable of numpy_arrays
+    When: binning an iterable of numpy_arrays
+    Then: an Iterator of binned versions of the input arrays is returned
+    """
+    results = bin_arrays(numpy_arrays, (5, 5))
+    for result, binned_array in zip(results, binned_arrays):
+        np.testing.assert_allclose(result, binned_array)
+
+
+def test_bin_arrays_single_array(numpy_array, binned_array):
+    """
+    Given: an single numpy_array
+    When: binning an iterable of numpy_arrays
+    Then: an Iterator containing the binned version of the input arrays is returned
+    """
+    result = next(bin_arrays(numpy_array, (5, 5)))
+    np.testing.assert_allclose(result, binned_array)
+
+
+def test_bin_arrays_bad_bin_factor(numpy_array):
+    """
+    Given: a single numpy array
+    When: binning an array using a bad binning factor
+    Then: an error is raised
+    """
+    with pytest.raises(ValueError):
+        next(bin_arrays(numpy_array, (3, 3)))
+
+
+def test_resize_arrays(numpy_arrays, resized_arrays):
+    """
+    Given: an iterable of numpy_arrays
+    When: resizing an iterable of numpy_arrays
+    Then: an Iterator of resized versions of the input arrays is returned
+    """
+    results = resize_arrays(numpy_arrays, (20, 100))
+    for result, resized_array in zip(results, resized_arrays):
+        np.testing.assert_allclose(result, resized_array)
+
+
+def test_resize_arrays_single_array(numpy_array, resized_array):
+    """
+    Given: a single numpy array
+    When: resizing that array
+    Then: an Iterator of resized versions of the input arrays is returned
+    """
+    result = next(resize_arrays(numpy_array, (20, 100)))
+    np.testing.assert_allclose(result, resized_array)
+
+
+def test_resize_arrays_local_mean(numpy_arrays, resized_arrays):
+    """
+    Given: an iterable of numpy_arrays
+    When: resizing an iterable of numpy_arrays
+    Then: an Iterator of resized versions of the input arrays is returned
+    """
+    results = resize_arrays_local_mean(numpy_arrays, (20, 100))
+    for result, resized_array in zip(results, resized_arrays):
+        np.testing.assert_allclose(result, resized_array)
+
+
+def test_resize_arrays_local_mean_single_array(numpy_array, resized_array):
+    """
+    Given: a single numpy array
+    When: resizing that array
+    Then: an Iterator of resized versions of the input arrays is returned
+    """
+    result = next(resize_arrays_local_mean(numpy_array, (20, 100)))
+    np.testing.assert_allclose(result, resized_array)
+
+
+@pytest.mark.parametrize(
+    "array_shape, shift, angle, order, expected_matrix",
+    [
+        pytest.param(
+            (100, 100),
+            np.array([0.0, 0.0]),
+            0.0,
+            "shift_then_rotate",
+            np.eye(3),
+            id="identity",
+        ),
+        pytest.param(
+            (100, 200),
+            np.array([0.0, 0.0]),
+            np.pi,
+            "shift_then_rotate",
+            np.array([[-1.0, 0.0, 99.0], [0.0, -1.0, 199.0], [0.0, 0.0, 1.0]]),
+            id="180_rotation_about_center",
+        ),
+        pytest.param(
+            (100, 100),
+            np.array([5.0, -3.0]),
+            0.0,
+            "shift_then_rotate",
+            np.array([[1.0, 0.0, -5.0], [0.0, 1.0, 3.0], [0.0, 0.0, 1.0]]),
+            id="pure_translation",
+        ),
+        pytest.param(
+            (100, 100),
+            np.array([0.0, 0.0]),
+            np.pi / 2,
+            "shift_then_rotate",
+            np.array([[0.0, 1.0, 0.0], [-1.0, 0.0, 99.0], [0.0, 0.0, 1.0]]),
+            id="90_deg_rotation",
+        ),
+    ],
+)
+def test_affine_inverse_transform_matrix_hand_derived(
+    array_shape, shift, angle, order, expected_matrix
+):
+    """
+    Given: 2D array shape / shift / angle / order combinations with easy-to-derive-by-hand expected matrices
+    When: building the homogeneous inverse transform matrix
+    Then: the result matches the hand-derived expectation
+    """
+    result = affine_inverse_transform_matrix(array_shape, shift, angle, order=order)
+    np.testing.assert_allclose(result, expected_matrix, atol=1e-10)
+
+
+def test_affine_inverse_transform_matrix_rejects_invalid_order():
+    """
+    Given: an `order` value that isn't one of the two recognized options
+    When: building the homogeneous inverse transform matrix
+    Then: a ValueError is raised, rather than silently falling back to some default behavior
+    """
+    with pytest.raises(ValueError, match="order must be"):
+        affine_inverse_transform_matrix(
+            (10, 10), np.array([0.0, 0.0]), 0.0, order="not_a_real_order"
+        )
+
+
+def test_affine_inverse_transform_matrix_requires_2d():
+    """
+    Given: an array_shape with more than 2 dimensions
+    When: building the homogeneous inverse transform matrix
+    Then: a ValueError is raised
+    """
+    with pytest.raises(ValueError, match="array_shape must be 2D"):
+        affine_inverse_transform_matrix((10, 10, 10), np.zeros(3), 0.3, order="shift_then_rotate")
+
+
+@pytest.mark.parametrize(
+    "shift",
+    [
+        pytest.param(5.0, id="scalar_shift"),
+        pytest.param(np.array([5.0]), id="length_one_shift"),
+        pytest.param(np.array([1.0, 2.0, 3.0]), id="wrong_length_shift"),
+    ],
+)
+def test_affine_inverse_transform_matrix_rejects_mismatched_shift(shift):
+    """
+    Given: a `shift` whose shape doesn't match `array_shape`'s dimensionality -- including scalar
+        and length-1 shifts, which would otherwise silently broadcast rather than raising
+    When: building the homogeneous inverse transform matrix for a 2D array_shape
+    Then: a ValueError is raised
+    """
+    with pytest.raises(ValueError, match="shift must have shape"):
+        affine_inverse_transform_matrix((10, 10), shift, 0.0, order="shift_then_rotate")
+
+
+def test_apply_affine_transform_identity():
+    """
+    Given: a zero shift and zero rotation
+    When: applying the correction
+    Then: the output array is numerically identical to the input
+    """
+    array = np.arange(100.0).reshape(10, 10)
+    result = next(
+        apply_affine_transform(array, np.array([0.0, 0.0]), 0.0, order="shift_then_rotate")
+    )
+    np.testing.assert_allclose(result, array, atol=1e-10)
+
+
+def test_apply_affine_transform_single_array_wrapped():
+    """
+    Given: a single ndarray (not wrapped in a list)
+    When: applying the correction
+    Then: it is accepted and the generator yields exactly one result
+    """
+    array = np.zeros((5, 5))
+    results = list(
+        apply_affine_transform(array, np.array([0.0, 0.0]), 0.0, order="shift_then_rotate")
+    )
+    assert len(results) == 1
+    assert results[0].shape == (5, 5)
+
+
+def test_apply_affine_transform_nonfinite_values_replaced():
+    """
+    Given: an input array containing NaN and ±inf
+    When: applying the correction
+    Then: the output is fully finite (NaN/inf do not survive interpolation)
+    """
+    array = np.ones((10, 10))
+    array[0, 0] = np.nan
+    array[0, 1] = np.inf
+    array[0, 2] = -np.inf
+    result = next(
+        apply_affine_transform(array, np.array([0.0, 0.0]), 0.0, order="shift_then_rotate")
+    )
+    assert np.isfinite(result).all()
+
+
+def test_apply_affine_transform_hand_derived_shift():
+    """
+    Given: a distinctive single-pixel array and a pure integer shift (no rotation)
+    When: applying the correction with shift_then_rotate
+    Then: the bright pixel lands exactly where hand-derived arithmetic says it should
+
+    With shift=[2, 3] and no rotation, a pixel at (row=1, col=1) moves to (row=3, col=4).
+    This directly tests that the sign convention is correct end-to-end -- that a positive
+    shift moves content in the positive direction -- with no ambiguity from interpolation.
+    """
+    array = np.zeros((10, 10))
+    array[1, 1] = 1.0
+    shift = np.array([2.0, 3.0])
+
+    result = next(apply_affine_transform(array, shift, 0.0, order="shift_then_rotate"))
+
+    assert result[3, 4] == pytest.approx(1.0)
+
+
+def test_apply_affine_transform_yields_one_per_input():
+    """
+    Given: a list of N arrays
+    When: applying the correction
+    Then: the generator yields exactly N arrays, each with the correct shape
+    """
+    arrays = [np.ones((8, 8)) * i for i in range(3)]
+    results = list(
+        apply_affine_transform(arrays, np.array([0.0, 0.0]), 0.0, order="shift_then_rotate")
+    )
+    assert len(results) == 3
+    assert all(r.shape == (8, 8) for r in results)
+
+
+def test_apply_affine_transform_hand_derived_rotation():
+    """
+    Given: a distinctive single-pixel array and a 90° CCW rotation (no shift)
+    When: applying the transform with shift_then_rotate
+    Then: the bright pixel lands exactly where hand-derived arithmetic says it should
+
+    With angle=π/2 and no shift, a pixel at (row=1, col=7) in a 10×10 array (center=(4.5, 4.5))
+    rotates CCW to (row=2, col=1). Derivation: the pull-back maps output (r', c') to input
+    (c', 9−r'), so output[2, 1] samples input[1, 7].
+    """
+    array = np.zeros((10, 10))
+    array[1, 7] = 1.0
+
+    result = next(
+        apply_affine_transform(array, np.array([0.0, 0.0]), np.pi / 2, order="shift_then_rotate")
+    )
+
+    assert result[2, 1] == pytest.approx(1.0)
+
+
+def test_apply_affine_transform_hand_derived_shift_and_rotate():
+    """
+    Given: a distinctive single-pixel array, a shift of [1, 0], and a 90° CCW rotation
+    When: applying shift_then_rotate
+    Then: the bright pixel lands exactly where hand-derived arithmetic says it should
+
+    Shift [1, 0] moves (1, 7) → (2, 7); 90° CCW about center (4.5, 4.5) then moves
+    (2, 7) → (2, 2). The pull-back for output (2, 2): after un-centering, applying CW
+    rotation, re-centering, and un-shifting gives input (1, 7).
+    """
+    array = np.zeros((10, 10))
+    array[1, 7] = 1.0
+
+    result = next(
+        apply_affine_transform(array, np.array([1.0, 0.0]), np.pi / 2, order="shift_then_rotate")
+    )
+
+    assert result[2, 2] == pytest.approx(1.0)
+
+
+def test_affine_inverse_transform_matrix_matches_numpy_inverse():
+    """
+    Given: a known shift and rotation angle
+    When: computing the inverse transform matrix
+    Then: the result matches np.linalg.inv of the hand-composed forward matrix
+
+    This verifies the matrix algebra is correct end-to-end, independently of any
+    hand-derived expected values.
+    """
+    shape = (11, 21)
+    shift = np.array([3.0, -5.0])
+    angle = np.pi / 4
+
+    cx, cy = (shape[0] - 1) / 2.0, (shape[1] - 1) / 2.0  # 5.0, 10.0
+    cos_a, sin_a = np.cos(angle), np.sin(angle)
+
+    # Hand-composed forward matrix for shift_then_rotate:
+    # T(center) @ R_fwd @ T(-center) @ T(shift)
+    R_fwd = np.array([[cos_a, -sin_a, 0.0], [sin_a, cos_a, 0.0], [0.0, 0.0, 1.0]])
+    T_cen = np.array([[1.0, 0.0, cx], [0.0, 1.0, cy], [0.0, 0.0, 1.0]])
+    T_neg_cen = np.array([[1.0, 0.0, -cx], [0.0, 1.0, -cy], [0.0, 0.0, 1.0]])
+    T_s = np.array([[1.0, 0.0, shift[0]], [0.0, 1.0, shift[1]], [0.0, 0.0, 1.0]])
+    forward = T_cen @ R_fwd @ T_neg_cen @ T_s
+
+    result = affine_inverse_transform_matrix(shape, shift, angle, order="shift_then_rotate")
+    np.testing.assert_allclose(result, np.linalg.inv(forward), atol=1e-10)
+
+
+def test_make_binary_image():
+    """
+    Given: a single numpy array
+    When: generating a binary image for values in the array below a threshold
+    Then: a correct binary array results from the generation
+    """
+    input_array = np.ones((10, 10), dtype=float)
+    input_array[:5, :] += 1.0
+    result = make_binary(input_array)  # Something ridiculous
+    assert isinstance(result, np.ndarray)
+
+    expected = np.ones((10, 10), dtype=int)
+    expected[:5, :] = 0
+    np.testing.assert_equal(result, expected)
+
+
+def test_make_binary_trigger_cutoff():
+    """
+    Given: a single numpy array
+    When: calling make_binary in such a way that the result will converge to all 0s or all 1s
+    Then: make_binary returns before a single value array is created
+    """
+    rng = np.random.default_rng()
+    input_array = rng.standard_normal((100, 100))
+    result = make_binary(input_array, numotsu=100)
+    frac = np.sum(result) / result.size
+    assert frac >= 1e-3
+
+
+def test_do_hough(numpy_array):
+    """
+    Given: a single numpy array
+    When: performing a hough line transformation
+    Then: return the correct hough space, array of angle values, and array of distance values
+    """
+    binary = make_binary(numpy_array)
+
+    # Rho and Theta ranges
+    thetas = np.linspace(-np.pi / 4, np.pi / 4, 1500)
+    width, height = binary.shape
+    diag_len = np.ceil(np.sqrt(width * width + height * height))  # max_dist
+    diag_len = int(diag_len)
+    num_rhos = 2 * diag_len + 1
+    rhos = np.linspace(-diag_len, diag_len, num_rhos)
+    # Cache some reusable values
+    cos_t = np.cos(thetas)
+    sin_t = np.sin(thetas)
+    num_thetas = len(thetas)
+    # Hough accumulator array of theta vs rho
+    accumulator = np.zeros((num_rhos, num_thetas), dtype=np.uint64)
+    y_idxs, x_idxs = np.nonzero(binary)  # (row, col) indexes to edges
+    for i in range(len(x_idxs)):
+        x = x_idxs[i]
+        y = y_idxs[i]
+        for t_idx in range(num_thetas):
+            # Calculate rho. diag_len is added for a positive index
+            rho = round(x * cos_t[t_idx] + y * sin_t[t_idx]) + diag_len
+            accumulator[rho, t_idx] += 1
+    desired_H = accumulator
+    desired_thetas = thetas
+    desired_rhos = rhos
+    assert isinstance(desired_H, np.ndarray)
+    assert isinstance(desired_thetas, np.ndarray)
+    assert isinstance(desired_rhos, np.ndarray)
+
+    result_H, result_theta, result_rho = do_hough(binary, theta_min=-np.pi / 4, theta_max=np.pi / 4)
+    assert isinstance(result_H, np.ndarray)
+    assert isinstance(result_theta, np.ndarray)
+    assert isinstance(result_rho, np.ndarray)
+
+    np.testing.assert_allclose(result_H, desired_H)
+    np.testing.assert_allclose(result_theta, desired_thetas)
+    np.testing.assert_allclose(result_rho, desired_rhos)

dkist_processing_math-3.0.0rc1/dkist_processing_math/transform/__init__.py

@@ -0,0 +1,15 @@
+"""init."""
+
+from .affine import affine_inverse_transform_matrix
+from .affine import apply_affine_transform
+from .binary import make_binary
+from .binning import bin_arrays
+from .hough import do_hough
+
+__all__ = [
+    "affine_inverse_transform_matrix",
+    "apply_affine_transform",
+    "make_binary",
+    "bin_arrays",
+    "do_hough",
+]