biotite 0.41.2__cp312-cp312-macosx_11_0_arm64.whl → 1.0.0__cp312-cp312-macosx_11_0_arm64.whl

biotite/structure/sse.py

@@ -12,51 +12,43 @@ __author__ = "Patrick Kunzmann"
 __all__ = ["annotate_sse"]
 
 import numpy as np
-from .celllist import CellList
-from .geometry import distance, angle, dihedral
-from .filter import filter_amino_acids
-from .residues import get_residue_starts
-from .integrity import check_res_id_continuity
+from biotite.structure.celllist import CellList
+from biotite.structure.filter import filter_amino_acids
+from biotite.structure.geometry import angle, dihedral, distance
+from biotite.structure.integrity import check_res_id_continuity
+from biotite.structure.residues import get_residue_starts
 
+_r_helix = (np.deg2rad(89 - 12), np.deg2rad(89 + 12))
+_a_helix = (np.deg2rad(50 - 20), np.deg2rad(50 + 20))
+_d2_helix = ((5.5 - 0.5), (5.5 + 0.5))  # Not used in the algorithm description
+_d3_helix = ((5.3 - 0.5), (5.3 + 0.5))
+_d4_helix = ((6.4 - 0.6), (6.4 + 0.6))
 
-_r_helix = (np.deg2rad(89-12), np.deg2rad(89+12))
-_a_helix = (np.deg2rad(50-20), np.deg2rad(50+20))
-_d2_helix = ((5.5-0.5), (5.5+0.5)) # Not used in the algorithm description
-_d3_helix = ((5.3-0.5), (5.3+0.5))
-_d4_helix = ((6.4-0.6), (6.4+0.6))
+_r_strand = (np.deg2rad(124 - 14), np.deg2rad(124 + 14))
+_a_strand = (np.deg2rad(-180), np.deg2rad(-125), np.deg2rad(145), np.deg2rad(180))
+_d2_strand = ((6.7 - 0.6), (6.7 + 0.6))
+_d3_strand = ((9.9 - 0.9), (9.9 + 0.9))
+_d4_strand = ((12.4 - 1.1), (12.4 + 1.1))
 
-_r_strand = (np.deg2rad(124-14), np.deg2rad(124+14))
-_a_strand = (np.deg2rad(-180), np.deg2rad(-125),
-             np.deg2rad(145), np.deg2rad(180))
-_d2_strand = ((6.7-0.6), (6.7+0.6))
-_d3_strand = ((9.9-0.9), (9.9+0.9))
-_d4_strand = ((12.4-1.1), (12.4+1.1))
 
-
-def annotate_sse(atom_array, chain_id=None):
+def annotate_sse(atom_array):
     r"""
     Calculate the secondary structure elements (SSEs) of a
     peptide chain based on the `P-SEA` algorithm.
     :footcite:`Labesse1997`
-    
+
     The annotation is based CA coordinates only, specifically
     distances and dihedral angles.
     Discontinuities between chains are detected by residue ID.
-    
+
     Parameters
     ----------
     atom_array : AtomArray
         The atom array to annotate for.
         Non-peptide residues are also allowed and obtain a ``''``
         SSE.
-    chain_id : str, optional
-        The peptide atoms belonging to this chain are filtered and
-        annotated.
-        DEPRECATED: By now multiple chains can be annotated at once.
-        To annotate only a certain chain, filter the `atom_array` before
-        giving it as input to this function.
-
-    
+
+
     Returns
     -------
     sse : ndarray
@@ -67,37 +59,30 @@ def annotate_sse(atom_array, chain_id=None):
         :math:`{\beta}`-strand/sheet, ``'c'`` means coil.
         ``''`` indicates that a residue is not an amino acid or it
         comprises no ``CA`` atom.
-    
+
     Notes
     -----
     Although this function is based on the original `P-SEA` algorithm,
     there are deviations compared to the official `P-SEA` software in
     some cases.
     Do not rely on getting the exact same results.
-    
+
     References
     ----------
 
     .. footbibliography::
-    
+
     Examples
     --------
-    
+
     SSE of PDB 1L2Y:
-    
-    >>> sse = annotate_sse(atom_array, "A")
+
+    >>> sse = 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']
-    
-    """
-    if chain_id is not None:
-        # Filter all CA atoms in the relevant chain
-        atom_array = atom_array[
-            (atom_array.chain_id == chain_id) & filter_amino_acids(atom_array)
-        ]
-    
 
