biotite 1.5.0__cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

biotite/file.py

@@ -0,0 +1,244 @@
+# 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"
+__author__ = "Patrick Kunzmann"
+__all__ = [
+    "File",
+    "TextFile",
+    "InvalidFileError",
+    "SerializationError",
+    "DeserializationError",
+]
+
+import abc
+import copy
+import io
+from os import PathLike
+from biotite.copyable import Copyable
+
+
+class File(Copyable, metaclass=abc.ABCMeta):
+    """
+    Base class for all file classes.
+    The constructor creates an empty file, that can be filled with data
+    using the class specific setter methods.
+    Conversely, the class method :func:`read()` reads a file from disk
+    (or a file-like object from other sources).
+    In order to write the instance content into a file the
+    :func:`write()` method is used.
+    """
+
+    @classmethod
+    @abc.abstractmethod
+    def read(cls, file):
+        """
+        Parse a file (or file-like object).
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+
+        Returns
+        -------
+        file : File
+            An instance from the respective :class:`File` subclass
+            representing the parsed file.
+        """
+        pass
+
+    @abc.abstractmethod
+    def write(self, file):
+        """
+        Write the contents of this :class:`File` object into a file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be written to.
+            Alternatively a file path can be supplied.
+        """
+        pass
+
+
+class TextFile(File, metaclass=abc.ABCMeta):
+    """
+    Base class for all line based text files.
+    When reading a file, the text content is saved as list of strings,
+    one for each line.
+    When writing a file, this list is written into the file.
+
+    Attributes
+    ----------
+    lines : list
+        List of string representing the lines in the text file.
+        PROTECTED: Do not modify from outside.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.lines = []
+
+    @classmethod
+    def read(cls, file, *args, **kwargs):
+        # File name
+        if is_open_compatible(file):
+            with open(file, "r") as f:
+                lines = f.read().splitlines()
+        # File object
+        else:
+            if not is_text(file):
+                raise TypeError("A file opened in 'text' mode is required")
+            lines = file.read().splitlines()
+        file_object = cls(*args, **kwargs)
+        file_object.lines = lines
+        return file_object
+
+    @staticmethod
+    def read_iter(file):
+        """
+        Create an iterator over each line of the given text file.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be read.
+            Alternatively a file path can be supplied.
+
+        Yields
+        ------
+        line : str
+            The current line in the file.
+        """
+        # File name
+        if is_open_compatible(file):
+            with open(file, "r") as f:
+                yield from f
+        # File object
+        else:
+            if not is_text(file):
+                raise TypeError("A file opened in 'text' mode is required")
+            yield from file
+
+    def write(self, file):
+        """
+        Write the contents of this object into a file
+        (or file-like object).
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be written to.
+            Alternatively a file path can be supplied.
+        """
+        if is_open_compatible(file):
+            with open(file, "w") as f:
+                f.write("\n".join(self.lines) + "\n")
+        else:
+            if not is_text(file):
+                raise TypeError("A file opened in 'text' mode is required")
+            file.write("\n".join(self.lines) + "\n")
+
+    @staticmethod
+    def write_iter(file, lines):
+        """
+        Iterate over the given `lines` of text and write each line into
+        the specified `file`.
+
+        In contrast to :meth:`write()`, each line of text is not stored
+        in an intermediate :class:`TextFile`, but is directly written
+        to the file.
+        Hence, this static method may save a large amount of memory if
+        a large file should be written, especially if the `lines`
+        are provided as generator.
+
+        Parameters
+        ----------
+        file : file-like object or str
+            The file to be written to.
+            Alternatively a file path can be supplied.
+        lines : generator or array-like of str
+            The lines of text to be written.
+            Must not include line break characters.
+        """
+        if is_open_compatible(file):
+            with open(file, "w") as f:
+                for line in lines:
+                    f.write(line + "\n")
+        else:
+            if not is_text(file):
+                raise TypeError("A file opened in 'text' mode is required")
+            for line in lines:
+                file.write(line + "\n")
+
+    def __copy_fill__(self, clone):
+        super().__copy_fill__(clone)
+        clone.lines = copy.copy(self.lines)
+
+    def __str__(self):
+        return "\n".join(self.lines)
+
+
+class InvalidFileError(Exception):
+    """
+    Indicates that the file is not suitable for the requested action,
+    either because the file does not contain the required data or
+    because the file is malformed.
+    """
+
+    pass
+
+
+class SerializationError(Exception):
+    pass
+
+
+class DeserializationError(Exception):
+    pass
+
+
+def wrap_string(text, width):
+    """
+    A much simpler and hence much more efficient version of
+    `textwrap.wrap()`.
+
+    This function simply wraps the given `text` after `width`
+    characters, ignoring sentences, whitespaces, etc.
+
+    Parameters
+    ----------
+    text : str
+        The text to be wrapped.
+    width : int
+        The maximum number of characters per line.
+
+    Returns
+    -------
+    lines : list of str
+        The wrapped lines.
+    """
+    lines = []
+    for i in range(0, len(text), width):
+        lines.append(text[i : i + width])
+    return lines
+
+
+def is_binary(file):
+    if isinstance(file, io.BufferedIOBase):
+        return True
+    # for file wrappers, e.g. 'TemporaryFile'
+    return hasattr(file, "file") and isinstance(file.file, io.BufferedIOBase)
+
+
+def is_text(file):
+    if isinstance(file, io.TextIOBase):
+        return True
+    # for file wrappers, e.g. 'TemporaryFile'
+    return hasattr(file, "file") and isinstance(file.file, io.TextIOBase)
+
+
+def is_open_compatible(file):
+    return isinstance(file, (str, bytes, PathLike))

biotite/interface/__init__.py

@@ -0,0 +1,19 @@
+# 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 provides interfaces to other Python packages in the bioinformatics
+ecosystem.
+Its purpose is to convert between native Biotite objects, such as :class:`.AtomArray`
+and :class:`.Sequence`, and the corresponding objects in the respective interfaced
+package.
+In contrast to :mod:`biotite.application`, where an entire application run is handled
+under the hood, :mod:`biotite.interface` only covers the object conversion, allowing
+for more flexibility.
+"""
+
+__name__ = "biotite.interface"
+__author__ = "Patrick Kunzmann"
+
+from .warning import *

