biotite 1.5.0__cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/structure/integrity.py

@@ -0,0 +1,213 @@
+# 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_atom_id_continuity",
+    "check_res_id_continuity",
+    "check_backbone_continuity",
+    "check_duplicate_atoms",
+    "check_linear_continuity",
+]
+
+import numpy as np
+from biotite.structure.box import coord_to_fraction
+from biotite.structure.filter import (
+    filter_linear_bond_continuity,
+    filter_peptide_backbone,
+    filter_phosphate_backbone,
+)
+
+
+def _check_continuity(array):
+    diff = np.diff(array)
+    discontinuity = np.where(((diff != 0) & (diff != 1)))
+    return discontinuity[0] + 1
+
+
+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_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
+    --------
+    filter_linear_bond_continuity : A function to filter for atoms preserving the continuity (used here).
+    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,29 @@
+# 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, common trajectory formats can be
+loaded as well.
+"""
+
+__name__ = "biotite.structure.io"
+__author__ = "Patrick Kunzmann"
+
+from .general import *
+from .trajfile import *

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,67 @@
+# 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 biotraj
+import numpy as np
+from biotite.structure.box import unitcell_from_vectors, vectors_from_unitcell
+from biotite.structure.io.trajfile import TrajectoryFile
+
+
+class DCDFile(TrajectoryFile):
+    """
+    This file class represents a DCD trajectory file.
+    """
+
+    @classmethod
+    def traj_type(cls):
+        return biotraj.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"
+            )

biotite/structure/io/general.py

@@ -0,0 +1,243 @@
+# 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 contains a convenience function for loading structures from
+general structure files.
+"""
+
+__name__ = "biotite.structure.io"
+__author__ = "Patrick Kunzmann"
+__all__ = ["load_structure", "save_structure"]
+
+import datetime
+import io
+import os.path
+from biotite.structure.atoms import AtomArrayStack
+
+
+def load_structure(file_path, template=None, **kwargs):
+    """
+    Load an :class:`AtomArray` or class`AtomArrayStack` from a structure
+    file without the need to manually instantiate a :class:`File`
+    object.
+
+    Internally this function uses a :class:`File` object, based on the
+    file extension.
+    Trajectory files furthermore require specification of the `template`
+    parameter.
+
+    Parameters
+    ----------
+    file_path : str
+        The path to structure file.
+    template : AtomArray or AtomArrayStack or file-like object or str, optional
+        Only required when reading a trajectory file.
+    **kwargs
+        Additional parameters will be passed to either the
+        :func:`get_structure()` or :func:`read()` method of the file
+        object.
+        This does not affect files given via the `template` parameter.
+        The only exception is the `atom_i`, which is applied to the template
+        as well if number of atoms do not match.
+
+    Returns
+    -------
+    array : AtomArray or AtomArrayStack
+        If the file contains multiple models, an AtomArrayStack is
+        returned, otherwise an AtomArray is returned.
+
+    Raises
+    ------
+    ValueError
+        If the file format (i.e. the file extension) is unknown.
+    TypeError
+        If a trajectory file is loaded without specifying the
+        `template` parameter.
+    """
+    # Optionally load template from file
+    if isinstance(template, (io.IOBase, str)):
+        template = load_structure(template)
+
+    # We only need the suffix here
+    _, suffix = os.path.splitext(file_path)
+    match suffix:
+        case ".pdb":
+            from biotite.structure.io.pdb import PDBFile
+
+            file = PDBFile.read(file_path)
+            array = file.get_structure(**kwargs)
+            return _as_single_model_if_possible(array)
+        case ".pdbqt":
+            from biotite.structure.io.pdbqt import PDBQTFile
+
+            file = PDBQTFile.read(file_path)
+            array = file.get_structure(**kwargs)
+            return _as_single_model_if_possible(array)
+        case ".cif" | ".pdbx":
+            from biotite.structure.io.pdbx import CIFFile, get_structure
+
+            file = CIFFile.read(file_path)
+            array = get_structure(file, **kwargs)
+            return _as_single_model_if_possible(array)
+        case ".bcif":
+            from biotite.structure.io.pdbx import BinaryCIFFile, get_structure
+
+            file = BinaryCIFFile.read(file_path)
+            array = get_structure(file, **kwargs)
+            return _as_single_model_if_possible(array)
+        case ".gro":
+            from biotite.structure.io.gro import GROFile
+
+            file = GROFile.read(file_path)
+            array = file.get_structure(**kwargs)
+            return _as_single_model_if_possible(array)
+        case ".mol":
+            from biotite.structure.io.mol import MOLFile
+
+            file = MOLFile.read(file_path)
+            array = file.get_structure(**kwargs)
+            # MOL and SDF files only contain a single model
+            return array
+        case ".sdf" | ".sd":
+            from biotite.structure.io.mol import SDFile, get_structure
+
+            file = SDFile.read(file_path)
+            array = get_structure(file, **kwargs)
+            return array
+        case ".trr" | ".xtc" | ".dcd" | ".netcdf":
+            if template is None:
+                raise TypeError("Template must be specified for trajectory files")
+            # Filter template for atom ids, if an unfiltered template
+            if "atom_i" in kwargs and template.shape[-1] != len(kwargs["atom_i"]):
+                template = template[..., kwargs["atom_i"]]
+            from biotite.structure.io.dcd import DCDFile
+            from biotite.structure.io.netcdf import NetCDFFile
+            from biotite.structure.io.trr import TRRFile
+            from biotite.structure.io.xtc import XTCFile
+
+            if suffix == ".trr":
+                traj_file_cls = TRRFile
+            if suffix == ".xtc":
+                traj_file_cls = XTCFile
+            if suffix == ".dcd":
+                traj_file_cls = DCDFile
+            if suffix == ".netcdf":
+                traj_file_cls = NetCDFFile
+            file = traj_file_cls.read(file_path, **kwargs)
+            return file.get_structure(template)
+        case unknown_suffix:
+            raise ValueError(f"Unknown file format '{unknown_suffix}'")
+
+
+def save_structure(file_path, array, **kwargs):
+    """
+    Save an :class:`AtomArray` or class`AtomArrayStack` to a structure
+    file without the need to manually instantiate a :class:`File`
+    object.
+
+    Internally this function uses a :class:`File` object, based on the
+    file extension.
+
+    Parameters
+    ----------
+    file_path : str
+        The path to structure file.
+    array : AtomArray or AtomArrayStack
+        The structure to be saved.
+    **kwargs
+        Additional parameters will be passed to the respective `set_structure`
+        method.
+
+    Raises
+    ------
+    ValueError
+        If the file format (i.e. the file extension) is unknown.
+    """
+    # We only need the suffix here
+    _, suffix = os.path.splitext(file_path)
+    match suffix:
+        case ".pdb":
+            from biotite.structure.io.pdb import PDBFile
+
+            file = PDBFile()
+            file.set_structure(array, **kwargs)
+            file.write(file_path)
+        case ".pdbqt":
+            from biotite.structure.io.pdbqt import PDBQTFile
+
+            file = PDBQTFile()
+            file.set_structure(array, **kwargs)
+            file.write(file_path)
+        case ".cif" | ".pdbx":
+            from biotite.structure.io.pdbx import CIFFile, set_structure
+
+            file = CIFFile()
+            set_structure(file, array, **kwargs)
+            file.write(file_path)
+        case ".bcif":
+            from biotite.structure.io.pdbx import BinaryCIFFile, set_structure
+
+            file = BinaryCIFFile()
+            set_structure(file, array, **kwargs)
+            file.write(file_path)
+        case ".gro":
+            from biotite.structure.io.gro import GROFile
+
+            file = GROFile()
+            file.set_structure(array, **kwargs)
+            file.write(file_path)
+        case ".mol":
+            from biotite.structure.io.mol import MOLFile
+
+            file = MOLFile()
+            file.set_structure(array, **kwargs)
+            file.header = _mol_header()
+            file.write(file_path)
+        case ".sdf" | ".sd":
+            from biotite.structure.io.mol import SDFile, SDRecord, set_structure
+
+            record = SDRecord()
+            record.set_structure(array, **kwargs)
+            record.header = _mol_header()
+            file = SDFile({"Molecule": record})
+            file.write(file_path)
+        case ".trr" | ".xtc" | ".dcd" | ".netcdf":
+            from biotite.structure.io.dcd import DCDFile
+            from biotite.structure.io.netcdf import NetCDFFile
+            from biotite.structure.io.trr import TRRFile
+            from biotite.structure.io.xtc import XTCFile
+
+            if suffix == ".trr":
+                traj_file_cls = TRRFile
+            if suffix == ".xtc":
+                traj_file_cls = XTCFile
+            if suffix == ".dcd":
+                traj_file_cls = DCDFile
+            if suffix == ".netcdf":
+                traj_file_cls = NetCDFFile
+            file = traj_file_cls()
+            file.set_structure(array, **kwargs)
+            file.write(file_path)
+        case unknown_suffix:
+            raise ValueError(f"Unknown file format '{unknown_suffix}'")
+
+
+def _as_single_model_if_possible(atoms):
+    if isinstance(atoms, AtomArrayStack) and atoms.stack_depth() == 1:
+        # Stack containing only one model -> return as atom array
+        return atoms[0]
+    else:
+        return atoms
+
+
+def _mol_header():
+    from biotite.structure.io.mol import Header
+
+    return Header(
+        mol_name="Molecule",
+        program="Biotite",
+        time=datetime.datetime.now(),
+        dimensions="3D",
+    )

biotite/structure/io/gro/__init__.py

@@ -0,0 +1,14 @@
+# 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 an :class:`AtomArray` or
+:class:`AtomArrayStack` using the Gro format used by the gromacs
+software package.
+"""
+
+__name__ = "biotite.structure.io.gro"
+__author__ = "Daniel Bauer"
+
+from .file import *