biotite 1.3.0__cp313-cp313-macosx_11_0_arm64.whl → 1.5.0__cp313-cp313-macosx_11_0_arm64.whl

biotite/structure/residues.py

@@ -16,13 +16,17 @@ __all__ = [
     "get_residue_masks",
     "get_residue_starts_for",
     "get_residue_positions",
+    "get_all_residue_positions",
     "get_residues",
     "get_residue_count",
     "residue_iter",
+    "get_atom_name_indices",
 ]
 
+import numpy as np
 from biotite.structure.segments import (
     apply_segment_wise,
+    get_all_segment_positions,
     get_segment_masks,
     get_segment_positions,
     get_segment_starts,
@@ -72,7 +76,7 @@ def get_residue_starts(array, add_exclusive_stop=False, extra_categories=()):
     [  0  16  35  56  75  92 116 135 157 169 176 183 197 208 219 226 250 264
      278 292 304]
     """
-    categories = ["chain_id", "res_id", "ins_code", "res_name"] + list(extra_categories)
+    categories = ["chain_id", "res_id", "ins_code"] + list(extra_categories)
     if "sym_id" in array.get_annotation_categories():
         categories.append("sym_id")
     return get_segment_starts(array, add_exclusive_stop, equal_categories=categories)
@@ -361,6 +365,11 @@ def get_residue_positions(array, indices):
     residue_indices : ndarray, dtype=int, shape=(k,)
         The indices that point to the position of the residues.
 
+    See Also
+    --------
+    get_all_residue_positions :
+        Similar to this function, but for all atoms in the :class:`struc.AtomArray`.
+
     Examples
     --------
     >>> atom_index = [5, 42]
@@ -380,6 +389,50 @@ def get_residue_positions(array, indices):
     return get_segment_positions(starts, indices)
 
 
+def get_all_residue_positions(array):
+    """
+    For each atom, obtain the position of the residue
+    corresponding to this atom in the input `array`.
+
+    For example, the position of the first residue in the atom array is
+    ``0``, the the position of the second residue is ``1``, etc.
+
+    Parameters
+    ----------
+    array : AtomArray or AtomArrayStack
+        The atom array (stack) to determine the residues from.
+
+    Returns
+    -------
+    residue_indices : ndarray, dtype=int, shape=(k,)
+        The indices that point to the position of the residues.
+
+    See Also
+    --------
+    get_residue_positions :
+        Similar to this function, but for a given subset of atom indices.
+
+    Examples
+    --------
+    >>> print(get_all_residue_positions(atom_array))
+    [ 0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  1  1  1  1  1  1  1  1
+      1  1  1  1  1  1  1  1  1  1  1  2  2  2  2  2  2  2  2  2  2  2  2  2
+      2  2  2  2  2  2  2  2  3  3  3  3  3  3  3  3  3  3  3  3  3  3  3  3
+      3  3  3  4  4  4  4  4  4  4  4  4  4  4  4  4  4  4  4  4  5  5  5  5
+      5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  5  6  6  6  6
+      6  6  6  6  6  6  6  6  6  6  6  6  6  6  6  7  7  7  7  7  7  7  7  7
+      7  7  7  7  7  7  7  7  7  7  7  7  7  8  8  8  8  8  8  8  8  8  8  8
+      8  9  9  9  9  9  9  9 10 10 10 10 10 10 10 11 11 11 11 11 11 11 11 11
+     11 11 11 11 11 12 12 12 12 12 12 12 12 12 12 12 13 13 13 13 13 13 13 13
+     13 13 13 14 14 14 14 14 14 14 15 15 15 15 15 15 15 15 15 15 15 15 15 15
+     15 15 15 15 15 15 15 15 15 15 16 16 16 16 16 16 16 16 16 16 16 16 16 16
+     17 17 17 17 17 17 17 17 17 17 17 17 17 17 18 18 18 18 18 18 18 18 18 18
+     18 18 18 18 19 19 19 19 19 19 19 19 19 19 19 19]
+    """
+    starts = get_residue_starts(array, add_exclusive_stop=True)
+    return get_all_segment_positions(starts, array.array_length())
+
+
 def get_residues(array):
     """
     Get the residue IDs and names of an atom array (stack).
@@ -542,3 +595,122 @@ def residue_iter(array):
     starts = get_residue_starts(array, add_exclusive_stop=True)
     for residue in segment_iter(array, starts):
         yield residue
+
+
+def get_atom_name_indices(atoms, atom_names):
+    """
+    For each residue, get the index of the atom with the given atom name.
+
+    Parameters
+    ----------
+    atoms : AtomArray or AtomArrayStack
+        Search for the indices of the given atom names in this structure.
+    atom_names : list of str, length=p
+        The names of the atoms to get the indices of.
+
+    Returns
+    -------
+    indices : ndarray, dtype=int, shape=(k, p)
+        For every residue and atom name, the return value contains the atom index in
+        the :class:`AtomArray` where the sought atom name is located.
+        Where the atom name is not present in a residue, the array is filled with `-1`.
+
+    Examples
+    --------
+
+    >>> indices = get_atom_name_indices(atom_array, ["CA", "CB"])
+    >>> print(indices)
+    [[  1   4]
+     [ 17  20]
+     [ 36  39]
+     [ 57  60]
+     [ 76  79]
+     [ 93  96]
+     [117 120]
+     [136 139]
+     [158 161]
+     [170  -1]
+     [177  -1]
+     [184 187]
+     [198 201]
+     [209 212]
+     [220  -1]
+     [227 230]
+     [251 254]
+     [265 268]
+     [279 282]
+     [293 296]]
+    >>> for row in indices:
+    ...     for index in row:
+    ...         if index != -1:
+    ...             print(atom_array[index])
+    ...     print()
+        A       1  ASN CA     C        -8.608    3.135   -1.618
+        A       1  ASN CB     C        -9.437    3.396   -2.889
+    <BLANKLINE>
+        A       2  LEU CA     C        -4.923    4.002   -2.452
+        A       2  LEU CB     C        -4.411    5.450   -2.619
+    <BLANKLINE>
+        A       3  TYR CA     C        -3.690    2.738    0.981
+        A       3  TYR CB     C        -3.964    3.472    2.302
+    <BLANKLINE>
+        A       4  ILE CA     C        -5.857   -0.449    0.613
+        A       4  ILE CB     C        -7.386   -0.466    0.343
+    <BLANKLINE>
+        A       5  GLN CA     C        -4.122   -1.167   -2.743
+        A       5  GLN CB     C        -4.292   -0.313   -4.013
+    <BLANKLINE>
+        A       6  TRP CA     C        -0.716   -0.631   -0.993
+        A       6  TRP CB     C        -0.221    0.703   -0.417
+    <BLANKLINE>
+        A       7  LEU CA     C        -1.641   -2.932    1.963
+        A       7  LEU CB     C        -2.710   -2.645    3.033
+    <BLANKLINE>
+        A       8  LYS CA     C        -3.024   -5.791   -0.269
+        A       8  LYS CB     C        -4.224   -5.697   -1.232
+    <BLANKLINE>
+        A       9  ASP CA     C         0.466   -6.016   -1.905
+        A       9  ASP CB     C         1.033   -4.839   -2.724
+    <BLANKLINE>
+        A      10  GLY CA     C         2.060   -6.618    1.593
+    <BLANKLINE>
+        A      11  GLY CA     C         2.626   -2.967    2.723
+    <BLANKLINE>
+        A      12  PRO CA     C         6.333   -2.533    3.806
+        A      12  PRO CB     C         6.740   -2.387    5.279
+    <BLANKLINE>
+        A      13  SER CA     C         7.049   -6.179    2.704
+        A      13  SER CB     C         6.458   -7.371    3.472
+    <BLANKLINE>
+        A      14  SER CA     C         6.389   -5.315   -1.015
+        A      14  SER CB     C         4.914   -4.993   -1.265
+    <BLANKLINE>
+        A      15  GLY CA     C         9.451   -3.116   -1.870
+    <BLANKLINE>
+        A      16  ARG CA     C         7.289    0.084   -2.054
+        A      16  ARG CB     C         6.110   -0.243   -2.994
+    <BLANKLINE>
+        A      17  PRO CA     C         6.782    3.088    0.345
+        A      17  PRO CB     C         7.554    4.394    0.119
+    <BLANKLINE>
+        A      18  PRO CA     C         3.287    4.031    1.686
+        A      18  PRO CB     C         3.035    4.190    3.187
+    <BLANKLINE>
+        A      19  PRO CA     C         1.185    6.543   -0.353
+        A      19  PRO CB     C         0.048    6.014   -1.229
+    <BLANKLINE>
+        A      20  SER CA     C         0.852   10.027    1.285
+        A      20  SER CB     C         1.972   11.071    1.284
+    <BLANKLINE>
+    """
+    residue_indices = get_all_residue_positions(atoms)
+    indices = np.full(
+        (residue_indices[-1] + 1, len(atom_names)), fill_value=-1, dtype=int
+    )
+    for i, atom_name in enumerate(atom_names):
+        if atom_name is None:
+            atom_name_indices = np.where(atoms.hetero)[0]
+        else:
+            atom_name_indices = np.where(atoms.atom_name == atom_name)[0]
+        indices[residue_indices[atom_name_indices], i] = atom_name_indices
+    return indices

biotite/structure/rings.py

@@ -8,7 +8,12 @@ This module provides functions related to aromatic rings.
 
 __name__ = "biotite.structure"
 __author__ = "Patrick Kunzmann"
-__all__ = ["find_aromatic_rings", "find_stacking_interactions", "PiStacking"]
+__all__ = [
+    "find_aromatic_rings",
+    "find_stacking_interactions",
+    "find_pi_cation_interactions",
+    "PiStacking",
+]
 
 
 from enum import IntEnum
@@ -268,6 +273,117 @@ def find_stacking_interactions(
     ]
 
 
+def find_pi_cation_interactions(
+    atoms,
+    distance_cutoff=5.0,
+    angle_tol=np.deg2rad(30.0),
+):
+    """
+    Find pi-cation interactions between aromatic rings and cations.
+
+    Parameters
+    ----------
+    atoms : AtomArray
+        The atoms to be searched for pi-cation interactions.
+        Requires an associated :class:`BondList` and ``charge`` annotation.
+    distance_cutoff : float, optional
+        The cutoff distance between ring centroid and cation.
+    angle_tol : float, optional
+        The tolerance for the angle between the ring plane normal
+        and the centroid-cation vector. Perfect pi-cation interaction
+        has 0° angle (perpendicular to ring plane).
+        Given in radians.
+
+    Returns
+    -------
+    interactions : list of tuple(ndarray, int)
+        The pi-cation interactions between aromatic rings and cations.
+        Each element in the list represents one pi-cation interaction.
+        The first element of each tuple represents atom indices of the
+        aromatic ring, the second element is the atom index of the cation.
+
+    See Also
+    --------
+    find_aromatic_rings : Used for finding the aromatic rings in this function.
+    find_stacking_interactions : Find pi-stacking interactions between rings.
+
+    Notes
+    -----
+    The conditions for pi-cation interactions are:
+        - The distance between ring centroid and cation must be within
+          `distance_cutoff`. :footcite:`Wojcikowski2015` uses 5.0 Å,
+          whereas :footcite:`Bouysset2021` uses 4.5 Å.
+        - The angle between the ring plane normal and the centroid-cation
+          vector must be within `angle_tol` of 0° (perpendicular to plane).
+
+    Examples
+    --------
+    >>> from os.path import join
+    >>> structure = load_structure(join(path_to_structures, "3wip.cif"), include_bonds=True, extra_fields=["charge"])
+    >>> interactions = find_pi_cation_interactions(structure)
+    >>> for ring_indices, cation_index in interactions:
+    ...     print(
+    ...         structure.res_name[ring_indices[0]],
+    ...         structure.res_name[cation_index]
+    ...     )
+    TYR ACH
+    TRP ACH
+    """
+    if atoms.bonds is None:
+        raise BadStructureError("Structure must have an associated BondList")
+
+    if atoms.charge is None:
+        raise BadStructureError(
+            "Structure must have a 'charge' annotation to identify cations."
+        )
+
+    rings = find_aromatic_rings(atoms)
+    if len(rings) == 0:
+        return []
+
+    cation_mask = atoms.charge > 0
+    cation_indices = np.where(cation_mask)[0]
+
+    if len(cation_indices) == 0:
+        return []
+
+    # Calculate ring centroids and normals
+    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]
+    )
+
+    cation_coords = atoms.coord[cation_indices]
+
+    # Create an index array that contains the Cartesian product of all rings and cations
+    indices = np.stack(
+        [
+            np.repeat(np.arange(len(rings)), len(cation_indices)),
+            np.tile(np.arange(len(cation_indices)), len(rings)),
+        ],
+        axis=-1,
+    )
+
+    ## Condition 1: Ring centroids and cations are close enough to each other
+    diff = displacement(ring_centroids[indices[:, 0]], cation_coords[indices[:, 1]])
+    # Use squared distance to avoid time consuming sqrt computation
+    sq_distance = vector_dot(diff, diff)
+    is_interacting = sq_distance < distance_cutoff**2
+    indices = indices[is_interacting]
+
+    ## Condition 2: Angle between ring normal and centroid-cation vector
+    diff = displacement(ring_centroids[indices[:, 0]], cation_coords[indices[:, 1]])
+    norm_vector(diff)
+    angles = _minimum_angle(ring_normals[indices[:, 0]], diff)
+    is_interacting = _is_within_tolerance(angles, 0, angle_tol)
+    indices = indices[is_interacting]
+
+    # Only return pairs where all conditions were fulfilled
+    return [(rings[ring_i], cation_indices[cation_j]) for ring_i, cation_j in indices]
+
+
 def _get_ring_normal(ring_coord):
     """
     Get the normal vector perpendicular to the ring plane.

biotite/structure/segments.py

@@ -11,6 +11,7 @@ __all__ = [
     "get_segment_masks",
     "get_segment_starts_for",
     "get_segment_positions",
+    "get_all_segment_positions",
     "segment_iter",
 ]
 
@@ -62,13 +63,13 @@ def get_segment_starts(
     # Convert mask to indices
     # Add 1, to shift the indices from the end of a segment
     # to the start of a new segment
-    chain_starts = np.where(segment_start_mask)[0] + 1
+    segment_starts = np.where(segment_start_mask)[0] + 1
 
     # The first chain is not included yet -> Insert '[0]'
     if add_exclusive_stop:
-        return np.concatenate(([0], chain_starts, [array.array_length()]))
+        return np.concatenate(([0], segment_starts, [array.array_length()]))
     else:
-        return np.concatenate(([0], chain_starts))
+        return np.concatenate(([0], segment_starts))
 
 
 def apply_segment_wise(starts, data, function, axis=None):
@@ -252,6 +253,11 @@ def get_segment_positions(starts, indices):
     -------
     segment_indices : ndarray, shape=(k,)
         The indices that point to the position of the segments.
+
+    See Also
+    --------
+    get_all_segment_positions :
+        Similar to this function, but for all atoms in the :class:`struc.AtomArray`.
     """
     indices = np.asarray(indices)
     length = starts[-1]
