biotite 0.39.0__cp312-cp312-win_amd64.whl → 0.41.0__cp312-cp312-win_amd64.whl

biotite/structure/superimpose.py

@@ -8,31 +8,226 @@ This module provides functions for structure superimposition.
 
 __name__ = "biotite.structure"
 __author__ = "Patrick Kunzmann, Claude J. Rogers"
-__all__ = ["superimpose", "superimpose_apply"]
+__all__ = ["superimpose", "superimpose_homologs",
+           "superimpose_without_outliers",
+           "AffineTransformation", "superimpose_apply"]
+
 
 import numpy as np
 from .atoms import coord
-from .geometry import centroid
+from .geometry import centroid, distance
+from .filter import filter_amino_acids, filter_nucleotides
+from .sequence import to_sequence
+from ..sequence.alphabet import common_alphabet
+from ..sequence.seqtypes import ProteinSequence
+from ..sequence.align import SubstitutionMatrix, align_optimal, get_codes
+
+
+class AffineTransformation:
+    """
+    An affine transformation, consisting of translations and a rotation.
+
+    Parameters
+    ----------
+    center_translation : ndarray, shape=(3,) or shape=(m,3), dtype=float
+        The translation vector for moving the centroid into the
+        origin.
+    rotation : ndarray, shape=(3,3) or shape=(m,3,3), dtype=float
+        The rotation matrix.
+    target_translation : ndarray, shape=(m,3), dtype=float
+        The translation vector for moving the structure onto the
+        fixed one.
+
+    Attributes
+    ----------
+    center_translation, rotation, target_translation : ndarray
+        Same as the parameters.
+        The dimensions are always expanded to *(m,3)* or *(m,3,3)*,
+        respectively.
+    """
+    def __init__(self, center_translation, rotation, target_translation):
+        self.center_translation = _expand_dims(center_translation, 2)
+        self.rotation = _expand_dims(rotation, 3)
+        self.target_translation = _expand_dims(target_translation, 2)
+
+
+    def apply(self, atoms):
+        """
+        Apply this transformation on the given structure.
+
+        Parameters
+        ----------
+        atoms : AtomArray or AtomArrayStack or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float
+            The structure to apply the transformation on.
+
+        Returns
+        -------
+        transformed : AtomArray or AtomArrayStack or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float
+            A copy of the `atoms` structure,
+            with transformations applied.
+            Only coordinates are returned, if coordinates were given in
+            `atoms`.
+
+        Examples
+        --------
+
+        >>> coord = np.arange(15).reshape(5,3)
+        >>> print(coord)
+        [[ 0  1  2]
+         [ 3  4  5]
+         [ 6  7  8]
+         [ 9 10 11]
+         [12 13 14]]
+        >>> # Rotates 90 degrees around the z-axis
+        >>> transform = AffineTransformation(
+        ...     center_translation=np.array([0,0,0]),
+        ...     rotation=np.array([
+        ...         [0, -1,  0],
+        ...         [1,  0,  0],
+        ...         [0,  0,  1]
+        ...     ]),
+        ...     target_translation=np.array([0,0,0])
+        ... )
+        >>> print(transform.apply(coord))
+        [[ -1.   0.   2.]
+         [ -4.   3.   5.]
+         [ -7.   6.   8.]
+         [-10.   9.  11.]
+         [-13.  12.  14.]]
+
+        """
+        mobile_coord = coord(atoms)
+        original_shape = mobile_coord.shape
+        mobile_coord = _reshape_to_3d(mobile_coord)
+        if mobile_coord.shape[0] != self.rotation.shape[0]:
+            raise IndexError(
+                f"Number of transformations is {self.rotation.shape[0]}, "
+                f"but number of structure models is {mobile_coord.shape[0]}"
+            )
+
+        superimposed_coord = mobile_coord.copy()
+        superimposed_coord += self.center_translation[:, np.newaxis, :]
+        superimposed_coord = _multi_matmul(self.rotation, superimposed_coord)
+        superimposed_coord += self.target_translation[:, np.newaxis, :]
+
+        superimposed_coord = superimposed_coord.reshape(original_shape)
+        if isinstance(atoms, np.ndarray):
+            return superimposed_coord
+        else:
+            superimposed = atoms.copy()
+            superimposed.coord = superimposed_coord
+            return superimposed
+
+
+    def as_matrix(self):
+        """
+        Get the translations and rotation as a combined 4x4
+        transformation matrix.
+
+        Multiplying this matrix with coordinates in the form
+        *(x, y, z, 1)* will apply the same transformation as
+        :meth:`apply()` to coordinates in the form *(x, y, z)*.
+
+        Returns
+        -------
+        transformation_matrix : ndarray, shape=(m,4,4), dtype=float
+            The transformation matrix.
+            *m* is the number of models in the transformation.
+
+        Examples
+        --------
+
+        >>> coord = np.arange(15).reshape(5,3)
+        >>> print(coord)
+        [[ 0  1  2]
+         [ 3  4  5]
+         [ 6  7  8]
+         [ 9 10 11]
+         [12 13 14]]
+        >>> # Rotates 90 degrees around the z-axis
+        >>> transform = AffineTransformation(
+        ...     center_translation=np.array([0,0,0]),
+        ...     rotation=np.array([
+        ...         [0, -1,  0],
+        ...         [1,  0,  0],
+        ...         [0,  0,  1]
+        ...     ]),
+        ...     target_translation=np.array([0,0,0])
+        ... )
+        >>> print(transform.apply(coord))
+        [[ -1.   0.   2.]
+         [ -4.   3.   5.]
+         [ -7.   6.   8.]
+         [-10.   9.  11.]
+         [-13.  12.  14.]]
+        >>> # Use a 4x4 matrix for transformation as alternative
+        >>> coord_4 = np.concatenate([coord, np.ones((len(coord), 1))], axis=-1)
+        >>> print(coord_4)
+        [[ 0.  1.  2.  1.]
+         [ 3.  4.  5.  1.]
+         [ 6.  7.  8.  1.]
+         [ 9. 10. 11.  1.]
+         [12. 13. 14.  1.]]
+        >>> print((transform.as_matrix()[0] @ coord_4.T).T)
+        [[ -1.   0.   2.   1.]
+         [ -4.   3.   5.   1.]
+         [ -7.   6.   8.   1.]
+         [-10.   9.  11.   1.]
+         [-13.  12.  14.   1.]]
+
+        """
+        n_models = self.rotation.shape[0]
+        rotation_mat = _3d_identity(n_models, 4)
+        rotation_mat[:, :3, :3] = self.rotation
+        center_translation_mat = _3d_identity(n_models, 4)
+        center_translation_mat[:, :3, 3] = self.center_translation
+        target_translation_mat = _3d_identity(n_models, 4)
+        target_translation_mat[:, :3, 3] = self.target_translation
+        return target_translation_mat @ rotation_mat @ center_translation_mat
+
+
+def _expand_dims(array, n_dims):
+    """
+    Expand the dimensions of an `ndarray` to a certain number of
+    dimensions.
+    """
+    while array.ndim < n_dims:
+        array = array[np.newaxis, ...]
+    return array
+
+
+def _3d_identity(m, n):
+    """
+    Create an array of *m* identity matrices of shape *(n, n)*
+    """
+    matrices = np.zeros((m, n, n), dtype=float)
+    indices = np.arange(n)
+    matrices[:, indices, indices] = 1
+    return matrices
 
 
 def superimpose(fixed, mobile, atom_mask=None):
     """
-    Superimpose structures onto a fixed structure.
-    
-    The superimposition is performed using the Kabsch algorithm
-    :footcite:`Kabsch1976, Kabsch1978`, so that the RMSD between the
-    superimposed and the fixed structure is minimized.
-    
+    Superimpose structures onto each other, minimizing the RMSD between
+    them.
+    :footcite:`Kabsch1976, Kabsch1978`.
+
+    More precisely, the `mobile` structure is rotated and translated onto
+    the `fixed` structure.
+
     Parameters
     ----------
-    fixed : AtomArray, shape(n,) or ndarray, shape(n,), dtype=float
-        The fixed structure.
+    fixed : AtomArray, shape(n,) or AtomArrayStack, shape(m,n) or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float
+        The fixed structure(s).
         Alternatively coordinates can be given.
     mobile: AtomArray, shape(n,) or AtomArrayStack, shape(m,n) or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float
         The structure(s) which is/are superimposed on the `fixed`
         structure.
         Each atom at index *i* in `mobile` must correspond the
         atom at index *i* in `fixed` to obtain correct results.
+        Furthermore, if both `fixed` and `mobile` are
+        :class:`AtomArrayStack` objects, they must have the same
+        number of models.
         Alternatively coordinates can be given.
     atom_mask: ndarray, dtype=bool, optional
         If given, only the atoms covered by this boolean mask will be
@@ -41,62 +236,55 @@ def superimpose(fixed, mobile, atom_mask=None):
         on the covered atoms instead of all atoms.
         The returned superimposed structure will contain all atoms
         of the input structure, regardless of this parameter.
-    
+
     Returns
     -------
     fitted : AtomArray or AtomArrayStack or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float
         A copy of the `mobile` structure(s),
-        superimposed on the fixed structure.
+        superimposed on the fixed structure(s).
         Only coordinates are returned, if coordinates were given in
         `mobile`.
-    transformation : tuple or tuple list
-        The tuple contains the transformations that were applied on
-        `mobile`. This can be used in `apply_superimposition()` in order
-        to transform another AtomArray in the same way.
-        The first element contains the translation vector for moving the
-        centroid into the origin.
-        The second element contains the rotation matrix.
-        The third element contains the translation vector for moving the
-        structure onto the fixed.
-        The three transformations are performed sequentially.
-    
+    transformation : AffineTransformation
+        The affine transformation(s) that were applied on `mobile`.
+        :meth:`AffineTransformation.apply()` can be used to transform
+        another AtomArray in the same way.
+
     See Also
     --------
-    superimpose_apply
-    
+    superimpose_without_outliers : Superimposition with outlier removal
+    superimpose_homologs : Superimposition of homologous structures
+
     Notes
     -----
-    The `transformation` tuple can be used in
-    :func:`superimpose_apply()` in order to transform another
-    :class:`AtomArray` in the same way.
-    This can come in handy, in case you want to superimpose two
+    The `transformation` can come in handy, in case you want to
+    superimpose two
     structures with different amount of atoms.
     Often the two structures need to be filtered in order to obtain the
     same size and annotation arrays.
     After superimposition the transformation can be applied on the
-    original structure using :func:`superimpose_apply()`.
-    
+    original structure using :meth:`AffineTransformation.apply()`.
+
     References
     ----------
-    
+
     .. footbibliography::
-    
+
     Examples
     --------
-    
+
     At first two models of a structure are taken and one of them is
     randomly rotated/translated.
     Consequently the RMSD is quite large:
-    
+
     >>> array1 = atom_array_stack[0]
     >>> array2 = atom_array_stack[1]
     >>> array2 = translate(array2, [1,2,3])
     >>> array2 = rotate(array2, [1,2,3])
     >>> print("{:.3f}".format(rmsd(array1, array2)))
     11.260
-    
+
     RMSD decreases after superimposition of only CA atoms:
-    
+
     >>> array2_fit, transformation = superimpose(
     ...     array1, array2, atom_mask=(array2.atom_name == "CA")
     ... )
@@ -110,95 +298,300 @@ def superimpose(fixed, mobile, atom_mask=None):
     >>> print("{:.3f}".format(rmsd(array1, array2_fit)))
     1.928
     """
