biotite 0.41.2__cp311-cp311-win_amd64.whl → 1.0.1__cp311-cp311-win_amd64.whl

biotite/structure/geometry.py

@@ -9,25 +9,33 @@ in a structure, mainly lenghts and angles.
 
 __name__ = "biotite.structure"
 __author__ = "Patrick Kunzmann"
-__all__ = ["displacement", "index_displacement", "distance", "index_distance",
-           "angle", "index_angle", "dihedral", "index_dihedral",
-           "dihedral_backbone", "centroid"]
+__all__ = [
+    "displacement",
+    "index_displacement",
+    "distance",
+    "index_distance",
+    "angle",
+    "index_angle",
+    "dihedral",
+    "index_dihedral",
+    "dihedral_backbone",
+    "centroid",
+]
 
 import numpy as np
-from .atoms import Atom, AtomArray, AtomArrayStack, coord
-from .util import vector_dot, norm_vector
-from .filter import filter_peptide_backbone
-from .chains import chain_iter
-from .box import (coord_to_fraction, fraction_to_coord,
-                  move_inside_box, is_orthogonal)
-from .error import BadStructureError
+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
 
 
 def displacement(atoms1, atoms2, box=None):
     """
     Measure the displacement vector, i.e. the vector difference, from
     one array of atom coordinates to another array of coordinates.
-    
+
     Parameters
     ----------
     atoms1, atoms2 : ndarray, shape=(m,n,3) or ndarray, shape=(n,3) or ndarray, shape=(3,) or Atom or AtomArray or AtomArrayStack
@@ -43,13 +51,13 @@ def displacement(atoms1, atoms2, box=None):
         the box vectors given with this parameter.
         The shape *(m,3,3)* is only allowed, when the input coordinates
         comprise multiple models.
-    
+
     Returns
     -------
     disp : ndarray, shape=(m,n,3) or ndarray, shape=(n,3) or ndarray, shape=(3,)
         The displacement vector(s). The shape is equal to the shape of
         the input `atoms` with the highest dimensionality.
-    
+
     See also
     --------
     index_displacement
@@ -62,7 +70,7 @@ def displacement(atoms1, atoms2, box=None):
         diff = v2 - v1
     else:
         diff = -(v1 - v2)
-    
+
     # Use minimum-image convention if box is given
     if box is not None:
         # Transform difference vector
@@ -81,28 +89,24 @@ def displacement(atoms1, atoms2, box=None):
             fractions = fractions[np.newaxis, :]
             disp = disp[np.newaxis, :]
             if orthogonality:
-                _displacement_orthogonal_box(
-                    fractions, box, disp
-                )
+                _displacement_orthogonal_box(fractions, box, disp)
             else:
                 _displacement_triclinic_box(
                     fractions.astype(diff.dtype, copy=False),
                     box.astype(diff.dtype, copy=False),
-                    disp
+                    disp,
                 )
             # Transform back
             disp = disp[0]
         if fractions.ndim == 2:
             # Single model
             if orthogonality:
-                _displacement_orthogonal_box(
-                    fractions, box, disp
-                )
+                _displacement_orthogonal_box(fractions, box, disp)
             else:
                 _displacement_triclinic_box(
                     fractions.astype(diff.dtype, copy=False),
                     box.astype(diff.dtype, copy=False),
-                    disp
+                    disp,
                 )
         elif fractions.ndim == 3:
             # Multiple models
@@ -117,21 +121,17 @@ def displacement(atoms1, atoms2, box=None):
                 else:
                     raise ValueError(f"{box.ndim} are to many box dimensions")
                 if orthogonality_for_model:
-                    _displacement_orthogonal_box(
-                        fractions[i], box_for_model, disp[i]
-                    )
+                    _displacement_orthogonal_box(fractions[i], box_for_model, disp[i])
                 else:
                     _displacement_triclinic_box(
                         fractions[i].astype(diff.dtype, copy=False),
                         box_for_model.astype(diff.dtype, copy=False),
-                        disp[i]
+                        disp[i],
                     )
         else:
-            raise ValueError(
-                f"{diff.shape} is an invalid shape for atom coordinates"
-            )
+            raise ValueError(f"{diff.shape} is an invalid shape for atom coordinates")
         return disp
-    
+
     else:
         return diff
 
@@ -139,7 +139,7 @@ def displacement(atoms1, atoms2, box=None):
 def index_displacement(*args, **kwargs):
     """
     index_displacement(atoms, indices, periodic=False, box=None)