+    """
     residue_starts = get_residue_starts(atom_array)
     # Sort CA coord into the coord array at the respective residue index
     # If a residue has no CA, e.g. because it is not an amino acid,
@@ -106,9 +91,9 @@ def annotate_sse(atom_array, chain_id=None):
     ca_indices = np.where(
         filter_amino_acids(atom_array) & (atom_array.atom_name == "CA")
     )[0]
-    ca_coord[
-        np.searchsorted(residue_starts, ca_indices, "right") - 1
-    ] = atom_array.coord[ca_indices]
+    ca_coord[np.searchsorted(residue_starts, ca_indices, "right") - 1] = (
+        atom_array.coord[ca_indices]
+    )
 
     if len(ca_coord) <= 5:
         # The number of atoms is too small #
@@ -125,12 +110,12 @@ def annotate_sse(atom_array, chain_id=None):
     # purpose of geometric measurements
     # -> the distances/angles spanning discontinuities are NaN
     discont_indices = check_res_id_continuity(atom_array)
-    discont_res_indices = np.searchsorted(
-        residue_starts, discont_indices, "right"
-    ) - 1
+    discont_res_indices = np.searchsorted(residue_starts, discont_indices, "right") - 1
     ca_coord = np.insert(
-        ca_coord, discont_res_indices,
-        np.full((len(discont_res_indices),3), np.nan), axis=0
+        ca_coord,
+        discont_res_indices,
+        np.full((len(discont_res_indices), 3), np.nan),
+        axis=0,
     )
     # Later the SSE for virtual residues are removed again
     # via this mask
@@ -139,73 +124,74 @@ def annotate_sse(atom_array, chain_id=None):
 
     length = len(ca_coord)
 
-
     # The distances and angles are not defined for the entire interval,
     # therefore the indices do not have the full range
     # Values that are not defined are NaN
     d2i = np.full(length, np.nan)
     d3i = np.full(length, np.nan)
     d4i = np.full(length, np.nan)
-    ri  = np.full(length, np.nan)
-    ai  = np.full(length, np.nan)
-
-    d2i[1 : length-1] = distance(ca_coord[0 : length-2], ca_coord[2 : length])
-    d3i[1 : length-2] = distance(ca_coord[0 : length-3], ca_coord[3 : length])
-    d4i[1 : length-3] = distance(ca_coord[0 : length-4], ca_coord[4 : length])
-    ri[1 : length-1]  = angle(
-        ca_coord[0 : length-2],
-        ca_coord[1 : length-1],
-        ca_coord[2 : length]
+    ri = np.full(length, np.nan)
+    ai = np.full(length, np.nan)
+
+    d2i[1 : length - 1] = distance(ca_coord[0 : length - 2], ca_coord[2:length])
+    d3i[1 : length - 2] = distance(ca_coord[0 : length - 3], ca_coord[3:length])
+    d4i[1 : length - 3] = distance(ca_coord[0 : length - 4], ca_coord[4:length])
+    ri[1 : length - 1] = angle(
+        ca_coord[0 : length - 2], ca_coord[1 : length - 1], ca_coord[2:length]
     )
-    ai[1 : length-2] = dihedral(
-        ca_coord[0 : length-3],
-        ca_coord[1 : length-2],
-        ca_coord[2 : length-1],
-        ca_coord[3 : length-0]
+    ai[1 : length - 2] = dihedral(
+        ca_coord[0 : length - 3],
+        ca_coord[1 : length - 2],
+        ca_coord[2 : length - 1],
+        ca_coord[3 : length - 0],
     )
-    
+
     # Find CA that meet criteria for potential helices and strands
-    relaxed_helix = (
-        (d3i >= _d3_helix[0]) & (d3i <= _d3_helix[1])
-    ) | (
-        (ri  >= _r_helix[0] ) & ( ri <=  _r_helix[1])
+    relaxed_helix = ((d3i >= _d3_helix[0]) & (d3i <= _d3_helix[1])) | (
+        (ri >= _r_helix[0]) & (ri <= _r_helix[1])
     )
     strict_helix = (
-        (d3i >= _d3_helix[0]) & (d3i <= _d3_helix[1]) &
-        (d4i >= _d4_helix[0]) & (d4i <= _d4_helix[1])
+        (d3i >= _d3_helix[0])
+        & (d3i <= _d3_helix[1])
+        & (d4i >= _d4_helix[0])
+        & (d4i <= _d4_helix[1])
     ) | (
-        (ri  >= _r_helix[0] ) & ( ri <=  _r_helix[1]) &
-        (ai  >= _a_helix[0] ) & ( ai <=  _a_helix[1])
+        (ri >= _r_helix[0])
+        & (ri <= _r_helix[1])
+        & (ai >= _a_helix[0])
+        & (ai <= _a_helix[1])
     )
 
     relaxed_strand = (d3i >= _d3_strand[0]) & (d3i <= _d3_strand[1])
     strict_strand = (
-        (d2i >= _d2_strand[0]) & (d2i <= _d2_strand[1]) &
-        (d3i >= _d3_strand[0]) & (d3i <= _d3_strand[1]) &
-        (d4i >= _d4_strand[0]) & (d4i <= _d4_strand[1])
+        (d2i >= _d2_strand[0])
+        & (d2i <= _d2_strand[1])
+        & (d3i >= _d3_strand[0])
+        & (d3i <= _d3_strand[1])
+        & (d4i >= _d4_strand[0])
+        & (d4i <= _d4_strand[1])
     ) | (
-        (ri  >= _r_strand[0] ) & ( ri <=  _r_strand[1]) &
-        (
+        (ri >= _r_strand[0])
+        & (ri <= _r_strand[1])
+        & (
             # Account for periodic boundary of dihedral angle
-            ((ai  >= _a_strand[0] ) & ( ai <=  _a_strand[1])) |
-            ((ai  >= _a_strand[2] ) & ( ai <=  _a_strand[3]))
+            ((ai >= _a_strand[0]) & (ai <= _a_strand[1]))
+            | ((ai >= _a_strand[2]) & (ai <= _a_strand[3]))
         )
     )
 
-
     helix_mask = _mask_consecutive(strict_helix, 5)
     helix_mask = _extend_region(helix_mask, relaxed_helix)
-    
+
     strand_mask = _mask_consecutive(strict_strand, 4)
     short_strand_mask = _mask_regions_with_contacts(
         ca_coord,
         _mask_consecutive(strict_strand, 3),
-        min_contacts=5, min_distance=4.2, max_distance=5.2
-    )
-    strand_mask = _extend_region(
-        strand_mask | short_strand_mask, relaxed_strand
+        min_contacts=5,
+        min_distance=4.2,
+        max_distance=5.2,
     )
-
+    strand_mask = _extend_region(strand_mask | short_strand_mask, relaxed_strand)
 
     sse = np.full(length, "c", dtype="U1")
     sse[helix_mask] = "a"
@@ -215,7 +201,7 @@ def annotate_sse(atom_array, chain_id=None):
     sse[np.isnan(ca_coord).any(axis=-1)] = ""
     # Remove SSE for virtual atoms and return
     return sse[no_virtual_mask]
-            
+
 
 def _mask_consecutive(mask, number):
     """