-
-    m_coord = coord(mobile)
-    f_coord = coord(fixed)
-    mshape = m_coord.shape
-    mdim = m_coord.ndim
-    if f_coord.ndim != 2:
-        raise ValueError("Expected fixed array to be an AtomArray")
-    if mdim < 2:
-        raise ValueError(
-            "Expected mobile array to be an AtomArray or AtomArrayStack"
-        )
-    if mdim == 2:
-        # normalize inputs. Fixed coords has shape (n, 3)
-        # and mobile has shape (m, n, 3)
-        m_coord = m_coord[np.newaxis, ...]
-
-    nmodels = m_coord.shape[0]
-    if f_coord.shape[0] != m_coord.shape[1]:
-        raise ValueError(
-            f"Expected fixed array and mobile array to have the same number "
-            f"of atoms, but {f_coord.shape[0]} != {m_coord.shape[1]}"
-        )
+    # Bring coordinates into the same dimensionality
+    mob_coord = _reshape_to_3d(coord(mobile))
+    fix_coord = _reshape_to_3d(coord(fixed))
 
     if atom_mask is not None:
         # Implicitly this creates array copies
-        mob_filtered = m_coord[..., atom_mask, :]
-        fix_filtered = f_coord[atom_mask, :]
+        mob_filtered = mob_coord[:, atom_mask, :]
+        fix_filtered = fix_coord[:, atom_mask, :]
     else:
-        mob_filtered = np.copy(m_coord)
-        fix_filtered = np.copy(f_coord)
-    
+        mob_filtered = np.copy(mob_coord)
+        fix_filtered = np.copy(fix_coord)
+
     # Center coordinates at (0,0,0)
     mob_centroid = centroid(mob_filtered)
     fix_centroid = centroid(fix_filtered)
-    mob_filtered -= mob_centroid[..., np.newaxis, :]
-    fix_filtered -= fix_centroid
-    
-    s_coord = m_coord.copy() - mob_centroid[..., np.newaxis, :]
-    # Perform Kabsch algorithm for every model
-    transformations = [None] * nmodels
-    for i in range(nmodels):
-        rotation = _superimpose(fix_filtered, mob_filtered[i])
-        s_coord[i] = np.dot(rotation, s_coord[i].T).T
-        transformations[i] = (-mob_centroid[i], rotation, fix_centroid)
-    s_coord += fix_centroid
-    
-    if isinstance(mobile, np.ndarray):
-        superimposed = s_coord.reshape(mshape)
-    else:
-        superimposed = mobile.copy()
-        superimposed.coord = s_coord.reshape(mshape)
+    mob_centered_filtered = mob_filtered - mob_centroid[:, np.newaxis, :]
+    fix_centered_filtered = fix_filtered - fix_centroid[:, np.newaxis, :]
 