@@ -269,6 +275,36 @@ def get_segment_positions(starts, indices):
     return np.searchsorted(starts, indices, side="right") - 1
 
 
+def get_all_segment_positions(starts, length):
+    """
+    Generalized version of :func:`get_all_residue_positions()`
+    for residues and chains.
+
+    Parameters
+    ----------
+    starts : ndarray, dtype=int
+        The sorted start indices of segments.
+        Includes exclusive stop, i.e. the length of the corresponding
+        atom array.
+    length : int
+        The length of the corresponding :class:`struc.AtomArray`.
+
+    Returns
+    -------
+    segment_indices : ndarray, shape=(k,)
+        For each atom the indices that point to the corresponding position of the
+        segments.
+
+    See Also
+    --------
+    get_segment_positions :
+        Similar to this function, but for a given subset of atom indices.
+    """
+    segment_changes = np.zeros(length, dtype=int)
+    segment_changes[starts[1:-1]] = 1
+    return np.cumsum(segment_changes)
+
+
 def segment_iter(array, starts):
     """
     Generalized version of :func:`residue_iter()`

biotite/structure/util.py

@@ -18,8 +18,9 @@ __all__ = [
 
 import numpy as np
 from biotite.structure.atoms import AtomArrayStack
-from biotite.structure.error import BadStructureError
-from biotite.structure.residues import get_residue_masks, get_residue_starts
+from biotite.structure.residues import (
+    get_atom_name_indices,
+)
 
 
 def vector_dot(v1, v2):
@@ -127,42 +128,33 @@ def coord_for_atom_name_per_residue(atoms, atom_names, mask=None):
     coord: ndarray, shape=(k, m, r, 3) or shape=(k, r, 3)
         The coordinates of the specified atom for each residue.
     """
