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

biotite/structure/geometry.py

@@ -25,10 +25,12 @@ __all__ = [
 import numpy as np
 from biotite.structure.atoms import AtomArray, AtomArrayStack, coord
 from biotite.structure.box import coord_to_fraction, fraction_to_coord, is_orthogonal
-from biotite.structure.chains import chain_iter
-from biotite.structure.error import BadStructureError
-from biotite.structure.filter import filter_peptide_backbone
-from biotite.structure.util import norm_vector, vector_dot
+from biotite.structure.filter import filter_amino_acids
+from biotite.structure.util import (
+    coord_for_atom_name_per_residue,
+    norm_vector,
+    vector_dot,
+)
 
 
 def displacement(atoms1, atoms2, box=None):
@@ -58,9 +60,9 @@ def displacement(atoms1, atoms2, box=None):
         The displacement vector(s). The shape is equal to the shape of
         the input `atoms` with the highest dimensionality.
 
-    See also
+    See Also
     --------
-    index_displacement
+    index_displacement : The same calculation, but using atom indices.
     """
     v1 = coord(atoms1)
     v2 = coord(atoms2)
@@ -189,7 +191,7 @@ def index_displacement(*args, **kwargs):
     copy is found for non-orthorhombic boxes; this is especially true
     for heavily skewed boxes.
 
-    See also
+    See Also
     --------
     displacement
     """
@@ -222,9 +224,9 @@ def distance(atoms1, atoms2, box=None):
         The shape is equal to the shape of the input `atoms` with the
         highest dimensionality minus the last axis.
 
-    See also
+    See Also
     --------
-    index_distance
+    index_distance : The same calculation, but using atom indices.
     """
     diff = displacement(atoms1, atoms2, box)
     return np.sqrt(vector_dot(diff, diff))
@@ -280,7 +282,7 @@ def index_distance(*args, **kwargs):
     copy is found for non-orthorhombic boxes; this is especially true
     for heavily skewed boxes.
 
-    See also
+    See Also
     --------
     distance
     """
@@ -310,9 +312,9 @@ def angle(atoms1, atoms2, atoms3, box=None):
         of the input `atoms` with the highest dimensionality minus the
         last axis.
 
-    See also
+    See Also
     --------
-    index_angle
+    index_angle : The same calculation, but using atom indices.
     """
     v1 = displacement(atoms1, atoms2, box)
     v2 = displacement(atoms3, atoms2, box)
@@ -369,7 +371,7 @@ def index_angle(*args, **kwargs):
     copy is found for non-orthorhombic boxes; this is especially true
     for heavily skewed boxes.
 
-    See also
+    See Also
     --------
     angle
     """
@@ -402,8 +404,8 @@ def dihedral(atoms1, atoms2, atoms3, atoms4, box=None):
 
     See Also
     --------
-    index_dihedral
-    dihedral_backbone
+    index_dihedral : The same calculation, but using atom indices.
+    dihedral_backbone : Calculate the dihedral angle along a peptide backbone.
     """
     v1 = displacement(atoms1, atoms2, box)
     v2 = displacement(atoms2, atoms3, box)
@@ -470,7 +472,7 @@ def index_dihedral(*args, **kwargs):
     copy is found for non-orthorhombic boxes; this is especially true
     for heavily skewed boxes.
 
-    See also
+    See Also
     --------
     dihedral
     dihedral_backbone
@@ -480,139 +482,84 @@ def index_dihedral(*args, **kwargs):
 
 def dihedral_backbone(atom_array):
     """
-    Measure the characteristic backbone dihedral angles of a protein
-    structure.
+    Measure the characteristic backbone dihedral angles of a chain.
 
     Parameters
     ----------
-    atom_array: AtomArray or AtomArrayStack
-        The protein structure. A complete backbone, without gaps,
-        is required here.
-        Chain transitions are allowed, the angles at the transition are
-        `NaN`.
-        The order of the backbone atoms for each residue must be
-        (N, CA, C).
+    atom_array : AtomArray or AtomArrayStack
+        The protein structure to measure the dihedral angles for.
+        For missing backbone atoms the corresponding angles are `NaN`.
 
     Returns
     -------
     phi, psi, omega : ndarray
-        An array containing the 3 backbone dihedral angles for every
-        CA. 'phi' is not defined at the N-terminus, 'psi' and 'omega'
-        are not defined at the C-terminus. In these places the arrays
-        have *NaN* values. If an :class:`AtomArrayStack` is given, the
-        output angles are 2-dimensional, the first dimension corresponds
-        to the model number.
-
-    Raises
-    ------
-    BadStructureError
-        If the amount of backbone atoms is not equal to amount of
-        residues times 3 (for N, CA and C).
-
-    See Also
-    --------
-    dihedral
-
-    Examples
-    --------
-
-    >>> phi, psi, omega = dihedral_backbone(atom_array)
-    >>> print(np.stack([np.rad2deg(phi), np.rad2deg(psi)]).T)
-    [[     nan  -56.145]
-     [ -43.980  -51.309]
-     [ -66.466  -30.898]
-     [ -65.219  -45.945]
-     [ -64.747  -30.346]
-     [ -73.136  -43.425]
-     [ -64.882  -43.255]
-     [ -59.509  -25.698]
-     [ -77.989   -8.823]
-     [ 110.784    8.079]
-     [  55.244 -124.371]
-     [ -57.983  -28.766]
-     [ -81.834   19.125]
-     [-124.057   13.401]
-     [  67.931   25.218]
-     [-143.952  131.297]
-     [ -70.100  160.068]
-     [ -69.484  145.669]
-     [ -77.264  124.223]
-     [ -78.100      nan]]
+        An array containing the 3 backbone dihedral angles for every CA atom.
+        `phi` is not defined at the N-terminus, `psi` and `omega` are not defined at the
+        C-terminus.
+        In these places the arrays have *NaN* values.
+        If an :class:`AtomArrayStack` is given, the output angles are 2-dimensional,
+        the first dimension corresponds to the model number.
     """
-    bb_filter = filter_peptide_backbone(atom_array)
-    backbone = atom_array[..., bb_filter]
-
-    if (
-        backbone.array_length() % 3 != 0
-        or (backbone.atom_name[0::3] != "N").any()
-        or (backbone.atom_name[1::3] != "CA").any()
-        or (backbone.atom_name[2::3] != "C").any()
-    ):
-        raise BadStructureError(
-            "The backbone is invalid, must be repeats of (N, CA, C), "
-            "maybe a backbone atom is missing"
-        )
-    phis = []
-    psis = []
-    omegas = []
-    for chain_bb in chain_iter(backbone):
-        phi, psi, omega = _dihedral_backbone(chain_bb)
-        phis.append(phi)
-        psis.append(psi)
-        omegas.append(omega)
-    return (
-        np.concatenate(phis, axis=-1),
-        np.concatenate(psis, axis=-1),
-        np.concatenate(omegas, axis=-1),
-    )
+    amino_acid_mask = filter_amino_acids(atom_array)
 
+    # Coordinates for dihedral angle calculation
+    coord_n, coord_ca, coord_c = coord_for_atom_name_per_residue(
+        atom_array,
+        ("N", "CA", "C"),
+        amino_acid_mask,
+    )
+    n_residues = coord_n.shape[-2]
 
-def _dihedral_backbone(chain_bb):
-    bb_coord = chain_bb.coord
     # Coordinates for dihedral angle calculation
     # Dim 0: Model index (only for atom array stacks)
     # Dim 1: Angle index
     # Dim 2: X, Y, Z coordinates
     # Dim 3: Atoms involved in dihedral angle
-    if isinstance(chain_bb, AtomArray):
-        angle_coord_shape = (len(bb_coord) // 3, 3, 4)
-    elif isinstance(chain_bb, AtomArrayStack):
-        angle_coord_shape = (bb_coord.shape[0], bb_coord.shape[1] // 3, 3, 4)
-    phi_coord = np.full(angle_coord_shape, np.nan)
-    psi_coord = np.full(angle_coord_shape, np.nan)
-    omega_coord = np.full(angle_coord_shape, np.nan)
-
-    # Indices for coordinates of CA atoms
-    ca_i = np.arange(bb_coord.shape[-2] // 3) * 3 + 1
+    if isinstance(atom_array, AtomArray):
+        angle_coord_shape: tuple[int, ...] = (n_residues, 3, 4)
+    elif isinstance(atom_array, AtomArrayStack):
+        angle_coord_shape = (atom_array.stack_depth(), n_residues, 3, 4)
+    coord_for_phi = np.full(angle_coord_shape, np.nan, dtype=np.float32)
+    coord_for_psi = np.full(angle_coord_shape, np.nan, dtype=np.float32)
+    coord_for_omg = np.full(angle_coord_shape, np.nan, dtype=np.float32)
+
     # fmt: off
-    phi_coord  [..., 1:,  :, 0] = bb_coord[..., ca_i[1: ]-2, :]
-    phi_coord  [..., 1:,  :, 1] = bb_coord[..., ca_i[1: ]-1, :]
-    phi_coord  [..., 1:,  :, 2] = bb_coord[..., ca_i[1: ],   :]
-    phi_coord  [..., 1:,  :, 3] = bb_coord[..., ca_i[1: ]+1, :]
-    psi_coord  [..., :-1, :, 0] = bb_coord[..., ca_i[:-1]-1, :]
-    psi_coord  [..., :-1, :, 1] = bb_coord[..., ca_i[:-1],   :]
-    psi_coord  [..., :-1, :, 2] = bb_coord[..., ca_i[:-1]+1, :]
-    psi_coord  [..., :-1, :, 3] = bb_coord[..., ca_i[:-1]+2, :]
-    omega_coord[..., :-1, :, 0] = bb_coord[..., ca_i[:-1],   :]
-    omega_coord[..., :-1, :, 1] = bb_coord[..., ca_i[:-1]+1, :]
-    omega_coord[..., :-1, :, 2] = bb_coord[..., ca_i[:-1]+2, :]
-    omega_coord[..., :-1, :, 3] = bb_coord[..., ca_i[:-1]+3, :]
+    coord_for_phi[..., 1:,   :, 0] =  coord_c[..., 0:-1, :]
+    coord_for_phi[..., 1:,   :, 1] =  coord_n[..., 1:,   :]
+    coord_for_phi[..., 1:,   :, 2] = coord_ca[..., 1:,   :]
+    coord_for_phi[..., 1:,   :, 3] =  coord_c[..., 1:,   :]
+
+    coord_for_psi[..., 0:-1, :, 0] =  coord_n[..., 0:-1, :]
+    coord_for_psi[..., 0:-1, :, 1] = coord_ca[..., 0:-1, :]
+    coord_for_psi[..., 0:-1, :, 2] =  coord_c[..., 0:-1, :]
+    coord_for_psi[..., 0:-1, :, 3] =  coord_n[..., 1:,   :]
+
+    coord_for_omg[..., 0:-1, :, 0] = coord_ca[..., 0:-1, :]
+    coord_for_omg[..., 0:-1, :, 1] =  coord_c[..., 0:-1, :]
+    coord_for_omg[..., 0:-1, :, 2] =  coord_n[..., 1:,   :]
+    coord_for_omg[..., 0:-1, :, 3] = coord_ca[..., 1:,   :]
     # fmt: on
 
     phi = dihedral(
-        phi_coord[..., 0], phi_coord[..., 1], phi_coord[..., 2], phi_coord[..., 3]
+        coord_for_phi[..., 0],
+        coord_for_phi[..., 1],
+        coord_for_phi[..., 2],
+        coord_for_phi[..., 3],
     )
     psi = dihedral(
-        psi_coord[..., 0], psi_coord[..., 1], psi_coord[..., 2], psi_coord[..., 3]
+        coord_for_psi[..., 0],
+        coord_for_psi[..., 1],
+        coord_for_psi[..., 2],
+        coord_for_psi[..., 3],
     )
-    omega = dihedral(
-        omega_coord[..., 0],
-        omega_coord[..., 1],
-        omega_coord[..., 2],
-        omega_coord[..., 3],
+    omg = dihedral(
+        coord_for_omg[..., 0],
+        coord_for_omg[..., 1],
+        coord_for_omg[..., 2],
+        coord_for_omg[..., 3],
     )
 
-    return phi, psi, omega
+    return phi, psi, omg
 
 
 def centroid(atoms):
@@ -621,7 +568,7 @@ def centroid(atoms):
 
     Parameters
     ----------
-    atoms: ndarray or AtomArray or AtomArrayStack
+    atoms : ndarray or AtomArray or AtomArrayStack
         The structures to determine the centroid from.
         Alternatively an ndarray containing the coordinates can be
         provided.
@@ -656,7 +603,7 @@ def _call_non_index_function(
                 box = atoms.box
             else:
                 raise ValueError(
-                    "If `atoms` are coordinates, " "the box must be set explicitly"
+                    "If `atoms` are coordinates, the box must be set explicitly"
                 )
     else:
         box = None

biotite/structure/hbond.py

@@ -43,30 +43,28 @@ def hbond(
     ----------
     atoms : AtomArray or AtomArrayStack
         The atoms to find hydrogen bonds in.
-    selection1, selection2: ndarray or None
+    selection1, selection2 : ndarray, optional
         Boolean mask for atoms to limit the hydrogen bond search to
         specific sections of the model. The shape must match the
         shape of the `atoms` argument. If None is given, the whole atoms
-        stack is used instead. (Default: None)
-    selection1_type: {'acceptor', 'donor', 'both'}, optional (default: 'both')
+        stack is used instead.
+    selection1_type : {'acceptor', 'donor', 'both'}, optional
         Determines the type of `selection1`.
         The type of `selection2` is chosen accordingly
         ('both' or the opposite).
-        (Default: 'both')
     cutoff_dist : float, optional
         The maximal distance between the hydrogen and acceptor to be
-        considered a hydrogen bond. (Default: 2.5)
+        considered a hydrogen bond.
     cutoff_angle : float, optional
         The angle cutoff in degree between Donor-H..Acceptor to be
-        considered a hydrogen bond (default: 120).
-    donor_elements, acceptor_elements: tuple of str
+        considered a hydrogen bond.
+    donor_elements, acceptor_elements : tuple of str
         Elements to be considered as possible donors or acceptors
         (Default: O, N, S).
     periodic : bool, optional
         If true, hydrogen bonds can also be detected in periodic
         boundary conditions.
         The `box` attribute of `atoms` is required in this case.
-        (Default: False).
 
     Returns
     -------
@@ -82,6 +80,10 @@ def hbond(
         `triplets` is present in the model *m* of the input `atoms`.
         Only returned if `atoms` is an :class:`AtomArrayStack`.
 
+    See Also
+    --------
+    hbond_frequency : Compute the frequency of each bond over the models.
+
     Notes
     -----
     The result of this function may include false positives:
@@ -92,6 +94,11 @@ def hbond(
     considered as acceptor atom by this method, although this does
     make sense from a chemical perspective.
 
+    References
+    ----------
+
+    .. footbibliography::
+
     Examples
     --------
     Calculate the total number of hydrogen bonds found in each model:
@@ -122,15 +129,6 @@ def hbond(
         A      15  GLY N      N         8.320   -3.632   -0.318
         A      16  ARG N      N         8.043   -1.206   -1.866
         A       6  TRP NE1    N         3.420    0.332   -0.121
-
-    See Also
-    --------
-    hbond_frequency
-
-    References
-    ----------
-
-    .. footbibliography::
     """
     if not (atoms.element == "H").any():
         warnings.warn(
@@ -400,7 +398,7 @@ def hbond_frequency(mask):
 
     Parameters
     ----------
-    mask: ndarray, dtype=bool, shape=(m,n)
+    mask : ndarray, dtype=bool, shape=(m,n)
         Input mask obtained from `hbond` function.
 
     Returns
@@ -412,7 +410,7 @@ def hbond_frequency(mask):
 
     See Also
     --------
-    hbond
+    hbond : Returns the mask that can be input into this function.
 
     Examples
     --------

biotite/structure/info/__init__.py

@@ -16,6 +16,7 @@ __author__ = "Patrick Kunzmann, Tom David Müller"
 
 from .atoms import *
 from .bonds import *
+from .ccd import *
 from .groups import *
 from .masses import *
 from .misc import *

biotite/structure/info/atoms.py

@@ -18,7 +18,7 @@ NON_HETERO_RESIDUES = set([
 # fmt: on
 
 
-def residue(res_name):
+def residue(res_name, allow_missing_coord=False):
     """
     Get an atom array, representing the residue with the given name.
 
@@ -30,6 +30,11 @@ def residue(res_name):
     ----------
     res_name : str
         The up to 3-letter name of the residue.
+    allow_missing_coord : bool, optional
+        Whether to allow missing coordinate values in the residue.
+        If ``True``, these will be represented as ``nan`` values.
+        If ``False``, a ``ValueError`` is raised when missing coordinates
+        are encountered.
 
     Returns
     -------
@@ -42,19 +47,19 @@ def residue(res_name):
     >>> alanine = residue("ALA")
     >>> # Atoms and geometry
     >>> print(alanine)
-                0  ALA N      N        -0.970    0.490    1.500
-                0  ALA CA     C         0.260    0.420    0.690
-                0  ALA C      C        -0.090    0.020   -0.720
-                0  ALA O      O        -1.060   -0.680   -0.920
-                0  ALA CB     C         1.200   -0.620    1.300
-                0  ALA OXT    O         0.660    0.440   -1.740
-                0  ALA H      H        -1.380   -0.420    1.480
-                0  ALA H2     H        -0.680    0.660    2.450
-                0  ALA HA     H         0.750    1.390    0.680
-                0  ALA HB1    H         1.460   -0.330    2.320
-                0  ALA HB2    H         0.720   -1.590    1.310
-                0  ALA HB3    H         2.110   -0.680    0.700
-                0  ALA HXT    H         0.440    0.180   -2.650
+                0  ALA N      N        -0.966    0.493    1.500
+                0  ALA CA     C         0.257    0.418    0.692
+                0  ALA C      C        -0.094    0.017   -0.716
+                0  ALA O      O        -1.056   -0.682   -0.923
+                0  ALA CB     C         1.204   -0.620    1.296
+                0  ALA OXT    O         0.661    0.439   -1.742
+                0  ALA H      H        -1.383   -0.425    1.482
+                0  ALA H2     H        -0.676    0.661    2.452
+                0  ALA HA     H         0.746    1.392    0.682
+                0  ALA HB1    H         1.459   -0.330    2.316
+                0  ALA HB2    H         0.715   -1.594    1.307
+                0  ALA HB3    H         2.113   -0.676    0.697
+                0  ALA HXT    H         0.435    0.182   -2.647
     >>> # Bonds
     >>> print(alanine.atom_name[alanine.bonds.as_array()[:,:2]])
     [['N' 'CA']
@@ -74,7 +79,11 @@ def residue(res_name):
     from biotite.structure.io.pdbx import get_component
 
     try:
-        component = get_component(get_ccd(), res_name=res_name)
+        component = get_component(
+            get_ccd(),
+            res_name=res_name,
+            allow_missing_coord=allow_missing_coord,
+        )
     except KeyError:
         raise KeyError(f"No atom information found for residue '{res_name}' in CCD")
     component.hetero[:] = res_name not in NON_HETERO_RESIDUES

biotite/structure/info/bonds.py

@@ -6,6 +6,7 @@ __name__ = "biotite.structure.info"
 __author__ = "Patrick Kunzmann"
 __all__ = ["bond_type", "bonds_in_residue"]
 
+import functools
 from biotite.structure.bonds import BondType
 from biotite.structure.info.ccd import get_from_ccd
 
@@ -69,6 +70,7 @@ def bond_type(res_name, atom_name1, atom_name2):
         return None
 
 
+@functools.cache
 def bonds_in_residue(res_name):
     """
     Get a dictionary containing all atoms inside a given residue
@@ -94,6 +96,10 @@ def bonds_in_residue(res_name):
     In other functionalities throughout *Biotite* that uses this
     function.
 
+    Notes
+    -----
+    The returned values are cached for faster access in subsequent calls.
+
     Examples
     --------
     >>> bonds = bonds_in_residue("PHE")
@@ -126,16 +132,16 @@ def bonds_in_residue(res_name):
     """
     global _intra_bonds
     if res_name not in _intra_bonds:
-        chem_comp_bond_dict = get_from_ccd("chem_comp_bond", res_name)
-        if chem_comp_bond_dict is None:
+        chem_comp_bond = get_from_ccd("chem_comp_bond", res_name)
+        if chem_comp_bond is None:
             _intra_bonds[res_name] = {}
         else:
             bonds_for_residue = {}
             for atom1, atom2, order, aromatic_flag in zip(
-                chem_comp_bond_dict["atom_id_1"],
-                chem_comp_bond_dict["atom_id_2"],
-                chem_comp_bond_dict["value_order"],
-                chem_comp_bond_dict["pdbx_aromatic_flag"],
+                chem_comp_bond["atom_id_1"].as_array(),
+                chem_comp_bond["atom_id_2"].as_array(),
+                chem_comp_bond["value_order"].as_array(),
+                chem_comp_bond["pdbx_aromatic_flag"].as_array(),
             ):
                 bond_type = BOND_TYPES[order, aromatic_flag]
                 bonds_for_residue[atom1.item(), atom2.item()] = bond_type