biotite 1.0.1__cp311-cp311-macosx_11_0_arm64.whl → 1.2.0__cp311-cp311-macosx_11_0_arm64.whl

biotite/structure/rings.py

@@ -0,0 +1,335 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+This module provides functions related to aromatic rings.
+"""
+
+__name__ = "biotite.structure"
+__author__ = "Patrick Kunzmann"
+__all__ = ["find_aromatic_rings", "find_stacking_interactions", "PiStacking"]
+
+
+from enum import IntEnum
+import networkx as nx
+import numpy as np
+from biotite.structure.bonds import BondType
+from biotite.structure.error import BadStructureError
+from biotite.structure.geometry import displacement
+from biotite.structure.util import norm_vector, vector_dot
+
+
+class PiStacking(IntEnum):
+    """
+    The type of pi-stacking interaction.
+
+    - ``PARALLEL``: parallel pi-stacking (also called *staggered* or *Sandwich*)
+    - ``PERPENDICULAR``: perpendicular pi-stacking (also called *T-shaped*)
+    """
+
+    PARALLEL = 0
+    PERPENDICULAR = 1
+
+
+def find_aromatic_rings(atoms):
+    """
+    Find (anti-)aromatic rings in a structure.
+
+    Parameters
+    ----------
+    atoms : AtomArray or AtomArrayStack
+        The atoms to be searched for aromatic rings.
+        Requires an associated :class:`BondList`.
+
+    Returns
+    -------
+    rings : list of ndarray
+        The indices of the atoms that form aromatic rings.
+        Each ring is represented by a list of indices.
+        Only rings with minimum size are returned, i.e. two connected rings
+        (e.g. in tryptophan) are reported as separate rings.
+
+    Notes
+    -----
+    This function does not distinguish between aromatic and antiaromatic rings.
+    All cycles containing atoms that are completely connected by aromatic bonds
+    are considered aromatic rings.
+
+    The PDB *Chemical Component Dictionary* (CCD) does not identify aromatic rings in
+    all compounds as such.
+    Prominent examples are the nucleobases, where the 6-membered rings are not
+    flagged as aromatic.
+
+    Examples
+    --------
+
+    >>> nad = residue("NAD")
+    >>> rings = find_aromatic_rings(nad)
+    >>> print(rings)
+    [array([41, 37, 36, 35, 43, 42]), array([19, 18, 16, 15, 21, 20]), array([12, 13, 14, 15, 21])]
+    >>> for atom_indices in rings:
+    ...     print(np.sort(nad.atom_name[atom_indices]))
+    ['C2N' 'C3N' 'C4N' 'C5N' 'C6N' 'N1N']
+    ['C2A' 'C4A' 'C5A' 'C6A' 'N1A' 'N3A']
+    ['C4A' 'C5A' 'C8A' 'N7A' 'N9A']
+    """
+    if atoms.bonds is None:
+        raise BadStructureError("Structure must have an associated BondList")
+    bond_array = atoms.bonds.as_array()
+    # To detect aromatic rings, only keep bonds that are aromatic
+    aromatic_bond_array = bond_array[
+        np.isin(
+            bond_array[:, 2],
+            [
+                BondType.AROMATIC,
+                BondType.AROMATIC_SINGLE,
+                BondType.AROMATIC_DOUBLE,
+                BondType.AROMATIC_TRIPLE,
+            ],
+        ),
+        # We can omit the bond type now
+        :2,
+    ]
+    aromatic_bond_graph = nx.from_edgelist(aromatic_bond_array.tolist())
+    # Find the cycles with minimum size -> cycle basis
+    rings = nx.cycle_basis(aromatic_bond_graph)
+    return [np.array(ring, dtype=int) for ring in rings]
+
+
+def find_stacking_interactions(
+    atoms,
+    centroid_cutoff=6.5,
+    plane_angle_tol=np.deg2rad(30.0),
+    shift_angle_tol=np.deg2rad(30.0),
+):
+    """
+    Find pi-stacking interactions between aromatic rings.
+
+    Parameters
+    ----------
+    atoms : AtomArray
+        The atoms to be searched for aromatic rings.
+        Requires an associated :class:`BondList`.
+    centroid_cutoff : float
+        The cutoff distance for ring centroids.
+    plane_angle_tol : float
+        The tolerance for the angle between ring planes that must be either
+        parallel or perpendicular.
+        Given in radians.
+    shift_angle_tol : float
+        The tolerance for the angle between the ring plane normals and the
+        centroid difference vector.
+        Given in radians.
+
+    Returns
+    -------
+    interactions : list of tuple(ndarray, ndarray, PiStacking)
+        The stacking interactions between aromatic rings.
+        Each element in the list represents one stacking interaction.
+        The first two elements of each tuple represent atom indices of the stacked
+        rings.
+        The third element of each tuple is the type of stacking interaction.
+
+    See Also
+    --------
+    find_aromatic_rings : Used for finding the aromatic rings in this function.
+
+    Notes
+    -----
+    This function does not distinguish between aromatic and antiaromatic rings.
+    Furthermore, it does not distinguish between repulsive and attractive stacking:
+    Usually, stacking two rings directly above each other is repulsive, as the pi
+    orbitals above the rings repel each other, so a slight horizontal shift is
+    usually required to make the interaction attractive.
+    However, in details this is strongly dependent on heteroatoms and the exact
+    orientation of the rings.
+    Hence, this function aggregates all stacking interactions to simplify the
+    conditions for pi-stacking.
+
+    The conditions for pi-stacking are :footcite:`Wojcikowski2015` :
+
+        - The ring centroids must be within cutoff distance (default: 6.5 Å).
+          While :footcite:`Wojcikowski2015` uses a cutoff of 5.0 Å, 6.5 Å was
+          adopted from :footcite:`Bouysset2021` to better identify perpendicular
+          stacking interactions.
+        - The planes must be parallel or perpendicular to each other within a default
+          tolerance of 30°.
+        - The angle between the plane normals and the centroid difference vector must be
+          be either 0° or 90° within a default tolerance of 30°, to check for lateral
+          shifts.
+
+    References
+    ----------
+
+    .. footbibliography::
+
+    Examples
+    --------
+
+    Detect base stacking interactions in a DNA helix
+
+    >>> from os.path import join
+    >>> dna_helix = load_structure(
+    ...     join(path_to_structures, "base_pairs", "1qxb.cif"), include_bonds=True
+    ... )
+    >>> interactions = find_stacking_interactions(dna_helix)
+    >>> for ring_atom_indices_1, ring_atom_indices_2, stacking_type in interactions:
+    ...     print(
+    ...         dna_helix.res_id[ring_atom_indices_1[0]],
+    ...         dna_helix.res_id[ring_atom_indices_2[0]],
+    ...         PiStacking(stacking_type).name
+    ...     )
+    17 18 PARALLEL
+    17 18 PARALLEL
+    5 6 PARALLEL
+    5 6 PARALLEL
+    5 6 PARALLEL
+    """
+    rings = find_aromatic_rings(atoms)
+    if len(rings) == 0:
+        return []
+
+    ring_centroids = np.array(
+        [atoms.coord[atom_indices].mean(axis=0) for atom_indices in rings]
+    )
+    ring_normals = np.array(
+        [_get_ring_normal(atoms.coord[atom_indices]) for atom_indices in rings]
+    )
+
+    # Create an index array that contains the Cartesian product of all rings
+    indices = np.stack(
+        [
+            np.repeat(np.arange(len(rings)), len(rings)),
+            np.tile(np.arange(len(rings)), len(rings)),
+        ],
+        axis=-1,
+    )
+    # Do not include duplicate pairs
+    indices = indices[indices[:, 0] > indices[:, 1]]
+
+    ## Condition 1: Ring centroids are close enough to each other
+    diff = displacement(ring_centroids[indices[:, 0]], ring_centroids[indices[:, 1]])
+    # Use squared distance to avoid time consuming sqrt computation
+    sq_distance = vector_dot(diff, diff)
+    is_interacting = sq_distance < centroid_cutoff**2
+    indices = indices[is_interacting]
+
+    ## Condition 2: Ring planes are parallel or perpendicular
+    plane_angles = _minimum_angle(
+        ring_normals[indices[:, 0]], ring_normals[indices[:, 1]]
+    )
+    is_parallel = _is_within_tolerance(plane_angles, 0, plane_angle_tol)
+    is_perpendicular = _is_within_tolerance(plane_angles, np.pi / 2, plane_angle_tol)
+    is_interacting = is_parallel | is_perpendicular
+    indices = indices[is_interacting]
+    # Keep in sync with the shape of the filtered indices,
+    # i.e. after filtering, `is_parallel==False` means a perpendicular interaction
+    is_parallel = is_parallel[is_interacting]
+
+    ## Condition 3: The ring centroids are not shifted too much
+    ## (in terms of normal-centroid angle)
+    diff = displacement(ring_centroids[indices[:, 0]], ring_centroids[indices[:, 1]])
+    norm_vector(diff)
+    angles = np.stack(
+        [_minimum_angle(ring_normals[indices[:, i]], diff) for i in range(2)]
+    )
+    is_interacting = (
+        # For parallel stacking, the lateral shift may not exceed the tolerance
+        (is_parallel & np.any(_is_within_tolerance(angles, 0, shift_angle_tol), axis=0))
+        # For perpendicular stacking, one ring must be above the other,
+        # but from the perspective of the other ring, the first ring is approximately
+        # in the same plane
+        | (
+            ~is_parallel
+            & (
+                (
+                    _is_within_tolerance(angles[0], 0, shift_angle_tol)
+                    & _is_within_tolerance(angles[1], np.pi / 2, shift_angle_tol)
+                )
+                | (
+                    _is_within_tolerance(angles[0], np.pi / 2, shift_angle_tol)
+                    & _is_within_tolerance(angles[1], 0, shift_angle_tol)
+                )
+            )
+        )
+    )
+    indices = indices[is_interacting]
+    is_parallel = is_parallel[is_interacting]
+
+    # Only return pairs of rings where all conditions were fulfilled
+    return [
+        (
+            rings[ring_i],
+            rings[ring_j],
+            PiStacking.PARALLEL if is_parallel[i] else PiStacking.PERPENDICULAR,
+        )
+        for i, (ring_i, ring_j) in enumerate(indices)
+    ]
+
+
+def _get_ring_normal(ring_coord):
+    """
+    Get the normal vector perpendicular to the ring plane.
+
+    Parameters
+    ----------
+    ring_coord : ndarray
+        The coordinates of the atoms in the ring.
+
+    Returns
+    -------
+    normal : ndarray
+        The normal vector of the ring plane.
+    """
+    # Simply use any three atoms in the ring to calculate the normal vector
+    # We can also safely assume that there are at least three atoms in the ring,
+    # as otherwise it would not be a ring
+    normal = np.cross(ring_coord[1] - ring_coord[0], ring_coord[2] - ring_coord[0])
+    norm_vector(normal)
+    return normal
+
+
+def _minimum_angle(v1, v2):
+    """
+    Get the minimum angle between two vectors, i.e. the possible angle range is
+    ``[0, pi/2]``.
+
+    Parameters
+    ----------
+    v1, v2 : ndarray, shape=(n,3), dtype=float
+        The vectors to measure the angle between.
+
+    Returns
+    -------
+    angle : ndarray, shape=(n,), dtype=float
+        The minimum angle between the two vectors.
+
+    Notes
+    -----
+    This restriction is added here as the normal vectors of the ring planes
+    have no 'preferred side'.
+    """
+    # Do not distinguish between the 'sides' of the rings -> take absolute of cosine
+    return np.arccos(np.abs(vector_dot(v1, v2)))
+
+
+def _is_within_tolerance(angles, expected_angle, tolerance):
+    """
+    Check if the angles are within a certain tolerance.
+
+    Parameters
+    ----------
+    angles : ndarray, shape=x, dtype=float
+        The angles to check.
+    expected_angle : float
+        The expected angle.
+    tolerance : float
+        The tolerance.
+
+    Returns
+    -------
+    is_within_tolerance : ndarray, shape=x, dtype=bool
+        True if the angles are within the tolerance, False otherwise.
+    """
+    return np.abs(angles - expected_angle) < tolerance

biotite/structure/sasa.pyx

@@ -83,7 +83,8 @@ def sasa(array, float probe_radius=1.4, np.ndarray atom_filter=None,
             - **Single** - A set, which uses a defined VdW radius for
               every single atom, therefore hydrogen atoms are required
               in the model (e.g. NMR elucidated structures).
-              :footcite:`Bondi1964`
+              Values for main group elements are taken from :footcite:`Mantina2009`,
+              and for relevant transition metals from the :footcite:`RDKit`.
               
         By default *ProtOr* is used.
               

biotite/structure/segments.py

@@ -16,7 +16,7 @@ __all__ = [
 import numpy as np
 
 
-def apply_segment_wise(starts, data, function, axis):
+def apply_segment_wise(starts, data, function, axis=None):
     """
     Generalized version of :func:`apply_residue_wise()` for
     residues and chains.
