biotite 0.39.0__cp312-cp312-win_amd64.whl → 0.40.0__cp312-cp312-win_amd64.whl

biotite/structure/info/ccd.py

@@ -0,0 +1,95 @@
+# 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__ = ["get_ccd", "get_from_ccd"]
+
+from pathlib import Path
+import numpy as np
+
+
+CCD_DIR = Path(__file__).parent / "ccd"
+INDEX_COLUMN_NAME = {
+    "chem_comp": "id",
+    "chem_comp_atom": "comp_id",
+    "chem_comp_bond": "comp_id",
+}
+
+_ccd_block = None
+# For each category this index gives the start and stop for each residue
+_residue_index = {}
+
+
+def get_ccd():
+    """
+    Get the PDB *Chemical Component Dictionary* (CCD).
+
+    Returns
+    -------
+    ccd : BinaryCIFFile
+        The CCD.
+    """
+    # Avoid circular import
+    from ..io.pdbx.bcif import BinaryCIFFile
+
+    global _ccd_block
+    if _ccd_block is None:
+        # Load CCD once and cache it for subsequent calls
+        _ccd_block = BinaryCIFFile.read(CCD_DIR / "components.bcif").block
+    return _ccd_block
+
+
+def get_from_ccd(category_name, comp_id, column_name=None):
+    """
+    Get the rows for the given residue in the given category from the
+    PDB *Chemical Component Dictionary* (CCD).
+
+    Parameters
+    ----------
+    category_name : str
+        The category in the CCD.
+    comp_id : str
+        The residue identifier, i.e. the ``res_name``.
+    column_name : str, optional
+        The name of the column to be retrieved.
+        If None, all columns are returned as dictionary.
+        By default None.
+
+    Returns
+    -------
+    value : ndarray or dict or None
+        The array of the given column or all columns as dictionary.
+        ``None`` if the `comp_id` is not found in the category.
+    """
+    global _residue_index
+    ccd = get_ccd()
+    category = ccd[category_name]
+    if category_name not in _residue_index:
+        _residue_index[category_name] = _index_residues(
+            category[INDEX_COLUMN_NAME[category_name]].as_array()
+        )
+    try:
+        start, stop = _residue_index[category_name][comp_id]
+    except KeyError:
+        return None
+
+    if column_name is None:
+        return {
+            col_name: category[col_name].as_array()[start:stop]
+            for col_name in category.keys()
+        }
+    else:
+        return category[column_name].as_array()[start:stop]
+
+
+def _index_residues(id_column):
+    residue_starts = np.where(id_column[:-1] != id_column[1:])[0] + 1
+    # The final start is the exclusive stop of last residue
+    residue_starts = np.concatenate(([0], residue_starts, [len(id_column)]))
+    index = {}
+    for i in range(len(residue_starts)-1):
+        comp_id = id_column[residue_starts[i]].item()
+        index[comp_id] = (residue_starts[i], residue_starts[i+1])
+    return index

biotite/structure/info/groups.py

@@ -0,0 +1,90 @@
+# 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__ = "Tom David Müller, Patrick Kunzmann"
+__all__ = ["amino_acid_names", "nucleotide_names", "carbohydrate_names"]
+
+from pathlib import Path
+import copy
+
+
+CCD_DIR = Path(__file__).parent / "ccd"
+
+
+group_lists = {}
+
+
+def amino_acid_names():
+    """
+    Get a tuple of amino acid three-letter codes according to the
+    PDB *Chemical Component Dictionary* :footcite:`Westbrook2015`.
+
+    Returns
+    -------
+    amino_acid_names : tuple of str
+        A list of three-letter-codes containing residues that are
+        peptide monomers.
+
+    Notes
+    -----
+
+    References
+    ----------
+
+    .. footbibliography::
+    """
+    return _get_group_members("amino_acids")
+
+
+def nucleotide_names():
+    """
+    Get a tuple of nucleotide three-letter codes according to the
+    PDB *Chemical Component Dictionary* :footcite:`Westbrook2015`.
+
+    Returns
+    -------
+    nucleotide_names : tuple of str
+        A list of three-letter-codes containing residues that are
+        DNA/RNA monomers.
+
+    Notes
+    -----
+
+    References
+    ----------
+
+    .. footbibliography::
+    """
+    return _get_group_members("nucleotides")
+
+
+def carbohydrate_names():
+    """
+    Get a tuple of carbohydrate three-letter codes according to the
+    PDB *Chemical Component Dictionary* :footcite:`Westbrook2015`.
+
+    Returns
+    -------
+    carbohydrate_names : tuple of str
+        A list of three-letter-codes containing residues that are
+        saccharide monomers.
+
+    Notes
+    -----
+
+    References
+    ----------
+
+    .. footbibliography::
+    """
+    return _get_group_members("carbohydrates")
+
+
+def _get_group_members(group_name):
+    global group_lists
+    if group_name not in group_lists:
+        with open(CCD_DIR / f"{group_name}.txt", "r") as file:
+            group_lists[group_name] = tuple(file.read().split())
+    return group_lists[group_name]