-    if mdim == 2:
-        return superimposed, transformations[0]
-    else:
-        return superimposed, transformations
+    rotation = _get_rotation_matrices(
+        fix_centered_filtered, mob_centered_filtered
+    )
+    transform = AffineTransformation(-mob_centroid, rotation, fix_centroid)
+    return transform.apply(mobile), transform
+
+
+def superimpose_without_outliers(fixed, mobile, min_anchors=3,
+                                 max_iterations=10, quantiles=(0.25, 0.75),
+                                 outlier_threshold=1.5):
+    r"""
+    Superimpose structures onto a fixed structure, ignoring
+    conformational outliers.
+
+    This method iteratively superimposes the `mobile` structure onto the
+    `fixed` structure, removes conformational outliers and superimposes
+    the remaining atoms (called *anchors*) again until no outlier
+    remains.
+
+
+    Parameters
+    ----------
+    fixed : AtomArray, shape(n,) or AtomArrayStack, shape(m,n) or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float
+        The fixed structure(s).
+        Alternatively coordinates can be given.
+    mobile: AtomArray, shape(n,) or AtomArrayStack, shape(m,n) or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float
+        The structure(s) which is/are superimposed on the `fixed`
+        structure.
+        Each atom at index *i* in `mobile` must correspond the
+        atom at index *i* in `fixed` to obtain correct results.
+        Furthermore, if both `fixed` and `mobile` are
+        :class:`AtomArrayStack` objects, they must have the same
+        number of models.
+        Alternatively coordinates can be given.
+    min_anchors : int, optional
+        The outlier removal is stopped, if less than `min_anchors`
+        anchors would be left.
+    max_iterations : int, optional
+        The maximum number of iterations for removing conformational
+        outliers.
+        Setting the value to 1 means that no outlier removal is
+        conducted.
+    quantiles : tuple (float, float), optional
+        The lower and upper quantile for the interpercentile range
+        (IPR).
+        By default the interquartile range is taken.
+    outlier_threshold : float, optional
+        The threshold for considering a conformational outlier.
+        The threshold is given in units of IPR.
+
+    Returns
+    -------
+    fitted : AtomArray or AtomArrayStack
+        A copy of the `mobile` structure(s), superimposed on the fixed
+        structure.
+        Only coordinates are returned, if coordinates were given in
+        `mobile`.
+    transform : AffineTransformation
+        This object contains the affine transformation(s) that were
+        applied on `mobile`.
+        :meth:`AffineTransformation.apply()` can be used to transform
+        another AtomArray in the same way.
+    anchor_indices : ndarray, shape(k,), dtype=int
+        The indices of the anchor atoms.
+        These atoms were used for the superimposition.
+
+    See Also
+    --------
+    superimpose : Superimposition without outlier removal
+    superimpose_homologs : Superimposition of homologous structures
 
+    Notes
+    -----
+    This method runs the following algorithm in iterations:
+
+    1. Superimpose anchor atoms of `mobile` onto `fixed`.
+    2. Calculate the squared distance :math:`d^2` between the
+       superimposed anchors.
+    3. Remove conformational outliers from anchors based on the
+       following criterion:
+
+       .. math:: d^2 > P_\text{upper}(d^2) + \left( P_\text{upper}(d^2) - P_\text{lower}(d^2) \right) \cdot T
+
+       In prose this means that an anchor is considered an outlier, if
+       it is `outlier_threshold` :math:`T` times the interpercentile
+       range (IPR) above the upper percentile.
+       By default, this is 1.5 times the interquartile range, which is
+       the usual threshold to mark outliers in box plots.
 
-def _superimpose(fix_centered, mob_centered):
+    In the beginning, all atoms are considered as anchors.
+
+    Considering all atoms (not only the anchors), this approach does
+    **not** minimize the RMSD, in contrast to :func:`superimpose()`.
+    The purpose of this function is to ignore outliers to decrease the
+    RMSD in the more conserved parts of the structure.
     """
