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

biotite/structure/basepairs.py

@@ -338,8 +338,8 @@ def base_pairs_edge(atom_array, base_pairs):
 
     See Also
     --------
-    base_pairs
-    base_pairs_glycosidic_bond
+    base_pairs : Get the base pairs required for this function.
+    base_pairs_glycosidic_bond : Determine the orientation for each base pair.
 
     Notes
     -----
@@ -351,6 +351,11 @@ def base_pairs_edge(atom_array, base_pairs):
     The edge returned always corresponds to the edge with the most
     hydrogen bonding interactions.
 
+    References
+    ----------
+
+    .. footbibliography::
+
     Examples
     --------
     Compute the interacting base edges for the dna helix with the PDB
@@ -392,11 +397,6 @@ def base_pairs_edge(atom_array, base_pairs):
     WATSON_CRICK to WATSON_CRICK
     WATSON_CRICK to WATSON_CRICK
     WATSON_CRICK to WATSON_CRICK
-
-    References
-    ----------
-
-    .. footbibliography::
     """
     # Result-``ndarray`` matches the dimensions of the input array
     results = np.zeros_like(base_pairs, dtype="uint8")
@@ -494,7 +494,7 @@ def base_pairs_glycosidic_bond(atom_array, base_pairs):
 
     Returns
     -------
-    results : ndarray, dtype=edge, shape=(n,)
+    results : ndarray, dtype=int, shape=(n,)
         The ``ndarray`` has the same dimensions as ``base_pairs``. Each
         cell corresponds to the interacting edge of the referenced base
         in ``base_pairs``.
@@ -504,15 +504,20 @@ def base_pairs_glycosidic_bond(atom_array, base_pairs):
 
     See Also
     --------
-    base_pairs
-    base_pairs_edge
-    GlycosidicBond
+    base_pairs : Get the base pairs required for this function.
+    base_pairs_edge : Determine the interacting edge for each base pair.
+    GlycosidicBond : The Enum type for interpretation of the return value.
 
     Notes
     -----
     The orientation is found using the geometric centers of the bases
     and the glycosidic bonds as described in :footcite:`Yang2003`.
 
+    References
+    ----------
+
+    .. footbibliography::
+
     Examples
     --------
     Compute the glycosidic bond orientations for the dna helix with the
@@ -544,11 +549,6 @@ def base_pairs_glycosidic_bond(atom_array, base_pairs):
     CIS
     CIS
     CIS
-
-    References
-    ----------
-
-    .. footbibliography::
     """
     results = np.zeros(len(base_pairs), dtype="uint8")
 
@@ -638,7 +638,7 @@ def base_stacking(atom_array, min_atoms_per_base=3):
     ----------
     atom_array : AtomArray
         The :class:`AtomArray` to find stacked bases in.
-    min_atoms_per_base : integer, optional (default: 3)
+    min_atoms_per_base : integer, optional
         The number of atoms a nucleotides' base must have to be
         considered a candidate for a stacking interaction.
 
@@ -654,6 +654,11 @@ def base_stacking(atom_array, min_atoms_per_base=3):
     Please note that ring normal vectors are assumed to be equal to the
     base normal vectors.
 
+    References
+    ----------
+
+    .. footbibliography::
+
     Examples
     --------
     Compute the stacking interactions for a DNA-double-helix (PDB ID
@@ -685,11 +690,6 @@ def base_stacking(atom_array, min_atoms_per_base=3):
      [21 22]
      [22 23]
      [23 24]]