biotite/interface/openmm/__init__.py

@@ -0,0 +1,20 @@
+# 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 provides an interface to the `OpenMM <https://openmm.org/>`_
+molecular simulation toolkit.
+It allows conversion between :class:`.AtomArray`/:class:`.AtomArrayStack` and
+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/openmm/state.py

@@ -0,0 +1,93 @@
+__name__ = "biotite.interface.openmm"
+__author__ = "Patrick Kunzmann"
+__all__ = ["from_context", "from_state", "from_states"]
+
+import numpy as np
+import openmm
+import biotite.structure as struc
+
+
+def from_context(template, context):
+    """
+    Parse the coordinates and box of the current state of an
+    :class:`openmm.openmm.Context` into an :class:`AtomArray`.
+
+    Parameters
+    ----------
+    template : AtomArray
+        This structure is used as template.
+        The output :class:`AtomArray` is equal to this template with the
+        exception of the coordinates and the box vectors.
+    context : Context
+        The coordinates are parsed from the current state of this
+        :class:`openmm.openmm.Context`.
+
+    Returns
+    -------
+    atoms : AtomArray
+        The created :class:`AtomArray`.
+    """
+    state = context.getState(getPositions=True)
+    return from_state(template, state)
+
+
+def from_state(template, state):
+    """
+    Parse the coordinates and box of the given :class:`openmm.openmm.State`
+    into an :class:`AtomArray`.
+
+    Parameters
+    ----------
+    template : AtomArray
+        This structure is used as template.
+        The output :class:`AtomArray` is equal to this template with the
+        exception of the coordinates and the box vectors.
+    state : State
+        The coordinates are parsed from this state.
+        Must be created with ``getPositions=True``.
+
+    Returns
+    -------
+    atoms : AtomArray
+        The created :class:`AtomArray`.
+    """
+    coord, box = _parse_state(state)
+    atoms = template.copy()
+    atoms.coord = coord
+    atoms.box = box
+    return atoms
+
+
+def from_states(template, states):
+    """
+    Parse the coordinates and box vectors of multiple :class:`openmm.openmm.State`
+    objects into an :class:`AtomArrayStack`.
+
+    Parameters
+    ----------
+    template : AtomArray
+        This structure is used as template.
+        The output :class:`AtomArray` is equal to this template with the
+        exception of the coordinates and the box vectors.
+    states : iterable of State
+        The coordinates are parsed from these states.
+        Must be created with ``getPositions=True``.
+
+    Returns
+    -------
+    atoms : AtomArrayStack
+        The created :class:`AtomArrayStack`.
+    """
+    coords = []
+    boxes = []
+    for state in states:
+        coord, box = _parse_state(state)
+        coords.append(coord)
+        boxes.append(box)
+    return struc.from_template(template, np.stack(coords), np.stack(boxes))
+
+
+def _parse_state(state):
+    coord = state.getPositions(asNumpy=True).value_in_unit(openmm.unit.angstrom)
+    box = state.getPeriodicBoxVectors(asNumpy=True).value_in_unit(openmm.unit.angstrom)
+    return coord, box