-    
+
     Measure the displacement, i.e. the vector difference, between pairs
     of atoms.
 
@@ -159,7 +159,7 @@ def index_displacement(*args, **kwargs):
         :class:`ndarray`.
     indices : ndarray, shape=(k,2)
         Pairs of indices that point to `atoms`.
-        The displacement is measured from ``indices[x,0]`` to 
+        The displacement is measured from ``indices[x,0]`` to
         ``indices[x,1]``.
     periodic : bool, optional
         If set to true, periodic boundary conditions are taken into
@@ -171,14 +171,14 @@ def index_displacement(*args, **kwargs):
     box : ndarray, shape=(3,3) or shape=(m,3,3), optional
         If this parameter is set, the given box is used instead of the
         `box` attribute of `atoms`.
-    
+
     Returns
     -------
     disp : ndarray, shape=(k,) or shape=(m,k)
         The pairwise displacements.
         If `atoms` is an atom array stack, The distances are
         calculated for each model.
-    
+
     Warnings
     --------
     In case `periodic` is set to true and if the box is not orthorhombic
@@ -199,7 +199,7 @@ def index_displacement(*args, **kwargs):
 def distance(atoms1, atoms2, box=None):
     """
     Measure the euclidian distance between atoms.
-    
+
     Parameters
     ----------
     atoms1, atoms2 : ndarray or Atom or AtomArray or AtomArrayStack
@@ -214,14 +214,14 @@ def distance(atoms1, atoms2, box=None):
         the box vectors given with this parameter.
         The shape *(m,3,3)* is only allowed, when the input coordinates
         comprise multiple models.
-    
+
     Returns
     -------
     dist : float or ndarray
         The atom distances.
         The shape is equal to the shape of the input `atoms` with the
         highest dimensionality minus the last axis.
-    
+
     See also
     --------
     index_distance
@@ -233,7 +233,7 @@ def distance(atoms1, atoms2, box=None):
 def index_distance(*args, **kwargs):
     """
     index_distance(atoms, indices, periodic=False, box=None)
-    
+
     Measure the euclidian distance between pairs of atoms.
 
     The pairs refer to indices of a given atom array, whose pairwise
@@ -262,14 +262,14 @@ def index_distance(*args, **kwargs):
     box : ndarray, shape=(3,3) or shape=(m,3,3), optional
         If this parameter is set, the given box is used instead of the
         `box` attribute of `atoms`.
-    
+
     Returns
     -------
     dist : ndarray, shape=(k,) or shape=(m,k)
         The pairwise distances.
         If `atoms` is an atom array stack, The distances are
         calculated for each model.
-    
+
     Warnings
     --------
     In case `periodic` is set to true and if the box is not orthorhombic
@@ -290,7 +290,7 @@ def index_distance(*args, **kwargs):
 def angle(atoms1, atoms2, atoms3, box=None):
     """
     Measure the angle between 3 atoms.
-    
+
     Parameters
     ----------
     atoms1, atoms2, atoms3 : ndarray or Atom or AtomArray or AtomArrayStack
@@ -302,14 +302,14 @@ def angle(atoms1, atoms2, atoms3, box=None):
         the box vectors given with this parameter.
         The shape *(m,3,3)* is only allowed, when the input coordinates
         comprise multiple models.
-    
+
     Returns
     -------
     angle : float or ndarray
         The angle(s) between the atoms. The shape is equal to the shape
         of the input `atoms` with the highest dimensionality minus the
         last axis.
-    
+
     See also
     --------
     index_angle
@@ -318,13 +318,13 @@ def angle(atoms1, atoms2, atoms3, box=None):
     v2 = displacement(atoms3, atoms2, box)
     norm_vector(v1)
     norm_vector(v2)
-    return np.arccos(vector_dot(v1,v2))
+    return np.arccos(vector_dot(v1, v2))
 
 
 def index_angle(*args, **kwargs):
     """
     index_angle(atoms, indices, periodic=False, box=None)
-    
+
     Measure the angle between triples of atoms.
 
     The triples refer to indices of a given atom array, whose triplewise
@@ -351,14 +351,14 @@ def index_angle(*args, **kwargs):
     box : ndarray, shape=(3,3) or shape=(m,3,3), optional
         If this parameter is set, the given box is used instead of the
         `box` attribute of `atoms`.
