biotite 1.2.0__cp312-cp312-win_amd64.whl → 1.4.0__cp312-cp312-win_amd64.whl

biotite/application/viennarna/rnaplot.py

@@ -28,15 +28,15 @@ class RNAplotApp(LocalApp):
 
     Parameters
     ----------
-    dot_bracket : str, optional (default: None)
+    dot_bracket : str, optional
         The structure in dot bracket notation.
-    base_pairs : ndarray, shape=(n,2), optional (default: None)
+    base_pairs : ndarray, shape=(n,2), optional
         Each row corresponds to the positions of the bases in the
         strand. This parameter is mutually exclusive to ``dot_bracket``.
-    length : int, optional (default: None)
+    length : int, optional
         The number of bases in the strand. This parameter is required if
         ``base_pairs`` is given.
-    layout_type : RNAplotApp.Layout, optional (default: RNAplotApp.Layout.NAVIEW)
+    layout_type : RNAplotApp.Layout, optional
         The layout type according to the *RNAplot* documentation.
     bin_path : str, optional
         Path of the *RNAplot* binary.
@@ -176,13 +176,13 @@ class RNAplotApp(LocalApp):
 
         Parameters
         ----------
-        dot_bracket : str, optional (default: None)
+        dot_bracket : str, optional
             The structure in dot bracket notation.
-        base_pairs : ndarray, shape=(n,2), optional (default: None)
+        base_pairs : ndarray, shape=(n,2), optional
             Each row corresponds to the positions of the bases in the
             strand. This parameter is mutually exclusive to
             ``dot_bracket``.
-        length : int, optional (default: None)
+        length : int, optional
             The number of bases in the strand. This parameter is
             required if ``base_pairs`` is given.
         layout_type : Layout

biotite/interface/openmm/__init__.py

@@ -12,5 +12,9 @@ structure-related objects from *OpenMM*.
 __name__ = "biotite.interface.openmm"
 __author__ = "Patrick Kunzmann"
 
+from biotite.interface.version import require_package
+
+require_package("openmm")
+
 from .state import *
 from .system import *

biotite/interface/pymol/__init__.py

@@ -162,6 +162,9 @@ or ``pymol_interface.cmd`` at the required places in your code.
 __name__ = "biotite.interface.pymol"
 __author__ = "Patrick Kunzmann"
 
+from biotite.interface.version import require_package
+
+require_package("pymol")
 
 from .cgo import *
 from .convert import *

biotite/interface/pymol/object.py

@@ -388,7 +388,9 @@ class PyMOLObject:
         elif isinstance(selection, str):
             return f"%{self._name} and ({selection})"
         else:
-            sel = self.where(np.asarray(selection))
+            if not isinstance(selection, slice):
+                selection = np.asarray(selection)
+            sel = self.where(selection)
             if sel == "none" and not_none:
                 raise ValueError("Selection contains no atoms")
             return sel

biotite/interface/rdkit/__init__.py

@@ -12,4 +12,8 @@ objects.
 __name__ = "biotite.interface.rdkit"
 __author__ = "Patrick Kunzmann"
 
+from biotite.interface.version import require_package
+
+require_package("rdkit")
+
 from .mol import *

biotite/interface/rdkit/mol.py

@@ -59,7 +59,7 @@ _STANDARD_ANNOTATIONS = frozenset(
         "charge",
         "b_factor",
         "occupancy",
-        "label_alt_id",
+        "altloc_id",
     }
 )
 