-    Perform the Kabsch algorithm using only the coordinates.
+    if max_iterations < 1:
+        raise ValueError("Maximum number of iterations must be at least 1")
+
+    # Ensure that the first quantile is smaller than the second one
+    quantiles = sorted(quantiles)
+
+    fixed_coord = coord(fixed)
+    mobile_coord = coord(mobile)
+    # Before refinement, all anchors are included
+    # 'inlier' is the opposite of 'outlier'
+    updated_inlier_mask = np.ones(fixed_coord.shape[-2], dtype=bool)
+
+    for _ in range(max_iterations):
+        # Run superimposition
+        inlier_mask = updated_inlier_mask
+        filtered_fixed_coord = fixed_coord[..., inlier_mask, :]
+        filtered_mobile_coord = mobile_coord[..., inlier_mask, :]
+        superimposed_coord, transform = superimpose(
+            filtered_fixed_coord, filtered_mobile_coord
+        )
+
+        # Find outliers
+        sq_dist = distance(filtered_fixed_coord, superimposed_coord) ** 2
+        if sq_dist.ndim == 2:
+            # If multiple models are superimposed,
+            # use the mean squared distance to determine outliers
+            sq_dist = np.mean(sq_dist, axis=0)
+        lower_quantile, upper_quantile = np.quantile(sq_dist, quantiles)
+        ipr = upper_quantile - lower_quantile
+        updated_inlier_mask = inlier_mask.copy()
+        # Squared distance was only calculated for the existing inliers
+        # -> update the mask only for these atoms
+        updated_inlier_mask[updated_inlier_mask] = (
+            sq_dist <= upper_quantile + outlier_threshold * ipr
+        )
+        if np.all(updated_inlier_mask):
+            # No outliers anymore -> early termination
+            break
+        if np.count_nonzero(updated_inlier_mask) < min_anchors:
+            # Less than min_anchors anchors would be left -> early termination
+            break
+
+    anchor_indices = np.where(inlier_mask)[0]
+    return transform.apply(mobile), transform, anchor_indices
+
+
+def superimpose_homologs(fixed, mobile, substitution_matrix=None,
+                         gap_penalty=-10, min_anchors=3, **kwargs):
+    r"""
+    Superimpose one protein or nucleotide chain onto another one,
+    considering sequence differences and conformational outliers.
+
+    The method finds corresponding residues by sequence alignment and
+    selects their :math:`C_{\alpha}` or :math:`P` atoms as
+    superimposition *anchors*.
+    Then iteratively the anchor atoms are superimposed and outliers are
+    removed.
+
+    Parameters
+    ----------
+    fixed : AtomArray, shape(n,) or AtomArrayStack, shape(m,n)
+        The fixed structure(s).
+        Must comprise a single chain.
+    mobile : AtomArray, shape(n,) or AtomArrayStack, shape(m,n)
+        The structure(s) which is/are superimposed on the `fixed`
+        structure.
+        Must comprise a single chain.
+    substitution_matrix : str or SubstitutionMatrix, optional
+        The (name of the) substitution matrix used for sequence
+        alignment.
+        Must fit the chain type.
+        By default, ``"BLOSUM62"`` and ``"NUC"`` are used respectively.
+        Only aligned residues with a positive score are considered as
+        initial anchors.
+    gap_penalty : int or tuple of int, optional
+        The gap penalty for sequence alignment.
+        A single value indicates a linear penalty, while a tuple
+        indicates an affine penalty.
+    min_anchors : int, optional
+        If less than `min_anchors` anchors are found by sequence
+        alignment, the method ditches the alignment and matches all
+        anchor atoms.
+        If the number of anchor atoms is not equal in `fixed` and
+        `mobile` in this fallback case, an exception is raised.
+        Furthermore, the outlier removal is stopped, if less than
+        `min_anchors` anchors would be left.
+    **kwargs
+        Additional parameters for
+        :func:`superimpose_without_outliers()`.
+
+    Returns
+    -------
+    fitted : AtomArray or AtomArrayStack
+        A copy of the `mobile` structure(s), superimposed on the fixed
+        structure(s).
+    transform : AffineTransformation
+        This object contains the affine transformation(s) that were
+        applied on `mobile`.
+        :meth:`AffineTransformation.apply()` can be used to transform
+        another AtomArray in the same way.
+    fixed_anchor_indices, mobile_anchor_indices : ndarray, shape(k,), dtype=int
+        The indices of the anchor atoms in the fixed and mobile
+        structure, respectively.
+        These atoms were used for the superimposition.
+
+    See Also
+    --------
+    superimpose : Superimposition without outlier removal
+    superimpose_without_outliers : Internally used for outlier removal
+
+    Notes
+    -----
+    As this method relies on sequence alignment, it works only for
+    proteins/nucleic acids with decent sequence homology.
     """