-
-    References
-    ----------
-
-    .. footbibliography::
     """
     # Get the stacking candidates according to a cutoff distance, where
     # each base is identified as the first index of its respective
@@ -783,10 +783,10 @@ def base_pairs(atom_array, min_atoms_per_base=3, unique=True):
     ----------
     atom_array : AtomArray
         The :class:`AtomArray` to find base pairs in.
-    min_atoms_per_base : integer, optional (default: 3)
+    min_atoms_per_base : integer, optional
         The number of atoms a nucleotides' base must have to be
         considered a candidate for a base pair.
-    unique : bool, optional (default: True)
+    unique : bool, optional
         If ``True``, each base is assumed to be only paired with one
         other base. If multiple pairings are plausible, the pairing with
         the most hydrogen bonds is selected.
@@ -833,6 +833,11 @@ def base_pairs(atom_array, min_atoms_per_base=3, unique=True):
     1.00Å and 0.96Å respectively. Thus, including some buffer, a 3.6Å
     cutoff should cover all hydrogen bonds.
 
+    References
+    ----------
+
+    .. footbibliography::
+
     Examples
     --------
     Compute the base pairs for the structure with the PDB ID 1QXB:
@@ -855,11 +860,6 @@ def base_pairs(atom_array, min_atoms_per_base=3, unique=True):
      ['DG' 'DC']
      ['DC' 'DG']
      ['DG' 'DC']]
-
-    References
-    ----------
-
-    .. footbibliography::
     """
 
     # Get the nucleotides for the given atom_array
@@ -1203,26 +1203,25 @@ def map_nucleotide(residue, min_atoms_per_base=3, rmsd_cutoff=0.28):
     If a different nucleotide is given, it is mapped to the best
     fitting base using the algorithm described below.
 
-    (i) The number of matching atom names with the reference bases is
-        counted. If the number of matching atoms with all reference
-        bases is less than the specified `min_atoms_per_base`
-        (default 3) the nucleotide cannot be mapped and ``None`` is
+    (i) The number of matching atom names with the reference bases is counted.
+        If the number of matching atoms with all reference bases is less than the
+        specified `min_atoms_per_base` the nucleotide cannot be mapped and ``None`` is
         returned.
 
-    (ii) The bases with maximum number of matching atoms are selected
-         and superimposed with each reference. The base with lowest RMSD
-         is chosen. If the RMSD is more than the specified
-         `rmsd_cutoff` (default 0.28) the nucleotide cannot be mapped
-         and ``None`` is returned.
+    (ii) The bases with maximum number of matching atoms are selected and superimposed
+         with each reference.
+         The base with lowest RMSD is chosen.
+         If the RMSD is more than the specified `rmsd_cutoff`, the nucleotide cannot be
+         mapped and ``None`` is returned.
 
     Parameters
     ----------
     residue : AtomArray
         The nucleotide to be mapped.
-    min_atoms_per_base : int, optional (default: 3)
+    min_atoms_per_base : int, optional
         The number of atoms the residue must have in common with the
         reference.
-    rmsd_cutoff : float, optional (default: 0.28)
+    rmsd_cutoff : float, optional
         The maximum RSMD that is allowed for a mapping to occur.
 
     Returns

biotite/structure/bonds.pyx

@@ -60,6 +60,7 @@ class BondType(IntEnum):
         - `AROMATIC_SINGLE` - Aromatic bond with a single formal bond
         - `AROMATIC_DOUBLE` - Aromatic bond with a double formal bond
         - `AROMATIC_TRIPLE` - Aromatic bond with a triple formal bond
+        - `AROMATIC` - Aromatic bond without specification of the formal bond
         - `COORDINATION` - Coordination complex involving a metal atom
     """
     ANY = 0
@@ -71,6 +72,7 @@ class BondType(IntEnum):
     AROMATIC_DOUBLE = 6
     AROMATIC_TRIPLE = 7
     COORDINATION = 8
+    AROMATIC = 9
 
 
     def without_aromaticity(self):
@@ -97,6 +99,8 @@ class BondType(IntEnum):
             return BondType.DOUBLE
         elif self == BondType.AROMATIC_TRIPLE:
             return BondType.TRIPLE
+        elif self == BondType.AROMATIC:
+            return BondType.ANY
         else:
             return self
 
@@ -517,7 +521,8 @@ class BondList(Copyable):
         for aromatic_type, non_aromatic_type in [
             (BondType.AROMATIC_SINGLE, BondType.SINGLE),
             (BondType.AROMATIC_DOUBLE, BondType.DOUBLE),
-            (BondType.AROMATIC_TRIPLE, BondType.TRIPLE)
+            (BondType.AROMATIC_TRIPLE, BondType.TRIPLE),
+            (BondType.AROMATIC, BondType.ANY),
         ]:
             bond_types[bond_types == aromatic_type] = non_aromatic_type
 
@@ -938,7 +943,6 @@ class BondList(Copyable):
         ----------
         atom_index : int
             The index of the atom whose bonds should be removed.
-
         """
         cdef uint32 index = _to_positive_index(atom_index, self._atom_count)
 