@@ -202,8 +202,8 @@ def to_mol(
             rdkit_atom_res_info.SetOccupancy(atoms.occupancy[i].item())
         if "b_factor" in has_annot:
             rdkit_atom_res_info.SetTempFactor(atoms.b_factor[i].item())
-        if "label_alt_id" in has_annot:
-            rdkit_atom_res_info.SetAltLoc(atoms.label_alt_id[i].item())
+        if "altloc_id" in has_annot:
+            rdkit_atom_res_info.SetAltLoc(atoms.altloc_id[i].item())
         rdkit_atom.SetPDBResidueInfo(rdkit_atom_res_info)
 
         # add extra annotations
@@ -361,7 +361,7 @@ def from_mol(mol, conformer_id=None, add_hydrogen=None):
     atoms.add_annotation("charge", int)
     atoms.add_annotation("b_factor", float)
     atoms.add_annotation("occupancy", float)
-    atoms.add_annotation("label_alt_id", str)
+    atoms.add_annotation("altloc_id", str)
 
     for rdkit_atom in rdkit_atoms:
         _atom_idx = rdkit_atom.GetIdx()
@@ -406,7 +406,7 @@ def from_mol(mol, conformer_id=None, add_hydrogen=None):
         atoms.res_id[_atom_idx] = residue_info.GetResidueNumber()
         atoms.ins_code[_atom_idx] = residue_info.GetInsertionCode()
         atoms.res_name[_atom_idx] = residue_info.GetResidueName()
-        atoms.label_alt_id[_atom_idx] = residue_info.GetAltLoc()
+        atoms.altloc_id[_atom_idx] = residue_info.GetAltLoc()
         atoms.hetero[_atom_idx] = residue_info.GetIsHeteroAtom()
         atoms.b_factor[_atom_idx] = residue_info.GetTempFactor()
         atoms.occupancy[_atom_idx] = residue_info.GetOccupancy()

biotite/interface/version.py

@@ -26,6 +26,29 @@ class VersionError(Exception):
     pass
 
 
+def require_package(package):
+    """
+    Check if the given package is installed and raise an exception if not.
+
+    Parameters
+    ----------
+    package : str
+        The name of the package to be checked.
+
+    Raises
+    ------
+    ImportError
+        If the package is not installed.
+
+    Notes
+    -----
+    It is useful to call this function in the ``__init__.py`` of each ``interface``
+    subpackage, to obtain clear error messages about missing dependencies.
+    """
+    if importlib.util.find_spec(package) is None:
+        raise ImportError(f"'{package}' is not installed")
+
+
 def requires_version(package, version_specifier):
     """
     Declare a function variant that is compatible with a specific version range of the

biotite/sequence/align/banded.pyx

@@ -76,7 +76,7 @@ def align_banded(seq1, seq2, matrix, band, gap_penalty=-10, local=False,
         If a tuple is provided, an affine gap penalty is used.
         The first integer in the tuple is the gap opening penalty,
         the second integer is the gap extension penalty.
-        The values need to be negative. (Default: *-10*)
+        The values need to be negative.
     local : bool, optional
         If set to true, a local alignment is performed.
         Otherwise (default) a semi-global alignment is performed.

biotite/sequence/align/multiple.pyx

@@ -92,10 +92,9 @@ def align_multiple(sequences, matrix, gap_penalty=-10, terminal_penalty=True,
         penalty is used. The first integer in the tuple is the gap
         opening penalty, the second integer is the gap extension
         penalty.
-        The values need to be negative. (Default: *-10*)
+        The values need to be negative.
     terminal_penalty : bool, optional
         If true, gap penalties are applied to terminal gaps.
-        (Default: True)
     distances : ndarray, shape=(n,n)
         Pairwise distances of the sequences.
         The matrix must be symmetric and all entries must be larger

biotite/sequence/align/pairwise.pyx

@@ -138,19 +138,17 @@ def align_optimal(seq1, seq2, matrix, gap_penalty=-10,
         If a tuple is provided, an affine gap penalty is used.
         The first integer in the tuple is the gap opening penalty,
         the second integer is the gap extension penalty.
-        The values need to be negative. (Default: *-10*)
+        The values need to be negative.
     terminal_penalty : bool, optional
         If true, gap penalties are applied to terminal gaps.
         If `local` is true, this parameter has no effect.
-        (Default: True)
     local : bool, optional
         If false, a global alignment is performed, otherwise a local
-        alignment is performed. (Default: False)
+        alignment is performed.
     max_number : int, optional
         The maximum number of alignments returned.
         When the number of branches exceeds this value in the traceback
         step, no further branches are created.
-        (Default: 1000)
 
     Returns
     -------

biotite/structure/basepairs.py

@@ -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.
 
@@ -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.
@@ -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

@@ -517,14 +517,41 @@ class BondList(Copyable):
         0 1 SINGLE
         1 2 DOUBLE
         """
-        bond_types = self._bonds[:,2]
         for aromatic_type, non_aromatic_type in [
             (BondType.AROMATIC_SINGLE, BondType.SINGLE),
             (BondType.AROMATIC_DOUBLE, BondType.DOUBLE),
             (BondType.AROMATIC_TRIPLE, BondType.TRIPLE),
             (BondType.AROMATIC, BondType.ANY),
         ]:
-            bond_types[bond_types == aromatic_type] = non_aromatic_type
+            mask = self._bonds[:, 2] == aromatic_type
+            self._bonds[mask, 2] = non_aromatic_type
+
+    def remove_kekulization(self):
+        """
+        Remove the bond order information from aromatic bonds, i.e. convert all
+        aromatic bonds to :attr:`BondType.ANY`.
+
+        Examples
+        --------
+
+        >>> bond_list = BondList(3)
+        >>> bond_list.add_bond(0, 1, BondType.AROMATIC_SINGLE)
+        >>> bond_list.add_bond(1, 2, BondType.AROMATIC_DOUBLE)
+        >>> bond_list.remove_kekulization()
+        >>> for i, j, bond_type in bond_list.as_array():
+        ...     print(i, j, BondType(bond_type).name)
+        0 1 AROMATIC
+        1 2 AROMATIC
+        """
+        kekulized_mask = np.isin(
+            self._bonds[:, 2],
+            (
+                BondType.AROMATIC_SINGLE,
+                BondType.AROMATIC_DOUBLE,
+                BondType.AROMATIC_TRIPLE,
+            ),
+        )
+        self._bonds[kekulized_mask, 2] = BondType.AROMATIC
 
     def remove_bond_order(self):
         """
@@ -532,6 +559,41 @@ class BondList(Copyable):
         """
         self._bonds[:,2] = BondType.ANY
 
+    def convert_bond_type(self, original_bond_type, new_bond_type):
+        """
+        convert_bond_type(original_bond_type, new_bond_type)
+
+        Convert all occurences of a given bond type into another bond type.
+
+        Parameters
+        ----------
+        original_bond_type : BondType or int
+            The bond type to convert.
+        new_bond_type : BondType or int
+            The new bond type.
+
+        Examples
+        --------
+
+        >>> bond_list = BondList(4)
+        >>> bond_list.add_bond(0, 1, BondType.DOUBLE)
+        >>> bond_list.add_bond(1, 2, BondType.COORDINATION)
+        >>> bond_list.add_bond(2, 3, BondType.COORDINATION)
+        >>> for i, j, bond_type in bond_list.as_array():
+        ...     print(i, j, BondType(bond_type).name)
+        0 1 DOUBLE
+        1 2 COORDINATION
+        2 3 COORDINATION
+        >>> bond_list.convert_bond_type(BondType.COORDINATION, BondType.SINGLE)
+        >>> for i, j, bond_type in bond_list.as_array():
+        ...     print(i, j, BondType(bond_type).name)
+        0 1 DOUBLE
+        1 2 SINGLE
+        2 3 SINGLE
+        """
+        mask = self._bonds[:, 2] == original_bond_type
+        self._bonds[mask, 2] = new_bond_type
+
     def get_atom_count(self):
         """
         get_atom_count()
@@ -1437,9 +1499,8 @@ _DEFAULT_DISTANCE_RANGE = {
 def connect_via_distances(atoms, dict distance_range=None, bint inter_residue=True,
                           default_bond_type=BondType.ANY, bint periodic=False):
     """
-    connect_via_distances(atoms, distance_range=None, atom_mask=None,
-                          inter_residue=True, default_bond_type=BondType.ANY,
-                          periodic=False)
+    connect_via_distances(atoms, distance_range=None, inter_residue=True,
+                          default_bond_type=BondType.ANY, periodic=False)
 
     Create a :class:`BondList` for a given atom array, based on
     pairwise atom distances.
@@ -1589,7 +1650,7 @@ def connect_via_distances(atoms, dict distance_range=None, bint inter_residue=Tr
 def connect_via_residue_names(atoms, bint inter_residue=True,
                               dict custom_bond_dict=None):
     """
-    connect_via_residue_names(atoms, atom_mask=None, inter_residue=True)
+    connect_via_residue_names(atoms, inter_residue=True, custom_bond_dict=None)
 
     Create a :class:`BondList` for a given atom array (stack), based on
     the deposited bonds for each residue in the RCSB ``components.cif``

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
@@ -160,6 +272,8 @@ 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
@@ -234,11 +348,20 @@ 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")
 
-    repeat_coord, indices = repeat_box_coord(atoms.coord, atoms.box)
+    repeat_coord, indices = repeat_box_coord(atoms.coord, atoms.box, amount)
     # Unroll repeated coordinates for input to 'repeat()'
     if repeat_coord.ndim == 2:
         repeat_coord = repeat_coord.reshape(-1, atoms.array_length(), 3)
@@ -247,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):
@@ -584,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)

biotite/structure/celllist.pyx

@@ -55,7 +55,6 @@ cdef class CellList:
     periodic : bool, optional
         If true, the cell list considers periodic copies of atoms.
         The periodicity is based on the `box` attribute of `atom_array`.
-        (Default: False)
     box : ndarray, dtype=float, shape=(3,3), optional
         If provided, the periodicity is based on this parameter instead
         of the :attr:`box` attribute of `atom_array`.