-    is_multi_model = isinstance(atoms, AtomArrayStack)
-    residue_starts = get_residue_starts(atoms)
-    all_residue_masks = get_residue_masks(atoms, residue_starts)
+    atom_name_indices = get_atom_name_indices(atoms, atom_names)
 
+    is_multi_model = isinstance(atoms, AtomArrayStack)
     if is_multi_model:
         coord = np.full(
-            (len(atom_names), atoms.stack_depth(), len(residue_starts), 3),
+            (len(atom_names), atoms.stack_depth(), atom_name_indices.shape[0], 3),
             np.nan,
             dtype=np.float32,
         )
     else:
         coord = np.full(
-            (len(atom_names), len(residue_starts), 3),
+            (len(atom_names), atom_name_indices.shape[0], 3),
             np.nan,
             dtype=np.float32,
         )
 
-    for i, atom_name in enumerate(atom_names):
-        specified_atom_mask = atoms.atom_name == atom_name
+    for atom_name_i, atom_indices in enumerate(atom_name_indices.T):
+        valid_mask = atom_indices != -1
         if mask is not None:
-            specified_atom_mask &= mask
-        all_residue_masks_for_specified_atom = all_residue_masks & specified_atom_mask
-        number_of_specified_atoms_per_residue = np.count_nonzero(
-            all_residue_masks_for_specified_atom, axis=-1
-        )
-        if np.any(number_of_specified_atoms_per_residue > 1):
-            raise BadStructureError(f"Multiple '{atom_name}' atoms per residue")
-        residues_with_specified_atom = number_of_specified_atoms_per_residue == 1
-        coord_of_specified_atoms = atoms.coord[..., specified_atom_mask, :]
+            valid_mask &= mask[atom_indices]
+        coord_for_atom_name = atoms.coord[..., atom_indices[valid_mask], :]
         if is_multi_model:
             # Swap dimensions due to NumPy's behavior when using advanced indexing
             # (https://numpy.org/devdocs/user/basics.indexing.html#combining-advanced-and-basic-indexing)
-            coord[i, ..., residues_with_specified_atom, :] = (
-                coord_of_specified_atoms.transpose(1, 0, 2)
+            coord[atom_name_i, ..., valid_mask, :] = coord_for_atom_name.transpose(
+                1, 0, 2
             )
         else:
-            coord[i, residues_with_specified_atom, :] = coord_of_specified_atoms
-
+            coord[atom_name_i, valid_mask, :] = coord_for_atom_name
     return coord

biotite/version.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '1.3.0'
-__version_tuple__ = version_tuple = (1, 3, 0)
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)
+
+__commit_id__ = commit_id = None

{biotite-1.3.0.dist-info → biotite-1.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biotite
-Version: 1.3.0
+Version: 1.5.0
 Summary: A comprehensive library for computational molecular biology
 Project-URL: homepage, https://www.biotite-python.org
 Project-URL: repository, https://github.com/biotite-dev/biotite