@@ -228,17 +214,17 @@ def _mask_consecutive(mask, number):
     # if it and the following `number-1` elements are True
     # The elements `mask[-(number-1):]` cannot have the sufficient count
     # by this definition, as they are at the end of the array
-    counts = np.zeros(len(mask) - (number-1), dtype=int)
+    counts = np.zeros(len(mask) - (number - 1), dtype=int)
     for i in range(number):
         counts[mask[i : i + len(counts)]] += 1
-    consecutive_seed = (counts == number)
-    
+    consecutive_seed = counts == number
+
     # Not only that element, but also the
     # following `number-1` elements are in a consecutive region
     consecutive_mask = np.zeros(len(mask), dtype=bool)
     for i in range(number):
         consecutive_mask[i : i + len(consecutive_seed)] |= consecutive_seed
-    
+
     return consecutive_mask
 
 
@@ -253,7 +239,7 @@ def _extend_region(base_condition_mask, extension_condition_mask):
     # Prepend absent region to the start to capture the event,
     # that the first element is already the start of a region
     region_change_mask = np.diff(np.append([False], base_condition_mask))
-    
+
     # These masks point to the first `False` element
     # left and right of a 'True' region
     # The left end is the element before the first element of a 'True' region
@@ -262,7 +248,7 @@ def _extend_region(base_condition_mask, extension_condition_mask):
     left_end_mask = np.append(left_end_mask[1:], [False])
     # The right end is first element of a 'False' region
     right_end_mask = region_change_mask & ~base_condition_mask