@@ -27,6 +27,22 @@ def apply_segment_wise(starts, data, function, axis):
         The sorted start indices of segments.
         Includes exclusive stop, i.e. the length of the corresponding
         atom array.
+    data : ndarray
+        The data, whose intervals are the parameter for `function`.
+        Must have same length as `array`.
+    function : function
+        The `function` must have either the form *f(data)* or
+        *f(data, axis)* in case `axis` is given. Every `function` call
+        must return a value with the same shape and data type.
+    axis : int, optional
+        This value is given to the `axis` parameter of `function`.
+
+    Returns
+    -------
+    processed_data : ndarray
+        Segment-wise evaluation of `data` by `function`.
+        The size of the first dimension of this array is equal to the amount of
+        residues.
     """
     # The result array
     processed_data = None
@@ -36,7 +52,6 @@ def apply_segment_wise(starts, data, function, axis):
             value = function(segment)
         else:
             value = function(segment, axis=axis)
-        value = function(segment, axis=axis)
         # Identify the shape of the resulting array by evaluation
         # of the function return value for the first segment
         if processed_data is None:
@@ -66,13 +81,19 @@ def spread_segment_wise(starts, input_data):
         The sorted start indices of segments.
         Includes exclusive stop, i.e. the length of the corresponding
         atom array.
+    input_data : ndarray
+        The data to be spread.
+        The length of the 0-th axis must be equal to the amount of different residue IDs
+        in `array`.
+
+    Returns
+    -------
+    output_data : ndarray
+        Segment-wise spread `input_data`.
+        Length is the same as `array_length()` of `array`.
     """