-    
+
     Returns
     -------
     angle : ndarray, shape=(k,) or shape=(m,k)
         The triplewise angles.
         If `atoms` is an atom array stack, The distances are
         calculated for each model.
-    
+
     Warnings
     --------
     In case `periodic` is set to true and if the box is not orthorhombic
@@ -379,7 +379,7 @@ def index_angle(*args, **kwargs):
 def dihedral(atoms1, atoms2, atoms3, atoms4, box=None):
     """
     Measure the dihedral angle between 4 atoms.
-    
+
     Parameters
     ----------
     atoms1, atoms2, atoms3, atoms4 : ndarray or Atom or AtomArray or AtomArrayStack
@@ -392,14 +392,14 @@ def dihedral(atoms1, atoms2, atoms3, atoms4, box=None):
         the box vectors given with this parameter.
         The shape *(m,3,3)* is only allowed, when the input coordinates
         comprise multiple models.
-    
+
     Returns
     -------
     dihed : float or ndarray
         The dihedral angle(s) between the atoms. The shape is equal to
         the shape of the input `atoms` with the highest dimensionality
         minus the last axis.
-    
+
     See Also
     --------
     index_dihedral
@@ -411,20 +411,20 @@ def dihedral(atoms1, atoms2, atoms3, atoms4, box=None):
     norm_vector(v1)
     norm_vector(v2)
     norm_vector(v3)
-    
+
     n1 = np.cross(v1, v2)
     n2 = np.cross(v2, v3)
-    
-    # Calculation using atan2, to ensure the correct sign of the angle 
-    x = vector_dot(n1,n2)
-    y = vector_dot(np.cross(n1,n2), v2)
-    return np.arctan2(y,x)
+
+    # Calculation using atan2, to ensure the correct sign of the angle
+    x = vector_dot(n1, n2)
+    y = vector_dot(np.cross(n1, n2), v2)
+    return np.arctan2(y, x)
 
 
 def index_dihedral(*args, **kwargs):
     """
     index_dihedral(atoms, indices, periodic=False, box=None)
-    
+
     Measure the dihedral angle between quadruples of atoms.
 
     The triples refer to indices of a given atom array, whose
@@ -452,14 +452,14 @@ def index_dihedral(*args, **kwargs):
     box : ndarray, shape=(3,3) or shape=(m,3,3), optional
         If this parameter is set, the given box is used instead of the
         `box` attribute of `atoms`.
-    
+
     Returns
     -------
     dihedral : ndarray, shape=(k,) or shape=(m,k)
         The quadruplewise dihedral angles.
         If `atoms` is an atom array stack, The distances are
         calculated for each model.
-    
+
     Warnings
     --------
     In case `periodic` is set to true and if the box is not orthorhombic
@@ -482,7 +482,7 @@ def dihedral_backbone(atom_array):
     """
     Measure the characteristic backbone dihedral angles of a protein
     structure.
-    
+
     Parameters
     ----------
     atom_array: AtomArray or AtomArrayStack
@@ -492,7 +492,7 @@ def dihedral_backbone(atom_array):
         `NaN`.
         The order of the backbone atoms for each residue must be
         (N, CA, C).
-    
+
     Returns
     -------
     phi, psi, omega : ndarray
@@ -502,20 +502,20 @@ def dihedral_backbone(atom_array):
         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]
@@ -541,15 +541,17 @@ def dihedral_backbone(atom_array):
     """
     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"
-            )
+
+    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 = []
@@ -558,9 +560,11 @@ def dihedral_backbone(atom_array):
         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)
-
+    return (
+        np.concatenate(phis, axis=-1),
+        np.concatenate(psis, axis=-1),
+        np.concatenate(omegas, axis=-1),
+    )
 
 
 def _dihedral_backbone(chain_bb):
@@ -571,49 +575,57 @@ def _dihedral_backbone(chain_bb):
     # 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)
