biotite 0.41.1__cp312-cp312-macosx_10_16_x86_64.whl

biotite/structure/info/standardize.py

@@ -0,0 +1,196 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.structure.info"
+__author__ = "Patrick Kunzmann"
+__all__ = ["standardize_order"]
+
+import warnings
+import numpy as np
+from .ccd import get_from_ccd
+from ..residues import get_residue_starts
+from ..error import BadStructureError
+
+
+def standardize_order(atoms):
+    """
+    Get an index array for an input :class:`AtomArray` or
+    :class:`AtomArrayStack` that reorders the atoms for each residue
+    to obtain the standard *RCSB PDB* atom order.
+
+    The standard atom order is determined from the reference residues in
+    the official *Chemical Component Dictionary*.
+    If a residue of the input structure contains additional atoms that
+    are not present in the reference residue, these indices to these
+    atoms are appended to the end of the respective residue.
+    A example for this are optional hydrogen atoms, that appear due to
+    protonation.
+
+    Parameters
+    ----------
+    atoms : AtomArray, shape=(n,) or AtomArrayStack, shape=(m,n)
+        Input structure with atoms that are potentially not in the
+        *standard* order.
+
+    Returns
+    -------
+    indices : ndarray, dtype=int, shape=(n,)
+        When this index array is applied on the input `atoms`,
+        the atoms for each residue are reordered to obtain the
+        standard *RCSB PDB* atom order.
+
+    Raises
+    ------
+    BadStructureError
+        If the input `atoms` have duplicate atoms (same atom name)
+        within a residue.
+
+    Examples
+    --------
+
+    Use as single residue as example.
+
+    >>> residue = atom_array[atom_array.res_id == 1]
+    >>> print(residue)
+        A       1  ASN N      N        -8.901    4.127   -0.555
+        A       1  ASN CA     C        -8.608    3.135   -1.618
+        A       1  ASN C      C        -7.117    2.964   -1.897
+        A       1  ASN O      O        -6.634    1.849   -1.758
+        A       1  ASN CB     C        -9.437    3.396   -2.889
+        A       1  ASN CG     C       -10.915    3.130   -2.611
+        A       1  ASN OD1    O       -11.269    2.700   -1.524
+        A       1  ASN ND2    N       -11.806    3.406   -3.543
+        A       1  ASN H1     H        -8.330    3.957    0.261
+        A       1  ASN H2     H        -8.740    5.068   -0.889
+        A       1  ASN H3     H        -9.877    4.041   -0.293
+        A       1  ASN HA     H        -8.930    2.162   -1.239
+        A       1  ASN HB2    H        -9.310    4.417   -3.193
+        A       1  ASN HB3    H        -9.108    2.719   -3.679
+        A       1  ASN HD21   H       -11.572    3.791   -4.444
+        A       1  ASN HD22   H       -12.757    3.183   -3.294
+
+    Reverse the atom array.
+    Consequently, this also changes the atom order within the residue.
+
+    >>> reordered = residue[np.arange(len(residue))[::-1]]
+    >>> print(reordered)
+        A       1  ASN HD22   H       -12.757    3.183   -3.294
+        A       1  ASN HD21   H       -11.572    3.791   -4.444
+        A       1  ASN HB3    H        -9.108    2.719   -3.679
+        A       1  ASN HB2    H        -9.310    4.417   -3.193
+        A       1  ASN HA     H        -8.930    2.162   -1.239
+        A       1  ASN H3     H        -9.877    4.041   -0.293
+        A       1  ASN H2     H        -8.740    5.068   -0.889
+        A       1  ASN H1     H        -8.330    3.957    0.261
+        A       1  ASN ND2    N       -11.806    3.406   -3.543
+        A       1  ASN OD1    O       -11.269    2.700   -1.524
+        A       1  ASN CG     C       -10.915    3.130   -2.611
+        A       1  ASN CB     C        -9.437    3.396   -2.889
+        A       1  ASN O      O        -6.634    1.849   -1.758
+        A       1  ASN C      C        -7.117    2.964   -1.897
+        A       1  ASN CA     C        -8.608    3.135   -1.618
+        A       1  ASN N      N        -8.901    4.127   -0.555
+
+    The order is restored with the exception of the N-terminus protonation.
+
+    >>> restored = reordered[info.standardize_order(reordered)]
+    >>> print(restored)
+        A       1  ASN N      N        -8.901    4.127   -0.555
+        A       1  ASN CA     C        -8.608    3.135   -1.618
+        A       1  ASN C      C        -7.117    2.964   -1.897
+        A       1  ASN O      O        -6.634    1.849   -1.758
+        A       1  ASN CB     C        -9.437    3.396   -2.889
+        A       1  ASN CG     C       -10.915    3.130   -2.611
+        A       1  ASN OD1    O       -11.269    2.700   -1.524
+        A       1  ASN ND2    N       -11.806    3.406   -3.543
+        A       1  ASN H2     H        -8.740    5.068   -0.889
+        A       1  ASN HA     H        -8.930    2.162   -1.239
+        A       1  ASN HB2    H        -9.310    4.417   -3.193
+        A       1  ASN HB3    H        -9.108    2.719   -3.679
+        A       1  ASN HD21   H       -11.572    3.791   -4.444
+        A       1  ASN HD22   H       -12.757    3.183   -3.294
+        A       1  ASN H3     H        -9.877    4.041   -0.293
+        A       1  ASN H1     H        -8.330    3.957    0.261
+    """
+    reordered_indices = np.zeros(atoms.array_length(), dtype=int)
+
+    starts = get_residue_starts(atoms, add_exclusive_stop=True)
+    for i in range(len(starts)-1):
+        start = starts[i]
+        stop = starts[i+1]
+
+        res_name = atoms.res_name[start]
+        standard_atom_names = get_from_ccd(
+            "chem_comp_atom", res_name, "atom_id"
+        )
+        if standard_atom_names is None:
+            # If the residue is not in the CCD, keep the current order
+            warnings.warn(
+                f"Residue '{res_name}' is not in the CCD, "
+                f"keeping current atom order"
+            )
+            reordered_indices[start : stop] = np.arange(start, stop)
+            continue
+
+        reordered_indices[start : stop] = _reorder(
+            atoms.atom_name[start : stop], standard_atom_names
+        ) + start
+
+    return reordered_indices
+
+
+def _reorder(origin, target):
+    """
+    Create indices to `origin`, that changes the order of `origin`,
+    so that the order is the same as in `target`.
+
+    Indices for elements of `target` that are not in `origin`
+    are ignored.
+    Indices for elements of `origin` that are not in `target`
+    are appended to the end of the returned array.
+
+
+    Parameters
+    ----------
+    origin : ndarray, dtype=str
+        The atom names to reorder.
+    target : ndarray, dtype=str
+        The atom names in target order.
+
+    Returns
+    -------
+    indices : ndarray, dtype=int
+        Indices for `origin` that that changes the order of `origin`
+        to the order of `target`.
+    """
+    target_hits, origin_hits = np.where(
+        target[:, np.newaxis] == origin[np.newaxis, :]
+    )
+
+    counts = np.bincount(target_hits, minlength=len(target))
+    if (counts > 1).any():
+        counts = np.bincount(target_hits, minlength=len(target))
+        # Identify which atom is duplicate
+        duplicate_i = np.where(
+            counts > 1
+        )[0][0]
+        duplicate_name = target[duplicate_i]
+        raise BadStructureError(
+            f"Input structure has duplicate atom '{duplicate_name}'"
+        )
+
+    if len(origin_hits) < len(origin):
+        # The origin structure has additional atoms
+        # to the target structure
+        # -> Identify which atoms are missing in the target structure
+        # and append these to the end of the residue
+        missing_atom_mask = np.bincount(
+            origin_hits, minlength=len(origin)
+        ).astype(bool)
+        return np.concatenate([
+            origin_hits,
+            np.where(~missing_atom_mask)[0]
+        ])
+    else:
+        return origin_hits