@@ -1478,7 +1482,7 @@ def connect_via_distances(atoms, dict distance_range=None, bint inter_residue=Tr
     BondList
         The created bond list.
 
-    See also
+    See Also
     --------
     connect_via_residue_names
 
@@ -1617,7 +1621,7 @@ def connect_via_residue_names(atoms, bint inter_residue=True,
         No bonds are added for residues that are not found in
         ``components.cif``.
 
-    See also
+    See Also
     --------
     connect_via_distances
 
@@ -1659,7 +1663,6 @@ def connect_via_residue_names(atoms, bint inter_residue=True,
              ('OXT', 'HXT'): <BondType.SINGLE: 1>},
      'XYZ': {('A', 'B'): <BondType.SINGLE: 1>,
              ('B', 'C'): <BondType.SINGLE: 1>}}
-
     """
     from .info.bonds import bonds_in_residue
     from .residues import get_residue_starts

biotite/structure/box.py

@@ -4,12 +4,13 @@
 
 """
 Functions related to working with the simulation box or unit cell
-of a structure
+of a structure.
 """
 
 __name__ = "biotite.structure"
 __author__ = "Patrick Kunzmann"
 __all__ = [
+    "space_group_transforms",
     "vectors_from_unitcell",
     "unitcell_from_vectors",
     "box_volume",
@@ -23,16 +24,127 @@ __all__ = [
     "is_orthogonal",
 ]
 
+import functools
+import json
 from numbers import Integral
+from pathlib import Path
 import numpy as np
 import numpy.linalg as linalg
 from biotite.structure.atoms import repeat
 from biotite.structure.chains import get_chain_masks, get_chain_starts
 from biotite.structure.error import BadStructureError
 from biotite.structure.molecules import get_molecule_masks
+from biotite.structure.transform import AffineTransformation
 from biotite.structure.util import vector_dot
 
 
+def space_group_transforms(space_group):
+    """
+    Get the coordinate transformations for a given space group.
+
+    Applying each transformation to a structure (in fractional coordinates) reproduces
+    the entire unit cell.
+
+    Parameters
+    ----------
+    space_group : str or int
+        The space group name (full *Hermann-Mauguin* symbol) or
+        *International Table*'s number.
+
+    Returns
+    -------
+    transformations : list of AffineTransformation
+        The transformations that creates the symmetric copies of a structure in a unit
+        cell of the given space group.
+        Note that the transformations need to be applied to coordinates in fractions
+        of the unit cell and also return fractional coordinates, when applied.
+
+    See Also
+    --------
+    coord_to_fraction : Used to convert to fractional coordinates.
+    fraction_to_coord : Used to convert back to Cartesian coordinates.
+
+    Examples
+    --------
+
+    >>> transforms = space_group_transforms("P 21 21 21")
+    >>> for transform in transforms:
+    ...     print(transform.rotation)
+    ...     print(transform.target_translation)
+    ...     print()
+    [[[1. 0. 0.]
+      [0. 1. 0.]
+      [0. 0. 1.]]]
+    [[0. 0. 0.]]
+    <BLANKLINE>
+    [[[-1.  0.  0.]
+      [ 0. -1.  0.]
+      [ 0.  0.  1.]]]
+    [[0.5 0.0 0.5]]
+    <BLANKLINE>
+    [[[-1.  0.  0.]
+      [ 0.  1.  0.]
+      [ 0.  0. -1.]]]
+    [[0.0 0.5 0.5]]
+    <BLANKLINE>
+    [[[ 1.  0.  0.]
+      [ 0. -1.  0.]
+      [ 0.  0. -1.]]]
+    [[0.5 0.5 0.0]]
+    <BLANKLINE>
+
+    Reproduce the unit cell for some coordinates (in this case only one atom).
+
+    >>> asym_coord = np.array([[1.0, 2.0, 3.0]])
+    >>> box = np.eye(3) * 10
+    >>> transforms = space_group_transforms("P 21 21 21")
+    >>> # Apply the transformations to fractional coordinates of the asymmetric unit
+    >>> unit_cell = np.concatenate(
+    ...     [
+    ...         fraction_to_coord(transform.apply(coord_to_fraction(asym_coord, box)), box)
+    ...         for transform in transforms
+    ...     ]
+    ... )
+    >>> print(unit_cell)
+    [[ 1.  2.  3.]
+     [ 4. -2.  8.]
+     [-1.  7.  2.]
+     [ 6.  3. -3.]]
+    """
+    transformation_data = _get_transformation_data()
+
+    if isinstance(space_group, str):
+        try:
+            space_group_index = transformation_data["group_names"][space_group]
+        except KeyError:
+            raise ValueError(f"Space group '{space_group}' does not exist")
+    else:
+        try:
+            space_group_index = transformation_data["group_numbers"][str(space_group)]
+        except KeyError:
+            raise ValueError(f"Space group number {space_group} does not exist")
+
+    space_group = transformation_data["space_groups"][space_group_index]
+    transformations = []
+    for transformation_index in space_group:
+        matrix = np.zeros((3, 3), dtype=np.float32)
+        translation = np.zeros(3, dtype=np.float32)
+        for i, part_index in enumerate(
+            transformation_data["transformations"][transformation_index]
+        ):
+            part = transformation_data["transformation_parts"][part_index]
+            matrix[i, :] = part[:3]
+            translation[i] = part[3]
+        transformations.append(
+            AffineTransformation(
+                center_translation=np.zeros(3, dtype=np.float32),
+                rotation=matrix,
+                target_translation=translation,
+            )
+        )
+    return transformations
+
+
 def vectors_from_unitcell(len_a, len_b, len_c, alpha, beta, gamma):
     """
     Calculate the three vectors spanning a box from the unit cell
@@ -45,10 +157,10 @@ def vectors_from_unitcell(len_a, len_b, len_c, alpha, beta, gamma):
     ----------
     len_a, len_b, len_c : float
         The lengths of the three box/unit cell vectors *a*, *b* and *c*.
-    alpha, beta, gamma:
+    alpha, beta, gamma : float
         The angles between the box vectors in radians.
         *alpha* is the angle between *b* and *c*,
-        *beta* between *a* and *c*, *gamma* between *a* and *b*
+        *beta* between *a* and *c*, *gamma* between *a* and *b*.
 
     Returns
     -------
@@ -58,9 +170,9 @@ def vectors_from_unitcell(len_a, len_b, len_c, alpha, beta, gamma):
         The value can be directly used as :attr:`box` attribute in an
         atom array.
 
-    See also
+    See Also
     --------
-    unitcell_from_vectors
+    unitcell_from_vectors : The reverse operation.
     """
     a_x = len_a
     b_x = len_b * np.cos(gamma)
@@ -87,7 +199,7 @@ def unitcell_from_vectors(box):
     Parameters
     ----------
     box : ndarray, shape=(3,3)
-        The box vectors
+        The box vectors.
 
     Returns
     -------
@@ -96,9 +208,9 @@ def unitcell_from_vectors(box):
     alpha, beta, gamma : float
         The angles between the box vectors in radians.
 
-    See also
+    See Also
     --------
-    vectors_from_unitcell
+    vectors_from_unitcell : The reverse operation.
     """
     a = box[0]
     b = box[1]
@@ -124,6 +236,7 @@ def box_volume(box):
     Returns
     -------
     volume : float or ndarray, shape=(m,)
+        The volume(s) of the given box(es).
     """
     # Using the triple product
     return np.abs(linalg.det(box))
@@ -159,14 +272,16 @@ def repeat_box(atoms, amount=1):
         The repeated atoms.
         Includes the original atoms (central box) in the beginning of
         the atom array (stack).
+        If the input contains the ``sym_id`` annotation, the IDs are continued in the
+        repeated atoms, i.e. they do not start at 0 again.
     indices : ndarray, dtype=int, shape=(n,3)
         Indices to the atoms in the original atom array (stack).
         Equal to
         ``numpy.tile(np.arange(atoms.array_length()), (1 + 2 * amount) ** 3)``.
 
-    See also
+    See Also
     --------
-    repeat_box_coord
+    repeat_box_coord : Variant that acts directly on coordinates.
 
     Examples
     --------
@@ -233,6 +348,15 @@ def repeat_box(atoms, amount=1):
     >>> print(indices)
     [0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0
      1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1]
+
+    The ``sym_id`` is continued in the repeated atoms.
+
+    >>> array.set_annotation("sym_id", np.array([0, 0]))
+    >>> repeated, indices = repeat_box(array)
+    >>> print(repeated.sym_id)
+    [ 0  0  1  1  2  2  3  3  4  4  5  5  6  6  7  7  8  8  9  9 10 10 11 11
+     12 12 13 13 14 14 15 15 16 16 17 17 18 18 19 19 20 20 21 21 22 22 23 23
+     24 24 25 25 26 26]
     """
     if atoms.box is None:
         raise BadStructureError("Structure has no box")
@@ -246,7 +370,16 @@ def repeat_box(atoms, amount=1):
             atoms.stack_depth(), -1, atoms.array_length(), 3
         )
         repeat_coord = np.swapaxes(repeat_coord, 0, 1)