-    output_data = np.zeros(starts[-1], dtype=input_data.dtype)
-    for i in range(len(starts) - 1):
-        start = starts[i]
-        stop = starts[i + 1]
-        output_data[start:stop] = input_data[i]
-    return output_data
+    seg_lens = starts[1:] - starts[:-1]
+    return np.repeat(input_data, seg_lens, axis=0)
 
 
 def get_segment_masks(starts, indices):
@@ -86,6 +107,17 @@ def get_segment_masks(starts, indices):
         The sorted start indices of segments.
         Includes exclusive stop, i.e. the length of the corresponding
         atom array.
+    indices : ndarray, dtype=int, shape=(k,)
+        These indices indicate the atoms to get the corresponding
+        segments for.
+        Negative indices are not allowed.
+
+    Returns
+    -------
+    residues_masks : ndarray, dtype=bool, shape=(k,n)
+        Multiple boolean masks, one for each given index in `indices`.
+        Each array masks the atoms that belong to the same segment as
+        the atom at the given index.
     """
     indices = np.asarray(indices)
     length = starts[-1]
@@ -96,7 +128,7 @@ def get_segment_masks(starts, indices):
     if (indices >= length).any():
         index = np.min(np.where(indices >= length)[0])
         raise ValueError(
-            f"Index {index} is out of range for " f"an atom array with length {length}"
+            f"Index {index} is out of range for an atom array with length {length}"
         )
 
     insertion_points = np.searchsorted(starts, indices, side="right") - 1
@@ -117,6 +149,16 @@ def get_segment_starts_for(starts, indices):
         The sorted start indices of segments.
         Includes exclusive stop, i.e. the length of the corresponding
         atom array.
+    indices : ndarray, dtype=int, shape=(k,)
+        These indices point to the atoms to get the corresponding
+        segment starts for.
+        Negative indices are not allowed.
+
+    Returns
+    -------
+    start_indices : ndarray, dtype=int, shape=(k,)
+        The indices that point to the segment starts for the input
+        `indices`.
     """
     indices = np.asarray(indices)
     length = starts[-1]