-    
+
     # The 'base_condition_mask' gets additional 'True' elements
     # at left or right ends, which meet the extension criterion
     return base_condition_mask | (
@@ -270,8 +256,9 @@ def _extend_region(base_condition_mask, extension_condition_mask):
     )
 
 
-def _mask_regions_with_contacts(coord, candidate_mask,
-                               min_contacts, min_distance, max_distance):
+def _mask_regions_with_contacts(
+    coord, candidate_mask, min_contacts, min_distance, max_distance
+):
     """
     Mask regions of `candidate_mask` that have at least `min_contacts`
     contacts with `coord` in the range `min_distance` to `max_distance`.
@@ -281,47 +268,41 @@ def _mask_regions_with_contacts(coord, candidate_mask,
         # No potential contacts -> no contacts
         # -> no residue can satisfy 'min_contacts'
         return np.zeros(len(candidate_mask), dtype=bool)
-    
-    cell_list = CellList(
-        potential_contact_coord, max_distance
-    )
+
+    cell_list = CellList(potential_contact_coord, max_distance)
     # For each candidate position,
     # get all contacts within maximum distance
     all_within_max_dist_indices = cell_list.get_atoms(
         coord[candidate_mask], max_distance
     )
-   
+
     contacts = np.zeros(len(coord), dtype=int)
     for i, atom_index in enumerate(np.where(candidate_mask)[0]):
         within_max_dist_indices = all_within_max_dist_indices[i]
         # Remove padding values
-        within_max_dist_indices = within_max_dist_indices[
-            within_max_dist_indices != -1
-        ]
-        # Now count all contacts within maximum distance 
+        within_max_dist_indices = within_max_dist_indices[within_max_dist_indices != -1]
+        # Now count all contacts within maximum distance
         # that also satisfy the minimum distance
         contacts[atom_index] = np.count_nonzero(
             distance(
-                coord[atom_index],
-                potential_contact_coord[within_max_dist_indices]
-            ) > min_distance
+                coord[atom_index], potential_contact_coord[within_max_dist_indices]
+            )
+            > min_distance
         )
-    
+
     # Count the number of contacts per region
     # These indices mark the start of either a 'True' or 'False' region
     # Prepend absent region to the start to capture the event,
     # that the first element is already the start of a region
-    region_change_indices = np.where(
-        np.diff(np.append([False], candidate_mask))
-    )[0]
+    region_change_indices = np.where(np.diff(np.append([False], candidate_mask)))[0]
     # Add exclusive stop
     region_change_indices = np.append(region_change_indices, [len(coord)])
     output_mask = np.zeros(len(candidate_mask), dtype=bool)
     for i in range(len(region_change_indices) - 1):
         start = region_change_indices[i]
-        stop = region_change_indices[i+1]
-        total_contacts = np.sum(contacts[start : stop])
+        stop = region_change_indices[i + 1]
+        total_contacts = np.sum(contacts[start:stop])
         if total_contacts >= min_contacts:
-            output_mask[start : stop] = True
-    
-    return output_mask
+            output_mask[start:stop] = True
+
+    return output_mask

biotite/structure/superimpose.py

@@ -8,19 +8,22 @@ This module provides functions for structure superimposition.
 
 __name__ = "biotite.structure"
 __author__ = "Patrick Kunzmann, Claude J. Rogers"
-__all__ = ["superimpose", "superimpose_homologs",
-           "superimpose_without_outliers",
-           "AffineTransformation", "superimpose_apply"]
+__all__ = [
+    "superimpose",
+    "superimpose_homologs",
+    "superimpose_without_outliers",
+    "AffineTransformation",
+]
 
 
 import numpy as np
-from .atoms import coord
-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
+from biotite.sequence.align import SubstitutionMatrix, align_optimal, get_codes
+from biotite.sequence.alphabet import common_alphabet
+from biotite.sequence.seqtypes import ProteinSequence
+from biotite.structure.atoms import coord
+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:
@@ -45,12 +48,12 @@ class AffineTransformation:
         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.
@@ -118,7 +121,6 @@ class AffineTransformation:
             superimposed.coord = superimposed_coord
             return superimposed
 
-
     def as_matrix(self):
         """
         Get the translations and rotation as a combined 4x4
