biotite 0.41.1__cp312-cp312-macosx_10_16_arm64.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

@@ -0,0 +1,123 @@
+# 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 ..atoms import Atom, AtomArray, AtomArrayStack
+from .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 = get_from_ccd(
+                    "chem_comp", item.upper(), "formula_weight"
+                ).item()
+        elif not is_residue:
+            result_mass = _atom_masses.get(item.upper())
+        else:
+            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

@@ -0,0 +1,144 @@
+# 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__ = ["all_residues", "full_name", "link_type", "one_letter_code"]
+
+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])
+    ['0V9', '0VA', '0VB', '0VC', '0VD', '0VE', '0VF', '0VG', '0VH', '0VI']
+    """
+    return get_ccd()["chem_comp"]["id"].as_array().tolist()
+
+
+def full_name(res_name):
+    """
+    Get the full name of a residue/compound from the up to 3-letter
+    residue name, based on the PDB chemical components dictionary.
+
+    Parameters
+    ----------
+    res_name : str
+        The up to 3-letter residue name.
+
+    Returns
+    -------
+    name : str or None
+        The full name of the residue.
+        If the residue is unknown to the chemical components dictionary,
+        ``None`` is returned.
+
+    Examples
+    --------
+
+    >>> print(full_name("MAN"))
+    alpha-D-mannopyranose
+    """
+    array = get_from_ccd("chem_comp", res_name.upper(), "name")
+    if array is None:
+        return None
+    return array.item()
+
+
+def link_type(res_name):
+    """
+    Get the linking type of a residue/compound,
+    based on the PDB chemical components dictionary.
+
+    Parameters
+    ----------
+    res_name : str
+        The up to 3-letter residue name.
+
+    Returns
+    -------
+    link_type : str or None
+        The link type.
+        If the residue is unknown to the chemical components dictionary,
+        ``None`` is returned.
+
+    Examples
+    --------
+
+    >>> print(link_type("MAN"))
+    D-saccharide, alpha linking
+    >>> print(link_type("TRP"))
+    L-PEPTIDE LINKING
+    >>> print(link_type("HOH"))
+    NON-POLYMER
+    """
+    array = get_from_ccd("chem_comp", res_name.upper(), "type")
+    if array is None:
+        return None
+    return array.item()
+
+
+def one_letter_code(res_name):
+    """
+    Get the one-letter code of a residue/compound,
+    based on the PDB chemical components dictionary.
+
+    The one-letter code is only defined for amino acids and nucleotides
+    and for compounds that are structurally similar to them.
+
+    Parameters
+    ----------
+    res_name : str
+        The up to 3-letter residue name.
+
+    Returns
+    -------
+    one_letter_code : str or None
+        The one-letter code.
+        None if the compound is not present in the CCD or if no
+        one-letter code is defined for this compound.
+
+    Examples
+    --------
+
+    Get the one letter code for an amino acid (or a nucleotide).
+
+    >>> print(full_name("ALA"))
+    ALANINE
+    >>> print(one_letter_code("ALA"))
+    A
+
+    For similar compounds, the one-letter code is also defined.
+
+    >>> print(full_name("DAL"))
+    D-ALANINE
+    >>> print(one_letter_code("DAL"))
+    A
+
+    For other compounds, the one-letter code is not defined.
+
+    >>> print(full_name("MAN"))
+    alpha-D-mannopyranose
+    >>> print(one_letter_code("MAN"))
+    None
+
+    """
+    array = get_from_ccd("chem_comp", res_name.upper(), "one_letter_code")
+    if array is None:
+        return None
+    item = array.item()
+    if item == "":
+        return None
+    return item

biotite/structure/info/radii.py

@@ -0,0 +1,197 @@
+# 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__ = ["vdw_radius_protor", "vdw_radius_single"]
+
+from .bonds import bonds_in_residue
+
+
+# Contains tuples for the different ProtOr groups:
+# Tuple contains: element, valency, H count
+_PROTOR_RADII = {
+    ("C",  3, 0) : 1.61,
+    ("C",  3, 1) : 1.76,
+    ("C",  4, 1) : 1.88,
+    ("C",  4, 2) : 1.88,
+    ("C",  4, 3) : 1.88,
+    ("N",  3, 0) : 1.64,
+    ("N",  3, 1) : 1.64,
+    ("N",  3, 2) : 1.64,
+    ("N",  4, 3) : 1.64,
+    ("O",  1, 0) : 1.42,
+    ("O",  2, 1) : 1.46,
+    ("S",  1, 0) : 1.77,
+    ("S",  2, 0) : 1.77, # Not official, added for completeness (MET)
+    ("S",  2, 1) : 1.77,
+    ("F",  1, 0) : 1.47, # Taken from _SINGLE_RADII
+    ("CL", 1, 0) : 1.75, # Taken from _SINGLE_RADII
+    ("BR", 1, 0) : 1.85, # Taken from _SINGLE_RADII
+    ("I",  1, 0) : 1.98, # Taken from _SINGLE_RADII
+}
+
+_SINGLE_RADII = {
+    "H":  1.20,
+    "HE": 1.40,
+    
+    "C":  1.70,
+    "N":  1.55,
+    "O":  1.52,
+    "F":  1.47,
+    "NE": 1.54,
+    
+    "SI": 2.10,
+    "P":  1.80,
+    "S":  1.80,
+    "CL": 1.75,
+    "AR": 1.88,
+    
+    "AS": 1.85,
+    "SE": 1.90,
+    "BR": 1.85,
+    "KR": 2.02,
+    
+    "TE": 2.06,
+    "I":  1.98,
+    "XE": 2.16,
+}
+
+# A dictionary that caches radii for each residue
+_protor_radii = {}
+
+
+def vdw_radius_protor(res_name, atom_name):
+    """
+    Estimate the Van-der-Waals radius of an non-hydrogen atom,
+    that includes the radius added by potential bonded hydrogen atoms.
+    The respective radii are taken from the ProtOr dataset.
+    :footcite:`Tsai1999`
+
+    This is especially useful for macromolecular structures where no
+    hydrogen atoms are resolved, e.g. crystal structures.
+    The valency of the non-hydrogen atom and the amount of normally
+    bonded hydrogen atoms is taken from the chemical compound dictionary
+    dataset.
+
+    Parameters
+    ----------
+    res_name : str
+        The up to 3-letter residue name the non-hydrogen atom belongs
+        to.
+    atom_name : str
+        The name of the non-hydrogen atom.
+    
+    Returns
+    -------
+    The Van-der-Waals radius of the given atom.
+    If the radius cannot be estimated for the atom, `None` is returned.
+
+    See also
+    --------
+    vdw_radius_single
+    
+    References
+    ----------
+    
+    .. footbibliography::
+    
+    Examples
+    --------
+
+    >>> print(vdw_radius_protor("GLY", "CA"))
+    1.88
+    """
+    res_name = res_name.upper()
+    if atom_name[0] == "H":
+        raise ValueError(
+            f"Calculating the ProtOr radius for the hydrogen atom "
+            f"'{atom_name}' is not meaningful"
+        )
+    if res_name in _protor_radii:
+        # Use cached radii for the residue, if already calculated
+        if atom_name not in _protor_radii[res_name]:
+            raise KeyError(
+                f"Residue '{res_name}' does not contain an atom named "
+                f"'{atom_name}'"
+            )
+        return _protor_radii[res_name].get(atom_name)
+    else:
+        # Otherwise calculate radii for the given residue and cache
+        _protor_radii[res_name] = _calculate_protor_radii(res_name)
+        # Recursive call, but this time the radii for the given residue
+        # are cached
+        return vdw_radius_protor(res_name, atom_name)
+
+def _calculate_protor_radii(res_name):
+    """
+    Calculate the ProtOr VdW radii for all atoms (atom names) in
+    a residue.
+    """
+    bonds = bonds_in_residue(res_name)
+    # Maps atom names to a ProtOr group
+    # -> tuple(element, valency, H count)
+    # Based on the group the radius is chosen from _PROTOR_RADII
+    groups = {}
+    for atom1, atom2 in bonds:
+        # Process each bond two times:
+        # One time the first atom is the one to get valency and H count
+        # for and the other time vice versa
+        for main_atom, bound_atom in ((atom1, atom2), (atom2, atom1)):
+            element = main_atom[0]
+            # Calculating ProtOr radii for hydrogens in not meaningful
+            if element == "H":
+                continue
+            # Only for these elements ProtOr groups exist
+            # Calculation of group for all other elements would be
+            # pointless
+            if element not in ["C", "N", "O", "S"]:
+                # Empty tuple to indicate nonexistent entry
+                groups[main_atom] = ()
+                continue
+            # Update existing entry if already existing
+            group = groups.get(main_atom, [element, 0, 0])
+            # Increase valency by one, since the bond entry exists
+            group[1] += 1
+            # If the atom is bonded to hydrogen, increase H count
+            if bound_atom[0] == "H":
+                group[2] += 1
+            groups[main_atom] = group
+    # Get radii based on ProtOr groups
+    radii = {atom : _PROTOR_RADII.get(tuple(group))
+             for atom, group in groups.items()}
+    return radii
+
+
+def vdw_radius_single(element):
+    """
+    Get the Van-der-Waals radius of an atom from the given element.
+    :footcite:`Bondi1964`
+
+    Parameters
+    ----------
+    element : str
+        The chemical element of the atoms.
+    
+    Returns
+    -------
+    The Van-der-Waals radius of the atom.
+    If the radius is unknown for the element, `None` is returned.
+    
+    See also
+    --------
+    vdw_radius_protor
+    
+    References
+    ----------
+    
+    .. footbibliography::
+    
+    Examples
+    --------
+
+    >>> print(vdw_radius_single("C"))
+    1.7
+    """
+    return _SINGLE_RADII.get(element.upper())