biotite/structure/integrity.py

@@ -0,0 +1,268 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+This module allows checking of atom arrays and atom array stacks for
+errors in the structure.
+"""
+
+__name__ = "biotite.structure"
+__author__ = "Patrick Kunzmann, Daniel Bauer"
+__all__ = ["check_id_continuity", "check_atom_id_continuity",
+           "check_res_id_continuity", "check_backbone_continuity",
+           "check_duplicate_atoms", "check_bond_continuity",
+           "check_linear_continuity"]
+
+import numpy as np
+import warnings
+from .atoms import AtomArray, AtomArrayStack
+from .filter import (
+    filter_peptide_backbone, filter_phosphate_backbone, filter_linear_bond_continuity)
+from .box import coord_to_fraction
+
+
+def _check_continuity(array):
+    diff = np.diff(array)
+    discontinuity = np.where( ((diff != 0) & (diff != 1)) )
+    return discontinuity[0] + 1
+
+
+def check_id_continuity(array):
+    """
+    Check if the residue IDs are incremented by more than 1 or
+    decremented, from one atom to the next one.
+
+    An increment by more than 1 is as strong clue for missing residues,
+    a decrement means probably a start of a new chain.
+
+    DEPRECATED: Use :func:`check_res_id_continuity()` instead.
+
+    Parameters
+    ----------
+    array : AtomArray or AtomArrayStack
+        The array to be checked.
+
+    Returns
+    -------
+    discontinuity : ndarray, dtype=int
+        Contains the indices of atoms after a discontinuity
+    """
+    warnings.warn(
+        "'check_id_continuity()' is deprecated, "
+        "use 'check_res_id_continuity()' instead",
+        DeprecationWarning
+    )
+    return check_res_id_continuity(array)
+
+
+def check_atom_id_continuity(array):
+    """
+    Check if the atom IDs are incremented by more than 1 or
+    decremented, from one atom to the next one.
+
+    An increment by more than 1 is as strong clue for missing atoms.
+
+    Parameters
+    ----------
+    array : AtomArray or AtomArrayStack
+        The array to be checked.
+
+    Returns
+    -------
+    discontinuity : ndarray, dtype=int
+        Contains the indices of atoms after a discontinuity
+    """
+    ids = array.atom_id
+    return _check_continuity(ids)
+
+
+def check_res_id_continuity(array):
+    """
+    Check if the residue IDs are incremented by more than 1 or
+    decremented, from one atom to the next one.
+
+    An increment by more than 1 is as strong clue for missing residues,
+    a decrement means probably a start of a new chain.
+
+    Parameters
+    ----------
+    array : AtomArray or AtomArrayStack
+        The array to be checked.
+
+    Returns
+    -------
+    discontinuity : ndarray, dtype=int
+        Contains the indices of atoms after a discontinuity
+    """
+    ids = array.res_id
+    return _check_continuity(ids)
+
+
+def check_bond_continuity(array, min_len=1.2, max_len=1.8):
+    """
+    Check if the peptide or phosphate backbone atoms have a
+    non-reasonable distance to the next residue.
+
+    A large or very small distance is a very strong clue, that there is
+    no bond between those atoms, therefore the chain is discontinued.
+
+    DEPRECATED: Please use :func:`check_backbone_continuity` for the same functionality.
+
+    Parameters
+    ----------
+    array : AtomArray
+        The array to be checked.
+    min_len, max_len : float, optional
+        The interval in which the atom-atom distance is evaluated as
+        bond.
+
+    Returns
+    -------
+    discontinuity : ndarray, dtype=int
+         Contains the indices of atoms after a discontinuity.
+    """
+    warnings.warn(
+        "Reimplemented into `check_backbone_continuity()`",
+        DeprecationWarning
+    )
+    return check_backbone_continuity(array, min_len, max_len)
+
+
+def check_linear_continuity(array, min_len=1.2, max_len=1.8):
+    """
+    Check linear (consecutive) bond continuity of atoms in atom array.
+
+    Parameters
+    ----------
+    array : AtomArray
+        Arbitrary structure.
+    min_len : float, optional
+        Minimum bond length.
+    max_len : float, optional
+        Maximum bond length.
+
+    Returns
+    -------
+    discontinuity : ndarray, dtype=int
+        Indices of `array` corresponding to atoms where the bond
+        with the preceding atom is beyond the provided bounds.
+
+    See Also
+    --------
+    biotite.structure.filter.filter_linear_bond_continuity :
+        A function to filter for atoms preserving the continuity (used here).
+    biotite.structure.bonds.BondList :
+        A class that doesn't depend on the atoms' order to identify bonds.
+    """
+    con_mask = filter_linear_bond_continuity(array, min_len, max_len)
+    # The continuity mask `con_mask` points to atoms for which the next atom is continuous.
+    # We invert this mask and shift-extend by one from the left.
+    # The resulting discontinuity mask points to atoms having the preceding atom exceeding
+    # the bond length requirements.
+    discon_mask = np.insert(~con_mask[:-1], 0, False)
+    return np.where(discon_mask)[0]
+
+
+def check_backbone_continuity(array, min_len=1.2, max_len=1.8):
+    """
+    Check if the (peptide or phosphate) backbone atoms have
+    non-reasonable distance to the next atom.
+
+    A large or very small distance is a very strong clue, that there is
+    no bond between those atoms, therefore the chain is discontinued.
+
+    Parameters
+    ----------
+    array : AtomArray
+        The array to be checked.
+    min_len, max_len : float, optional
+        The interval in which the atom-atom distance is evaluated as
+        bond.
+
+    Returns
+    -------
+    discontinuity : ndarray, dtype=int
+         Contains the indices of atoms after a discontinuity.
+
+    See Also
+    --------
+    filter_linear_bond_continuity : A function to filter for atoms preserving the continuity.
+    filter_peptide_backbone : A function to filter for peptide backbone atoms.
+    filter_phosphate_backbone : A function to filter for phosphate backbone atoms.
+    """
+    backbone_mask = filter_peptide_backbone(array) | filter_phosphate_backbone(array)
+    con_mask = filter_linear_bond_continuity(array[backbone_mask], min_len, max_len)
+
+    # See the comments for `check_linear_continuity()`
+    discon_mask = np.insert(~con_mask[:-1], 0, False)
+    discon_mask_full = np.full_like(backbone_mask, False)
+    discon_mask_full[backbone_mask] = discon_mask
+
+    return np.where(discon_mask_full)[0]
+
+
+def check_duplicate_atoms(array):
+    """
+    Check if a structure contains duplicate atoms, i.e. two atoms in a
+    structure have the same annotations (coordinates may be different).
+
+    Duplicate atoms may appear, when a structure has occupancy for an
+    atom at two or more positions or when the *altloc* positions are
+    improperly read.
+
+    Parameters
+    ----------
+    array : AtomArray or AtomArrayStack
+        The array to be checked.
+
+    Returns
+    -------
+    duplicate : ndarray, dtype=int
+        Contains the indices of duplicate atoms.
+        The first occurence of an atom is not counted as duplicate.
+    """
+    duplicates = []
+    annots = [array.get_annotation(category) for category
+              in array.get_annotation_categories()]
+    for i in range(1, array.array_length()):
+        # Start with assumption that all atoms in the array
+        # until index i are duplicates of the atom at index i
+        is_duplicate = np.full(i, True, dtype=bool)
+        for annot in annots:
+            # For each annotation array filter out the atoms until
+            # index i that have an unequal annotation
+            # to the atom at index i
+            is_duplicate &= (annot[:i] == annot[i])
+        # After checking all annotation arrays,
+        # if there still is any duplicate to the atom at index i,
+        # add i the the list of duplicate atom indices
+        if is_duplicate.any():
+            duplicates.append(i)
+    return np.array(duplicates)
+
+
+def check_in_box(array):
+    r"""
+    Check if a structure contains atoms whose position is outside the
+    box.
+
+    Coordinates are outside the box, when they cannot be represented by
+    a linear combination of the box vectors with scalar factors
+    :math:`0 \le a_i \le 1`.
+
+    Parameters
+    ----------
+    array : AtomArray or AtomArrayStack
+        The array to be checked.
+
+    Returns
+    -------
+    outside : ndarray, dtype=int
+        Contains the indices of atoms outside the atom array's box.
+    """
+    if array.box is None:
+        raise TypeError("Structure has no box")
+    box = array.box
+    fractions = coord_to_fraction(array, box)
+    return np.where(((fractions >= 0) & (fractions < 1)).all(axis=-1))[0]

biotite/structure/io/__init__.py

@@ -0,0 +1,30 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+A subpackage for reading and writing structure related data.
+
+Macromolecular structure files (PDB, PDBx/mmCIF, BinaryCIF, etc.) and
+small molecule files (MOL, SDF, etc.) can be used
+to load an :class:`AtomArray` or :class:`AtomArrayStack`.
+
+Since the data model for the :class:`AtomArray` and
+:class:`AtomArrayStack` class does not support duplicate atoms,
+only one *altloc* can be chosen for each atom. Hence, the amount of
+atoms may be lower in the atom array (stack) than in respective
+structure file.
+
+The recommended format for reading structure files is *BinaryCIF*.
+It has by far the shortest parsing time and file size.
+
+Besides the mentioned structure formats, Gromacs trajectory files can be
+loaded, if `mdtraj` is installed.
+"""
+
+__name__ = "biotite.structure.io"
+__author__ = "Patrick Kunzmann"
+
+from .ctab import *
+from .general import *
+from .trajfile import *