-    # Calculating rotation matrix
-    y = mob_centered
-    x = fix_centered
-    # Calculate covariance matrix
-    cov = np.dot(x.T, y)
-    v, s, w = np.linalg.svd(cov)
-    # Remove possibility of reflected atom coordinates
-    if np.linalg.det(v) * np.linalg.det(w) < 0:
-        v[:,-1] *= -1
-    rotation = np.dot(v,w)
-    return rotation
+    fixed_anchor_indices = _get_backbone_anchor_indices(fixed)
+    mobile_anchor_indices = _get_backbone_anchor_indices(mobile)
+    if (
+        len(fixed_anchor_indices) < min_anchors or
+        len(mobile_anchor_indices) < min_anchors
+    ):
+        raise ValueError(
+            "Structures have too few CA atoms for required number of anchors"
+        )
+
+    anchor_indices = _find_matching_anchors(
+        fixed[..., fixed_anchor_indices],
+        mobile[..., mobile_anchor_indices],
+        substitution_matrix,
+        gap_penalty,
+    )
+    if len(anchor_indices) < min_anchors:
+        # Fallback: Match all backbone anchors
+        if len(fixed_anchor_indices) != len(mobile_anchor_indices):
+            raise ValueError(
+                "Tried fallback due to low anchor number, "
+                "but number of CA atoms does not match"
+            )
+        fixed_anchor_indices = fixed_anchor_indices
+        mobile_anchor_indices = mobile_anchor_indices
+    else:
+        # The anchor indices point to the CA atoms
+        # -> get the corresponding indices for the whole structure
+        fixed_anchor_indices = fixed_anchor_indices[anchor_indices[:, 0]]
+        mobile_anchor_indices = mobile_anchor_indices[anchor_indices[:, 1]]
+
+    _, transform, selected_anchor_indices = superimpose_without_outliers(
+        fixed[..., fixed_anchor_indices],
+        mobile[..., mobile_anchor_indices],
+        min_anchors,
+        **kwargs
+    )
+    fixed_anchor_indices = fixed_anchor_indices[selected_anchor_indices]
+    mobile_anchor_indices = mobile_anchor_indices[selected_anchor_indices]
+
+    return (
+        transform.apply(mobile),
+        transform,
+        fixed_anchor_indices,
+        mobile_anchor_indices,
+    )
 
 
 def superimpose_apply(atoms, transformation):
     """
-    Superimpose structures using a given transformation tuple.
-    
-    The transformation tuple is obtained by prior superimposition.
-    
+    Superimpose structures using a given :class:`AffineTransformation`.
+
+    The :class:`AffineTransformation` can be obtained by prior
+    superimposition.
+
+    DEPRECATED: Use :func:`AffineTransformation.apply()` instead.
+
     Parameters
     ----------
     atoms : AtomArray or ndarray, shape(n,), dtype=float
         The structure to apply the transformation on.
         Alternatively coordinates can be given.
-    transformation: tuple, size=3
-        The transformation tuple, obtained by :func:`superimpose()`.
-    
+    transformation: AffineTransformation
+        The transformation, obtained by :func:`superimpose()`.
+
     Returns
     -------
     fitted : AtomArray or AtomArrayStack
@@ -206,20 +599,129 @@ def superimpose_apply(atoms, transformation):
         with transformations applied.
         Only coordinates are returned, if coordinates were given in
         `atoms`.
-    
+
     See Also
     --------
     superimpose
     """