biotite/structure/info/masses.py

@@ -7,20 +7,14 @@ __author__ = "Patrick Kunzmann"
 __all__ = ["mass"]
 
 import json
-from os.path import join, dirname, realpath
-import msgpack
+from pathlib import Path
 from ..atoms import Atom, AtomArray, AtomArrayStack
+from .ccd import get_from_ccd
 
 
-_info_dir = dirname(realpath(__file__))
 # Masses are taken from http://www.sbcs.qmul.ac.uk/iupac/AtWt/ (2018/03/01)
-with open(join(_info_dir, "atom_masses.json"), "r") as file:
-    _atom_masses = json.load(file)
-# Masses are taken from
-# ftp://ftp.wwpdb.org/pub/pdb/data/monomers/components.cif
-# (2019/01/27)
-with open(join(_info_dir, "residue_masses.msgpack"), "rb") as file:
-    _res_masses = msgpack.load(file, raw=False)
+ATOM_MASSES_FILE = Path(__file__).parent / "atom_masses.json"
+_atom_masses = None
 
 
 def mass(item, is_residue=None):
@@ -34,7 +28,7 @@ def mass(item, is_residue=None):
     from the molecule.
     For example non-terminal residues in a protein or nucleotide chain
     miss the mass of a water molecule.
-    
+
     Parameters
     ----------
     item : str or Atom or AtomArray or AtomArrayStack
@@ -50,17 +44,17 @@ def mass(item, is_residue=None):
         If set to false, the string is strictly interpreted as element.
         By default the string will be interpreted as element at first
         and secondly as residue name, if the element is unknown.
-    
+
     Returns
     -------
     mass : float or None
         The mass of the given object in *u*. None if the mass is unknown.
-    
+
     References
     ----------
-    
+
     .. footbibliography::
-    
+
     Examples
     --------
 
@@ -94,29 +88,36 @@ def mass(item, is_residue=None):
     >>> print(mass("N"))
     14.007
     """
+    global _atom_masses
+    with open(ATOM_MASSES_FILE, "r") as file:
+        _atom_masses = json.load(file)
 
     if isinstance(item, str):
         if is_residue is None:
             result_mass = _atom_masses.get(item.upper())
             if result_mass is None:
-                result_mass = _res_masses.get(item.upper())
+                result_mass = get_from_ccd(
+                    "chem_comp", item.upper(), "formula_weight"
+                ).item()
         elif not is_residue:
             result_mass = _atom_masses.get(item.upper())
         else:
-            result_mass = _res_masses.get(item.upper())
-    
+            result_mass = get_from_ccd(
+                "chem_comp", item.upper(), "formula_weight"
+            ).item()
+
     elif isinstance(item, Atom):
         result_mass = mass(item.element, is_residue=False)
     elif isinstance(item, AtomArray) or isinstance(item, AtomArrayStack):
         result_mass = sum(
             (mass(element, is_residue=False) for element in item.element)
         )
-    
+
     else:
         raise TypeError(
             f"Cannot calculate mass for {type(item).__name__} objects"
         )
-    
+
     if result_mass is None:
         raise KeyError(f"{item} is not known")
     return result_mass

biotite/structure/info/misc.py

@@ -6,37 +6,26 @@ __name__ = "biotite.structure.info"
 __author__ = "Patrick Kunzmann"
 __all__ = ["all_residues", "full_name", "link_type"]
 
-from os.path import join, dirname, realpath
-import msgpack
-
-
-_info_dir = dirname(realpath(__file__))
-# Data is taken from
-# ftp://ftp.wwpdb.org/pub/pdb/data/monomers/components.cif
-# (2019/01/27)
-with open(join(_info_dir, "residue_names.msgpack"), "rb") as file:
-    _res_names = msgpack.load(file, raw=False)
-with open(join(_info_dir, "link_types.msgpack"), "rb") as file:
-    _link_types = msgpack.load(file, raw=False)
+from .ccd import get_ccd, get_from_ccd
 
 
 def all_residues():
     """
     Get a list of all residues/compound names in the
     PDB chemical components dictionary.