@@ -316,16 +318,19 @@ def superimpose(fixed, mobile, atom_mask=None):
     mob_centered_filtered = mob_filtered - mob_centroid[:, np.newaxis, :]
     fix_centered_filtered = fix_filtered - fix_centroid[:, np.newaxis, :]
 
-    rotation = _get_rotation_matrices(
-        fix_centered_filtered, mob_centered_filtered
-    )
+    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):
+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.
@@ -458,8 +463,9 @@ def superimpose_without_outliers(fixed, mobile, min_anchors=3,
     return transform.apply(mobile), transform, anchor_indices
 
 
-def superimpose_homologs(fixed, mobile, substitution_matrix=None,
-                         gap_penalty=-10, min_anchors=3, **kwargs):
+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.
@@ -530,8 +536,8 @@ def superimpose_homologs(fixed, mobile, substitution_matrix=None,
     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
+        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"
@@ -562,7 +568,7 @@ def superimpose_homologs(fixed, mobile, substitution_matrix=None,
         fixed[..., fixed_anchor_indices],
         mobile[..., mobile_anchor_indices],
         min_anchors,
-        **kwargs
+        **kwargs,
     )
     fixed_anchor_indices = fixed_anchor_indices[selected_anchor_indices]
     mobile_anchor_indices = mobile_anchor_indices[selected_anchor_indices]
@@ -575,54 +581,18 @@ def superimpose_homologs(fixed, mobile, substitution_matrix=None,
     )
 
 
-def superimpose_apply(atoms, transformation):
-    """
-    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: AffineTransformation
-        The transformation, obtained by :func:`superimpose()`.
-
-    Returns
-    -------
-    fitted : AtomArray or AtomArrayStack
-        A copy of the `atoms` structure,
-        with transformations applied.
-        Only coordinates are returned, if coordinates were given in
-        `atoms`.
-
-    See Also
-    --------
-    superimpose
-    """
-    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"
-        )
+        raise ValueError("Coordinates must be at least two-dimensional")
     if coord.ndim == 2:
         return coord[np.newaxis, ...]
     elif coord.ndim == 3:
         return coord
     else:
-        raise ValueError(
-            "Coordinates must be at most three-dimensional"
-        )
+        raise ValueError("Coordinates must be at most three-dimensional")
 
 
 def _get_rotation_matrices(fixed, mobile):
@@ -634,10 +604,10 @@ def _get_rotation_matrices(fixed, mobile):
     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)
+    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)
+    reflected_mask = np.linalg.det(v) * np.linalg.det(w) < 0
     v[reflected_mask, :, -1] *= -1
     matrices = np.matmul(v, w)
     return matrices
@@ -649,11 +619,7 @@ def _multi_matmul(matrices, vectors):
     with m x n vectors.
     """
     return np.transpose(
-        np.matmul(
-            matrices,
-            np.transpose(vectors, axes=(0, 2, 1))
-        ),
-        axes=(0, 2, 1)
+        np.matmul(matrices, np.transpose(vectors, axes=(0, 2, 1))), axes=(0, 2, 1)
     )
 
 
@@ -663,8 +629,8 @@ def _get_backbone_anchor_indices(atoms):
     nucleotide and return their indices.
     """
     return np.where(
-        ((filter_amino_acids(atoms)) & (atoms.atom_name == "CA")) |
-        ((filter_nucleotides(atoms)) & (atoms.atom_name == "P"))
+        ((filter_amino_acids(atoms)) & (atoms.atom_name == "CA"))
+        | ((filter_nucleotides(atoms)) & (atoms.atom_name == "P"))
     )[0]
 
 
@@ -717,11 +683,7 @@ def _find_matching_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"
-        )
+        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]
+        raise ValueError("Structure contains multiple chains, but only one is allowed")
+    return sequences[0]