biotite 1.1.0__cp313-cp313-macosx_10_13_x86_64.whl

biotite/structure/info/bonds.py

@@ -0,0 +1,149 @@
+# 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__ = ["bond_type", "bonds_in_residue"]
+
+import functools
+from biotite.structure.bonds import BondType
+from biotite.structure.info.ccd import get_from_ccd
+
+BOND_TYPES = {
+    ("SING", "N"): BondType.SINGLE,
+    ("DOUB", "N"): BondType.DOUBLE,
+    ("TRIP", "N"): BondType.TRIPLE,
+    ("QUAD", "N"): BondType.QUADRUPLE,
+    ("SING", "Y"): BondType.AROMATIC_SINGLE,
+    ("DOUB", "Y"): BondType.AROMATIC_DOUBLE,
+    ("TRIP", "Y"): BondType.AROMATIC_TRIPLE,
+}
+
+_intra_bonds = {}
+
+
+def bond_type(res_name, atom_name1, atom_name2):
+    """
+    Get the :class:`BondType` for two atoms of the same residue, based
+    on the PDB chemical components dictionary.
+
+    Parameters
+    ----------
+    res_name : str
+        The up to 3-letter name of the residue
+        `atom_name1` and `atom_name2` belong to.
+    atom_name1, atom_name2 : str
+        The names of the two atoms to get the bond order from.
+
+    Returns
+    -------
+    order : BondType or None
+        The :class:`BondType` of the bond between `atom_name1` and
+        `atom_name2`.
+        If the atoms form no bond, if any of the two atoms does not
+        exist in the context of the residue or if the residue is unknown
+        to the chemical components dictionary, `None` is returned.
+
+    Examples
+    --------
+
+    >>> print(repr(bond_type("PHE", "CA", "CB")))
+    <BondType.SINGLE: 1>
+    >>> print(repr(bond_type("PHE", "CG", "CD1")))
+    <BondType.AROMATIC_DOUBLE: 6>
+    >>> print(repr(bond_type("PHE", "CA", "CG")))
+    None
+    >>> print(repr(bond_type("PHE", "FOO", "BAR")))
+    None
+    """
+    bonds_for_residue = bonds_in_residue(res_name)
+    if bonds_for_residue is None:
+        return None
+    # Try both atom orders
+    bond_type_int = bonds_for_residue.get(
+        (atom_name1, atom_name2), bonds_for_residue.get((atom_name2, atom_name1))
+    )
+    if bond_type_int is not None:
+        return BondType(bond_type_int)
+    else:
+        return None
+
+
+@functools.cache
+def bonds_in_residue(res_name):
+    """
+    Get a dictionary containing all atoms inside a given residue
+    that form a bond.
+
+    Parameters
+    ----------
+    res_name : str
+        The up to 3-letter name of the residue to get the bonds for.
+
+    Returns
+    -------
+    bonds : dict ((str, str) -> int)
+        A dictionary that maps tuples of two atom names to their
+        respective bond types (represented as integer).
+        Empty, if the residue is unknown to the
+        chemical components dictionary.
+
+    Warnings
+    --------
+    Treat the returned dictionary as immutable.
+    Modifying the dictionary may lead to unexpected behavior.
+    In other functionalities throughout *Biotite* that uses this
+    function.
+
+    Notes
+    -----
+    The returned values are cached for faster access in subsequent calls.
+
+    Examples
+    --------
+    >>> bonds = bonds_in_residue("PHE")
+    >>> for atoms, bond_type_int in sorted(bonds.items()):
+    ...     atom1, atom2 = sorted(atoms)
+    ...     print(f"{atom1:3} + {atom2:3} -> {BondType(bond_type_int).name}")
+    C   + O   -> DOUBLE
+    C   + OXT -> SINGLE
+    C   + CA  -> SINGLE
+    CA  + CB  -> SINGLE
+    CA  + HA  -> SINGLE
+    CB  + CG  -> SINGLE
+    CB  + HB2 -> SINGLE
+    CB  + HB3 -> SINGLE
+    CD1 + CE1 -> AROMATIC_SINGLE
+    CD1 + HD1 -> SINGLE
+    CD2 + CE2 -> AROMATIC_DOUBLE
+    CD2 + HD2 -> SINGLE
+    CE1 + CZ  -> AROMATIC_DOUBLE
+    CE1 + HE1 -> SINGLE
+    CE2 + CZ  -> AROMATIC_SINGLE
+    CE2 + HE2 -> SINGLE
+    CD1 + CG  -> AROMATIC_DOUBLE
+    CD2 + CG  -> AROMATIC_SINGLE
+    CZ  + HZ  -> SINGLE
+    CA  + N   -> SINGLE
+    H   + N   -> SINGLE
+    H2  + N   -> SINGLE
+    HXT + OXT -> SINGLE
+    """
+    global _intra_bonds
+    if res_name not in _intra_bonds:
+        chem_comp_bond = get_from_ccd("chem_comp_bond", res_name)
+        if chem_comp_bond is None:
+            _intra_bonds[res_name] = {}
+        else:
+            bonds_for_residue = {}
+            for atom1, atom2, order, aromatic_flag in zip(
+                chem_comp_bond["atom_id_1"].as_array(),
+                chem_comp_bond["atom_id_2"].as_array(),
+                chem_comp_bond["value_order"].as_array(),
+                chem_comp_bond["pdbx_aromatic_flag"].as_array(),
+            ):
+                bond_type = BOND_TYPES[order, aromatic_flag]
+                bonds_for_residue[atom1.item(), atom2.item()] = bond_type
+            _intra_bonds[res_name] = bonds_for_residue
+    return _intra_bonds[res_name]