-    return repeat(atoms, repeat_coord), indices
+
+    repeated_atoms = repeat(atoms, repeat_coord)
+    if "sym_id" in atoms.get_annotation_categories():
+        max_sym_id = np.max(atoms.sym_id)
+        # for the first repeat, (max_sym_id + 1) is added,
+        # for the second repeat 2*(max_sym_id + 1) etc.
+        repeated_atoms.sym_id += (max_sym_id + 1) * (
+            np.arange(repeated_atoms.array_length()) // atoms.array_length()
+        )
+    return repeated_atoms, indices
 
 
 def repeat_box_coord(coord, box, amount=1):
@@ -383,9 +516,9 @@ def remove_pbc(atoms, selection=None):
         The input structure with removed segmentation over periodic
         boundaries.
 
-    See also
+    See Also
     --------
-    remove_pbc_from_coord
+    remove_pbc_from_coord : Variant that acts directly on coordinates.
 
     Notes
     -----
@@ -430,8 +563,6 @@ def remove_pbc_from_coord(coord, box):
     is moved inside the box.
     All other coordinates are assembled relative to the origin by using
     the displacement coordinates in adjacent array positions.
-    Basically, this function performs the reverse action of
-    :func:`move_inside_box()`.
 
     Parameters
     ----------
@@ -447,10 +578,9 @@ def remove_pbc_from_coord(coord, box):
     sanitized_coord : ndarray, dtype=float, shape=(m,n,3) or shape=(n,3)
         The reassembled coordinates.
 
