dkist-processing-math 2.1.1__py3-none-any.whl

dkist_processing_math/__init__.py

@@ -0,0 +1,9 @@
+"""init."""
+from pkg_resources import DistributionNotFound
+from pkg_resources import get_distribution
+
+try:
+    __version__ = get_distribution(__name__).version
+except DistributionNotFound:
+    # package is not installed
+    __version__ = "unknown"

dkist_processing_math/arithmetic.py

@@ -0,0 +1,125 @@
+"""Arithmetic."""
+from typing import Generator
+from typing import Iterable
+from typing import Union
+
+import numpy as np
+from dkist_processing_common.models.fits_access import FitsAccessBase
+
+
+def subtract_array_from_arrays(
+    arrays: Union[Iterable[np.ndarray], np.ndarray],
+    array_to_subtract: np.ndarray,
+) -> Generator[np.ndarray, None, None]:
+    """
+    Subtract a single array from an iterable of arrays.
+
+    This will work if a single array is used in lieu of an iterable as well.
+
+    Parameters
+    ----------
+    arrays
+        The arrays from which to subtract
+    array_to_subtract
+        The array to be subtracted
+
+    Returns
+    -------
+    An generator of modified arrays
+
+    """
+    arrays = [arrays] if isinstance(arrays, np.ndarray) else arrays
+    for array in arrays:
+        if array.shape != array_to_subtract.shape:
+            raise ValueError(
+                f"All arrays must be the same shape. "
+                f"Shape of subtraction array = {array_to_subtract.shape} "
+                f"Shape of current array = {array.shape}"
+            )
+        yield array - array_to_subtract
+
+
+def subtract_array_from_fits_access(
+    access_objs: Union[Iterable[FitsAccessBase], FitsAccessBase], array_to_subtract: np.ndarray
+) -> Generator[FitsAccessBase, None, None]:
+    """
+    Subtract a single array from an iterable of FitsAccess objects.
+
+    This will work if a single object is used in lieu of an iterable as well. The objects themselves are modified in place.
+
+    Parameters
+    ----------
+    access_objs
+        The objects from which to subtract
+
+    array_to_subtract
+        The array to be subtracted
+
+    Returns
+    -------
+    An generator of modified FitsAccess objects
+
+    """
+    access_objs = [access_objs] if isinstance(access_objs, FitsAccessBase) else access_objs
+    for obj in access_objs:
+        obj.data = next(subtract_array_from_arrays(obj.data, array_to_subtract))
+        yield obj
+
+
+def divide_arrays_by_array(
+    arrays: Union[Iterable[np.ndarray], np.ndarray],
+    array_to_divide_by: np.ndarray,
+) -> Generator[np.ndarray, None, None]:
+    """
+    Divide an iterable of arrays by a single array.
+
+    This will work if a single array is used in lieu of an iterable as well.
+
+    Parameters
+    ----------
+    arrays
+        The arrays to be divided
+    array_to_divide_by
+        The array by which to divide
+
+    Returns
+    -------
+    A generator of modified arrays
+
+    """
+    arrays = [arrays] if isinstance(arrays, np.ndarray) else arrays
+    for array in arrays:
+        if array.shape != array_to_divide_by.shape:
+            raise ValueError(
+                f"All arrays must be the same shape. "
+                f"Shape of array to divide by = {array_to_divide_by.shape} "
+                f"Shape of current array = {array.shape}"
+            )
+        yield array / array_to_divide_by
+
+
+def divide_fits_access_by_array(
+    access_objs: Union[Iterable[FitsAccessBase], FitsAccessBase], array_to_divide_by: np.ndarray
+) -> Generator[FitsAccessBase, None, None]:
+    """
+    Divide an iterable of FitsAccess objects by a single array.
+
+    This will work if a single object is used in lieu of an iterable as well. The objects themselves are modified in place.
+
+    Parameters
+    ----------
+    access_objs
+        The FitsAccess objects to be divided
+
+    array_to_divide_by
+        The array by which to divide
+
+    Returns
+    -------
+    A generator of modified FitsAccess objects
+
+    """
+    access_objs = [access_objs] if isinstance(access_objs, FitsAccessBase) else access_objs
+    for obj in access_objs:
+        obj.data = next(divide_arrays_by_array(obj.data, array_to_divide_by))
+        yield obj

dkist_processing_math/feature.py

