biotite 1.1.0__cp313-cp313-macosx_11_0_arm64.whl → 1.3.0__cp313-cp313-macosx_11_0_arm64.whl

biotite/database/pubchem/download.py

@@ -41,22 +41,22 @@ def fetch(
         to be downloaded.
     format : {'sdf', 'asnt' 'asnb', 'xml', 'json', 'jsonp', 'png'}
         The format of the files to be downloaded.
+    target_path : str, optional
+        The target directory of the downloaded files.
+        By default, the file content is stored in a file-like object
+        (:class:`StringIO` or :class:`BytesIO`, respectively).
     as_structural_formula : bool, optional
         If set to true, the structural formula is download instead of
         an 3D conformer.
         This means that coordinates lie in th xy-plane and represent
         the positions atoms would have an a structural formula
         representation.
-    target_path : str, optional
-        The target directory of the downloaded files.
-        By default, the file content is stored in a file-like object
-        (:class:`StringIO` or :class:`BytesIO`, respectively).
     overwrite : bool, optional
         If true, existing files will be overwritten.
         Otherwise the respective file will only be downloaded, if the
         file does not exist yet in the specified target directory or if
         the file is empty.
-    verbose: bool, optional
+    verbose : bool, optional
         If set to true, the function will output the download progress.
     throttle_threshold : float or None, optional
         A value between 0 and 1.
@@ -114,7 +114,7 @@ def fetch(
             raise TypeError("CIDs must be given as integers, not as string")
         # Verbose output
         if verbose:
-            print(f"Fetching file {i+1:d} / {len(cids):d} ({cid})...", end="\r")
+            print(f"Fetching file {i + 1:d} / {len(cids):d} ({cid})...", end="\r")
 
         # Fetch file from database
         if target_path is not None:

biotite/database/pubchem/error.py

@@ -11,6 +11,16 @@ def parse_error_details(response_text):
     """
     Parse the ``Detail: ...`` or alternatively ``Message: ...`` part of
     an error response.
+
+    Parameters
+    ----------
+    response_text : str
+        The text of the response.
+
+    Returns
+    -------
+    error_details : str
+        The error details.
     """
     for message_line_indicator in ["Detail: ", "Message: "]:
         for line in response_text.splitlines():

biotite/database/pubchem/query.py

@@ -240,6 +240,11 @@ class FormulaQuery(Query):
             The maximum number of matches that this query may return.
             By default, the *PubChem* default value is used, which can
             be considered unlimited.
+
+        Returns
+        -------
+        query : FormulaQuery
+            The query.
         """
         element_counter = collections.Counter(atoms.element)
         formula = ""
@@ -327,7 +332,7 @@ class StructureQuery(Query, metaclass=abc.ABCMeta):
                     )
         if not query_key_found:
             raise TypeError(
-                "Expected exactly one of 'smiles', 'smarts', 'inchi', 'sdf' " "or 'cid'"
+                "Expected exactly one of 'smiles', 'smarts', 'inchi', 'sdf' or 'cid'"
             )
         if "number" in kwargs:
             self._number = kwargs["number"]
@@ -348,8 +353,13 @@ class StructureQuery(Query, metaclass=abc.ABCMeta):
         ----------
         atoms : AtomArray or AtomArrayStack
             The query structure.
-        **kwargs : dict, optional
+        *args, **kwargs
             See the constructor for additional options.
+
+        Returns
+        -------
+        query : StructureQuery
+            The query object.
         """
         mol_file = MOLFile()
         mol_file.set_structure(atoms)
@@ -448,26 +458,19 @@ class SuperOrSubstructureQuery(StructureQuery, metaclass=abc.ABCMeta):
         be considered unlimited.
     match_charges : bool, optional
         If set to true, atoms must match the specified charge.
-        (Default: False)
     match_tautomers : bool, optional
         If set to true, allow match to tautomers of the given structure.
-        (Default: False)
     rings_not_embedded : bool, optional
         If set to true, rings may not be embedded in a larger system.
-        (Default: False)
     single_double_bonds_match : bool, optional
         If set to true, single or double bonds match aromatic bonds.
-        (Default: True)
     chains_match_rings : bool, optional
         If set to true, chain bonds in the query may match rings in
         hits.
-        (Default: True)
     strip_hydrogen : bool, optional
         If set to true, remove any explicit hydrogens before searching.
-        (Default: False)
     stereo : {'ignore', 'exact', 'relative', 'nonconflicting'}, optional
         How to handle stereo.
-        (Default: 'ignore')
 
     Notes
     -----
@@ -528,26 +531,19 @@ class SuperstructureQuery(SuperOrSubstructureQuery):
         be considered unlimited.
     match_charges : bool, optional
         If set to true, atoms must match the specified charge.
-        (Default: False)
     match_tautomers : bool, optional
         If set to true, allow match to tautomers of the given structure.
-        (Default: False)
     rings_not_embedded : bool, optional
         If set to true, rings may not be embedded in a larger system.
-        (Default: False)
     single_double_bonds_match : bool, optional
         If set to true, single or double bonds match aromatic bonds.
-        (Default: True)
     chains_match_rings : bool, optional
         If set to true, chain bonds in the query may match rings in
         hits.
-        (Default: True)
     strip_hydrogen : bool, optional
         If set to true, remove any explicit hydrogens before searching.
-        (Default: False)
     stereo : {'ignore', 'exact', 'relative', 'nonconflicting'}, optional
         How to handle stereo.
-        (Default: 'ignore')
 
     Notes
     -----
@@ -601,26 +597,19 @@ class SubstructureQuery(SuperOrSubstructureQuery):
         be considered unlimited.
     match_charges : bool, optional
         If set to true, atoms must match the specified charge.
-        (Default: False)
     match_tautomers : bool, optional
         If set to true, allow match to tautomers of the given structure.
-        (Default: False)
     rings_not_embedded : bool, optional
         If set to true, rings may not be embedded in a larger system.
-        (Default: False)
     single_double_bonds_match : bool, optional
         If set to true, single or double bonds match aromatic bonds.
-        (Default: True)
     chains_match_rings : bool, optional
         If set to true, chain bonds in the query may match rings in
         hits.
-        (Default: True)
     strip_hydrogen : bool, optional
         If set to true, remove any explicit hydrogens before searching.
-        (Default: False)
     stereo : {'ignore', 'exact', 'relative', 'nonconflicting'}, optional
         How to handle stereo.
-        (Default: 'ignore')
 
     Notes
     -----

biotite/database/rcsb/download.py

@@ -44,7 +44,7 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
         Otherwise the respective file will only be downloaded, if the
         file does not exist yet in the specified target directory or if
         the file is empty.
-    verbose: bool, optional
+    verbose : bool, optional
         If set to true, the function will output the download progress.
 
     Returns
@@ -91,7 +91,7 @@ def fetch(pdb_ids, format, target_path=None, overwrite=False, verbose=False):
     for i, id in enumerate(pdb_ids):
         # Verbose output
         if verbose:
-            print(f"Fetching file {i+1:d} / {len(pdb_ids):d} ({id})...", end="\r")
+            print(f"Fetching file {i + 1:d} / {len(pdb_ids):d} ({id})...", end="\r")
 
         # Fetch file from database
         if target_path is not None:
@@ -152,6 +152,7 @@ def _assert_valid_file(response_text, pdb_id):
         for err_msg in [
             "404 Not Found",
             "<title>RCSB Protein Data Bank Error Page</title>",
+            "<title>PDB Archive over AWS</title>",
             "No fasta files were found.",
             "No valid PDB IDs were submitted.",
         ]

biotite/database/rcsb/query.py

@@ -257,7 +257,7 @@ class FieldQuery(SingleQuery):
             "exists",
         ]:
             raise TypeError(
-                f"Constructor got an unexpected keyword argument " f"'{self._operator}'"
+                f"Constructor got an unexpected keyword argument '{self._operator}'"
             )
 
         # Convert dates into ISO 8601
@@ -944,8 +944,7 @@ def _initialize_query_dict(query, return_type, group_by, content_types):
     if group_by is not None:
         if not group_by.is_compatible_return_type(return_type):
             raise ValueError(
-                f"Return type '{return_type}' is not compatible "
-                f"with the given Grouping"
+                f"Return type '{return_type}' is not compatible with the given Grouping"
             )
         request_options["group_by"] = group_by.get_content()
 

biotite/database/uniprot/check.py

@@ -16,8 +16,8 @@ def assert_valid_response(response):
 
     Parameters
     ----------
-    response_status_code: int
-        Status code of request.get.
+    response : Response
+        Status code of :func:`requests.get()`.
     """
     if len(response.content) == 0:
         raise RequestError("No content returned")

biotite/database/uniprot/download.py

@@ -41,7 +41,6 @@ def fetch(ids, format, target_path=None, overwrite=False, verbose=False):
     Download files from the UniProt in various formats.
 
     Available databases are UniProtKB, UniRef and UniParc.
-
     This function requires an internet connection.
 
     Parameters
@@ -58,11 +57,9 @@ def fetch(ids, format, target_path=None, overwrite=False, verbose=False):
     overwrite : bool, optional
         If true, existing files will be overwritten. Otherwise the
         respective file will only be downloaded if the file does not
-        exist yet in the specified target directory or if the file is
-        empty. (Default: False)
-    verbose: bool, optional
+        exist yet in the specified target directory.
+    verbose : bool, optional
         If true, the function will output the download progress.
-        (Default: False)
 
     Returns
     -------

biotite/database/uniprot/query.py

@@ -50,9 +50,9 @@ class CompositeQuery(Query):
 
     Parameters
     ----------
-    operator: str, {"AND", "OR", "NOT"}
+    operator : str, {"AND", "OR", "NOT"}
         The combination operator.
-    queries : iterable object of SimpleQuery
+    query1, query2 : SimpleQuery
         The queries to be combined.
     """
 
@@ -114,7 +114,7 @@ class SimpleQuery(Query):
        The list of possible fields and the required search term
        formatting can be found
        `here <https://www.uniprot.org/help/query-fields>`_.
-    term: str
+    term : str
        The search term.
     """
 
@@ -264,7 +264,6 @@ def search(query, number=500):
         The search query.
     number : int
         The maximum number of IDs that are obtained.
-        (Default: 500)
 
     Returns
     -------

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,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)