biotite/structure/info/ccd.py

@@ -0,0 +1,202 @@
+# 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", "set_ccd_path", "get_from_ccd"]
+
+import functools
+import importlib
+import inspect
+import pkgutil
+from pathlib import Path
+import numpy as np
+
+_CCD_FILE = Path(__file__).parent / "components.bcif"
+_SPECIAL_ID_COLUMN_NAMES = {
+    "chem_comp": "id",
+}
+_DEFAULT_ID_COLUMN_NAME = "comp_id"
+
+
+@functools.cache
+def get_ccd():
+    """
+    Get the internal subset of the PDB
+    *Chemical Component Dictionary* (CCD).
+    :footcite:`Westbrook2015`
+
+    Returns
+    -------
+    ccd : BinaryCIFBlock
+        The CCD.
+        It contains the categories `chem_comp`, `chem_comp_atom` and `chem_comp_bond`.
+
+    Warnings
+    --------
+
+    Consider the return value as read-only.
+    As other functions cache data from it, changing data may lead to undefined
+    behavior.
+
+    References
+    ----------
+
+    .. footbibliography::
+
+    """
+    # Avoid circular import
+    from biotite.structure.io.pdbx.bcif import BinaryCIFFile
+
+    try:
+        return BinaryCIFFile.read(_CCD_FILE).block
+    except FileNotFoundError:
+        raise RuntimeError(
+            "Internal CCD not found. Please run 'python -m biotite.setup_ccd'."
+        )
+
+
+def set_ccd_path(ccd_path):
+    """
+    Replace the internal *Chemical Component Dictionary* (CCD) with a custom one.
+
+    This function also clears the cache of functions depending on the CCD to ensure
+    that the new CCD is used.
+
+    Parameters
+    ----------
+    ccd_path : path-like
+        The path to the custom CCD in BinaryCIF format, prepared with the
+        ``setup_ccd.py`` module.
+
+    Notes
+    -----
+    This function is intended for advanced users who need to add information for
+    compounds, which are not part of the internal CCD.
+    The reason might be that an updated version already exists upstream or that
+    the user wants to add custom compounds to the CCD.
+    """
+    global _CCD_FILE
+    _CCD_FILE = Path(ccd_path)
+
+    # Clear caches in all functions in biotite.structure.info
+    info_modules = [
+        importlib.import_module(f"biotite.structure.info.{mod_name}")
+        for _, mod_name, _ in pkgutil.iter_modules([str(Path(__file__).parent)])
+    ]
+    for module in info_modules:
+        for _, function in inspect.getmembers(module, callable):
+            if hasattr(function, "cache_clear"):
+                function.cache_clear()
+
+
+@functools.cache
+def get_from_ccd(category_name, comp_id, column_name=None):
+    """
+    Get the rows for the given residue in the given category from the
+    internal subset of the PDB *Chemical Component Dictionary* (CCD).
+    :footcite:`Westbrook2015`
+
+    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
+    -------
+    slice : BinaryCIFCategory or BinaryCIFColumn
+        The category or column (if `column_name` is provided) containing only the rows
+        for the given residue.
+
+    Notes
+    -----
+    The returned values are cached for faster access in subsequent calls.
+
+    References
+    ----------
+
+    .. footbibliography::
+
+    """
+    try:
+        start, stop = _residue_index(category_name)[comp_id]
+    except KeyError:
+        return None
+
+    category = get_ccd()[category_name]
+    if column_name is None:
+        return _filter_category(category, slice(start, stop))
+    else:
+        return _filter_column(category[column_name], slice(start, stop))
+
+
+@functools.cache
+def _residue_index(category_name):
+    """
+    Get the start and stop index for each component name in the given
+    CCD category.
+
+    Parameters
+    ----------
+    category_name : str
+        The category to determine start and stop indices for each component in.
+
+    Returns
+    -------
+    index : dict (str -> (int, int))
+        The index maps each present component name to the corresponding
+        start and exclusive stop index in `id_column`.
+    """
+    category = get_ccd()[category_name]
+    id_column_name = _SPECIAL_ID_COLUMN_NAMES.get(
+        category_name, _DEFAULT_ID_COLUMN_NAME
+    )
+    id_column = category[id_column_name].as_array()
+
+    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
+
+
+def _filter_category(category, index):
+    """
+    Reduce the category to the values for the given index.∂
+    """
+    # Avoid circular import
+    from biotite.structure.io.pdbx.bcif import BinaryCIFCategory
+
+    return BinaryCIFCategory(
+        {key: _filter_column(column, index) for key, column in category.items()}
+    )
+
+
+def _filter_column(column, index):
+    """
+    Reduce the column to the values for the given index.
+    """
+    # Avoid circular import
+    from biotite.structure.io.pdbx.bcif import BinaryCIFColumn, BinaryCIFData
+    from biotite.structure.io.pdbx.component import MaskValue
+
+    data_array = column.data.array[index]
+    mask_array = column.mask.array[index] if column.mask is not None else None
+    return BinaryCIFColumn(
+        BinaryCIFData(data_array),
+        (
+            BinaryCIFData(mask_array)
+            if column.mask is not None and (mask_array != MaskValue.PRESENT).any()
+            else None
+        ),
+    )