@@ -0,0 +1,62 @@
+"""Feature finding."""
+from typing import Callable
+from typing import Tuple
+
+import numpy
+import numpy as np
+import peakutils as pku
+from peakutils import gaussian_fit
+
+
+def find_px_angles(
+    hough_accumulator: numpy.ndarray,
+    theta: numpy.ndarray,
+    peak_func: Callable = gaussian_fit,
+    px_width: int = 10,
+    raise_error_on_failed_interpolation: bool = False,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Find the most significant angles in a Hough transform.
+
+    Peaks in the Hough transform are first found with a simple max filter and then refined via interpolation of the
+    surrounding peak.
+
+    Parameters
+    ----------
+    hough_accumulator
+        A 2D array representing a Hough accumulator
+
+    theta
+        A 1D array of the angle values corresponding to hough_accumulator
+
+    peak_func
+        Function that will be called to detect a unique peak in the x,y data. Must have args (x, y) and return x peak value.
+
+    px_width
+        The width, in pixels, around (+/-) the initial peak to apply peak_func for peak refinement
+
+    raise_error_on_failed_interpolation
+        If True, raise an error if the peak refinement minimization fails. Otherwise return the non-refined peak in this case.
+
+    Returns
+    -------
+    peak_theta
+        The most significant angles found
+
+    """
+    rss = np.sqrt(np.sum(hough_accumulator**2, axis=0))
+    # This min distance limits us to only finding the single most prominent angle
+    idx = pku.indexes(rss, min_dist=theta.size)
+    peak_theta = pku.interpolate(theta, rss, ind=idx, width=px_width, func=peak_func)
+
+    # If pku.interpolate fails to find a good fit it will return idx, which is not what we want.
+    # In this case we either...
+    if peak_theta == idx:
+        if raise_error_on_failed_interpolation:
+            # ...raise an Error
+            raise RuntimeError("Interpolation of peak failed")
+
+        # ...return the non-interpolated peak angle
+        peak_theta = theta[peak_theta]
+
+    return peak_theta

dkist_processing_math/linear_algebra.py

@@ -0,0 +1,109 @@
+"""Linear algebra functions."""
+import numpy as np
+
+
+def nd_left_matrix_multiply(*, vector_stack: np.ndarray, matrix_stack: np.ndarray) -> np.ndarray:
+    """
+    Left-multiply an arbitrarily dimensioned stack of vectors by a similarly dimensioned stack of matrices.
+
+    In math:
+
+        result = M @ v
+
+    where M is a matrix with dimensions ([n1, ...nn], D1, D2)
+    and v is a vector with dimensions ([n1, ...nn], D2).
+
+    The higher-order dimensions (n1, ...nn) can be anything (or nothing), but they must be the same for M and v.
+    A special case where either the matrix or vector has NO higher-order dimensions is also allowed; the result will be
+    the single matrix/vector broadcast over the higher-order dimensionality of the other element.
+
+    Processing inputs with different numbers of higher-order dummy dimensions (i.e., dimension of length 1), while
+    technically possible, is not supported because it would be unclear which input should set the output shape.
+
+    Parameters
+    ----------
+    vector_stack : np.ndarray
+        ([n1, ...nn], D2) ND stack of vectors with length D2
+
+    matrix_stack : np.ndarray
+        ([n1, ...nn], D1, D2) ND stack of matrices with shape (D1, D2)
+
+
+    Returns
+    -------
+    np.ndarray
+        ([n1, ...nn], D1) ND stack of vectors with length D1
+    """
+    _check_nd_dimensionality(matrix_stack=matrix_stack, vector_stack=vector_stack)
+
+    matrix_shape = matrix_stack.shape[-2:]
+    vector_size = vector_stack.shape[-1]
+    if matrix_shape[-1] != vector_size:
+        raise ValueError(
+            f"Cannot perform left-multiplication with shapes {matrix_shape} @ {vector_size}."
+        )
+
+    result = np.sum(matrix_stack * vector_stack[..., None, :], axis=-1)
+    return result
+
+
+def nd_right_matrix_multiply(*, vector_stack: np.ndarray, matrix_stack: np.ndarray) -> np.ndarray:
+    """
+    Right-multiply an arbitrarily dimensioned stack of vectors by a similarly dimensioned stack of matrices.
+
+    In math:
+
+        result = v @ M
+
+    where M is a matrix with dimensions ([n1, ...nn], D1, D2)
+    and v is a vector with dimensions ([n1, ...nn], D1).
+
+    The higher-order dimensions (n1, ...nn) can be anything (or nothing), but they must be the same for M and v.
+    A special case where either the matrix or vector has NO higher-order dimensions is also allowed; the result will be
+    the single matrix/vector broadcast over the higher-order dimensionality of the other element.
+
+    Processing inputs with different numbers of higher-order dummy dimensions (i.e., dimension of length 1), while
+    technically possible, is not supported because it would be unclear which input should set the output shape.
+
+    Parameters
+    ----------
+    vector_stack : np.ndarray
+        ([n1, ...nn], D2) ND stack of vectors with length D1
+
+    matrix_stack : np.ndarray
+        ([n1, ...nn], D1, D2) ND stack of matrices with shape (D1, D2)
+
+
+    Returns
+    -------
+    np.ndarray
+        ([n1, ...nn], D1) ND stack of vectors with length D2
+    """
+    _check_nd_dimensionality(matrix_stack=matrix_stack, vector_stack=vector_stack)
+
+    matrix_shape = matrix_stack.shape[-2:]
+    vector_size = vector_stack.shape[-1]
+    if matrix_shape[-2] != vector_size:
+        raise ValueError(
+            f"Cannot perform left-multiplication with shapes {vector_size} @ {matrix_shape}."
+        )
+
+    result = np.sum(matrix_stack * vector_stack[..., :, None], axis=-2)
+    return result
+
+
+def _check_nd_dimensionality(matrix_stack, vector_stack):
+    """
+    Check that the matrix and vector stacks have higher-order dimensions that can be broadcast together.
+
+    Enforces matrix stack shape[:-2] equals vector stack shape[:-1]. Raises a ValueError if the condition is not met.
+
+    A special case of a matrix or vector with no higher-order dimensions is allowed.
+    """
+    matrix_ND_shape = matrix_stack.shape[:-2]
+    vector_ND_shape = vector_stack.shape[:-1]
+    if matrix_ND_shape and vector_ND_shape and matrix_ND_shape != vector_ND_shape:
+        raise ValueError(
+            f"Inputs must have the same shape for all but the last dimensions. "
+            f"{matrix_ND_shape} != {vector_ND_shape}"
+        )

dkist_processing_math/statistics.py

@@ -0,0 +1,40 @@
+"""Statistics."""
+from typing import Iterable
+from typing import Union
+
+import numpy as np
+
+
+def average_numpy_arrays(arrays: Union[Iterable[np.ndarray], np.ndarray]) -> np.ndarray:
+    """
+    Given an iterable of numpy arrays, calculate the pixel-wise average and return it in a numpy array.
+
+    This will work for a single array as well, just in case...
+
+    Parameters
+    ----------
+    arrays
+        The arrays to be averaged
+
+    Returns
+    -------
+    The average of the input arrays
+
+    """
+    arrays = [arrays] if isinstance(arrays, np.ndarray) else arrays
+    count = 0  # This statement is here only to suppress an uninitialized variable warning
+    output = None
+    for count, array in enumerate(arrays):
+        if output is None:
+            output = np.array(array).astype(float)
+        else:
+            if array.shape != output.shape:
+                raise ValueError(
+                    f"All arrays must be the same shape. "
+                    f"Shape of initial array = {output.shape} "
+                    f"Shape of current array = {array.shape}"
+                )
+            output += array
+    if output is not None:
+        return output / (count + 1)
+    raise ValueError("data_arrays is empty")

dkist_processing_math/tests/conftest.py

@@ -0,0 +1,68 @@
+import numpy as np
+import pytest
+
+rng = np.random.default_rng()
+
+
+@pytest.fixture()
+def numpy_arrays():
+    """
+    Create an iterable of random 10 x 10 arrays
+
+    Returns
+    -------
+    List[np.ndarray]
+
+    """
+    arrays = [rng.standard_normal((10, 10)), rng.standard_normal((10, 10))]
+    return arrays
+
+
+@pytest.fixture()
+def numpy_array(numpy_arrays):
+    """
+    Create a single random 10 x 10 array
+
+    Returns
+    -------
+    np.ndarray
+
+    """
+    return numpy_arrays[0]
+
+
+@pytest.fixture()
+def numpy_arrays_wrong_shape():
+    """
+    Create an iterable of random arrays of differing sizes
+
+    Returns
+    -------
+    List[np.ndarray]
+
+    """
+    arrays = [rng.standard_normal((10, 10)), rng.standard_normal((10, 15))]
+    return arrays
+
+
+@pytest.fixture(params=["multiple", "single"])
+def multiple_test_arrays(request, numpy_arrays):
+    """
+    Create an input test array or list of test arrays
+
+    Parameters
+    ----------
+    request: Union['multiple, 'single']
+        indicates whether to return a single array or an iterable of arrays
+    numpy_arrays: List[np.ndarray]
+        the arrays from which the return value is selected
+
+    Returns
+    -------
+    Union[List[np.ndarray], np.ndarray]
+
+    """
+    if request.param == "multiple":
+        return numpy_arrays
+    else:
+        return numpy_arrays[0]

dkist_processing_math/tests/test_arithmetic.py

@@ -0,0 +1,128 @@
+from typing import Generator
+
+import numpy as np
+import pytest
+from astropy.io import fits
+from dkist_processing_common.models.fits_access import FitsAccessBase
+
+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
+from dkist_processing_math.arithmetic import subtract_array_from_fits_access
+
+
+@pytest.fixture(params=["multiple", "single"])
+def multiple_test_fits_access(request, numpy_arrays):
+
+    access_list = []
+    for i, array in enumerate(numpy_arrays):
+        hdu = fits.PrimaryHDU(data=array)
+        hdu.header["TEST"] = i
+        access_list.append(FitsAccessBase(hdu=hdu))
+    if request.param == "multiple":
+        return access_list
+    return access_list[0]
+
+
+def test_subtract_array_from_arrays(multiple_test_arrays, numpy_array):
+    """
+    Given: an iterable of numpy arrays that are all the same shape
+    When: subtracting a fixed array from each array in the iterable
+    Then: an Generator of subtracted arrays is returned
+    """
+    if isinstance(multiple_test_arrays, np.ndarray):
+        desired_shape = multiple_test_arrays.shape
+        desired_result = [multiple_test_arrays - numpy_array]
+    else:
+        desired_shape = multiple_test_arrays[0].shape
+        desired_result = multiple_test_arrays - numpy_array
+    result = subtract_array_from_arrays(multiple_test_arrays, numpy_array)
+    assert isinstance(result, Generator)
+    for result_array, test_array in zip(result, desired_result):
+        assert result_array.shape == desired_shape
+        assert result_array.dtype == np.result_type(test_array)
+        np.testing.assert_allclose(result_array, test_array)
+
+
+def test_subtract_array_from_fits_access(multiple_test_fits_access, numpy_array):
+    """
+    Given: an iterable of or single FitsAccess object(s) with data
+    When: subtracting an array from all input objects
+    Then: a generator of FitsAccess objects is returned with correctly subtracted data
+    """
+    if isinstance(multiple_test_fits_access, FitsAccessBase):
+        desired_result = [multiple_test_fits_access.data - numpy_array]
+        desired_header_val = [multiple_test_fits_access.header["TEST"]]
+    else:
+        desired_result = [i.data - numpy_array for i in multiple_test_fits_access]
+        desired_header_val = [i.header["TEST"] for i in multiple_test_fits_access]
+
+    result = subtract_array_from_fits_access(multiple_test_fits_access, numpy_array)
+    assert isinstance(result, Generator)
+
+    for result_obj, test_array, test_header_val in zip(result, desired_result, desired_header_val):
+        assert result_obj.data.dtype == np.result_type(test_array)
+        assert result_obj.header["TEST"] == test_header_val
+        np.testing.assert_allclose(result_obj.data, test_array)
+
+
+def test_subtract_array_from_arrays_wrong_shape(numpy_arrays_wrong_shape, numpy_array):
+    """
+    Given: an iterable of numpy arrays that are not all the same shape
+    When: subtracting arrays
+    Then: an error is raised as the shapes are required to be the same
+    """
+    with pytest.raises(ValueError):
+        list(subtract_array_from_arrays(numpy_arrays_wrong_shape, numpy_array))
+
+
+def test_divide_arrays_by_array(multiple_test_arrays, numpy_array):
+    """
+    Given: an iterable of numpy arrays that are all the same shape
+    When: dividing each array in the iterable by a fixed array
+    Then: an Generator of divided arrays is returned
+    """
+    if isinstance(multiple_test_arrays, np.ndarray):
+        desired_shape = multiple_test_arrays.shape
+        desired_result = [multiple_test_arrays / numpy_array]
+    else:
+        desired_shape = multiple_test_arrays[0].shape
+        desired_result = multiple_test_arrays / numpy_array
+    result = divide_arrays_by_array(multiple_test_arrays, numpy_array)
+    assert isinstance(result, Generator)
+    for result_array, test_array in zip(result, desired_result):
+        assert result_array.shape == desired_shape
+        assert result_array.dtype == np.result_type(test_array)
+        np.testing.assert_allclose(result_array, test_array)
+
+
+def test_divide_fits_access_by_array(multiple_test_fits_access, numpy_array):
+    """
+    Given: an iterable of or single FitsAccess object(s) with data
+    When: dividing an array from all input objects
+    Then: a generator of FitsAccess objects is returned with correctly subtracted data
+    """
+    if isinstance(multiple_test_fits_access, FitsAccessBase):
+        desired_result = [multiple_test_fits_access.data / numpy_array]
+        desired_header_val = [multiple_test_fits_access.header["TEST"]]
+    else:
+        desired_result = [i.data / numpy_array for i in multiple_test_fits_access]
+        desired_header_val = [i.header["TEST"] for i in multiple_test_fits_access]
+
+    result = divide_fits_access_by_array(multiple_test_fits_access, numpy_array)
+    assert isinstance(result, Generator)
+
+    for result_obj, test_array, test_header_val in zip(result, desired_result, desired_header_val):
+        assert result_obj.data.dtype == np.result_type(test_array)
+        assert result_obj.header["TEST"] == test_header_val
+        np.testing.assert_allclose(result_obj.data, test_array)
+
+
+def test_divide_arrays_by_array_wrong_shape(numpy_arrays_wrong_shape, numpy_array):
+    """
+    Given: an iterable of numpy arrays that are not all the same shape
+    When: dividing arrays
+    Then: an error is raised as the shapes are required to be the same
+    """
+    with pytest.raises(ValueError):
+        list(divide_arrays_by_array(numpy_arrays_wrong_shape, numpy_array))

dkist_processing_math/tests/test_feature.py

@@ -0,0 +1,76 @@
+import numpy as np
+import pytest
+
+from dkist_processing_math.feature import find_px_angles
+
+
+def test_find_px_angles():
+    """
+    Given: a single numpy array
+    When: finding the most significant angles in a hough transform
+    Then: return the correct peak angle
+    """
+
+    theta = np.linspace(-np.pi / 4, np.pi / 4, 1500)
+
+    def Gaussian(x, mu, sig):
+        return np.exp(-np.power(x - mu, 2.0) / (2 * np.power(sig, 2.0)))
+
+    mu = 0.1
+    sigma = 0.2
+    gaussian = Gaussian(theta, mu, sigma)
+
+    H = np.zeros((20, 1500)) + gaussian[None, :]
+    desired_peaktheta = np.array(mu)
+
+    result_peaktheta = find_px_angles(H, theta)
+    assert isinstance(result_peaktheta, np.ndarray)
+
+    np.testing.assert_array_almost_equal(result_peaktheta, desired_peaktheta)
+
+
+def always_fail_gaussian_fitter(*args):
+    """This is how we force a failure to fit.
+
+    Easier than trying to contrive a signal that fails to fit.
+    """
+    raise RuntimeError("Failing for a test")
+
+
+def test_find_px_angles_interpolation_failure():
+    """
+    Given: A signal that will cause a fitting error in peakutils
+    When: Trying to find the peak angle through interpolation
+    Then: The non-interpolated peak angle is returned
+    """
+    theta = np.linspace(-np.pi / 4, np.pi / 4, 1500)
+    signal = np.random.random(1500) * 10
+    peak_idx = 400
+    signal[peak_idx] = 100.0
+    H = np.zeros((20, 1500)) + signal[None, :]
+
+    desired_peaktheta = theta[peak_idx]
+    result_peaktheta = find_px_angles(H, theta, peak_func=always_fail_gaussian_fitter)
+
+    np.testing.assert_array_equal(desired_peaktheta, result_peaktheta)
+
+
+def test_find_px_angles_interpolation_failure_raise_error():
+    """
+    Given: A signal that will cause a fitting error in peakutils
+    When: Trying to find the peak angle through interpolation with the flag set to raise an error on interpolation failure
+    Then: An error is raised
+    """
+    theta = np.linspace(-np.pi / 4, np.pi / 4, 1500)
+    signal = np.random.random(1500) * 10
+    peak_idx = 400
+    signal[peak_idx] = 100.0
+    H = np.zeros((20, 1500)) + signal[None, :]
+
+    with pytest.raises(RuntimeError):
+        find_px_angles(
+            H,
+            theta,
+            peak_func=always_fail_gaussian_fitter,
+            raise_error_on_failed_interpolation=True,
+        )