+        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)
+        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
-    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 ,:]
-    
-    phi = dihedral(phi_coord[...,0], phi_coord[...,1],
-                   phi_coord[...,2], phi_coord[...,3])
-    psi = dihedral(psi_coord[...,0], psi_coord[...,1],
-                   psi_coord[...,2], psi_coord[...,3])
-    omega = dihedral(omega_coord[...,0], omega_coord[...,1],
-                     omega_coord[...,2], omega_coord[...,3])
-    
+
+    # Indices for coordinates of CA atoms
+    ca_i = np.arange(bb_coord.shape[-2] // 3) * 3 + 1
+    # 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, :]
+    # fmt: on
+
+    phi = dihedral(
+        phi_coord[..., 0], phi_coord[..., 1], phi_coord[..., 2], phi_coord[..., 3]
+    )
+    psi = dihedral(
+        psi_coord[..., 0], psi_coord[..., 1], psi_coord[..., 2], psi_coord[..., 3]
+    )
+    omega = dihedral(
+        omega_coord[..., 0],
+        omega_coord[..., 1],
+        omega_coord[..., 2],
+        omega_coord[..., 3],
+    )
+
     return phi, psi, omega
 
 
 def centroid(atoms):
     """
     Measure the centroid of a structure.
-    
+
     Parameters
     ----------
     atoms: ndarray or AtomArray or AtomArrayStack
         The structures to determine the centroid from.
         Alternatively an ndarray containing the coordinates can be
         provided.
-    
+
     Returns
     -------
     centroid : float or ndarray
@@ -623,8 +635,9 @@ def centroid(atoms):
     return np.mean(coord(atoms), axis=-2)
 
 
-def _call_non_index_function(function, expected_amount,
-                             atoms, indices, periodic=False, box=None):
+def _call_non_index_function(
+    function, expected_amount, atoms, indices, periodic=False, box=None
+):
     """
     Call an `xxx()` function based on the parameters given to a
     `index_xxx()` function.
@@ -636,15 +649,14 @@ def _call_non_index_function(function, expected_amount,
         )
     coord_list = []
     for i in range(expected_amount):
-        coord_list.append(coord(atoms)[..., indices[:,i], :])
+        coord_list.append(coord(atoms)[..., indices[:, i], :])
     if periodic:
         if box is None:
             if isinstance(atoms, (AtomArray, AtomArrayStack)):
                 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
@@ -656,7 +668,7 @@ def _displacement_orthogonal_box(fractions, box, disp):
     Fill in the PBC-aware displacement vector for non-PBC-aware
     displacements given as fractions of given box vectors.
     """
-    # Fraction components are guaranteed to be positive 
+    # Fraction components are guaranteed to be positive
     # Use fraction vector components with lower absolute
     # -> new_vec[i] = vec[i] - 1 if vec[i] > 0.5 else vec[i]
     fractions[fractions > 0.5] -= 1
@@ -669,7 +681,7 @@ def _displacement_triclinic_box(fractions, box, disp):
     displacements given as fractions of given box vectors.
     """
     diffs = fraction_to_coord(fractions, box)
-    # Fraction components are guaranteed to be positive 
+    # Fraction components are guaranteed to be positive
     # Test all 3 fraction vector components
     # with positive and negative sign
     # (i,j,k in {-1, 0})
@@ -678,10 +690,10 @@ def _displacement_triclinic_box(fractions, box, disp):
     for i in range(-1, 1):
         for j in range(-1, 1):
             for k in range(-1, 1):
-                x = i*box[0,0] + j*box[1,0] + k*box[2,0]
-                y = i*box[0,1] + j*box[1,1] + k*box[2,1]
-                z = i*box[0,2] + j*box[1,2] + k*box[2,2]
-                periodic_shift.append([x,y,z])
+                x = i * box[0, 0] + j * box[1, 0] + k * box[2, 0]
+                y = i * box[0, 1] + j * box[1, 1] + k * box[2, 1]
+                z = i * box[0, 2] + j * box[1, 2] + k * box[2, 2]
+                periodic_shift.append([x, y, z])
     periodic_shift = np.array(periodic_shift, dtype=disp.dtype)
     # Create 8 periodically shifted variants for each atom
     shifted_diffs = diffs[:, np.newaxis, :] + periodic_shift[np.newaxis, :, :]
@@ -692,6 +704,5 @@ def _displacement_triclinic_box(fractions, box, disp):
     # for each given non-PBC-aware displacement find the PBC-aware
     # displacement with the lowest distance
     disp[:] = shifted_diffs[
-        np.arange(len(shifted_diffs)),
-        np.argmin(sq_distance, axis=1)
+        np.arange(len(shifted_diffs)), np.argmin(sq_distance, axis=1)
     ]