biotite/structure/info/groups.py

@@ -0,0 +1,131 @@
+# 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"]
+
+import functools
+import numpy as np
+from biotite.structure.info.ccd import get_ccd
+
+_AMINO_ACID_TYPES = [
+    "D-beta-peptide, C-gamma linking",
+    "D-gamma-peptide, C-delta linking",
+    "D-peptide COOH carboxy terminus",
+    "D-peptide NH3 amino terminus",
+    "D-peptide linking",
+    "L-beta-peptide, C-gamma linking",
+    "L-gamma-peptide, C-delta linking",
+    "L-peptide COOH carboxy terminus",
+    "L-peptide NH3 amino terminus",
+    "L-peptide linking",
+    "peptide linking",
+]
+_NUCLEOTIDE_TYPES = [
+    "DNA OH 3 prime terminus",
+    "DNA OH 5 prime terminus",
+    "DNA linking",
+    "L-DNA linking",
+    "L-RNA linking",
+    "RNA OH 3 prime terminus",
+    "RNA OH 5 prime terminus",
+    "RNA linking",
+]
+_CARBOHYDRATE_TYPES = [
+    "D-saccharide",
+    "D-saccharide, alpha linking",
+    "D-saccharide, beta linking",
+    "L-saccharide",
+    "L-saccharide, alpha linking",
+    "L-saccharide, beta linking",
+    "saccharide",
+]
+
+
+@functools.cache
+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.
+
+    References
+    ----------
+
+    .. footbibliography::
+
+    """
+    return _get_group_members(_AMINO_ACID_TYPES)
+
+
+@functools.cache
+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.
+
+    References
+    ----------
+
+    .. footbibliography::
+
+    """
+    return _get_group_members(_NUCLEOTIDE_TYPES)
+
+
+@functools.cache
+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.
+
+    References
+    ----------
+
+    .. footbibliography::
+
+    """
+    return _get_group_members(_CARBOHYDRATE_TYPES)
+
+
+def _get_group_members(match_types):
+    """
+    Identify component IDs that matches a given component *type* from the CCD.
+
+    Parameters
+    ----------
+    match_types : list of str
+        The component types to extract.
+
+    Returns
+    -------
+    comp_ids : list of str
+        The extracted component IDs.
+    """
+    category = get_ccd()["chem_comp"]
+    comp_ids = category["id"].as_array()
+    types = category["type"].as_array()
+    # Ignore case
+    return comp_ids[np.isin(np.char.lower(types), np.char.lower(match_types))].tolist()

biotite/structure/info/masses.py

@@ -0,0 +1,121 @@
+# 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__ = ["mass"]
+
+import json
+from pathlib import Path
+from biotite.structure.atoms import Atom, AtomArray, AtomArrayStack
+from biotite.structure.info.ccd import get_from_ccd
+
+# Masses are taken from http://www.sbcs.qmul.ac.uk/iupac/AtWt/ (2018/03/01)
+ATOM_MASSES_FILE = Path(__file__).parent / "atom_masses.json"
+_atom_masses = None
+
+
+def mass(item, is_residue=None):
+    """
+    Calculate the mass for the given object.
+    :footcite:`Meija2016`
+
+    If a residue name is given, the mass values refer to the masses of
+    the complete molecule without additional or missing protons.
+    In case of residues in a longer chain, some atoms might be missing
+    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
+        The atom or molecule to get the mass for.
+        If a string is given, it is interpreted as residue name or
+        chemical element.
+        If an :class:`Atom` is given the mass is taken from its element.
+        If an :class:`AtomArray` or :class:`AtomArrayStack` is given the
+        mass is the sum of the mass of its atoms.
+    is_residue : bool, optional
+        If set to true and a string is given for `item`, the string
+        will be strictly interpreted as residue.
+        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
+    --------
+
+    >>> print(mass(atom_array))
+    2170.438
+    >>> first_residue = list(residue_iter(atom_array))[0]
+    >>> print(first_residue)
+        A       1  ASN N      N        -8.901    4.127   -0.555
+        A       1  ASN CA     C        -8.608    3.135   -1.618
+        A       1  ASN C      C        -7.117    2.964   -1.897
+        A       1  ASN O      O        -6.634    1.849   -1.758
+        A       1  ASN CB     C        -9.437    3.396   -2.889
+        A       1  ASN CG     C       -10.915    3.130   -2.611
+        A       1  ASN OD1    O       -11.269    2.700   -1.524
+        A       1  ASN ND2    N       -11.806    3.406   -3.543
+        A       1  ASN H1     H        -8.330    3.957    0.261
+        A       1  ASN H2     H        -8.740    5.068   -0.889
+        A       1  ASN H3     H        -9.877    4.041   -0.293
+        A       1  ASN HA     H        -8.930    2.162   -1.239
+        A       1  ASN HB2    H        -9.310    4.417   -3.193
+        A       1  ASN HB3    H        -9.108    2.719   -3.679
+        A       1  ASN HD21   H       -11.572    3.791   -4.444
+        A       1  ASN HD22   H       -12.757    3.183   -3.294
+    >>> print(mass("ASN"))
+    132.118
+    >>> first_atom = first_residue[0]
+    >>> print(first_atom)
+        A       1  ASN N      N        -8.901    4.127   -0.555
+    >>> print(mass(first_atom))
+    14.007
+    >>> 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 = _mass_for_residue(item)
+        elif not is_residue:
+            result_mass = _atom_masses.get(item.upper())
+        else:
+            result_mass = _mass_for_residue(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
+
+
+def _mass_for_residue(res_name):
+    column = get_from_ccd("chem_comp", res_name.upper(), "formula_weight")
+    if column is None:
+        raise KeyError(f"Residue '{res_name}' is not known")
+    return column.as_item()