pytme 0.3.1.post2__cp311-cp311-macosx_15_0_arm64.whl → 0.3.2__cp311-cp311-macosx_15_0_arm64.whl

tests/test_density.py

@@ -101,9 +101,10 @@ class TestDensity:
 
     def test_from_file_baseline(self):
         self.test_to_file(gzip=False)
-        density = Density.from_file(str(BASEPATH.joinpath("Maps/emd_8621.mrc.gz")))
-        assert np.allclose(density.origin, (4.35, 2.90, -1.45), rtol=0.1)
-        assert np.allclose(density.sampling_rate, (1.45), rtol=0.3)
+        density = Density.from_file(str(BASEPATH.joinpath("Raw/em_map.map")))
+        assert density.shape == (19, 14, 20)
+        assert np.allclose(density.origin, (-52.8, -10.56, -52.8), rtol=0.1)
+        assert np.allclose(density.sampling_rate, (5.28), rtol=0.1)
 
     @pytest.mark.parametrize("extension", ("mrc", "em", "tiff", "h5"))
     @pytest.mark.parametrize("gzip", (True, False))
@@ -315,7 +316,7 @@ class TestDensity:
         "cutoff", [DEFAULT_DATA.min() - 1, 0, DEFAULT_DATA.max() - 0.1]
     )
     def test_centered(self, cutoff):