biotite/interface/openmm/system.py

@@ -0,0 +1,227 @@
+__name__ = "biotite.interface.openmm"
+__author__ = "Patrick Kunzmann"
+__all__ = ["to_system", "to_topology", "from_topology"]
+
+import numpy as np
+import openmm
+import openmm.app as app
+import openmm.unit as unit
+import biotite.structure as struc
+import biotite.structure.info as info
+
+_BOND_TYPE_TO_ORDER = {
+    struc.BondType.SINGLE: 1,
+    struc.BondType.DOUBLE: 2,
+    struc.BondType.TRIPLE: 3,
+    struc.BondType.QUADRUPLE: 4,
+    struc.BondType.AROMATIC_SINGLE: 1,
+    struc.BondType.AROMATIC_DOUBLE: 2,
+    struc.BondType.AROMATIC_TRIPLE: 3,
+}
+
+
+def to_system(atoms):
+    """
+    Create a :class:`openmm.openmm.System` from an :class:`AtomArray` or
+    :class:`AtomArrayStack`.
+
+    Parameters
+    ----------
+    atoms : AtomArray or AtomArrayStack
+        The structure to be converted.
+        The box vectors are set from the ``box`` attribute.
+        If multiple models are given the box of the first model is selected.
+
+    Returns
+    -------
+    system : System
+        The created :class:`openmm.openmm.System`.
+    """
+    system = openmm.System()
+
+    for element in atoms.element:
+        system.addParticle(info.mass(element))
+
+    if atoms.box is not None:
+        if atoms.box.ndim == 3:
+            # If an `AtomArrayStack`, the first box is chosen
+            box = atoms.box[0]
+        else:
+            box = atoms.box
+        if not _check_box_requirements(box):
+            raise struc.BadStructureError(
+                "Box does not fulfill OpenMM's requirements for periodic boxes"
+            )
+        system.setDefaultPeriodicBoxVectors(*(box * unit.angstrom))
+
+    return system
+
+
+def to_topology(atoms):
+    """
+    Create a :class:`openmm.app.topology.Topology` from an :class:`AtomArray` or
+    :class:`AtomArrayStack`.
+
+    Parameters
+    ----------
+    atoms : AtomArray or AtomArrayStack
+        The structure to be converted.
+        An associated :class:`BondList` is required.
+
+    Returns
+    -------
+    topology : Topology
+        The created :class:`openmm.app.topology.Topology`.
+    """
+    if "atom_id" in atoms.get_annotation_categories():
+        atom_id = atoms.atom_id
+    else:
+        atom_id = np.arange(atoms.array_length()) + 1
+
+    chain_starts = struc.get_chain_starts(atoms)
+    res_starts = struc.get_residue_starts(atoms)
+
+    # Lists of chain, residue and atom objects that will be filled later
+    chain_list = []
+    residue_list = []
+    atom_list = []
+    # Each atom's index in the chain and residue list
+    chain_idx = _generate_idx(chain_starts, atoms.array_length())
+    res_idx = _generate_idx(res_starts, atoms.array_length())
+
+    topology = app.Topology()
+
+    ## Add atoms
+    for start_i in chain_starts:
+        chain_list.append(topology.addChain(id=atoms.chain_id[start_i]))
+    for start_i in res_starts:
+        residue_list.append(
+            topology.addResidue(
+                name=atoms.res_name[start_i],
+                chain=chain_list[chain_idx[start_i]],
+                insertionCode=atoms.ins_code[start_i],
+                id=str(atoms.res_id[start_i]),
+            )
+        )
+    for i in np.arange(atoms.array_length()):
+        atom_list.append(
+            topology.addAtom(
+                name=atoms.atom_name[i],
+                element=app.Element.getBySymbol(atoms.element[i]),
+                residue=residue_list[res_idx[i]],
+                id=str(atom_id[start_i]),
+            )
+        )
+
+    ## Add bonds
+    if atoms.bonds is None:
+        raise struc.BadStructureError("Input structure misses an associated BondList")
+    for atom_i, atom_j, bond_type in atoms.bonds.as_array():
+        topology.addBond(
+            atom_list[atom_i],
+            atom_list[atom_j],
+            order=_BOND_TYPE_TO_ORDER.get(bond_type),
+        )
+
+    ## Add box
+    if atoms.box is not None:
+        if atoms.box.ndim == 3:
+            # If an `AtomArrayStack`, the first box is chosen
+            box = atoms.box[0]
+        else:
+            box = atoms.box
+        if not _check_box_requirements(box):
+            raise struc.BadStructureError(
+                "Box does not fulfill OpenMM's requirements for periodic boxes"
+            )
+        topology.setPeriodicBoxVectors(box * unit.angstrom)
+
+    return topology
+
+
+def from_topology(topology):
+    """
+    Create a :class:`AtomArray` from a :class:`openmm.app.topology.Topology`.
+
+    Parameters
+    ----------
+    topology : Topology
+        The topology to be converted.
+
+    Returns
+    -------
+    atoms : AtomArray
+        The created :class:`AtomArray`.
+        As the :class:`openmm.app.topology.Topology` does not contain atom
+        coordinates, the values of the :class:`AtomArray` ``coord``
+        are set to *NaN*.
+
+    Notes
+    -----
+    This function is especially useful for obtaining an updated
+    template, if the original topology was modified
+    (e.g. via :class:`openmm.app.modeller.Modeller`).
+    """
+    atoms = struc.AtomArray(topology.getNumAtoms())
+
+    chain_ids = []
+    res_ids = []
+    ins_codes = []
+    res_names = []
+    atom_names = []
+    elements = []
+    for chain in topology.chains():
+        chain_id = chain.id
+        for residue in chain.residues():
+            res_name = residue.name
+            res_id = int(residue.id)
+            ins_code = residue.insertionCode
+            for atom in residue.atoms():
+                chain_ids.append(chain_id)
+                res_ids.append(res_id)
+                ins_codes.append(ins_code)
+                res_names.append(res_name)
+                atom_names.append(atom.name.upper())
+                elements.append(atom.element.symbol.upper())
+    atoms.chain_id = chain_ids
+    atoms.res_id = res_ids
+    atoms.ins_code = ins_codes
+    atoms.res_name = res_names
+    atoms.atom_name = atom_names
+    atoms.element = elements
+    atoms.hetero = ~(struc.filter_amino_acids(atoms) | struc.filter_nucleotides(atoms))
+
+    bonds = []
+    atom_to_index = {atom: i for i, atom in enumerate(topology.atoms())}
+    for bond in topology.bonds():
+        order = bond.order if bond.order is not None else struc.BondType.ANY
+        bonds.append([atom_to_index[bond.atom1], atom_to_index[bond.atom2], order])
+    atoms.bonds = struc.BondList(atoms.array_length(), np.array(bonds))
+
+    box = topology.getPeriodicBoxVectors()
+    if box is None:
+        atoms.box = None
+    else:
+        atoms.box = np.asarray(box.value_in_unit(openmm.unit.angstrom))
+
+    return atoms
+
+
+def _generate_idx(starts, length):
+    # An array that is 1, at start positions and 0 everywhere else
+    start_counter = np.zeros(length, dtype=int)
+    start_counter[starts] = 1
+    # The first index should be zero -> the first start is not counted
+    start_counter[0] = 0
+    return np.cumsum(start_counter)
+
+
+def _check_box_requirements(box):
+    """
+    Return True, if the given box fulfills *OpenMM*'s requirements for
+    boxes, else otherwise.
+
+    The first vector must be on the x-axis
+    and the second vector must be on the xy-plane.
+    """
+    return np.all(np.triu(box, k=1) == 0)