diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a9fa4c7..f10e6c5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,5 +1,3 @@ -default_language_version: - python: python3.13 ci: autofix_commit_msg: | [pre-commit.ci] auto fixes from pre-commit hooks diff --git a/README.rst b/README.rst index 2695e88..d7331c0 100644 --- a/README.rst +++ b/README.rst @@ -38,7 +38,25 @@ Tool for extracting signals with specific rotational symmetries from noisy data at scale -* LONGER DESCRIPTION HERE +.. long-description-start + +``diffpy.saf`` finds the orientation angles of signals with n-fold +rotational symmetry in 2D data, such as diffraction patterns. It builds +symmetry adapted filters (SAFs), angular filters with the same n-fold +symmetry as the signal, and finds the angle at which each image overlaps +most strongly with the filter. + +The package provides two main classes: + +* ``SymmetryAdaptedFilter`` builds a SAF and a matching angular mask for + any n-fold symmetry, angular resolution, and image shape. +* ``RatchetModel`` tracks the orientation angles of up to two signals + through a stack of images, such as a rotating sample. Each image is + searched starting from the angles found in the previous image, so the + angles accumulate as the sample rotates instead of wrapping back into + one symmetry period. + +.. long-description-end For more information about the diffpy.saf library, please consult our `online documentation `_. @@ -82,7 +100,7 @@ and run the following :: This package also provides command-line utilities. To check the software has been installed correctly, type :: - diffpy.saf --version + diffpy-saf --version You can also type the following command to verify the installation. :: @@ -91,7 +109,7 @@ You can also type the following command to verify the installation. :: To view the basic usage and available commands, type :: - diffpy.saf -h + diffpy-saf -h Getting Started --------------- diff --git a/docs/source/api/diffpy.saf.example_package.rst b/docs/source/api/diffpy.saf.example_package.rst deleted file mode 100644 index 89d1cf2..0000000 --- a/docs/source/api/diffpy.saf.example_package.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _example_package documentation: - -|title| -======= - -.. |title| replace:: diffpy.saf.example_package package - -.. automodule:: diffpy.saf.example_package - :members: - :undoc-members: - :show-inheritance: - -|foo| ------ - -.. |foo| replace:: diffpy.saf.example_package.foo module - -.. automodule:: diffpy.saf.example_package.foo - :members: - :undoc-members: - :show-inheritance: - -|bar| ------ - -.. |bar| replace:: diffpy.saf.example_package.bar module - -.. automodule:: diffpy.saf.example_package.foo - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/diffpy.saf.rst b/docs/source/api/diffpy.saf.rst index 8fdf9e6..68bfdf9 100644 --- a/docs/source/api/diffpy.saf.rst +++ b/docs/source/api/diffpy.saf.rst @@ -10,21 +10,25 @@ :undoc-members: :show-inheritance: -Subpackages ------------ - -.. toctree:: - diffpy.saf.example_package - Submodules ---------- -|module| --------- +|filters| +--------- + +.. |filters| replace:: diffpy.saf.filters module + +.. automodule:: diffpy.saf.filters + :members: + :undoc-members: + :show-inheritance: + +|ratchet_model| +--------------- -.. |module| replace:: diffpy.saf.example_submodule module +.. |ratchet_model| replace:: diffpy.saf.ratchet_model module -.. automodule:: diffpy.saf.example_submodule +.. automodule:: diffpy.saf.ratchet_model :members: :undoc-members: :show-inheritance: diff --git a/docs/source/conf.py b/docs/source/conf.py index ca00d1e..fa9dfdf 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,6 +15,7 @@ import sys import time +import tomllib from importlib.metadata import version from pathlib import Path @@ -24,6 +25,12 @@ except Exception: fullversion = "No version found. The correct version will appear in the released version." # noqa: E501 +# Read the package description from pyproject.toml, its single source. +pyproject_path = Path(__file__).resolve().parents[2] / "pyproject.toml" +with pyproject_path.open("rb") as pyproject_file: + description = tomllib.load(pyproject_file)["project"]["description"] +rst_epilog = f".. |description| replace:: {description}" + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use Path().resolve() to make it absolute, like shown here. # noqa: E501 @@ -300,7 +307,7 @@ "diffpy.saf Documentation", ab_authors, "diffpy.saf", - "One line description of project.", + description, "Miscellaneous", ), ] diff --git a/docs/source/index.rst b/docs/source/index.rst index aa3f962..6977f60 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,7 +4,11 @@ .. |title| replace:: diffpy.saf documentation -``diffpy.saf`` - Tool for extracting signals with specific rotational symmetries from noisy data at scale +``diffpy.saf`` - |description| + +.. include:: ../../README.rst + :start-after: .. long-description-start + :end-before: .. long-description-end | Software version |release| | Last updated |today|. diff --git a/news/migrate-source.rst b/news/migrate-source.rst new file mode 100644 index 0000000..6aca6f4 --- /dev/null +++ b/news/migrate-source.rst @@ -0,0 +1,24 @@ +**Added:** + +* ``SymmetryAdaptedFilter`` class in ``diffpy.saf.filters`` for building n-fold symmetry-adapted filters. +* ``RatchetModel`` class in ``diffpy.saf.ratchet_model`` for extracting orientation angles of symmetric signals in 2D data. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* Template ``dot_product`` function and its tests from ``diffpy.saf.functions``. + +**Fixed:** + +* + +**Security:** + +* diff --git a/pyproject.toml b/pyproject.toml index 09e11cc..a64a38d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -51,7 +51,7 @@ exclude = [] # exclude packages matching these glob patterns (empty by default) namespaces = false # to disable scanning PEP 420 namespaces (true by default) [project.scripts] -diffpy-saf = "diffpy.saf.app:main" +diffpy-saf = "diffpy.saf.saf_app:main" [tool.setuptools.dynamic] dependencies = {file = ["requirements/pip.txt"]} diff --git a/requirements/conda.txt b/requirements/conda.txt index 24ce15a..3229764 100644 --- a/requirements/conda.txt +++ b/requirements/conda.txt @@ -1 +1,3 @@ numpy +scipy +tqdm diff --git a/requirements/pip.txt b/requirements/pip.txt index 24ce15a..3229764 100644 --- a/requirements/pip.txt +++ b/requirements/pip.txt @@ -1 +1,3 @@ numpy +scipy +tqdm diff --git a/src/diffpy/saf/__init__.py b/src/diffpy/saf/__init__.py index 8f8f23b..a4df954 100644 --- a/src/diffpy/saf/__init__.py +++ b/src/diffpy/saf/__init__.py @@ -12,7 +12,8 @@ # See LICENSE.rst for license information. # ############################################################################## -"""Tool for extracting signals with specific rotational symmetries from noisy data at scale""" +"""Tool for extracting signals with specific rotational symmetries from +noisy data at scale.""" # package version from diffpy.saf.version import __version__ # noqa diff --git a/src/diffpy/saf/filters.py b/src/diffpy/saf/filters.py new file mode 100644 index 0000000..a918cbe --- /dev/null +++ b/src/diffpy/saf/filters.py @@ -0,0 +1,116 @@ +import numpy as np + + +class SymmetryAdaptedFilter: + """Build an angular filter with n-fold rotational symmetry. + + The filter has `n_folds` lobes radiating from `center`, centered on + the directions `phi_0 + m * 360 / n_folds` degrees. Angles are measured + from the +column axis toward the +row axis, which appears clockwise + when the image is shown with its origin in the upper left. + + Parameters + ---------- + resolution : float + The angular resolution, in degrees, that sets the width of each + lobe. + n_folds : int + The number of lobes, i.e. the order of the rotational symmetry. + imshape : tuple of int, optional + The shape of the filter as (rows, columns). Default is (128, 128). + phi_0 : float, optional + The rotation angle of the filter in degrees. Default is 0. + center : tuple of int, optional + The position of the filter center as (row, column). Defaults to + `(imshape[0] // 2, imshape[1] // 2)`. + """ + + def __init__( + self, + resolution, + n_folds, + imshape=(128, 128), + phi_0=0.0, + center=None, + ): + self.k = self._find_k_value(resolution, n_folds) + self.n_folds = n_folds + self.phi_0 = phi_0 + self.imshape = imshape + if center is None: + center = (imshape[0] // 2, imshape[1] // 2) + self.center = center + + @staticmethod + def _find_k_value(resolution, n_folds): + res_rad = np.deg2rad(resolution) + k = np.log(1 / 2) / (np.log(np.cos((n_folds / 4 * res_rad)) ** 2)) + return k + + def _get_phi_grid(self): + y_grid, x_grid = np.mgrid[0 : self.imshape[0], 0 : self.imshape[1]] + center_row, center_col = self.center + return np.arctan2(y_grid - center_row, x_grid - center_col) + + def generate_filter(self): + """Generate the symmetry adapted filter (SAF). + + Returns + ------- + saf : ndarray + The generated SAF of shape `imshape`. + """ + phi_grid = self._get_phi_grid() + phi_0_rad = np.deg2rad(self.phi_0) + saf = ( + np.abs(np.cos(0.5 * self.n_folds * (phi_grid - phi_0_rad))) + ** self.k + ) + return saf + + def generate_mask(self, width): + """Generate a mask that covers each lobe out to an angular + width. + + A pixel is in the mask when its direction from `center` lies within + `width` / 2 degrees of a lobe center, and a width of 0 masks + nothing. The SAF falls off steadily + from each lobe center to halfway between lobes, so the mask equals + the SAF thresholded at cos(`n_folds` * `width` / 4) ** `k`, but its + width does not depend on `resolution`. + + Parameters + ---------- + width : float + The full angular width of the mask around each lobe, in + degrees. It must be from 0, which masks nothing, to one period + of 360 / `n_folds` degrees, which covers every direction. + + Returns + ------- + mask : ndarray of bool + The mask of shape `imshape`, True on and near each lobe. + + Raises + ------ + ValueError + If `width` is not from 0 to 360 / `n_folds`. + """ + period = 360 / self.n_folds + if not 0 <= width <= period: + raise ValueError( + "The mask width must be from 0 to one period of 360 / " + f"n_folds = {period:g} degrees, but {width} was given.\n" + "Please choose a width from 0, for no masking, to " + f"{period:g} degrees." + ) + if width == 0: + mask = np.zeros(self.imshape, dtype=bool) + return mask + phi_grid = self._get_phi_grid() + phi_0_rad = np.deg2rad(self.phi_0) + lobe_profile = np.abs( + np.cos(0.5 * self.n_folds * (phi_grid - phi_0_rad)) + ) + mask = lobe_profile >= np.cos(np.deg2rad(self.n_folds * width / 4)) + return mask diff --git a/src/diffpy/saf/functions.py b/src/diffpy/saf/functions.py deleted file mode 100644 index e7e2c8e..0000000 --- a/src/diffpy/saf/functions.py +++ /dev/null @@ -1,31 +0,0 @@ -import numpy as np - - -def dot_product(a, b): - """Compute the dot product of two vectors of any size. - - Ensure that the inputs, a and b, are of the same size. - The supported types are "array_like" objects, which can - be converted to a NumPy array. Examples include lists and tuples. - - Parameters - ---------- - a : array_like - The first input vector. - b : array_like - The second input vector. - - Returns - ------- - float - The dot product of the two vectors. - - Examples - -------- - Compute the dot product of two lists: - >>> a = [1, 2, 3] - >>> b = [4, 5, 6] - >>> dot_product(a, b) - 32.0 - """ - return float(np.dot(a, b)) diff --git a/src/diffpy/saf/ratchet_model.py b/src/diffpy/saf/ratchet_model.py new file mode 100644 index 0000000..bc5f0d3 --- /dev/null +++ b/src/diffpy/saf/ratchet_model.py @@ -0,0 +1,610 @@ +import numpy as np +from scipy.signal import argrelextrema +from tqdm import tqdm + +from diffpy.saf.filters import SymmetryAdaptedFilter + + +class RatchetModel: + """Track the orientation of up to two signals through a stack of + images. + + The signals may have any n-fold rotational symmetry. For each image, the + orientation angle of the strongest signal (`phi1`) is found by + maximizing its overlap with a symmetry adapted filter (SAF). If the + curvature of the overlap shows a second signal, the first signal is + masked out and the orientation angle of the second signal (`phi2`) is + found the same way. Otherwise `phi2` follows `phi1`. The first image is + searched over one full period of 360 / `n_folds` degrees. Every later + image is searched only from `search_behind` degrees behind to + `search_ahead` degrees ahead of the previous image's angles, so the + angles accumulate as the sample rotates instead of wrapping back into + one period. + + Parameters + ---------- + n_folds : int + The order of the rotational symmetry of the signals. + resolution : float + The angular resolution of the SAF, in degrees. + search_ahead : float, optional + The distance, in degrees, searched ahead of the previous angle in + the direction of rotation given to `find_orientation_angles`. + Defaults to half a period, 180 / `n_folds` degrees. + search_behind : float, optional + The distance, in degrees, searched behind the previous angle, + against the direction of rotation given to + `find_orientation_angles`. Defaults to half a period, 180 / + `n_folds` degrees, so that with both defaults the search covers one + full period centered on the previous angle. + offset_step : float, optional + The spacing, in degrees, of the angles searched. If a whole number of + steps does not fit in one period of 360 / `n_folds` degrees, the + step is adjusted to the nearest spacing that does. Default is 0.5. + mask_width : float, optional + The full angular width, in degrees, masked out around each lobe of + the first signal when searching for the second. A width of 0 + masks nothing. Defaults to twice `resolution`. + center : tuple of int, optional + The position of the SAF center as (row, column). Defaults to the + center of the images. + + Attributes + ---------- + overlap1 : ndarray or None + The overlap of each image with the SAF at `phi1` from the most + recent call to `find_orientation_angles`, which is the maximum + overlap found for the strongest signal. None until + `find_orientation_angles` is called. + overlap2 : ndarray or None + The overlap of each image with the SAF at `phi2` from the most + recent call to `find_orientation_angles`, taken after masking out + the first signal whenever a second signal is found. It equals + `overlap1` wherever no second signal is found. None until + `find_orientation_angles` is called. + """ + + def __init__( + self, + n_folds, + resolution, + search_ahead=None, + search_behind=None, + offset_step=0.5, + mask_width=None, + center=None, + ): + self.n_folds = n_folds + self.resolution = resolution + half_period = 180 / n_folds + if search_ahead is None: + search_ahead = half_period + if search_behind is None: + search_behind = half_period + self.search_ahead = search_ahead + self.search_behind = search_behind + self.offset_step = offset_step + if mask_width is None: + mask_width = 2 * resolution + self.mask_width = mask_width + self.center = center + self.overlap1 = None + self.overlap2 = None + + def find_orientation_angles(self, images, direction="ccw", verbose=True): + """Find the orientation angles of up to two signals in each + image. + + The overlap behind each angle is saved in the `overlap1` and + `overlap2` attributes. + + Parameters + ---------- + images : ndarray + The images, either a single image of shape (rows, columns) or a + stack of shape (n_images, rows, columns). + direction : {"ccw", "cw"}, optional + The direction of rotation. "ccw" means the angles increase from + one image to the next, and "cw" means they decrease. It sets + which way `search_ahead` and `search_behind` reach. Default is + "ccw". + verbose : bool, optional + The switch for printing a progress bar over the images to + stderr. Default is True. + + Returns + ------- + phi1 : ndarray + The orientation angle of the strongest signal in each image, in + degrees. + phi2 : ndarray + The orientation angle of the second signal in each image, in + degrees. It equals `phi1` wherever no second signal is found. + + Raises + ------ + ValueError + If `images` is neither a single 2D image nor a 3D stack, or if + `direction` is not "ccw" or "cw". + """ + if direction not in ("ccw", "cw"): + raise ValueError( + f"The direction must be 'ccw' or 'cw', but {direction!r} was " + "given.\nPlease use 'ccw' if the angles increase from one " + "image to the next, or 'cw' if they decrease." + ) + images = self._get_image_stack(images) + self._generate_search_filters(images.shape[1:]) + phi1, phi2 = [], [] + overlap1, overlap2 = [], [] + previous_phi1, previous_phi2 = 0.0, 0.0 + progress_bar = tqdm( + images, desc="Finding orientation angles", disable=not verbose + ) + for image_index, image in enumerate(progress_bar): + is_first_image = image_index == 0 + overlap_curve1 = self._compute_overlap_optimized(image) + window1 = self._get_search_window( + previous_phi1, is_first_image, direction + ) + best_phi1 = self._find_best_phi(overlap_curve1, window1) + if self._has_second_signal(overlap_curve1): + masked_image = self._mask_signal(image, best_phi1) + overlap_curve2 = self._compute_overlap_optimized(masked_image) + window2 = self._get_search_window( + previous_phi2, is_first_image, direction + ) + else: + overlap_curve2 = overlap_curve1 + window2 = self._get_period_window(previous_phi2) + best_phi2 = self._find_best_phi(overlap_curve2, window2) + phi1.append(best_phi1) + phi2.append(best_phi2) + overlap1.append(self._get_overlap_at(overlap_curve1, best_phi1)) + overlap2.append(self._get_overlap_at(overlap_curve2, best_phi2)) + previous_phi1, previous_phi2 = best_phi1, best_phi2 + self.overlap1 = np.array(overlap1) + self.overlap2 = np.array(overlap2) + phi1 = np.array(phi1) + phi2 = np.array(phi2) + return phi1, phi2 + + def predict_direction(self, images, n_frames=10): + """Predict the direction of rotation from the first images of a + stack. + + The orientation angle of the strongest signal is found in each of + the first `n_frames` images. Instead of `search_ahead` and + `search_behind`, each image is searched over one full period + centered on the previous image's angle, so the angles are followed + in either direction and keep accumulating instead of wrapping back + into one period. A line is fit to the angles, and the direction is + `"ccw"` if its slope is positive and `"cw"` if it is negative. The + signal must rotate by less than half a period, 180 / `n_folds` + degrees, from one image to the next. + + Parameters + ---------- + images : ndarray + The stack of images, of shape (n_images, rows, columns). + n_frames : int, optional + The number of images, from the start of the stack, used for the + prediction. Default is 10. + + Returns + ------- + direction : {`"ccw"`, `"cw"`} + The predicted direction of rotation. + + Raises + ------ + ValueError + If `images` is neither a single 2D image nor a 3D stack, if + fewer than two images are used, or if the angle does not change + over the images used. + """ + images = self._get_image_stack(images)[:n_frames] + if len(images) < 2: + raise ValueError( + "At least two images are needed to predict the direction of " + f"rotation, but only {len(images)} was used.\nPlease pass a " + "stack of two or more images and set n_frames to 2 or more." + ) + self._generate_search_filters(images.shape[1:]) + phis = [] + previous_phi = 0.0 + for image in images: + overlap_curve = self._compute_overlap_optimized(image) + previous_phi = self._find_best_phi( + overlap_curve, self._get_period_window(previous_phi) + ) + phis.append(previous_phi) + slope = np.polyfit(np.arange(len(phis)), phis, 1)[0] + if np.isclose(slope, 0): + raise ValueError( + "The orientation angle did not change over the first " + f"{len(images)} images, so the direction of rotation could " + "not be predicted.\nPlease increase n_frames to include " + "images where the sample rotates, or set the direction " + "yourself." + ) + direction = "ccw" if slope > 0 else "cw" + return direction + + def compute_overlap(self, images, phis=None): + """Compute the overlap of each image with the SAF as a function + of orientation angle. + + The overlap at an angle is the sum over pixels of the image times + the SAF with its first lobe along that angle, so it peaks at the + orientation of each signal. + + Parameters + ---------- + images : ndarray + The images, either a single image of shape (rows, columns) or a + stack of shape (n_images, rows, columns). + phis : array-like, optional + The orientation angles, in degrees, at which to compute the + overlap. Defaults to one period, from 0 up to 360 / `n_folds` + degrees in steps of `offset_step`. + + Returns + ------- + phis : ndarray + The orientation angles, in degrees. + overlap : ndarray + The overlap of each image at each angle, of shape + (n_images, n_phis). + + Raises + ------ + ValueError + If `images` is neither a single 2D image nor a 3D stack. + """ + images = self._get_image_stack(images) + if phis is None: + phis = self._get_period_phis(self.offset_step) + phis = np.asarray(phis, dtype=float) + filter_stack = self._generate_filter_stack(images.shape[1:], phis) + overlap = np.tensordot(images, filter_stack, axes=([1, 2], [1, 2])) + return phis, overlap + + def run_smoke_screen(self, image): + """Find the orientation angles in one image and return the + intermediate results. + + The image is searched the same way `find_orientation_angles` + searches the first image of a stack, so the results show why `phi1` + and `phi2` were found where they were. Signals are detected where + the overlap curve bends downward, at local minima of its second + derivative with negative values. Each angle found is shown with the + mask `mask_width` degrees wide around each lobe of its SAF. + + Parameters + ---------- + image : ndarray + The image, of shape (rows, columns). + + Returns + ------- + smoke_screen : dict + The intermediate results, with the keys: + + - ``"phis"`` + The angles searched over one period, in degrees. + - ``"overlap_curve"`` + The overlap of the image with the SAF at each angle in + ``"phis"``. + - ``"overlap_second_derivative"`` + The second derivative of ``"overlap_curve"`` with respect + to the angle index, wrapping around the period. + - ``"signal_phis"`` + The angles in ``"phis"`` where signals are detected. + - ``"number_of_signals"`` + The number of signals detected. + - ``"overlap_contrast"`` + The range of ``"overlap_curve"`` divided by its maximum, + from 0 for an image with no preferred orientation to 1. + - ``"phi1"``, ``"phi2"`` + The orientation angles of the strongest and second signal, + in degrees. + - ``"saf_opt1"``, ``"saf_opt2"`` + The SAF at ``"phi1"`` and ``"phi2"``. + - ``"saf_opt1_mask"``, ``"saf_opt2_mask"`` + The pixels within `mask_width` / 2 degrees of a lobe of + ``"saf_opt1"`` and ``"saf_opt2"``, as boolean arrays. + - ``"saf_opt1_image"``, ``"saf_opt2_image"`` + The image times ``"saf_opt1_mask"`` and + ``"saf_opt2_mask"``. For the second signal, the + image has the first signal masked out whenever a second + signal is detected. + - ``"overlap1"``, ``"overlap2"`` + The overlap at ``"phi1"`` and ``"phi2"``, as saved by + `find_orientation_angles`. + - ``"signal_fraction1"``, ``"signal_fraction2"`` + The sums of ``"saf_opt1_image"`` and ``"saf_opt2_image"`` + divided by the sum of the image. + - ``"masked_image"`` + The image with the first signal masked out. + - ``"overlap_curve2"`` + The overlap curve searched for ``"phi2"``. It equals + ``"overlap_curve"`` unless a second signal is detected. + + Raises + ------ + ValueError + If `image` is not a single 2D image. + """ + image = np.asarray(image, dtype=float) + if image.ndim != 2: + raise ValueError( + "The smoke screen runs on a single image of shape (rows, " + f"columns), but an array of shape {image.shape} was given.\n" + "Please pass one image, for example images[0] from a stack." + ) + self._generate_search_filters(image.shape) + overlap_curve = self._compute_overlap_optimized(image) + second_derivative = self._compute_second_derivative(overlap_curve) + signal_indices = self._find_signal_indices(overlap_curve) + phi1 = self._find_best_phi(overlap_curve, self._get_period_window(0.0)) + masked_image = self._mask_signal(image, phi1) + if len(signal_indices) > 1: + image2 = masked_image + overlap_curve2 = self._compute_overlap_optimized(masked_image) + window2 = self._get_period_window(0.0) + else: + image2 = image + overlap_curve2 = overlap_curve + window2 = self._get_period_window(phi1) + phi2 = self._find_best_phi(overlap_curve2, window2) + smoke_screen = { + "phis": self._phis, + "overlap_curve": overlap_curve, + "overlap_second_derivative": second_derivative, + "signal_phis": self._phis[signal_indices], + "number_of_signals": len(signal_indices), + "overlap_contrast": np.ptp(overlap_curve) / np.max(overlap_curve), + "masked_image": masked_image, + "overlap_curve2": overlap_curve2, + } + for label, phi, search_image, search_curve in ( + ("1", phi1, image, overlap_curve), + ("2", phi2, image2, overlap_curve2), + ): + saf_opt = self._filter_stack[self._get_period_index(phi)] + saf_opt_mask = self._generate_signal_mask(image.shape, phi) + saf_opt_image = np.where(saf_opt_mask, search_image, 0) + smoke_screen[f"phi{label}"] = phi + smoke_screen[f"saf_opt{label}"] = saf_opt + smoke_screen[f"saf_opt{label}_mask"] = saf_opt_mask + smoke_screen[f"saf_opt{label}_image"] = saf_opt_image + smoke_screen[f"overlap{label}"] = self._get_overlap_at( + search_curve, phi + ) + smoke_screen[f"signal_fraction{label}"] = np.sum( + saf_opt_image + ) / np.sum(image) + return smoke_screen + + @staticmethod + def _get_image_stack(images): + images = np.asarray(images) + if images.ndim == 2: + images = images[np.newaxis] + if images.ndim != 3: + raise ValueError( + "The images must be a single image of shape (rows, columns) " + "or a stack of shape (n_images, rows, columns), but an array " + f"of shape {images.shape} was given.\nPlease pass a 2D image " + "or a 3D stack of images." + ) + return images + + def _get_period_phis(self, step): + """Return evenly spaced angles over one period, with the spacing + adjusted to the nearest one that fits a whole number of + times.""" + period = 360 / self.n_folds + n_steps = max(int(round(period / step)), 1) + period_phis = np.arange(n_steps) * period / n_steps + return period_phis + + def _generate_filter_stack(self, imshape, phis): + """Return the SAF at each angle in `phis`, stacked along axis + 0.""" + saf = SymmetryAdaptedFilter( + self.resolution, self.n_folds, imshape=imshape, center=self.center + ) + filters = [] + for phi in phis: + saf.phi_0 = phi + filters.append(saf.generate_filter()) + filter_stack = np.array(filters) + return filter_stack + + def _generate_search_filters(self, imshape): + """Build the SAFs searched by `find_orientation_angles`, once + per call, at every angle in one period spaced by + `offset_step`.""" + self._phis = self._get_period_phis(self.offset_step) + self._phi_step = 360 / self.n_folds / len(self._phis) + self._filter_stack = self._generate_filter_stack(imshape, self._phis) + + def _compute_overlap_optimized(self, image): + """Return the overlap of `image` at each angle in one period, + reusing the SAFs built by `_generate_search_filters` instead of + building them again like `compute_overlap` does.""" + overlap_curve = np.tensordot( + self._filter_stack, image, axes=([1, 2], [0, 1]) + ) + return overlap_curve + + def _get_overlap_at(self, overlap_curve, phis): + """Look up the overlap at any angles, using that the overlap + curve repeats every period.""" + overlaps = overlap_curve[self._get_period_index(phis)] + return overlaps + + def _get_period_index(self, phis): + """Return the position of each angle within one period of + `self._phis`.""" + steps_from_zero = np.round(np.asarray(phis) / self._phi_step) + period_index = steps_from_zero.astype(int) % len(self._phis) + return period_index + + def _find_best_phi(self, overlap_curve, window): + """Return the angle in `window` with the largest overlap.""" + overlaps = self._get_overlap_at(overlap_curve, window) + best_phi = window[np.argmax(overlaps)] + return best_phi + + def _get_search_window(self, previous_phi, is_first_image, direction): + """Return the angles to search, in degrees. + + The first image is searched over a full period around 0 degrees, + and every later image within `search_behind` and `search_ahead` + around `previous_phi`. + """ + if is_first_image: + search_window = self._get_period_window(0.0) + else: + search_window = self._get_tracking_window(previous_phi, direction) + return search_window + + def _get_period_window(self, center_phi): + """Return one period of angles centered on `center_phi`.""" + period = 360 / self.n_folds + period_window = self._get_grid_window( + center_phi - period / 2, center_phi + period / 2 + ) + return period_window + + def _get_tracking_window(self, previous_phi, direction): + """Return the angles from `search_behind` degrees behind to + `search_ahead` degrees ahead of `previous_phi`, in the direction + of rotation.""" + if direction == "ccw": + low = previous_phi - self.search_behind + high = previous_phi + self.search_ahead + else: + low = previous_phi - self.search_ahead + high = previous_phi + self.search_behind + tracking_window = self._get_grid_window(low, high) + return tracking_window + + def _get_grid_window(self, low, high): + """Return the angles from `low` up to, but not including, `high` + that lie on the grid of the SAF stack, so every angle has a + precomputed SAF.""" + first_step = np.ceil(round(low / self._phi_step, 9)) + last_step = np.ceil(round(high / self._phi_step, 9)) + grid_window = np.arange(first_step, last_step) * self._phi_step + return grid_window + + @staticmethod + def _has_second_signal(overlap_curve): + has_second_signal = ( + RatchetModel.count_number_of_signals(overlap_curve) > 1 + ) + return has_second_signal + + @staticmethod + def count_number_of_signals(overlap_curve): + """Count the signals in one period of the overlap curve. + + Each signal makes the overlap bend downward, so it shows up as a + local maximum of positive curvature, the negative second + derivative. Local maxima with negative curvature sit in the + valleys between signals and are not counted. The curve repeats + every period, so the second derivative and the maximum search + both wrap around its ends. + """ + number_of_signals = len( + RatchetModel._find_signal_indices(overlap_curve) + ) + return number_of_signals + + @staticmethod + def _find_signal_indices(overlap_curve): + """Return the indices of the local maxima of positive curvature + in one period of the overlap curve.""" + curvature = -RatchetModel._compute_second_derivative(overlap_curve) + maxima = argrelextrema(curvature, np.greater, mode="wrap")[0] + signal_indices = maxima[curvature[maxima] > 0] + return signal_indices + + @staticmethod + def _compute_second_derivative(overlap_curve): + """Return the second derivative of one period of the overlap + curve, wrapping around its ends.""" + second_derivative = ( + np.roll(overlap_curve, -1) + - 2 * overlap_curve + + np.roll(overlap_curve, 1) + ) + return second_derivative + + def mask_with_annulus(self, images, inner_radius, outer_radius): + """Zero the pixels of each image outside an annulus around + `center`. + + Pixels whose distance from `center` lies between `inner_radius` + and `outer_radius`, inclusive, keep their values and all other + pixels are set to 0. + + Parameters + ---------- + images : ndarray + The images, either a single image of shape (rows, columns) or a + stack of shape (n_images, rows, columns). + inner_radius : float + The inner radius of the annulus, in pixels. + outer_radius : float + The outer radius of the annulus, in pixels. + + Returns + ------- + masked_images : ndarray + The masked images, of shape (n_images, rows, columns). + + Raises + ------ + ValueError + If `images` is neither a single 2D image nor a 3D stack. + """ + images = self._get_image_stack(images) + n_rows, n_cols = images.shape[1:] + y_grid, x_grid = np.mgrid[0:n_rows, 0:n_cols] + center = self.center + if center is None: + center = (n_rows // 2, n_cols // 2) + center_row, center_col = center + distance_from_center = np.sqrt( + (y_grid - center_row) ** 2 + (x_grid - center_col) ** 2 + ) + annular_mask = (distance_from_center >= inner_radius) & ( + distance_from_center <= outer_radius + ) + masked_images = np.where(annular_mask, images, 0) + return masked_images + + def _generate_signal_mask(self, imshape, phi): + """Return the mask `mask_width` degrees wide around each lobe of + the SAF at `phi`.""" + saf = SymmetryAdaptedFilter( + self.resolution, + self.n_folds, + imshape=imshape, + phi_0=phi, + center=self.center, + ) + signal_mask = saf.generate_mask(self.mask_width) + return signal_mask + + def _mask_signal(self, image, phi): + """Zero the pixels of `image` within `mask_width` / 2 degrees of + a lobe of the SAF at `phi`.""" + signal_mask = self._generate_signal_mask(image.shape, phi) + masked_image = np.where(signal_mask, 0, image) + return masked_image diff --git a/src/diffpy/saf/saf_app.py b/src/diffpy/saf/saf_app.py index eb8ee32..9c8700e 100644 --- a/src/diffpy/saf/saf_app.py +++ b/src/diffpy/saf/saf_app.py @@ -1,13 +1,15 @@ import argparse +from importlib.metadata import metadata from diffpy.saf.version import __version__ # noqa def main(): + package_description = metadata("diffpy.saf")["Summary"] parser = argparse.ArgumentParser( prog="diffpy.saf", description=( - "Tool for extracting signals with specific rotational symmetries from noisy data at scale\n\n" + f"{package_description}\n\n" "For more information, visit: " "https://github.com/diffpy/diffpy.saf/" ), diff --git a/tests/conftest.py b/tests/conftest.py index e3b6313..2e26de1 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1,6 +1,7 @@ import json from pathlib import Path +import numpy as np import pytest @@ -17,3 +18,62 @@ def user_filesystem(tmp_path): json.dump(home_config_data, f) yield tmp_path + + +def generate_signal_image( + n_folds, + angles_deg, + amplitudes, + imshape=(64, 64), + radius=20, + sigma=1.5, +): + """Generate an image of n-fold signals. + + Each signal is drawn as `n_folds` Gaussian peaks spaced evenly on a ring + around the image center, with the first peak along the signal's + orientation angle. Angles are measured from the +column axis toward the + +row axis, so the true angle of every signal is known exactly. + + Parameters + ---------- + n_folds : int + The number of peaks in each signal. + angles_deg : list of float + The orientation angle of each signal, in degrees. + amplitudes : list of float + The peak height of each signal. + imshape : tuple of int, optional + The shape of the image as (rows, columns). Default is (64, 64). + radius : float, optional + The distance of the peaks from the image center, in pixels. Default + is 20. + sigma : float, optional + The standard deviation of each Gaussian peak, in pixels. Default is + 1.5. + + Returns + ------- + image : ndarray + The image, of shape (rows, columns). + """ + row_grid, col_grid = np.mgrid[0 : imshape[0], 0 : imshape[1]] + center_row, center_col = imshape[0] // 2, imshape[1] // 2 + image = np.zeros(imshape) + for signal_angle, amplitude in zip(angles_deg, amplitudes): + for peak_index in range(n_folds): + peak_angle = np.deg2rad(signal_angle + peak_index * 360 / n_folds) + peak_row = center_row + radius * np.sin(peak_angle) + peak_col = center_col + radius * np.cos(peak_angle) + squared_distance = (row_grid - peak_row) ** 2 + ( + col_grid - peak_col + ) ** 2 + image += amplitude * np.exp(-squared_distance / (2 * sigma**2)) + return image + + +@pytest.fixture +def make_signal_image(): + """Return `generate_signal_image`, a factory for images of n-fold + signals.""" + return generate_signal_image diff --git a/tests/test_filters.py b/tests/test_filters.py new file mode 100644 index 0000000..75fa622 --- /dev/null +++ b/tests/test_filters.py @@ -0,0 +1,148 @@ +import re + +import numpy as np +import pytest + +from diffpy.saf.filters import SymmetryAdaptedFilter + +# The filter has n_folds lobes, at phi_0 + m * 360 / n_folds degrees from +# the center, where angles run from the +column axis toward the +row axis. +# Each case reads an 11x11 filter at one pixel on its edge or corner: 1 +# means the pixel sits on a lobe, 0 means it sits halfway between two lobes. +# With the default center (5, 5), the edge and corner pixels lie along these +# directions: +# +# column 0 column 5 column 10 +# row 0 225 270 315 +# row 5 180 center 0 +# row 10 135 90 45 + + +@pytest.mark.parametrize( + "input_n_folds, input_phi_0, input_imshape, input_center, input_pixel, " + "expected_value", + [ + # C1: 6-fold filter with no rotation, pixel along 0 degrees. + # Expected: The pixel sits on a lobe. + (6, 0.0, (11, 11), None, (5, 10), 1.0), + # C2: 6-fold filter with no rotation, pixel along 90 degrees + # (halfway between the lobes at 60 and 120 degrees). + # Expected: The pixel sits between lobes. + (6, 0.0, (11, 11), None, (10, 5), 0.0), + # C3: 2-fold filter rotated by 45 degrees, pixel along 45 degrees. + # Expected: The pixel sits on a lobe, so phi_0 is read in degrees + # and rotates the lobes toward the +row axis. + (2, 45.0, (11, 11), None, (10, 10), 1.0), + # C4: 2-fold filter rotated by 45 degrees, pixel along 135 degrees + # (the mirror image of C3). + # Expected: The pixel sits between lobes, so the lobes are not + # rotated the opposite way. + (2, 45.0, (11, 11), None, (10, 0), 0.0), + # C5: 4-fold filter rotated by a full period (90 degrees), pixel + # along 0 degrees. + # Expected: The pixel sits on a lobe, since the lobes repeat every + # period. + (4, 90.0, (11, 11), None, (5, 10), 1.0), + # C6: Non-square 11x21 filter with the default center (5, 10), pixel + # along 0 degrees. + # Expected: The pixel sits on a lobe, so the default center is + # (imshape[0] // 2, imshape[1] // 2) as (row, column). + (6, 0.0, (11, 21), None, (5, 20), 1.0), + # C7: Explicit center at the top middle pixel (0, 5), 2-fold filter + # rotated by 45 degrees, pixel along 45 degrees from that center. + # Expected: The pixel sits on a lobe. + (2, 45.0, (11, 11), (0, 5), (5, 10), 1.0), + # C8: Explicit center at the top middle pixel (0, 5), 2-fold filter + # rotated by 45 degrees, pixel along 135 degrees from that center. + # Expected: The pixel sits between lobes. + (2, 45.0, (11, 11), (0, 5), (5, 0), 0.0), + ], +) +def test_symmetry_adapted_filter_lobe_directions( + input_n_folds, + input_phi_0, + input_imshape, + input_center, + input_pixel, + expected_value, +): + saf = SymmetryAdaptedFilter( + resolution=10, + n_folds=input_n_folds, + imshape=input_imshape, + phi_0=input_phi_0, + center=input_center, + ) + actual_filter = saf.generate_filter() + actual_value = actual_filter[input_pixel] + assert actual_filter.shape == input_imshape + assert actual_value == pytest.approx(expected_value, abs=1e-9) + + +# The mask is 1 at every pixel whose direction from the center lies within +# width / 2 degrees of a lobe center, and 0 everywhere else. The expected +# mask is built from each pixel's angular distance to the nearest lobe, +# where the lobes sit every 360 / n_folds degrees from phi_0. + + +@pytest.mark.parametrize( + "input_n_folds, input_phi_0, input_width", + [ + # C1: 6-fold mask with no rotation, 20 degrees wide. + # Expected: 1 within 10 degrees of each lobe, 0 elsewhere. + (6, 0.0, 20), + # C2: 2-fold mask rotated by 40 degrees, 8 degrees wide. + # Expected: 1 within 4 degrees of each lobe, 0 elsewhere. + (2, 40.0, 8), + # C3: 4-fold mask rotated by 10 degrees, 60 degrees wide. + # Expected: 1 within 30 degrees of each lobe, 0 elsewhere. + (4, 10.0, 60), + # C4: 6-fold mask 0 degrees wide. + # Expected: 0 everywhere, since no pixel is within 0 degrees. + (6, 0.0, 0), + ], +) +def test_generate_mask(input_n_folds, input_phi_0, input_width): + saf = SymmetryAdaptedFilter( + resolution=10, + n_folds=input_n_folds, + imshape=(51, 51), + phi_0=input_phi_0, + ) + row_grid, col_grid = np.mgrid[0:51, 0:51] + pixel_phis = np.rad2deg(np.arctan2(row_grid - 25, col_grid - 25)) + period = 360 / input_n_folds + distance_to_lobe = np.abs( + (pixel_phis - input_phi_0 + period / 2) % period - period / 2 + ) + expected_mask = distance_to_lobe < input_width / 2 + actual_mask = saf.generate_mask(input_width) + assert np.array_equal(actual_mask, expected_mask) + + +@pytest.mark.parametrize( + "input_width, expected_msg", + [ + # C1: A negative width of -5 degrees for a 6-fold filter. + # Expected: A ValueError gives the allowed range of widths. + ( + -5, + "The mask width must be from 0 to one period of 360 / n_folds " + "= 60 degrees, but -5 was given.\n" + "Please choose a width from 0, for no masking, to 60 degrees.", + ), + # C2: A width of 70 degrees for a 6-fold filter, more than one + # period. + # Expected: A ValueError gives the allowed range of widths. + ( + 70, + "The mask width must be from 0 to one period of 360 / n_folds " + "= 60 degrees, but 70 was given.\n" + "Please choose a width from 0, for no masking, to 60 degrees.", + ), + ], +) +def test_generate_mask_bad_width(input_width, expected_msg): + saf = SymmetryAdaptedFilter(resolution=10, n_folds=6, imshape=(11, 11)) + with pytest.raises(ValueError, match=re.escape(expected_msg)): + saf.generate_mask(input_width) diff --git a/tests/test_functions.py b/tests/test_functions.py deleted file mode 100644 index 166be25..0000000 --- a/tests/test_functions.py +++ /dev/null @@ -1,40 +0,0 @@ -import numpy as np -import pytest - -from diffpy.saf import functions # noqa - - -def test_dot_product_2D_list(): - a = [1, 2] - b = [3, 4] - expected = 11.0 - actual = functions.dot_product(a, b) - assert actual == expected - - -def test_dot_product_3D_list(): - a = [1, 2, 3] - b = [4, 5, 6] - expected = 32.0 - actual = functions.dot_product(a, b) - assert actual == expected - - -@pytest.mark.parametrize( - "a, b, expected", - [ - # Test whether the dot product function works with 2D and 3D vectors - # C1: lists, expect correct float output - ([1, 2], [3, 4], 11.0), - ([1, 2, 3], [4, 5, 6], 32.0), - # C2: tuples, expect correct float output - ((1, 2), (3, 4), 11.0), - ((1, 2, 3), (4, 5, 6), 32.0), - # C3: numpy arrays, expect correct float output - (np.array([1, 2]), np.array([3, 4]), 11.0), - (np.array([1, 2, 3]), np.array([4, 5, 6]), 32.0), - ], -) -def test_dot_product(a, b, expected): - actual = functions.dot_product(a, b) - assert actual == expected diff --git a/tests/test_ratchet_model.py b/tests/test_ratchet_model.py new file mode 100644 index 0000000..1cb1cc9 --- /dev/null +++ b/tests/test_ratchet_model.py @@ -0,0 +1,596 @@ +import re + +import numpy as np +import pytest + +from diffpy.saf.filters import SymmetryAdaptedFilter +from diffpy.saf.ratchet_model import RatchetModel + +# The ratchet model follows up to two n-fold signals through a stack of images. +# phi1 tracks the strongest signal. phi2 tracks the second signal when one is +# present, and otherwise follows phi1. After the first frame, each angle is +# searched only from search_behind degrees behind to search_ahead degrees ahead +# of its value in the previous frame, so the angles keep accumulating instead +# of wrapping back into one period of 360 / n_folds degrees. Every case rotates +# the signals by 8 degrees per frame, which is inside the 10 degree +# search_ahead but outside the 5 degree search_behind, so the signals can only +# be followed if the window opens in the given direction of rotation. + + +@pytest.mark.parametrize( + "input_n_folds, input_start_angles, input_amplitudes, input_step, " + "input_n_frames, input_direction, expected_phi1, expected_phi2", + [ + # C1: One 6-fold signal rotating toward increasing angles, tracked + # in the "ccw" direction. + # Expected: phi1 follows the signal, and phi2 matches phi1. + (6, [0], [1.0], 8, 6, "ccw", 8 * np.arange(6), 8 * np.arange(6)), + # C2: One 6-fold signal rotating toward decreasing angles, tracked + # in the "cw" direction. + # Expected: phi1 follows the signal, and phi2 matches phi1. + (6, [0], [1.0], -8, 6, "cw", -8 * np.arange(6), -8 * np.arange(6)), + # C3: One 6-fold signal rotating from 0 to 80 degrees, past its 60 + # degree period. + # Expected: The angles keep accumulating past 60 degrees instead of + # wrapping back to 0. + (6, [0], [1.0], 8, 11, "ccw", 8 * np.arange(11), 8 * np.arange(11)), + # C4: One 4-fold signal rotating from 0 to 96 degrees, past its 90 + # degree period. + # Expected: The angles keep accumulating past 90 degrees instead of + # wrapping back to 0. + (4, [0], [1.0], 8, 13, "ccw", 8 * np.arange(13), 8 * np.arange(13)), + # C5: One 3-fold signal rotating toward increasing angles. + # Expected: phi1 follows the signal, and phi2 matches phi1. + (3, [0], [1.0], 8, 6, "ccw", 8 * np.arange(6), 8 * np.arange(6)), + # C6: One 2-fold signal rotating toward increasing angles. + # Expected: phi1 follows the signal, and phi2 matches phi1. + (2, [0], [1.0], 8, 6, "ccw", 8 * np.arange(6), 8 * np.arange(6)), + # C7: Two 6-fold signals 25 degrees apart rotating together, with + # the signal at 0 degrees the stronger of the two. + # Expected: phi1 follows the stronger signal and phi2 follows the + # weaker signal. + ( + 6, + [0, 25], + [1.0, 0.6], + 8, + 6, + "ccw", + 8 * np.arange(6), + 25 + 8 * np.arange(6), + ), + # C8: Two 4-fold signals 40 degrees apart rotating together, with + # the signal at 0 degrees the stronger of the two. + # Expected: phi1 follows the stronger signal and phi2 follows the + # weaker signal. + ( + 4, + [0, 40], + [1.0, 0.6], + 8, + 6, + "ccw", + 8 * np.arange(6), + 40 + 8 * np.arange(6), + ), + ], +) +def test_find_orientation_angles( + make_signal_image, + input_n_folds, + input_start_angles, + input_amplitudes, + input_step, + input_n_frames, + input_direction, + expected_phi1, + expected_phi2, +): + input_images = np.array( + [ + make_signal_image( + input_n_folds, + np.add(input_start_angles, frame_index * input_step), + input_amplitudes, + ) + for frame_index in range(input_n_frames) + ] + ) + model = RatchetModel( + n_folds=input_n_folds, + resolution=10, + search_ahead=10, + search_behind=5, + ) + actual_phi1, actual_phi2 = model.find_orientation_angles( + input_images, direction=input_direction + ) + assert actual_phi1 == pytest.approx(expected_phi1, abs=1e-6) + assert actual_phi2 == pytest.approx(expected_phi2, abs=1e-6) + + +# Each of search_ahead and search_behind not given defaults to half a period, +# 180 / n_folds degrees, so together they cover one full period centered on the +# previous angle. The signals can then be followed in either direction, +# whatever direction is passed to find_orientation_angles, as long as they +# rotate by less than half a period per frame. + + +@pytest.mark.parametrize( + "input_n_folds, input_search_distances, expected_search_ahead, " + "expected_search_behind", + [ + # C1: A 6-fold model with neither search distance given. + # Expected: Both search distances are 30 degrees, half the 60 degree + # period. + (6, {}, 30, 30), + # C2: A 4-fold model with neither search distance given. + # Expected: Both search distances are 45 degrees, half the 90 degree + # period. + (4, {}, 45, 45), + # C3: A 6-fold model with only search_ahead given. + # Expected: search_ahead is kept, and search_behind is 30 degrees. + (6, {"search_ahead": 10}, 10, 30), + # C4: A 6-fold model with only search_behind given. + # Expected: search_behind is kept, and search_ahead is 30 degrees. + (6, {"search_behind": 5}, 30, 5), + # C5: A 6-fold model with both search distances given. + # Expected: Both search distances are kept. + (6, {"search_ahead": 10, "search_behind": 5}, 10, 5), + ], +) +def test_ratchet_model_default_search_distances( + input_n_folds, + input_search_distances, + expected_search_ahead, + expected_search_behind, +): + model = RatchetModel( + n_folds=input_n_folds, resolution=10, **input_search_distances + ) + actual_search_ahead = model.search_ahead + actual_search_behind = model.search_behind + assert actual_search_ahead == pytest.approx(expected_search_ahead) + assert actual_search_behind == pytest.approx(expected_search_behind) + + +@pytest.mark.parametrize( + "input_n_folds, input_step, input_n_frames, expected_phi1", + [ + # C1: One 6-fold signal rotating toward increasing angles by 8 + # degrees per frame, past its 60 degree period. + # Expected: phi1 follows the signal and keeps accumulating past 60 + # degrees. + (6, 8, 11, 8 * np.arange(11)), + # C2: One 6-fold signal rotating toward decreasing angles by 8 + # degrees per frame, while the direction is left at its default + # "ccw". + # Expected: phi1 still follows the signal, since the default window + # reaches equally far in both directions. + (6, -8, 11, -8 * np.arange(11)), + # C3: One 4-fold signal rotating by 20 degrees per frame, within + # half its 90 degree period. + # Expected: phi1 follows the signal. + (4, 20, 6, 20 * np.arange(6)), + ], +) +def test_find_orientation_angles_default_search_distances( + make_signal_image, input_n_folds, input_step, input_n_frames, expected_phi1 +): + input_images = np.array( + [ + make_signal_image(input_n_folds, [frame_index * input_step], [1.0]) + for frame_index in range(input_n_frames) + ] + ) + model = RatchetModel(n_folds=input_n_folds, resolution=10) + actual_phi1, _ = model.find_orientation_angles(input_images) + assert actual_phi1 == pytest.approx(expected_phi1, abs=1e-6) + + +# A single 2D image is treated as a stack of one image, so the angles are +# returned as arrays of length one. + + +@pytest.mark.parametrize( + "input_n_folds, input_start_angles, input_amplitudes, expected_phi1, " + "expected_phi2", + [ + # C1: A single image of one 6-fold signal at 10 degrees. + # Expected: phi1 and phi2 are both [10]. + (6, [10], [1.0], [10], [10]), + # C2: A single image of two 4-fold signals at 0 and 40 degrees, + # with the signal at 0 degrees the stronger of the two. + # Expected: phi1 is [0] and phi2 is [40]. + (4, [0, 40], [1.0, 0.6], [0], [40]), + ], +) +def test_find_orientation_angles_single_image( + make_signal_image, + input_n_folds, + input_start_angles, + input_amplitudes, + expected_phi1, + expected_phi2, +): + input_image = make_signal_image( + input_n_folds, input_start_angles, input_amplitudes + ) + model = RatchetModel( + n_folds=input_n_folds, + resolution=10, + search_ahead=10, + search_behind=5, + ) + actual_phi1, actual_phi2 = model.find_orientation_angles(input_image) + assert actual_phi1 == pytest.approx(expected_phi1, abs=1e-6) + assert actual_phi2 == pytest.approx(expected_phi2, abs=1e-6) + + +# The direction of rotation is predicted from the first n_frames images of a +# stack. Each image is searched over one full period centered on the previous +# angle, so the angles are followed in either direction without search_ahead +# and search_behind and keep accumulating past one period of 360 / n_folds +# degrees. A line is fit to the angles of the strongest signal, and a positive +# slope means "ccw" while a negative slope means "cw". + + +@pytest.mark.parametrize( + "input_n_folds, input_angles, input_n_frames, expected_direction", + [ + # C1: One 6-fold signal rotating toward increasing angles by 8 + # degrees per frame. + # Expected: The direction is "ccw". + (6, 8 * np.arange(10), 10, "ccw"), + # C2: One 6-fold signal rotating toward decreasing angles by 8 + # degrees per frame. + # Expected: The direction is "cw". + (6, -8 * np.arange(10), 10, "cw"), + # C3: One 4-fold signal rotating toward decreasing angles by 15 + # degrees per frame. + # Expected: The direction is "cw". + (4, -15 * np.arange(10), 10, "cw"), + # C4: One 6-fold signal rotating by 20 degrees per frame, beyond any + # usual search distance but within half its 60 degree period. + # Expected: The direction is "ccw". + (6, 20 * np.arange(10), 10, "ccw"), + # C5: One 6-fold signal rotating from 0 to 152 degrees, well past + # its 60 degree period, with only the default first 10 frames used. + # Expected: The angles keep accumulating instead of wrapping back + # to 0, and the direction is "ccw". + (6, 8 * np.arange(20), None, "ccw"), + # C6: One 6-fold signal that rotates toward increasing angles for 5 + # frames and then toward decreasing angles, with only the first 5 + # frames used. + # Expected: The later frames are ignored, and the direction is + # "ccw". + (6, [0, 8, 16, 24, 32, 24, 16, 8, 0, -8], 5, "ccw"), + # C7: A stack of only 2 frames, shorter than the default 10. + # Expected: Both frames are used, and the direction is "cw". + (6, [0, -8], None, "cw"), + ], +) +def test_predict_direction( + make_signal_image, + input_n_folds, + input_angles, + input_n_frames, + expected_direction, +): + input_images = np.array( + [ + make_signal_image(input_n_folds, [angle], [1.0]) + for angle in input_angles + ] + ) + model = RatchetModel( + n_folds=input_n_folds, + resolution=10, + search_ahead=10, + search_behind=5, + ) + if input_n_frames is None: + actual_direction = model.predict_direction(input_images) + else: + actual_direction = model.predict_direction( + input_images, n_frames=input_n_frames + ) + assert actual_direction == expected_direction + + +@pytest.mark.parametrize( + "input_angles, input_n_frames, expected_msg", + [ + # C1: A single image, so there is no change in angle to fit. + # Expected: A ValueError explains that at least two images are + # needed. + ( + [0], + 10, + "At least two images are needed to predict the direction of " + "rotation, but only 1 was used.\n" + "Please pass a stack of two or more images and set n_frames to " + "2 or more.", + ), + # C2: A stack of images with n_frames set to 1. + # Expected: A ValueError explains that at least two images are + # needed. + ( + [0, 8, 16], + 1, + "At least two images are needed to predict the direction of " + "rotation, but only 1 was used.\n" + "Please pass a stack of two or more images and set n_frames to " + "2 or more.", + ), + # C3: A signal that does not rotate. + # Expected: A ValueError explains that the angle did not change. + ( + [10, 10, 10, 10], + 10, + "The orientation angle did not change over the first 4 images, " + "so the direction of rotation could not be predicted.\n" + "Please increase n_frames to include images where the sample " + "rotates, or set the direction yourself.", + ), + ], +) +def test_predict_direction_bad_input( + make_signal_image, input_angles, input_n_frames, expected_msg +): + input_images = np.array( + [make_signal_image(6, [angle], [1.0]) for angle in input_angles] + ) + model = RatchetModel( + n_folds=6, resolution=10, search_ahead=10, search_behind=5 + ) + with pytest.raises(ValueError, match=re.escape(expected_msg)): + model.predict_direction(input_images, n_frames=input_n_frames) + + +# The overlap at an orientation angle is the sum over pixels of the image +# times the SAF with its first lobe along that angle, so for each image it +# peaks at the orientation of the signal. By default it is computed over one +# period, from 0 up to 360 / n_folds degrees in steps of offset_step, but any +# angles can be passed instead, including angles outside one period. + + +@pytest.mark.parametrize( + "input_n_folds, input_start_angles, input_step, input_n_frames, " + "input_phis, expected_phis, expected_peak_phis", + [ + # C1: One image of a 6-fold signal at 10 degrees, default angles. + # Expected: The overlap covers 0 to 60 degrees in 0.5 degree steps + # and peaks at 10 degrees. + (6, [10], 0, 1, None, np.arange(0, 60, 0.5), [10]), + # C2: The same image with angles from -20 to 40 degrees in 1 degree + # steps. + # Expected: The overlap is computed at the given angles and peaks at + # 10 degrees. + (6, [10], 0, 1, np.arange(-20, 40, 1), np.arange(-20, 40, 1), [10]), + # C3: The same image with angles from 40 to 100 degrees, outside + # the first period. + # Expected: The overlap peaks at 70 degrees, one period after the + # signal at 10 degrees. + (6, [10], 0, 1, np.arange(40, 100, 1), np.arange(40, 100, 1), [70]), + # C4: A stack of three images of a 4-fold signal rotating by 8 + # degrees per image, default angles. + # Expected: One overlap curve per image, covering 0 to 90 degrees in + # 0.5 degree steps, each peaking at that image's orientation. + (4, [0], 8, 3, None, np.arange(0, 90, 0.5), [0, 8, 16]), + ], +) +def test_compute_overlap( + make_signal_image, + input_n_folds, + input_start_angles, + input_step, + input_n_frames, + input_phis, + expected_phis, + expected_peak_phis, +): + input_images = np.array( + [ + make_signal_image( + input_n_folds, + np.add(input_start_angles, frame_index * input_step), + [1.0], + ) + for frame_index in range(input_n_frames) + ] + ) + model = RatchetModel( + n_folds=input_n_folds, + resolution=10, + search_ahead=10, + search_behind=5, + ) + actual_phis, actual_overlap = model.compute_overlap( + input_images, phis=input_phis + ) + actual_peak_phis = actual_phis[np.argmax(actual_overlap, axis=1)] + assert actual_phis == pytest.approx(expected_phis) + assert actual_peak_phis == pytest.approx(expected_peak_phis) + + +def get_saf_overlap(image, n_folds, phi, masked_phi=None): + """Return the overlap of an image with the SAF at `phi`, after + masking out the signal at `masked_phi` if one is given.""" + if masked_phi is not None: + signal_mask = SymmetryAdaptedFilter( + 10, n_folds, image.shape, phi_0=masked_phi + ).generate_mask(20) + image = np.where(signal_mask, 0, image) + saf = SymmetryAdaptedFilter(10, n_folds, image.shape, phi_0=phi) + overlap = np.sum(image * saf.generate_filter()) + return overlap + + +# The number of signals is counted from one period of the overlap curve of +# an image with two 6-fold signals: a strong signal at 0 degrees and a +# weaker signal rotated away from it. Every angle difference below is +# combined with every weak signal amplitude. The angle differences get +# finer as the signals get closer, down to well below the 10 degree +# resolution of the SAF, and the weak signal should always be counted. +# The angles phi1 and phi2 should also land on the two signals. They are +# compared in sorted order, since with equal amplitudes either signal may +# be found first. A single image is searched over [-30, 30) degrees, +# so a signal at 30 degrees is reported at -30 degrees, the same +# orientation one period earlier. + + +@pytest.mark.parametrize( + "input_signal2_phi", + [ + # Far apart, in 5 degree steps. + # C1: The weak signal 30 degrees from the strong signal, halfway + # between two of its lobes. + 30, + # C2: The weak signal 25 degrees from the strong signal. + 25, + # C3: The weak signal 20 degrees from the strong signal. + 20, + # C4: The weak signal 15 degrees from the strong signal. + 15, + # Around the 10 degree resolution of the SAF, in 2 degree steps. + # C5: The weak signal 12 degrees from the strong signal. + 12, + ], +) +@pytest.mark.parametrize( + "input_signal2_amplitude, expected_number_of_signals", + [ + # C1: The weak signal is a quarter as bright as the strong signal. + # Expected: Two signals are counted. + (0.25, 2), + # C2: The weak signal is half as bright as the strong signal. + # Expected: Two signals are counted. + (0.5, 2), + # C3: The weak signal is three quarters as bright as the strong + # signal. + # Expected: Two signals are counted. + (0.75, 2), + # C4: Both signals are equally bright. + # Expected: Two signals are counted. + (1.0, 2), + ], +) +def test_count_number_of_signals( + make_signal_image, + input_signal2_phi, + input_signal2_amplitude, + expected_number_of_signals, +): + # Generating the image from the fixture + sigma_signals = 1.5 + n_folds_signals = 6 + signal1_phi = 0 + signal1_amplitude = 1 + # generate a single image with two 6-fold signals, + # one at 0 degrees and the other rotated away by + # input_signal2_phi, with the second signal weaker + # by input_signal2_amplitude + input_image = make_signal_image( + n_folds_signals, + [signal1_phi, input_signal2_phi], + [signal1_amplitude, input_signal2_amplitude], + sigma=sigma_signals, + ) + # model setup, masking 15 degrees around the strong signal since its + # peaks are wider in angle than the 4 degree resolution + model = RatchetModel( + n_folds=6, + resolution=4, + search_ahead=10, + search_behind=5, + mask_width=15, + ) + model._generate_search_filters(input_image.shape) + overlap_curve = model._compute_overlap_optimized(input_image) + + # extract number of signals + actual_number_of_signals = model.count_number_of_signals(overlap_curve) + actual_phi1, actual_phi2 = model.find_orientation_angles(input_image) + actual_phis = sorted([actual_phi1[0], actual_phi2[0]]) + # modulo to get the equivalent angle in the range [-30, 30) + input_phi2_mod = (input_signal2_phi + 30) % 60 - 30 + expected_phis = sorted([0, input_phi2_mod]) + assert actual_number_of_signals == expected_number_of_signals + assert actual_phis == pytest.approx(expected_phis, abs=3) # ±3 deg + + +# With only one signal present, nothing else in the overlap curve should be +# counted as a second signal. + + +@pytest.mark.parametrize( + "input_start_angle, expected_number_of_signals", + [ + # C1: A single 6-fold signal at 0 degrees. + # Expected: One signal is counted. + (0, 1), + ], +) +def test_count_number_of_signals_with_one_signal( + make_signal_image, input_start_angle, expected_number_of_signals +): + input_image = make_signal_image(6, [input_start_angle], [1.0]) + model = RatchetModel( + n_folds=6, resolution=10, search_ahead=10, search_behind=5 + ) + model._generate_search_filters(input_image.shape) + overlap_curve = model._compute_overlap_optimized(input_image) + actual_number_of_signals = model.count_number_of_signals(overlap_curve) + assert actual_number_of_signals == expected_number_of_signals + + +def test_find_orientation_angles_bad_direction(make_signal_image): + # C1: A direction other than "ccw" or "cw" is given. + # Expected: A ValueError explains the two allowed values. + input_image = make_signal_image(6, [0], [1.0]) + model = RatchetModel( + n_folds=6, resolution=10, search_ahead=10, search_behind=5 + ) + expected_msg = ( + "The direction must be 'ccw' or 'cw', but 'up' was given.\n" + "Please use 'ccw' if the angles increase from one image to the " + "next, or 'cw' if they decrease." + ) + with pytest.raises(ValueError, match=re.escape(expected_msg)): + model.find_orientation_angles(input_image, direction="up") + + +@pytest.mark.parametrize( + "input_shape, expected_msg", + [ + # C1: A 1D array. + # Expected: A ValueError explains that a 2D image or a 3D stack is + # needed. + ( + (64,), + "The images must be a single image of shape (rows, columns) or " + "a stack of shape (n_images, rows, columns), but an array of " + "shape (64,) was given.\n" + "Please pass a 2D image or a 3D stack of images.", + ), + # C2: A 4D array. + # Expected: A ValueError explains that a 2D image or a 3D stack is + # needed. + ( + (2, 3, 64, 64), + "The images must be a single image of shape (rows, columns) or " + "a stack of shape (n_images, rows, columns), but an array of " + "shape (2, 3, 64, 64) was given.\n" + "Please pass a 2D image or a 3D stack of images.", + ), + ], +) +def test_find_orientation_angles_bad_input_dimension( + input_shape, expected_msg +): + model = RatchetModel( + n_folds=6, resolution=10, search_ahead=10, search_behind=5 + ) + with pytest.raises(ValueError, match=re.escape(expected_msg)): + model.find_orientation_angles(np.zeros(input_shape)) diff --git a/tests/test_saf_app.py b/tests/test_saf_app.py new file mode 100644 index 0000000..33939f6 --- /dev/null +++ b/tests/test_saf_app.py @@ -0,0 +1,17 @@ +import sys +from importlib.metadata import metadata + +import pytest + +from diffpy.saf import saf_app + + +def test_main_help_shows_package_description(monkeypatch, capsys): + # C1: The help flag is given. + # Expected: The help text shows the description in pyproject.toml. + monkeypatch.setattr(sys, "argv", ["diffpy-saf", "--help"]) + with pytest.raises(SystemExit): + saf_app.main() + actual_help = " ".join(capsys.readouterr().out.split()) + expected_description = metadata("diffpy.saf")["Summary"] + assert expected_description in actual_help