biotite 1.2.0__cp311-cp311-macosx_11_0_arm64.whl → 1.3.0__cp311-cp311-macosx_11_0_arm64.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/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/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/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,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")
@@ -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`.

biotite/structure/chains.py

@@ -22,23 +22,23 @@ __all__ = [
     "chain_iter",
 ]
 
-import numpy as np
 from biotite.structure.segments import (
     apply_segment_wise,
     get_segment_masks,
     get_segment_positions,
+    get_segment_starts,
     get_segment_starts_for,
     segment_iter,
     spread_segment_wise,
 )
 
 
-def get_chain_starts(array, add_exclusive_stop=False):
+def get_chain_starts(array, add_exclusive_stop=False, extra_categories=()):
     """
     Get the indices in an atom array, which indicates the beginning of
     a new chain.
 
-    A new chain starts, when the chain ID changes or when the residue ID
+    A new chain starts, when the chain or sym ID changes or when the residue ID
     decreases.
 
     Parameters
@@ -49,6 +49,9 @@ def get_chain_starts(array, add_exclusive_stop=False):
         If true, the exclusive stop of the input atom array, i.e.
         ``array.array_length()``, is added to the returned array of
         start indices as last element.
+    extra_categories : tuple of str, optional
+        Additional annotation categories that induce the start of a new chain,
+        when their value change from one atom to the next.
 
     Returns
     -------
@@ -60,24 +63,15 @@ def get_chain_starts(array, add_exclusive_stop=False):
     This method is internally used by all other chain-related
     functions.
     """
-    if array.array_length() == 0:
-        return np.array([], dtype=int)
-
-    diff = np.diff(array.res_id)
-    res_id_decrement = diff < 0
-    # This mask is 'true' at indices where the value changes
-    chain_id_changes = array.chain_id[1:] != array.chain_id[:-1]
-
-    # Convert mask to indices
-    # Add 1, to shift the indices from the end of a chain
-    # to the start of a new chain
-    chain_starts = np.where(res_id_decrement | chain_id_changes)[0] + 1
-
-    # The first chain is not included yet -> Insert '[0]'
-    if add_exclusive_stop:
-        return np.concatenate(([0], chain_starts, [array.array_length()]))
-    else:
-        return np.concatenate(([0], chain_starts))
+    categories = ["chain_id"] + list(extra_categories)
+    if "sym_id" in array.get_annotation_categories():
+        categories.append("sym_id")
+    return get_segment_starts(
+        array,
+        add_exclusive_stop,
+        continuous_categories=("res_id",),
+        equal_categories=categories,
+    )
 
 
 def apply_chain_wise(array, data, function, axis=None):

biotite/structure/dotbracket.py

@@ -33,10 +33,10 @@ def dot_bracket_from_structure(
     ----------
     nucleic_acid_strand : AtomArray
         The nucleic acid strand to be represented in DBL-notation.
-    scores : ndarray, dtype=int, shape=(n,) (default: None)
+    scores : ndarray, dtype=int, shape=(n,)
         The score for each base pair, which is passed on to
         :func:`pseudoknots()`.
-    max_pseudoknot_order : int (default: None)
+    max_pseudoknot_order : int
         The maximum pseudoknot order to be found. If a base pair would
         be of a higher order, it is represented as unpaired. If ``None``
         is given, all base pairs are evaluated.
@@ -82,9 +82,9 @@ def dot_bracket(basepairs, length, scores=None, max_pseudoknot_order=None):
         strand.
     length : int
         The number of bases in the strand.
-    scores : ndarray, dtype=int, shape=(n,) (default: None)
+    scores : ndarray, dtype=int, shape=(n,)
         The score for each base pair, which is passed on to :func:`pseudoknots()`.
-    max_pseudoknot_order : int (default: None)
+    max_pseudoknot_order : int
         The maximum pseudoknot order to be found. If a base pair would
         be of a higher order, it is represented as unpaired. If ``None``
         is given, all pseudoknot orders are evaluated.

biotite/structure/graphics/rna.py

@@ -57,59 +57,62 @@ def plot_nucleotide_secondary_structure(
         sequence. The positions are counted from zero.
     length : int
         The number of bases in the sequence.
-    layout_type : RNAplotApp.Layout, optional (default: RNAplotApp.Layout.NAVIEW)
+    layout_type : RNAplotApp.Layout, optional
         The layout type according to the *RNAplot* documentation.
-    draw_pseudoknots : bool, optional (default: True)
+    draw_pseudoknots : bool, optional
         Whether pseudoknotted bonds should be drawn.
-    pseudoknot_order : iterable, optional (default: None)
+    pseudoknot_order : iterable, optional
         The pseudoknot order of each pair in the input `base_pairs`.
         If no pseudoknot order is given, a solution determined by
         :func:`biotite.structure.pseudoknots` is picked at random.
-    angle : int or float, optional (default: 0)
+    angle : int or float, optional
         The angle the plot should be rotated.
-    bond_linewidth : float or int or iterable, optional (default: 1)
+    bond_linewidth : float or int or iterable, optional
         The linewidth of each bond. Provide a single value to set the
         linewidth for all bonds or an iterable to set the linewidth for
         each individual bond.
-    bond_linestyle : str or iterable, optional (default: None)
+    bond_linestyle : str or iterable, optional
         The *Matplotlib* compatible linestyle of each bond. Provide a
         single value to set the linewidth for all bonds or an iterable
         to set the linewidth for each individual bond. By default, solid
         lines are used for non-pseudoknotted bonds and dashed lines are
         used for pseudoknotted bonds.
-    bond_color : str or ndarray, shape(n,) or shape(n,3) or shape(n,4), optional (default: 'black')
+    bond_color : str or ndarray, shape(n,) or shape(n,3) or shape(n,4), optional
         The *Matplotlib* compatible color of each bond. Provide a single
         string to set the color for all bonds or an array to set the
         color for each individual bond.
-    backbone_linewidth : float, optional (default: 1)
+    backbone_linewidth : float, optional
         The linewidth of the backbone.
-    backbone_linestyle : str, optional (default: 'solid')
+    backbone_linestyle : str, optional
         The *Matplotlib* compatible linestyle of the backbone.
-    backbone_color : str or ndarray, shape=(3,) or shape=(4,), dtype=float, optional (default: 'grey')
+    backbone_color : str or ndarray, shape=(3,) or shape=(4,), dtype=float, optional
         The *Matplotlib* compatible color of the backbone.
-    base_text : dict or iterable, optional (default: {'size': 'small'})
+    base_text : dict or iterable, optional
         The keyword parameters for the *Matplotlib* ``Text`` objects
         denoting the type of each base. Provide a single value to set
         the parameters for all labels or an iterable to set the
         parameters for each individual label.
-    base_box : dict or iterable, optional (default: {'pad'=0, 'color'='white'})
+        The default is ``{'size': 'small'}``.
+    base_box : dict or iterable, optional)
         The *Matplotlib* compatible properties of the ``FancyBboxPatch``
         surrounding the base labels. Provide a single dictionary to
         set the properties of all base lables or an iterable to set the
         properties for each individual label.
-    annotation_positions : iterable, optional (default: None)
+        The default is ``{'pad'=0, 'color'='white'}``.
+    annotation_positions : iterable, optional
         The positions of the bases to be numbered. By default every
         second base is annotated. Please note that while the positions
         in the sequence are counted from zero, they are displayed on the
         graph counted from one.
-    annotation_offset : int or float, optional (default: 8.5)
+    annotation_offset : int or float, optional
         The offset of the annotations from the base labels.
-    annotation_text : dict or iterable, optional (default: {'size': 'small'})
+    annotation_text : dict or iterable, optional
         The keyword parameters for the *Matplotlib* ``Text`` objects
         annotating the sequence. Provide a single value to set the
         parameters for all annotations or an iterable to set the
         parameters for each individual annotation.
-    border : float, optional (default: 0.03)
+        The default is ``{'size': 'small'}``.
+    border : float, optional
         The percentage of the coordinate range to be left as whitespace
         to create a border around the plot.
     bin_path : str, optional

biotite/structure/hbond.py

@@ -59,8 +59,7 @@ def hbond(
         The angle cutoff in degree between Donor-H..Acceptor to be
         considered a hydrogen bond.
     donor_elements, acceptor_elements : tuple of str
-        Elements to be considered as possible donors or acceptors
-        (Default: O, N, S).
+        Elements to be considered as possible donors or acceptors.
     periodic : bool, optional
         If true, hydrogen bonds can also be detected in periodic
         boundary conditions.