-    
+
     Returns
     -------
     residues : list of str
         A list of all available The up to 3-letter residue names.
-    
+
     Examples
     --------
 
     >>> print(all_residues()[1000 : 1010])
-    ['0Y4', '0Y5', '0Y7', '0Y8', '0Y9', '0YA', '0YB', '0YC', '0YD', '0YE']
+    ['0V9', '0VA', '0VB', '0VC', '0VD', '0VE', '0VF', '0VG', '0VH', '0VI']
     """
-    return list(_res_names.keys()) 
+    return get_ccd()["chem_comp"]["id"].as_array().tolist()
 
 
 def full_name(res_name):
@@ -48,19 +37,19 @@ def full_name(res_name):
     ----------
     res_name : str
         The up to 3-letter residue name.
-    
+
     Returns
     -------
     name : str
         The full name of the residue.
-    
+
     Examples
     --------
 
     >>> print(full_name("MAN"))
     alpha-D-mannopyranose
     """
-    return _res_names.get(res_name.upper())
+    return get_from_ccd("chem_comp", res_name.upper(), "name").item()
 
 
 def link_type(res_name):
@@ -72,12 +61,12 @@ def link_type(res_name):
     ----------
     res_name : str
         The up to 3-letter residue name.
-    
+
     Returns
     -------
     link_type : str
         The link type.
-    
+
     Examples
     --------
 
@@ -88,4 +77,4 @@ def link_type(res_name):
     >>> print(link_type("HOH"))
     NON-POLYMER
     """
-    return _link_types.get(res_name.upper())
+    return get_from_ccd("chem_comp", res_name.upper(), "type").item()

biotite/structure/info/standardize.py

@@ -6,15 +6,13 @@ __name__ = "biotite.structure.info"
 __author__ = "Patrick Kunzmann"
 __all__ = ["standardize_order"]
 
+import warnings
 import numpy as np
-from .atoms import residue
+from .ccd import get_from_ccd
 from ..residues import get_residue_starts
 from ..error import BadStructureError
 
 
-_atom_name_cache = {}
-
-
 def standardize_order(atoms):
     """
     Get an index array for an input :class:`AtomArray` or
@@ -34,20 +32,20 @@ def standardize_order(atoms):
     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
     --------
 
@@ -123,11 +121,18 @@ def standardize_order(atoms):
         stop = starts[i+1]
 
         res_name = atoms.res_name[start]
-        standard_atom_names = _atom_name_cache.get(res_name)
+        standard_atom_names = get_from_ccd(
+            "chem_comp_atom", res_name, "atom_id"
+        )
         if standard_atom_names is None:
-            standard_atom_names = residue(res_name).atom_name
-            _atom_name_cache[res_name] = standard_atom_names
-        
+            # 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
@@ -152,7 +157,7 @@ def _reorder(origin, target):
         The atom names to reorder.
     target : ndarray, dtype=str
         The atom names in target order.
-    
+
     Returns
     -------
     indices : ndarray, dtype=int

biotite/structure/io/__init__.py