biotite/structure/io/ctab.py

@@ -0,0 +1,72 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.structure.io"
+__author__ = "Patrick Kunzmann"
+__all__ = ["read_structure_from_ctab", "write_structure_to_ctab"]
+
+import warnings
+from ..bonds import BondType
+
+
+def read_structure_from_ctab(ctab_lines):
+    """
+    Parse a *MDL* connection table (Ctab) to obtain an
+    :class:`AtomArray`. :footcite:`Dalby1992`.
+
+    DEPRECATED: Moved to :mod:`biotite.structure.io.mol.ctab`.
+
+    Parameters
+    ----------
+    ctab_lines : lines of str
+        The lines containing the *ctab*.
+        Must begin with the *counts* line and end with the `M END` line
+
+    Returns
+    -------
+    atoms : AtomArray
+        This :class:`AtomArray` contains the optional ``charge``
+        annotation and has an associated :class:`BondList`.
+
+    References
+    ----------
+
+    .. footbibliography::
+    """
+    warnings.warn("Moved to biotite.structure.io.mol.ctab", DeprecationWarning)
+    from biotite.structure.io.mol.ctab import read_structure_from_ctab
+    return read_structure_from_ctab(ctab_lines)
+
+
+def write_structure_to_ctab(atoms, default_bond_type=BondType.ANY):
+    """
+    Convert an :class:`AtomArray` into a
+    *MDL* connection table (Ctab). :footcite:`Dalby1992`
+
+    DEPRECATED: Moved to :mod:`biotite.structure.io.mol.ctab`.
+
+    Parameters
+    ----------
+    atoms : AtomArray
+        The array must have an associated :class:`BondList`.
+
+    Returns
+    -------
+    ctab_lines : lines of str
+        The lines containing the *ctab*.
+        The lines begin with the *counts* line and end with the `M END`
+        .line
+    default_bond_type : BondType
+        Bond type fallback in the *Bond block* if a bond has no bond_type
+        defined in *atoms* array. By default, each bond is treated as
+        :attr:`BondType.ANY`.
+
+    References
+    ----------
+
+    .. footbibliography::
+    """
+    warnings.warn("Moved to biotite.structure.io.mol.ctab", DeprecationWarning)
+    from biotite.structure.io.mol.ctab import write_structure_to_ctab
+    return write_structure_to_ctab(atoms, default_bond_type)