-    See also
+    See Also
     --------
-    remove_pbc_from_coord
-    move_inside_box
+    move_inside_box : The reverse operation.
 
     Notes
     -----
@@ -501,9 +631,9 @@ def coord_to_fraction(coord, box):
     fraction : ndarray, dtype=float, shape=(n,3) or shape=(m,n,3)
         The fractions of the box vectors.
 
-    See also
+    See Also
     --------
-    fraction_to_coord
+    fraction_to_coord : The reverse operation.
 
     Examples
     --------
@@ -548,9 +678,9 @@ def fraction_to_coord(fraction, box):
     coord : ndarray, dtype=float, shape=(n,3) or shape=(m,n,3)
         The coordinates.
 
-    See also
+    See Also
     --------
-    coord_to_fraction
+    coord_to_fraction : The reverse operation.
     """
     return np.matmul(fraction, box)
 
@@ -570,7 +700,7 @@ def is_orthogonal(box):
     Returns
     -------
     is_orthgonal : bool or ndarray, shape=(m,), dtype=bool
-        True, if the box vectors are orthogonal, false otherwise
+        True, if the box vectors are orthogonal, false otherwise.
 
     Notes
     -----
@@ -586,3 +716,9 @@ def is_orthogonal(box):
         & (np.abs(vector_dot(box[..., 0, :], box[..., 2, :])) < tol)
         & (np.abs(vector_dot(box[..., 1, :], box[..., 2, :])) < tol)
     )
+
+
+@functools.cache
+def _get_transformation_data():
+    with open(Path(__file__).parent / "spacegroups.json") as file:
+        return json.load(file)