biotite 1.0.1__cp311-cp311-win_amd64.whl → 1.2.0__cp311-cp311-win_amd64.whl

biotite/file.py

@@ -44,7 +44,7 @@ class File(Copyable, metaclass=abc.ABCMeta):
 
         Returns
         -------
-        file_object : File
+        file : File
             An instance from the respective :class:`File` subclass
             representing the parsed file.
         """
@@ -57,7 +57,7 @@ class File(Copyable, metaclass=abc.ABCMeta):
 
         Parameters
         ----------
-        file_name : file-like object or str
+        file : file-like object or str
             The file to be written to.
             Alternatively a file path can be supplied.
         """
@@ -207,6 +207,18 @@ def wrap_string(text, width):
 
     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):

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,16 @@
+# 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 .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)

biotite/interface/pymol/__init__.py

@@ -0,0 +1,198 @@
+# ruff: noqa: F401
+
+# 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 package enables the transfer of structures from *Biotite* to
+`PyMOL <https://pymol.org/>`_ for visualization and vice versa,
+via *PyMOL*'s Python API:
+
+- Import :class:`AtomArray` and :class:`AtomArrayStack` objects into *PyMOL* -
+  without intermediate structure files.
+- Convert *PyMOL* objects into :class:`AtomArray` and :class:`AtomArrayStack`
+  instances.
+- Use *Biotite*'s boolean masks for atom selection in *PyMOL*.
+- Display images rendered with *PyMOL* in *Jupyter* notebooks.
+
+Launching PyMOL
+---------------
+
+Library mode
+^^^^^^^^^^^^
+The recommended way to invoke *PyMOL* in a Python script depends on whether a GUI should
+be displayed.
+If no GUI is required, we recommend launching a *PyMOL* session in library mode.
+
+.. code-block:: python
+
+    import biotite.interface.pymol as pymol_interface
+
+    pymol_interface.launch_pymol()
+
+Usually launching *PyMOL* manually via :func:`launch_pymol()` is not even necessary:
+When *Biotite* requires a *PyMOL* session, e.g. for creating a *PyMOL* object or
+invoking a command, and none is already running, *PyMOL* is automatically started in
+library mode.
+
+GUI mode
+^^^^^^^^
+When the *PyMOL* GUI is necessary, the *PyMOL* library mode is not available.
+Instead *PyMOL* can be launched in interactive (GUI) mode:
+
+.. code-block:: python
+
+    import biotite.interface.pymol as pymol_interface
+
+    pymol_interface.launch_interactive_pymol("-qixkF", "-W", "400", "-H", "400")
+
+:func:`launch_interactive_pymol()` starts *PyMOL* using the given command line options,
+reinitializes it and sets necessary parameters.
+
+After that, the usual *PyMOL* commands and the other functions from
+*Biotite* are available.
+
+Note that the *PyMOL* window will stay open after the end of the script.
+This can lead to issues when using interactive Python (e.g. *IPython*):
+The *PyMOL* window could not be closed by normal means and a forced termination might be
+necessary.
+This can be solved by using *PyMOL*'s integrated command line for executing Python.
+
+Launching PyMOL directly
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+    This is not the recommended way to use *PyMOL* in the context of
+    :mod:`biotite.interface.pymol`.
+    Usage is at your own risk.
+
+You can also launch *PyMOL* directly using the *PyMOL* Python API, that
+:func:`launch_pymol()` and :func:`launch_interactive_pymol()` use internally.
+In this case, it is important to call :func:`setup_parameters()` for setting
+parameters that are necessary for *Biotite* to interact properly with *PyMOL*.
+Furthermore, the ``pymol_instance`` parameter must be set the first time
+a :class:`PyMOLObject` is created to inform *Biotite* about the *PyMOL* session.
+
+.. code-block:: python
+
+    from pymol2 import PyMOL
+    import biotite.interface.pymol as pymol_interface
+
+    pymol_app = PyMOL()
+    pymol_app.start()
+    pymol_interface.setup_parameters(pymol_instance=pymol_app)
+    cmd = pymol_app.cmd
+
+    pymol_object = pymol_interface.PyMOLObject.from_structure(
+        atom_array, pymol_instance=pymol_app
+    )
+
+Common issues
+-------------
+As *PyMOL* is a quite complex software with a lot of its functionality written
+in *C++*, sometimes unexpected results or crashes may occur under certain
+circumstances.
+This page should provide help in such and similar cases.
+
+Interactive PyMOL crashes when launched on MacOS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Unfortunately, the *PyMOL* GUI is not supported on MacOS, as described in
+`this issue <https://github.com/schrodinger/pymol-open-source/issues/97>`_.
+The library mode launched by default should still work.
+
+Interactive PyMOL crashes when launched after usage of Matplotlib
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Interactive *PyMOL* will crash, if it is launched after a *Matplotlib* figure
+is created. This does not happen in the object-oriented library mode of
+*PyMOL*.
+Presumably the reason is a conflict in the *OpenGL* contexts.
+
+Example code that leads to crash:
+
+.. code-block:: python
+
+  import matplotlib.pyplot as plt
+  import biotite.interface.pymol as pymol_interface
+
+  figure = plt.figure()
+  pymol_interface.launch_interactive_pymol()
+
+'cmd.png()' command crashes in pytest function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``pytest`` executes the test functions via ``exec()``, which might lead to the crash.
+Up to now the only way to prevent this, is not to test the ``png()`` command
+in pytest.
+
+Launching PyMOL for the first time raises DuplicatePyMOLError
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For example the code snippet
+
+.. code-block:: python
+
+  import biotite.interface.pymol import cmd, launch_pymol
+
+  launch_pymol()
+
+raises
+
+.. code-block:: python
+
+  biotite.interface.pymol.DuplicatePyMOLError: A PyMOL instance is already running
+
+The reason:
+
+If ``from biotite.interface.pymol import pymol``
+or ``from biotite.interface.pymol import cmd`` is called, *PyMOL* is already launched
+upon import in order to make the ``pymol`` or ``cmd`` attribute available.
+Subsequent calls of :func:`launch_pymol()` or
+:func:`launch_interactive_pymol()` would start a second *PyMOL* session,
+which is forbidden.
+
+To circumvent this problem do not import ``pymol`` or ``cmd`` from
+``biotite.interface.pymol``, but access these attributes via ``pymol_interface.pymol``
+or ``pymol_interface.cmd`` at the required places in your code.
+
+|
+
+*PyMOL is a trademark of Schrodinger, LLC.*
+"""
+
+__name__ = "biotite.interface.pymol"
+__author__ = "Patrick Kunzmann"
+
+
+from .cgo import *
+from .convert import *
+from .display import *
+from .object import *
+from .shapes import *
+
+# Do not import expose the internally used 'get_and_set_pymol_instance()'
+from .startup import (
+    DuplicatePyMOLError,
+    launch_interactive_pymol,
+    launch_pymol,
+    reset,
+    setup_parameters,
+)
+
+
+# Make the PyMOL instance accessible via `biotite.interface.pymol.pymol`
+# analogous to a '@property' of a class, but on module level instead
+def __getattr__(name):
+    from .startup import get_and_set_pymol_instance
+
+    if name == "pymol":
+        return get_and_set_pymol_instance()
+    elif name == "cmd":
+        return __getattr__("pymol").cmd
+    elif name in list(globals().keys()):
+        return globals()["name"]
+    else:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+def __dir__():
+    return list(globals().keys()) + ["pymol", "cmd"]