-    trans1, rot, trans2 = transformation
-    s_coord = coord(atoms).copy()
-    s_coord += trans1
-    s_coord = np.dot(rot, s_coord.T).T
-    s_coord += trans2
+    return transformation.apply(atoms)
+
 
-    if isinstance(atoms, np.ndarray):
-        return s_coord
+def _reshape_to_3d(coord):
+    """
+    Reshape the coordinate array to 3D, if it is 2D.
+    """
+    if coord.ndim < 2:
+        raise ValueError(
+            "Coordinates must be at least two-dimensional"
+        )
+    if coord.ndim == 2:
+        return coord[np.newaxis, ...]
+    elif coord.ndim == 3:
+        return coord
     else:
-        transformed = atoms.copy()
-        transformed.coord = s_coord
-        return transformed
+        raise ValueError(
+            "Coordinates must be at most three-dimensional"
+        )
+
+
+def _get_rotation_matrices(fixed, mobile):
+    """
+    Get the rotation matrices to superimpose the given mobile
+    coordinates into the given fixed coordinates, minimizing the RMSD.
+
+    Uses the *Kabsch* algorithm.
+    Both sets of coordinates must already be centered at origin.
+    """
+    # Calculate cross-covariance matrices
+    cov = np.sum(fixed[:,:,:,np.newaxis] * mobile[:,:,np.newaxis,:], axis=1)
+    v, s, w = np.linalg.svd(cov)
+    # Remove possibility of reflected atom coordinates
+    reflected_mask = (np.linalg.det(v) * np.linalg.det(w) < 0)
+    v[reflected_mask, :, -1] *= -1
+    matrices = np.matmul(v, w)
+    return matrices
+
+
+def _multi_matmul(matrices, vectors):
+    """
+    Calculate the matrix multiplication of m matrices
+    with m x n vectors.
+    """
+    return np.transpose(
+        np.matmul(
+            matrices,
+            np.transpose(vectors, axes=(0, 2, 1))
+        ),
+        axes=(0, 2, 1)
+    )
+
+
+def _get_backbone_anchor_indices(atoms):
+    """
+    Select one representative anchor atom for each amino acid and
+    nucleotide and return their indices.
+    """
+    return np.where(
+        ((filter_amino_acids(atoms)) & (atoms.atom_name == "CA")) |
+        ((filter_nucleotides(atoms)) & (atoms.atom_name == "P"))
+    )[0]
+
+
+def _find_matching_anchors(
+    fixed_anchor_atoms,
+    mobile_anchors_atoms,
+    substitution_matrix,
+    gap_penalty,
+):
+    """
+    Find corresponding residues using pairwise sequence alignment.
+    """
+    fixed_seq = _to_sequence(fixed_anchor_atoms)
+    mobile_seq = _to_sequence(mobile_anchors_atoms)
+    common_alph = common_alphabet([fixed_seq.alphabet, mobile_seq.alphabet])
+    if common_alph is None:
+        raise ValueError("Cannot superimpose peptides with nucleic acids")
+
+    if substitution_matrix is None:
+        if isinstance(fixed_seq, ProteinSequence):
+            substitution_matrix = SubstitutionMatrix.std_protein_matrix()
+        else:
+            substitution_matrix = SubstitutionMatrix.std_nucleotide_matrix()
+    elif isinstance(substitution_matrix, str):
+        substitution_matrix = SubstitutionMatrix(
+            common_alph, common_alph, substitution_matrix
+        )
+    score_matrix = substitution_matrix.score_matrix()
+
+    alignment = align_optimal(
+        fixed_seq,
+        mobile_seq,
+        substitution_matrix,
+        gap_penalty,
+        terminal_penalty=False,
+        max_number=1,
+    )[0]
+    alignment_codes = get_codes(alignment)
+    anchor_mask = (
+        # Anchors must be similar amino acids
+        (score_matrix[alignment_codes[0], alignment_codes[1]] > 0)
+        # Cannot anchor gaps
+        & (alignment_codes[0] != -1)
+        & (alignment_codes[1] != -1)
+    )
+    anchors = alignment.trace[anchor_mask]
+    return anchors
+
+
+def _to_sequence(atoms):
+    sequences, _ = to_sequence(atoms, allow_hetero=True)
+    if len(sequences) == 0:
+        raise ValueError(
+            "Structure does not contain any amino acids or nucleotides"
+        )
+    if len(sequences) > 1:
+        raise ValueError(
+            "Structure contains multiple chains, but only one is allowed"
+        )
+    return sequences[0]