biotite 1.1.0__cp311-cp311-macosx_11_0_arm64.whl → 1.3.0__cp311-cp311-macosx_11_0_arm64.whl

biotite/structure/spacegroups.license

@@ -0,0 +1,26 @@
+The transformations in 'spacegroups.json' are adapted from
+'molstar/src/mol-math/geometry/spacegroup/tables.ts' from the Mol* project
+(https://github.com/molstar/molstar) governed by the following license:
+
+
+The MIT License
+
+    Copyright (c) 2017 - now, Mol* contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

biotite/structure/sse.py

@@ -48,7 +48,6 @@ def annotate_sse(atom_array):
         Non-peptide residues are also allowed and obtain a ``''``
         SSE.
 
-
     Returns
     -------
     sse : ndarray
@@ -81,7 +80,6 @@ def annotate_sse(atom_array):
     >>> print(sse)
     ['c' 'a' 'a' 'a' 'a' 'a' 'a' 'a' 'a' 'c' 'c' 'c' 'c' 'c' 'c' 'c' 'c' 'c'
      'c' 'c']
-
     """
     residue_starts = get_residue_starts(atom_array)
     # Sort CA coord into the coord array at the respective residue index

biotite/structure/superimpose.py

@@ -12,200 +12,21 @@ __all__ = [
     "superimpose",
     "superimpose_homologs",
     "superimpose_without_outliers",
-    "AffineTransformation",
 ]
 
 
 import numpy as np
-from biotite.sequence.align import SubstitutionMatrix, align_optimal, get_codes
+from biotite.sequence.align.alignment import get_codes, remove_gaps
+from biotite.sequence.align.matrix import SubstitutionMatrix
+from biotite.sequence.align.pairwise import align_optimal
 from biotite.sequence.alphabet import common_alphabet
 from biotite.sequence.seqtypes import ProteinSequence
 from biotite.structure.atoms import coord
+from biotite.structure.chains import chain_iter
 from biotite.structure.filter import filter_amino_acids, filter_nucleotides
 from biotite.structure.geometry import centroid, distance
 from biotite.structure.sequence import to_sequence
-
-
-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
+from biotite.structure.transform import AffineTransformation
 
 
 def superimpose(fixed, mobile, atom_mask=None):
@@ -222,7 +43,7 @@ def superimpose(fixed, mobile, atom_mask=None):
     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
+    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
@@ -231,7 +52,7 @@ def superimpose(fixed, mobile, atom_mask=None):
         :class:`AtomArrayStack` objects, they must have the same
         number of models.
         Alternatively coordinates can be given.
-    atom_mask: ndarray, dtype=bool, optional
+    atom_mask : ndarray, dtype=bool, optional
         If given, only the atoms covered by this boolean mask will be
         considered for superimposition.
         This means that the algorithm will minimize the RMSD based
@@ -253,8 +74,8 @@ def superimpose(fixed, mobile, atom_mask=None):
 
     See Also
     --------
-    superimpose_without_outliers : Superimposition with outlier removal
-    superimpose_homologs : Superimposition of homologous structures
+    superimpose_without_outliers : Superimposition with outlier removal.
+    superimpose_homologs : Superimposition of homologous structures.
 
     Notes
     -----
@@ -340,13 +161,12 @@ def superimpose_without_outliers(
     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
+    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
@@ -389,8 +209,8 @@ def superimpose_without_outliers(
 
     See Also
     --------
-    superimpose : Superimposition without outlier removal
-    superimpose_homologs : Superimposition of homologous structures
+    superimpose : Superimposition without outlier removal.
+    superimpose_homologs : Superimposition of homologous structures.
 
     Notes
     -----
@@ -464,10 +284,16 @@ def superimpose_without_outliers(
 
 
 def superimpose_homologs(
-    fixed, mobile, substitution_matrix=None, gap_penalty=-10, min_anchors=3, **kwargs
+    fixed,
+    mobile,
+    substitution_matrix=None,
+    gap_penalty=-10,
+    min_anchors=3,
+    terminal_penalty=False,
+    **kwargs,
 ):
     r"""
-    Superimpose one protein or nucleotide chain onto another one,
+    Superimpose a protein or nucleotide structure onto another one,
     considering sequence differences and conformational outliers.
 
     The method finds corresponding residues by sequence alignment and
@@ -480,11 +306,11 @@ def superimpose_homologs(
     ----------
     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.
+        The structure(s) which is/are superimposed on the `fixed` structure.
+        Must contain the same number of chains as `fixed` with corresponding chains
+        being in the same order.
+        The specific chain IDs can be different.
     substitution_matrix : str or SubstitutionMatrix, optional
         The (name of the) substitution matrix used for sequence
         alignment.
@@ -504,6 +330,9 @@ def superimpose_homologs(
         `mobile` in this fallback case, an exception is raised.
         Furthermore, the outlier removal is stopped, if less than
         `min_anchors` anchors would be left.
+    terminal_penalty : bool, optional
+        If set to true, gap penalties are applied to terminal gaps in the sequence
+        alignment.
     **kwargs
         Additional parameters for
         :func:`superimpose_without_outliers()`.
@@ -525,8 +354,9 @@ def superimpose_homologs(
 
     See Also
     --------
-    superimpose : Superimposition without outlier removal
-    superimpose_without_outliers : Internally used for outlier removal
+    superimpose : Superimposition without outlier removal.
+    superimpose_without_outliers : Internally used for outlier removal.
+    superimpose_structural_homologs : Better suited for low sequence similarity.
 
     Notes
     -----
@@ -540,7 +370,7 @@ def superimpose_homologs(
         or len(mobile_anchor_indices) < min_anchors
     ):
         raise ValueError(
-            "Structures have too few CA atoms for required number of anchors"
+            "Structures have too few backbone atoms for required number of anchors"
         )
 
     anchor_indices = _find_matching_anchors(
@@ -548,18 +378,19 @@ def superimpose_homologs(
         mobile[..., mobile_anchor_indices],
         substitution_matrix,
         gap_penalty,
+        terminal_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"
+                "but number of backbone 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
+        # The anchor indices point to the backbone 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]]
@@ -613,16 +444,6 @@ def _get_rotation_matrices(fixed, mobile):
     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
@@ -639,51 +460,52 @@ def _find_matching_anchors(
     mobile_anchors_atoms,
     substitution_matrix,
     gap_penalty,
+    terminal_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()
+    anchor_list = []
+    fixed_seq_offset = 0
+    mobile_seq_offset = 0
+    for fixed_chain, mobile_chain in zip(
+        chain_iter(fixed_anchor_atoms), chain_iter(mobile_anchors_atoms), strict=True
+    ):
+        # The input is a single chain -> expect a single sequence
+        fixed_seq = to_sequence(fixed_chain, allow_hetero=True)[0][0]
+        mobile_seq = to_sequence(mobile_chain, allow_hetero=True)[0][0]
+
+        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
+            )
 
-    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)
+        alignment = align_optimal(
+            fixed_seq,
+            mobile_seq,
+            substitution_matrix,
+            gap_penalty,
+            terminal_penalty=terminal_penalty,
+            max_number=1,
+        )[0]
         # Cannot anchor gaps
-        & (alignment_codes[0] != -1)
-        & (alignment_codes[1] != -1)
-    )
-    anchors = alignment.trace[anchor_mask]
-    return anchors
+        alignment = remove_gaps(alignment)
+        ali_codes = get_codes(alignment)
+        score_matrix = substitution_matrix.score_matrix()
+        # Anchors must be similar amino acids
+        anchors = alignment.trace[score_matrix[ali_codes[0], ali_codes[1]] > 0]
 
+        anchors += fixed_seq_offset, mobile_seq_offset
+        fixed_seq_offset += len(fixed_seq)
+        mobile_seq_offset += len(mobile_seq)
+        anchor_list.append(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]
+    return np.concatenate(anchor_list, axis=0)