biotite/structure/io/dcd/__init__.py

@@ -0,0 +1,13 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+"""
+This subpackage is used for reading and writing trajectories in the
+CDC format used by software like *CHARMM*, *OpenMM* and *NAMD*.
+"""
+
+__name__ = "biotite.structure.io.dcd"
+__author__ = "Patrick Kunzmann"
+
+from .file import *

biotite/structure/io/dcd/file.py

@@ -0,0 +1,65 @@
+# This source code is part of the Biotite package and is distributed
+# under the 3-Clause BSD License. Please see 'LICENSE.rst' for further
+# information.
+
+__name__ = "biotite.structure.io.dcd"
+__author__ = "Patrick Kunzmann"
+__all__ = ["DCDFile"]
+
+import numpy as np
+from ..trajfile import TrajectoryFile
+from ...box import vectors_from_unitcell, unitcell_from_vectors
+
+
+class DCDFile(TrajectoryFile):
+    """
+    This file class represents a DCD trajectory file.
+    """
+    
+    @classmethod
+    def traj_type(cls):
+        import mdtraj.formats as traj
+        return traj.DCDTrajectoryFile
+    
+    @classmethod
+    def process_read_values(cls, read_values):
+        # .netcdf files use Angstrom
+        coord = read_values[0]
+        cell_lengths = read_values[1]
+        cell_angles = read_values[2]
+        if cell_lengths is None or cell_angles is None:
+             box = None
+        else:
+            box = np.stack(
+                [vectors_from_unitcell(a, b, c, alpha, beta, gamma)
+                for (a, b, c), (alpha, beta, gamma)
+                in zip(cell_lengths, np.deg2rad(cell_angles))],
+                axis=0
+            )
+        return coord, box, None
+    
+    @classmethod
+    def prepare_write_values(cls, coord, box, time):
+        xyz = coord.astype(np.float32, copy=False) \
+              if coord is not None else None
+        if box is None:
+            cell_lengths = None
+            cell_angles  = None
+        else:
+            cell_lengths = np.zeros((len(box), 3), dtype=np.float32)
+            cell_angles  = np.zeros((len(box), 3), dtype=np.float32)
+            for i, model_box in enumerate(box):
+                a, b, c, alpha, beta, gamma = unitcell_from_vectors(model_box)
+                cell_lengths[i] = np.array((a, b, c))
+                cell_angles[i] = np.rad2deg((alpha, beta, gamma))
+        return {
+            "xyz" : xyz,
+            "cell_lengths" : cell_lengths,
+            "cell_angles" : cell_angles,
+        }
+
+    def set_time(self, time):
+        if time is not None:
+            raise NotImplementedError(
+                "This trajectory file does not support writing simulation time"
+            )