-        centered_density, translation = self.density.centered(cutoff=cutoff)
+        centered_density = self.density.centered(cutoff=cutoff)
         com = centered_density.center_of_mass(centered_density.data, 0)
 
         difference = np.abs(
@@ -334,7 +335,7 @@ class TestDensity:
             box = temp.minimum_enclosing_box(cutoff=0, use_geometric_center=True)
             temp.adjust_box(box)
         else:
-            temp, translation = temp.centered()
+            temp = temp.centered()
 
         swaps = set(permutations([0, 1, 2]))
         temp_matrix = np.eye(temp.data.ndim).astype(np.float32)
@@ -436,7 +437,7 @@ class TestDensity:
         arr = np.linalg.norm(np.indices(shape) - position, axis=0)
         arr = (arr <= radius).astype(np.float32)
 
-        center_of_mass = Density.center_of_mass(arr)
+        center_of_mass = Density(arr).center_of_mass()
         assert np.allclose(center, center_of_mass)
 
     @pytest.mark.parametrize(
@@ -451,7 +452,7 @@ class TestDensity:
         target[5:10, 15:22, 10:13] = 1
 
         target = Density(target, sampling_rate=(1, 1, 1), origin=(0, 0, 0))
-        target, translation = target.centered(cutoff=0)
+        target = target.centered(cutoff=0)
 
         template = target.copy()
 
@@ -474,21 +475,79 @@ class TestDensity:
         assert np.allclose(np.linalg.inv(rotation), initial_rotation, atol=0.2)
 
     def test_match_structure_to_density(self):
-        density = Density.from_file("tests/data/Maps/emd_8621.mrc.gz")
-        density = density.resample(density.sampling_rate * 4)
-        structure = Structure.from_file(
-            "tests/data/Structures/5uz4.cif", filter_by_residues=None
+        mask = create_mask(
+            mask_type="ellipse",
+            center=(20, 20, 20),
+            radius=(10, 5, 10),
+            shape=(50, 50, 50),
         )
 
+        coordinates = np.array(np.where(mask > 0), dtype=np.float32).T
+        structure = Structure(
+            record_type=[
+                "ATOM",
+            ]
+            * coordinates.shape[0],
+            atom_serial_number=list(range(coordinates.shape[0])),
+            atom_name=[
+                "C",
+            ]
+            * coordinates.shape[0],
+            atom_coordinate=coordinates,
+            alternate_location_indicator=[
+                ".",
+            ]
+            * coordinates.shape[0],
+            residue_name=[
+                "GLY",
+            ]
+            * coordinates.shape[0],
+            chain_identifier=[
+                "A",
+            ]
+            * coordinates.shape[0],
+            residue_sequence_number=[
+                0,
+            ]
+            * coordinates.shape[0],
+            code_for_residue_insertion=[
+                "?",
+            ]
+            * coordinates.shape[0],
+            occupancy=[
+                0,
+            ]
+            * coordinates.shape[0],
+            temperature_factor=[
+                0,
+            ]
+            * coordinates.shape[0],
+            segment_identifier=[
+                "1",
+            ]
+            * coordinates.shape[0],
+            element_symbol=[
+                "C",
+            ]
+            * coordinates.shape[0],
+            charge=[
+                "?",
+            ]
+            * coordinates.shape[0],
+            metadata={},
+        )
+        density = Density(mask, sampling_rate=1.0)
+        density = density.resample(density.sampling_rate * 2)
+
         initial_translation = np.array([-1, 0, 5])
         initial_rotation = euler_to_rotationmatrix((-10, 2, 5))
-        structure.rigid_transform(
+        structure_mod = structure.rigid_transform(
             translation=initial_translation, rotation_matrix=initial_rotation
         )
         np.random.seed(12)
         ret = Density.match_structure_to_density(
             target=density,
-            template=structure,
+            template=structure_mod,
             cutoff_target=0,
             scoring_method="CrossCorrelation",
             maxiter=10,

tests/test_extensions.py

@@ -53,6 +53,7 @@ class TestExtensions:
     @pytest.mark.parametrize("min_distance", [0, 5, 10])
     def test_find_candidate_indices(self, dimension, dtype, min_distance):
         coordinates = COORDINATES[dimension].astype(dtype)
+        print(coordinates.shape)
 
         min_distance = np.array([min_distance]).astype(dtype)[0]
 

tests/test_matching_cli.py

@@ -10,7 +10,7 @@ from tme import Density, Orientations
 from tme.backends import backend as be
 
 np.random.seed(42)
-available_backends = (x for x in be.available_backends() if x != "mlx")
+available_backends = tuple(x for x in be.available_backends() if x != "mlx")
 
 
 def argdict_to_command(input_args, executable: str):
@@ -29,7 +29,7 @@ def argdict_to_command(input_args, executable: str):
     return " ".join(ret)
 
 
-class TestMatchTemplate:
+class TestSetup:
     @classmethod
     def setup_class(cls):
         target = np.random.rand(20, 20, 20)
@@ -98,6 +98,7 @@ class TestMatchTemplate:
         use_target_mask: bool = False,
         backend: str = "numpyfftw",
         test_rejection_sampling: bool = False,
+        background_correction: str = None,
     ):
         output_path = tempfile.NamedTemporaryFile(delete=False, suffix="pickle").name
 
@@ -120,6 +121,9 @@ class TestMatchTemplate:
         if test_rejection_sampling:
             argdict["--orientations"] = self.orientations_path
 
+        if background_correction is not None:
+            argdict["--background-correction"] = background_correction
+
         if test_filter:
             argdict["--lowpass"] = 30
             argdict["--defocus"] = 3000
@@ -136,11 +140,15 @@ class TestMatchTemplate:
         assert ret.returncode == 0
         return output_path
 
+
+class TestMatchTemplate(TestSetup):
+
     @pytest.mark.parametrize("backend", available_backends)
     @pytest.mark.parametrize("call_peaks", (False, True))
     @pytest.mark.parametrize("use_template_mask", (False, True))
     @pytest.mark.parametrize("test_filter", (False, True))
     @pytest.mark.parametrize("test_rejection_sampling", (False, True))
+    @pytest.mark.parametrize("background_correction", (None, "phase-scrambling"))
     def test_match_template(
         self,
         backend: bool,
@@ -148,8 +156,14 @@ class TestMatchTemplate:
         use_template_mask: bool,
         test_filter: bool,
         test_rejection_sampling: bool,
+        background_correction: str,
     ):
-        if backend == "jax" and (call_peaks or test_rejection_sampling):
+        # Jax does not support peak calling yet
+        if backend == "jax" and call_peaks:
+            return None
+
+        # These use different analyzers raising an error in the interface
+        if call_peaks and test_rejection_sampling:
             return None
 
         self.run_matching(
@@ -163,10 +177,11 @@ class TestMatchTemplate:
             template_mask_path=self.template_mask_path,
             target_mask_path=self.target_mask_path,
             test_rejection_sampling=test_rejection_sampling,
+            background_correction=background_correction,
         )
 
 
-class TestPostprocessing(TestMatchTemplate):
+class TestPostprocessing(TestSetup):
     @classmethod
     def setup_class(cls):
         super().setup_class()
@@ -256,7 +271,6 @@ class TestPostprocessing(TestMatchTemplate):
         }
         cmd = argdict_to_command(argdict, executable="postprocess.py")
         ret = subprocess.run(cmd, capture_output=True, shell=True)
-        print(ret)
 
         match output_format:
             case "orientations":
@@ -289,14 +303,14 @@ class TestPostprocessing(TestMatchTemplate):
         assert ret.returncode == 0
 
 
-class TestEstimateMemoryUsage(TestMatchTemplate):
+class TestEstimateMemoryUsage(TestSetup):
     @classmethod
     def setup_class(cls):
         super().setup_class()
 
     @pytest.mark.parametrize("ncores", (1, 4, 8))
     @pytest.mark.parametrize("pad_edges", (False, True))
-    def test_estimation(self, ncores, pad_edges):
+    def test_estimation_cli(self, ncores, pad_edges):
 
         argdict = {
             "-m": self.target_path,
@@ -311,7 +325,7 @@ class TestEstimateMemoryUsage(TestMatchTemplate):
         assert ret.returncode == 0
 
 
-class TestPreprocess(TestMatchTemplate):
+class TestPreprocess(TestSetup):
     @classmethod
     def setup_class(cls):
         super().setup_class()
@@ -319,7 +333,7 @@ class TestPreprocess(TestMatchTemplate):
     @pytest.mark.parametrize("backend", available_backends)
     @pytest.mark.parametrize("align_axis", (False, True))
     @pytest.mark.parametrize("invert_contrast", (False, True))
-    def test_estimation(self, backend, align_axis, invert_contrast):
+    def test_preprocess_cli(self, backend, align_axis, invert_contrast):
 
         argdict = {
             "-m": self.target_path,

tests/test_matching_exhaustive.py

@@ -1,5 +1,5 @@
-import numpy as np
 import pytest
+import numpy as np
 
 from scipy.ndimage import laplace
 
@@ -7,7 +7,7 @@ from tme.matching_data import MatchingData
 from tme.memory import MATCHING_MEMORY_REGISTRY
 from tme.analyzer import MaxScoreOverRotations, PeakCallerSort
 from tme.matching_exhaustive import (
-    scan_subsets,
+    match_exhaustive,
     MATCHING_EXHAUSTIVE_REGISTER,
     register_matching_exhaustive,
 )
@@ -35,11 +35,11 @@ class TestMatchExhaustive:
         self.coordinates_weights = None
         self.rotations = None
 
-    @pytest.mark.parametrize("evaluate_peak", (True,))
+    @pytest.mark.parametrize("evaluate_peak", (True, False))
     @pytest.mark.parametrize("score", tuple(MATCHING_EXHAUSTIVE_REGISTER.keys()))
     @pytest.mark.parametrize("job_schedule", ((2, 1),))
     @pytest.mark.parametrize("pad_edge", (False, True))
-    def test_scan_subset(
+    def test_match_exhaustive(
         self,
         score: str,
         job_schedule: int,
@@ -64,7 +64,7 @@ class TestMatchExhaustive:
         if evaluate_peak:
             callback_class = PeakCallerSort
 
-        ret = scan_subsets(
+        ret = match_exhaustive(
             matching_data=matching_data,
             matching_setup=setup,
             matching_score=process,

tests/test_matching_utils.py

@@ -15,7 +15,7 @@ from tme.matching_utils import (
     apply_convolution_mode,
     write_pickle,
     load_pickle,
-    _normalize_template_overflow_safe,
+    _standardize_safe,
 )
 
 BASEPATH = files("tests.data")
@@ -127,12 +127,12 @@ class TestMatchingUtils:
         loaded_data = load_pickle(filename)
         assert np.array_equal(loaded_data, data)
 
-    def test_normalize_template_overflow_safe(self):
+    def test_standardize_safe(self):
         template = be.random.random((10, 10)).astype(be.float32)
         mask = be.ones_like(template)
         n_observations = 100.0
 
-        result = _normalize_template_overflow_safe(template, mask, n_observations)
+        result = _standardize_safe(template, mask, n_observations)
         assert result.shape == template.shape
         assert result.dtype == template.dtype
         assert np.allclose(result.mean(), 0, atol=0.1)

tests/test_orientations.py

@@ -95,6 +95,18 @@ class TestDensity:
             self.orientations.rotations, orientations_new.rotations, atol=1e-3
         )
 
+    @pytest.mark.parametrize("input_format", ("text", "star", "tbl"))
+    @pytest.mark.parametrize("output_format", ("text", "star", "tbl"))
+    def test_file_format_io(self, input_format: str, output_format: str):
+        _, output_file = mkstemp(suffix=f".{input_format}")
+        _, output_file2 = mkstemp(suffix=f".{output_format}")
+
+        self.orientations.to_file(output_file)
+        orientations_new = Orientations.from_file(output_file)
+        orientations_new.to_file(output_file2)
+
+        assert True
+
     @pytest.mark.parametrize("drop_oob", (True, False))
     @pytest.mark.parametrize("shape", (10, 40, 80))
     @pytest.mark.parametrize("odd", (True, False))

tests/test_rotations.py

@@ -35,24 +35,19 @@ class TestRotations:
         )
 
     @pytest.mark.parametrize(
-        "initial_vector, target_vector, convention",
+        "initial_vector, target_vector",
         [
-            ([1, 0, 0], [0, 1, 0], None),
-            ([0, 1, 0], [0, 0, 1], "zyx"),
-            ([1, 1, 1], [1, 0, 0], "xyz"),
+            ([1, 0, 0], [0, 1, 0]),
+            ([0, 1, 0], [0, 0, 1]),
+            ([1, 1, 1], [1, 0, 0]),
         ],
     )
-    def test_align_vectors(self, initial_vector, target_vector, convention):
-        result = align_vectors(initial_vector, target_vector, convention)
+    def test_align_vectors(self, initial_vector, target_vector):
+        result = align_vectors(initial_vector, target_vector)
 
         assert isinstance(result, np.ndarray)
-        if convention is None:
-            assert result.shape == (3, 3)
-            assert np.allclose(np.dot(result, result.T), np.eye(3), atol=1e-6)
-        else:
-            assert len(result) == 3
-            result = Rotation.from_euler(convention, result, degrees=True).as_matrix()
-            assert np.allclose(np.dot(result, result.T), np.eye(3), atol=1e-6)
+        assert result.shape == (3, 3)
+        assert np.allclose(np.dot(result, result.T), np.eye(3), atol=1e-6)
 
         rotated = np.dot(Rotation.from_matrix(result).as_matrix(), initial_vector)
         assert np.allclose(
@@ -62,11 +57,11 @@ class TestRotations:
         )
 
     @pytest.mark.parametrize(
-        "cone_angle, cone_sampling, axis_angle, axis_sampling, vector, n_symmetry, convention",
+        "cone_angle, cone_sampling, axis_angle, axis_sampling, vector, n_symmetry",
         [
-            (30, 5, 360, None, (1, 0, 0), 1, None),
-            (45, 10, 180, 15, (0, 1, 0), 2, "zyx"),
-            (60, 15, 90, 30, (0, 0, 1), 4, "xyz"),
+            (30, 5, 360, None, (1, 0, 0), 1),
+            (45, 10, 180, 15, (0, 1, 0), 2),
+            (60, 15, 90, 30, (0, 0, 1), 4),
         ],
     )
     def test_get_cone_rotations(
@@ -77,7 +72,6 @@ class TestRotations:
         axis_sampling,
         vector,
         n_symmetry,
-        convention,
     ):
         result = get_cone_rotations(
             cone_angle=cone_angle,
@@ -86,14 +80,10 @@ class TestRotations:
             axis_sampling=axis_sampling,
             reference=vector,
             n_symmetry=n_symmetry,
-            seq=convention,
         )
 
         assert isinstance(result, np.ndarray)
-        if convention is None:
-            assert result.shape[1:] == (3, 3)
-        else:
-            assert result.shape[1] == 3
+        assert result.shape[1:] == (3, 3)
 
     def test_euler_conversion(self):
         rotation_matrix_initial = np.array(

tests/test_structure.py

@@ -6,7 +6,6 @@ import pytest
 import numpy as np
 
 from tme import Structure
-from tme.matching_utils import minimum_enclosing_box
 from tme.rotations import euler_to_rotationmatrix
 
 
@@ -196,11 +195,6 @@ class TestStructure:
         assert center_of_mass.shape[0] == self.structure.atom_coordinate.shape[1]
         assert np.allclose(center_of_mass, [-0.89391639, 29.94908928, -2.64736741])
 
-    def test_centered(self):
-        ret, translation = self.structure.centered()
-        box = minimum_enclosing_box(coordinates=self.structure.atom_coordinate.T)
-        assert np.allclose(ret.center_of_mass(), np.divide(box, 2), atol=1)
-
     def test__get_atom_weights_error(self):
         with pytest.raises(NotImplementedError):
             self.structure._get_atom_weights(
@@ -242,6 +236,6 @@ class TestStructure:
         assert final_rmsd <= 0.1
 
         aligned, final_rmsd = Structure.align_structures(
-            self.structure, structure_transform, sampling_rate=1
+            self.structure, structure_transform
         )
         assert final_rmsd <= 1

tme/__version__.py

@@ -1 +1 @@
-__version__ = "0.3.1"
+__version__ = "0.3.2"

tme/analyzer/aggregation.py

@@ -192,6 +192,15 @@ class MaxScoreOverRotations(AbstractAnalyzer):
         )
         return scores, rotations, rotation_mapping, ssum
 
+    def correct_background(self, state, mean=0, inv_std=1, **kwargs):
+        scores, rotations, rotation_mapping, ssum = state
+
+        scores = be.subtract(scores, mean, out=scores)
+        scores = be.multiply(scores, inv_std, out=scores)
+
+        scores = be.maximum(scores, self._score_threshold, out=scores)
+        return scores, rotations, rotation_mapping, ssum
+
     @staticmethod
     def _invert_rmap(rotation_mapping: dict) -> dict:
         """
@@ -201,7 +210,12 @@ class MaxScoreOverRotations(AbstractAnalyzer):
         new_map, ndim = {}, None
         for k, v in rotation_mapping.items():
             nbytes = be.datatype_bytes(be._float_dtype)
-            dtype = np.float32 if nbytes == 4 else np.float16
+            if nbytes == 8:
+                dtype = np.float64
+            elif nbytes == 4:
+                dtype = np.float32
+            else:
+                np.float16
             rmat = np.frombuffer(k, dtype=dtype)
             if ndim is None:
                 ndim = int(np.sqrt(rmat.size))
@@ -451,7 +465,7 @@ class MaxScoreOverRotationsConstrained(MaxScoreOverRotations):
         Maximum accepted rotational deviation in degrees.
     positions : BackendArray
         Array of shape (n, d) with n seed point translations.
-    positions : BackendArray
+    rotations : BackendArray
         Array of shape (n, d, d) with n seed point rotation matrices.
     reference : BackendArray
         Reference orientation of the template, wlog defaults to (0,0,1).
@@ -489,6 +503,7 @@ class MaxScoreOverRotationsConstrained(MaxScoreOverRotations):
             be.reshape(be.to_backend_array(reference), (-1,)), be._float_dtype
         )
         positions = be.astype(be.to_backend_array(positions), be._int_dtype)
+        rotations = be.astype(be.to_backend_array(rotations), be._float_dtype)
 
         ndim = positions.shape[1]
         rotate_mask = len(set(acceptance_radius)) != 1
@@ -515,7 +530,13 @@ class MaxScoreOverRotationsConstrained(MaxScoreOverRotations):
         )
 
         self._positions = positions[valid_positions]
-        rotations = be.to_backend_array(rotations)[valid_positions]
+        rotations = rotations[valid_positions]
+
+        # Convert to pull matrix to remain consistent with rotation convention
+        rotations = be.concatenate(
+            [rotations[i].T[None] for i in range(rotations.shape[0])]
+        )
+
         ex = be.astype(be.to_backend_array((1, 0, 0)), be._float_dtype)
         ey = be.astype(be.to_backend_array((0, 1, 0)), be._float_dtype)
         ez = be.astype(be.to_backend_array((0, 0, 1)), be._float_dtype)
@@ -524,6 +545,15 @@ class MaxScoreOverRotationsConstrained(MaxScoreOverRotations):
         self._normals_y = (rotations @ ey[..., None])[..., 0]
         self._normals_z = (rotations @ ez[..., None])[..., 0]
 
+        # All scores will be rejected in this case. We should think about a
+        # unified interface for checking analyzer validity to skip such runs
+        if self._positions.shape[0] == 0:
+
+            def _get_score_mask(*args, **kwargs):
+                return 0
+
+            self._get_score_mask = _get_score_mask
+
         # Periodic wrapping could be avoided by padding the target
         shape = be.to_backend_array(self._shape)
         starts = be.subtract(self._positions, extend)
@@ -539,9 +569,7 @@ class MaxScoreOverRotationsConstrained(MaxScoreOverRotations):
         self._mask_shape = tuple(1 if i != 0 else -1 for i in range(1 + ndim))
 
         if rotate_mask:
-            self._score_mask = be.zeros(
-                (rotations.shape[0], *self._score_mask.shape), dtype=be._float_dtype
-            )
+            self._score_mask = []
             for i in range(rotations.shape[0]):
                 mask = create_mask(
                     mask_type="ellipse",
@@ -550,9 +578,10 @@ class MaxScoreOverRotationsConstrained(MaxScoreOverRotations):
                     center=tuple(extend for _ in range(ndim)),
                     orientation=be.to_numpy_array(rotations[i]),
                 )
-                self._score_mask[i] = be.astype(
-                    be.to_backend_array(mask), be._float_dtype
+                self._score_mask.append(
+                    be.astype(be.to_backend_array(mask), be._float_dtype)[None]
                 )
+            self._score_mask = be.concatenate(self._score_mask)
 
     def __call__(
         self,
@@ -573,7 +602,7 @@ class MaxScoreOverRotationsConstrained(MaxScoreOverRotations):
         """
         Determine whether the angle between projection of reference w.r.t to
         a given rotation matrix and a set of rotations fall within the set
-        cone_angle cutoff.
+        cone angle cutoff.
 
         Parameters
         ----------
@@ -585,7 +614,7 @@ class MaxScoreOverRotationsConstrained(MaxScoreOverRotations):
         BackerndArray
             Boolean mask of shape (n, )
         """
-        template_rot = rotation_matrix @ self._reference
+        template_rot = rotation_matrix.T @ self._reference
 
         x = be.sum(be.multiply(self._normals_x, template_rot), axis=1)
         y = be.sum(be.multiply(self._normals_y, template_rot), axis=1)
@@ -596,10 +625,9 @@ class MaxScoreOverRotationsConstrained(MaxScoreOverRotations):
     def _get_score_mask(self, mask: BackendArray, scores: BackendArray, **kwargs):
         score_mask = be.zeros(scores.shape, scores.dtype)
 
-        if be.sum(mask) == 0:
-            return score_mask
+        # The indexing could be improved to avoid expanding the mask to
+        # the number of seed points
         mask = be.reshape(mask, self._mask_shape)
-
         score_mask = be.addat(score_mask, self._index_grid, self._score_mask * mask)
         return score_mask > 0
 
@@ -663,13 +691,16 @@ class MaxScoreOverTranslations(MaxScoreOverRotations):
         rotation_index = len(rotation_mapping)
         if self._inversion_mapping:
             rotation_mapping[rotation_index] = rotation_matrix
+        elif self._jax_mode:
+            rotation_index = kwargs.get("rotation_index", 0)
         else:
             rotation = be.tobytes(rotation_matrix)
             rotation_index = rotation_mapping.setdefault(rotation, rotation_index)
-        max_score = be.max(scores, axis=self._aggregate_axis)
 
-        update = prev_scores[rotation_index]
-        update = be.maximum(max_score, update, out=update)
+        scores = be.max(scores, axis=self._aggregate_axis)
+        scores = be.maximum(scores, prev_scores[rotation_index])
+        prev_scores = be.at(prev_scores, rotation_index, scores)
+
         return prev_scores, rotations, rotation_mapping
 
     @classmethod

tme/analyzer/base.py

@@ -73,6 +73,40 @@ class AbstractAnalyzer(ABC):
             Updated analyzer state incorporating the new data.
         """
 
+    @abstractmethod
+    def correct_background(self, state, mean=0, inv_std=1, **kwargs):
+        """
+        Applies flat-fielding correction to scores f as
+
+        .. math::
+
+            f' = (f - \\text{mean}) \\cdot \\text{inv_std},
+
+        transforming raw correlations to SNR-like scores.
+
+        Parameters
+        ----------
+        state : tuple
+            Current analyzer state as returned :py:meth:`AbstractAnalyzer.init_state`
+            or previous invocations of :py:meth:`AbstractAnalyzer.__call__`.
+        mean : BackendArray, optional
+            Background mean (or equivalent), defaults to 0.
+        inv_std : BackendArray, optional
+            Reciprocal background standard deviation (or equivalent), defaults to 1.
+
+        Notes
+        -----
+        This method should be called after all rotations have been processed
+        but before calling :py:meth:`result`. The correction helps distinguish genuine
+        template matches from systematic background artifacts that may arise from
+        template edges, interpolation artifacts, or structured noise in the target.
+
+        Returns
+        -------
+        tuple
+            Updated analyzer state incorporating the new data.
+        """
+
     @abstractmethod
     def result(self, state: Tuple, **kwargs) -> Tuple:
         """