@@ -128,7 +170,7 @@ def get_segment_starts_for(starts, indices):
     if (indices >= length).any():
         index = np.min(np.where(indices >= length)[0])
         raise ValueError(
-            f"Index {index} is out of range for " f"an atom array with length {length}"
+            f"Index {index} is out of range for an atom array with length {length}"
         )
 
     insertion_points = np.searchsorted(starts, indices, side="right") - 1
@@ -146,6 +188,15 @@ def get_segment_positions(starts, indices):
         The sorted start indices of segments.
         Includes exclusive stop, i.e. the length of the corresponding
         atom array.
+    indices : ndarray, shape=(k,)
+        These indices point to the atoms to get the corresponding
+        residue positions for.
+        Negative indices are not allowed.
+
+    Returns
+    -------
+    segment_indices : ndarray, shape=(k,)
+        The indices that point to the position of the segments.
     """
     indices = np.asarray(indices)
     length = starts[-1]
@@ -157,7 +208,7 @@ def get_segment_positions(starts, indices):
     if (indices >= length).any():
         index = np.min(np.where(indices >= length)[0])
         raise ValueError(
-            f"Index {index} is out of range for " f"an atom array with length {length}"
+            f"Index {index} is out of range for an atom array with length {length}"
         )
 
     return np.searchsorted(starts, indices, side="right") - 1
@@ -170,10 +221,17 @@ def segment_iter(array, starts):
 
     Parameters
     ----------
+    array : AtomArray or AtomArrayStack
+        The structure to iterate over.
     starts : ndarray, dtype=int
         The sorted start indices of segments.
         Includes exclusive stop, i.e. the length of the corresponding
         atom array.
+
+    Yields
+    ------
+    segment : AtomArray or AtomArrayStack
+       Each residue or chain of the structure.
     """
     for i in range(len(starts) - 1):
         yield array[..., starts[i] : starts[i + 1]]

biotite/structure/sequence.py

@@ -58,7 +58,6 @@ def to_sequence(atoms, allow_hetero=False):
     >>> sequences, chain_starts = to_sequence(atom_array)
     >>> print(sequences)
     [ProteinSequence("NLYIQWLKDGGPSSGRPPPS")]
-
     """
     sequences = []
     chain_start_indices = get_chain_starts(atoms, add_exclusive_stop=True)

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