biotite 0.39.0__cp311-cp311-win_amd64.whl → 0.40.0__cp311-cp311-win_amd64.whl

biotite/structure/superimpose.py

@@ -8,24 +8,86 @@ This module provides functions for structure superimposition.
 
 __name__ = "biotite.structure"
 __author__ = "Patrick Kunzmann, Claude J. Rogers"
-__all__ = ["superimpose", "superimpose_apply"]
+__all__ = ["superimpose", "superimpose_apply", "AffineTransformation"]
+
 
 import numpy as np
 from .atoms import coord
 from .geometry import centroid
 
 
+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.
+    """
+    def __init__(self, center_translation, rotation, target_translation):
+        self.center_translation = center_translation
+        self.rotation = rotation
+        self.target_translation = target_translation
+
+
+    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`.
+        """
+        mobile_coord = coord(atoms)
+        original_shape = mobile_coord.shape
+        mobile_coord = _reshape_to_3d(mobile_coord)
+
+        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 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.
-    
+
     Parameters
     ----------
-    fixed : AtomArray, shape(n,) or ndarray, shape(n,), dtype=float
+    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.
         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
@@ -41,7 +103,7 @@ 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
@@ -49,54 +111,43 @@ def superimpose(fixed, mobile, atom_mask=None):
         superimposed on the fixed structure.
         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.
-    
-    See Also
-    --------
-    superimpose_apply
-    
+    transformation : 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.
+
     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 +161,48 @@ 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(fix_centered, mob_centered):
-    """
-    Perform the Kabsch algorithm using only the coordinates.
+def superimpose_apply(atoms, transformation):
     """
-    # 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
+    Superimpose structures using a given :class:`AffineTransformation`.
 
+    The :class:`AffineTransformation` can be obtained by prior
+    superimposition.
+
+    DEPRECATED: Use :func:`AffineTransformation.apply()` instead.
 
-def superimpose_apply(atoms, transformation):
-    """
-    Superimpose structures using a given transformation tuple.
-    
-    The transformation tuple is obtained by prior superimposition.
-    
     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 +210,59 @@ 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
-
-    if isinstance(atoms, np.ndarray):
-        return s_coord
+    return transformation.apply(atoms)
+
+
+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)
+    )

{biotite-0.39.0.dist-info → biotite-0.40.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: biotite
-Version: 0.39.0
+Version: 0.40.0
 Summary: A comprehensive library for computational molecular biology
 Author: The Biotite contributors
 License: BSD 3-Clause License
@@ -52,7 +52,7 @@ Requires-Python: >=3.7
 Description-Content-Type: text/x-rst
 License-File: LICENSE.rst
 Requires-Dist: requests >=2.12
-Requires-Dist: numpy >=1.14.5
+Requires-Dist: numpy <=2.0,>=1.14.5
 Requires-Dist: msgpack >=0.5.6
 Requires-Dist: networkx >=2.0
 Provides-Extra: test