@@ -5,7 +5,7 @@
 """
 A subpackage for reading and writing structure related data.
 
-Macromolecular structure files (PDB, PDBx/mmCIF, MMTF, etc.) and
+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`.
 
@@ -15,10 +15,8 @@ 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 MMTF.
+The recommended format for reading structure files is *BinaryCIF*.
 It has by far the shortest parsing time and file size.
-Furthermore, chemical bond information can be read from MMTF files
-as :class:`BondList` instances.
 
 Besides the mentioned structure formats, Gromacs trajectory files can be
 loaded, if `mdtraj` is installed.

biotite/structure/io/ctab.py

@@ -13,7 +13,7 @@ __all__ = ["read_structure_from_ctab", "write_structure_to_ctab"]
 
 import warnings
 import numpy as np
-from biotite.structure.error import BadStructureError
+from ..error import BadStructureError
 from ..atoms import AtomArray, AtomArrayStack
 from ..bonds import BondList, BondType
 

biotite/structure/io/general.py

@@ -21,12 +21,12 @@ 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
@@ -40,13 +40,13 @@ def load_structure(file_path, template=None, **kwargs):
         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
@@ -65,56 +65,37 @@ def load_structure(file_path, template=None, **kwargs):
         from .pdb import PDBFile
         file = PDBFile.read(file_path)
         array = file.get_structure(**kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
+        return _as_single_model_if_possible(array)
     elif suffix == ".pdbqt":
         from .pdbqt import PDBQTFile
         file = PDBQTFile.read(file_path)
         array = file.get_structure(**kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
+        return _as_single_model_if_possible(array)
     elif suffix == ".cif" or suffix == ".pdbx":
-        from .pdbx import PDBxFile, get_structure
-        file = PDBxFile.read(file_path)
+        from .pdbx import CIFFile, get_structure
+        file = CIFFile.read(file_path)
         array = get_structure(file, **kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
+        return _as_single_model_if_possible(array)
+    elif suffix == ".bcif":
+        from .pdbx import BinaryCIFFile, get_structure
+        file = BinaryCIFFile.read(file_path)
+        array = get_structure(file, **kwargs)
+        return _as_single_model_if_possible(array)
     elif suffix == ".gro":
         from .gro import GROFile
         file = GROFile.read(file_path)
         array = file.get_structure(**kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
+        return _as_single_model_if_possible(array)
     elif suffix == ".mmtf":
         from .mmtf import MMTFFile, get_structure
         file = MMTFFile.read(file_path)
         array = get_structure(file, **kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
+        return _as_single_model_if_possible(array)
     elif suffix == ".npz":
         from .npz import NpzFile
         file = NpzFile.read(file_path)
         array = file.get_structure(**kwargs)
-        if isinstance(array, AtomArrayStack) and array.stack_depth() == 1:
-            # Stack containing only one model -> return as atom array
-            return array[0]
-        else:
-            return array
+        return _as_single_model_if_possible(array)
     elif suffix == ".mol" or suffix == ".sdf":
         from .mol import MOLFile
         file = MOLFile.read(file_path)
@@ -153,10 +134,10 @@ 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
@@ -185,9 +166,14 @@ def save_structure(file_path, array, **kwargs):
         file.set_structure(array, **kwargs)
         file.write(file_path)
     elif suffix == ".cif" or suffix == ".pdbx":
-        from .pdbx import PDBxFile, set_structure
-        file = PDBxFile()
-        set_structure(file, array, data_block="STRUCTURE", **kwargs)
+        from .pdbx import CIFFile, set_structure
+        file = CIFFile()
+        set_structure(file, array, **kwargs)
+        file.write(file_path)
+    elif suffix == ".bcif":
+        from .pdbx import BinaryCIFFile, set_structure
+        file = BinaryCIFFile()
+        set_structure(file, array, **kwargs)
         file.write(file_path)
     elif suffix == ".gro":
         from .gro import GROFile
@@ -232,8 +218,16 @@ def save_structure(file_path, array, **kwargs):
         raise ValueError(f"Unknown file format '{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
+
+
 # Helper function to estimate elements from atom names
-_elements = [elem.upper() for elem in 
+_elements = [elem.upper() for elem in
 ["H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne", "Na", "Mg",
 "Al", "Si", "P", "S", "Cl", "Ar", "K", "Ca", "Sc", "Ti", "V", "Cr", "Mn", "Fe",
 "Co", "Ni", "Cu", "Zn", "Ga", "Ge", "As", "Se", "Br", "Kr", "Rb", "Sr", "Y",
@@ -268,4 +262,4 @@ def _guess_element(atom_name):
             pass
 
     return ""
- 
+

biotite/structure/io/mmtf/__init__.py

@@ -7,6 +7,9 @@ This subpackage is used for reading and writing an :class:`AtomArray` or
 :class:`AtomArrayStack` using the binary MMTF format. This format
 features a smaller file size and a highly increased I/O operation
 performance, than the text based file formats.
+
+DEPRECATED: Use :class:`biotite.structure.io.pdbx.BinaryCIFFile`
+instead.
 """
 
 __name__ = "biotite.structure.io.mmtf"