biotite 1.1.0__cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

biotite/structure/info/misc.py

@@ -0,0 +1,138 @@
+# 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 biotite.structure.info.ccd import get_ccd, get_from_ccd
+
+
+def all_residues():
+    """
+    Get a list of all residues/compound names in the PDB
+    *Chemical Component Dictionary* (CCD).
+
+    Returns
+    -------
+    residues : list of str
+        A list of all available residue names.
+    """
+    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
+    """
+    column = get_from_ccd("chem_comp", res_name.upper(), "name")
+    if column is None:
+        return None
+    return column.as_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
+    """
+    column = get_from_ccd("chem_comp", res_name.upper(), "type")
+    if column is None:
+        return None
+    return column.as_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
+
+    """
+    column = get_from_ccd("chem_comp", res_name.upper(), "one_letter_code")
+    if column is None:
+        return None
+    if column.mask is not None:
+        # Value is masked, i.e. inapplicable or missing
+        return None
+    return column.as_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 biotite.structure.info.bonds import bonds_in_residue
+
+# fmt: off
+# 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,
+}
+# fmt: on
+
+# 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())

biotite/structure/info/standardize.py

@@ -0,0 +1,186 @@
+# 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__ = ["standardize_order"]
+
+import warnings
+import numpy as np
+from biotite.structure.error import BadStructureError
+from biotite.structure.info.ccd import get_from_ccd
+from biotite.structure.residues import get_residue_starts
+
+
+def standardize_order(atoms):
+    """
+    Get an index array for an input :class:`AtomArray` or
+    :class:`AtomArrayStack` that reorders the atoms for each residue
+    to obtain the standard *RCSB PDB* atom order.
+
+    The standard atom order is determined from the reference residues in
+    the official *Chemical Component Dictionary*.
+    If a residue of the input structure contains additional atoms that
+    are not present in the reference residue, these indices to these
+    atoms are appended to the end of the respective residue.
+    A example for this are optional hydrogen atoms, that appear due to
+    protonation.
+
+    Parameters
+    ----------
+    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
+    --------
+
+    Use as single residue as example.
+
+    >>> residue = atom_array[atom_array.res_id == 1]
+    >>> print(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
+
+    Reverse the atom array.
+    Consequently, this also changes the atom order within the residue.
+
+    >>> reordered = residue[np.arange(len(residue))[::-1]]
+    >>> print(reordered)
+        A       1  ASN HD22   H       -12.757    3.183   -3.294
+        A       1  ASN HD21   H       -11.572    3.791   -4.444
+        A       1  ASN HB3    H        -9.108    2.719   -3.679
+        A       1  ASN HB2    H        -9.310    4.417   -3.193
+        A       1  ASN HA     H        -8.930    2.162   -1.239
+        A       1  ASN H3     H        -9.877    4.041   -0.293
+        A       1  ASN H2     H        -8.740    5.068   -0.889
+        A       1  ASN H1     H        -8.330    3.957    0.261
+        A       1  ASN ND2    N       -11.806    3.406   -3.543
+        A       1  ASN OD1    O       -11.269    2.700   -1.524
+        A       1  ASN CG     C       -10.915    3.130   -2.611
+        A       1  ASN CB     C        -9.437    3.396   -2.889
+        A       1  ASN O      O        -6.634    1.849   -1.758
+        A       1  ASN C      C        -7.117    2.964   -1.897
+        A       1  ASN CA     C        -8.608    3.135   -1.618
+        A       1  ASN N      N        -8.901    4.127   -0.555
+
+    The order is restored with the exception of the N-terminus protonation.
+
+    >>> restored = reordered[info.standardize_order(reordered)]
+    >>> print(restored)
+        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 H2     H        -8.740    5.068   -0.889
+        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
+        A       1  ASN H3     H        -9.877    4.041   -0.293
+        A       1  ASN H1     H        -8.330    3.957    0.261
+    """
+    reordered_indices = np.zeros(atoms.array_length(), dtype=int)
+
+    starts = get_residue_starts(atoms, add_exclusive_stop=True)
+    for i in range(len(starts) - 1):
+        start = starts[i]
+        stop = starts[i + 1]
+
+        res_name = atoms.res_name[start]
+        chem_comp_atom = get_from_ccd("chem_comp_atom", res_name, "atom_id")
+        if chem_comp_atom is None:
+            # 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
+
+        standard_atom_names = chem_comp_atom.as_array()
+        reordered_indices[start:stop] = (
+            _reorder(atoms.atom_name[start:stop], standard_atom_names) + start
+        )
+
+    return reordered_indices
+
+
+def _reorder(origin, target):
+    """
+    Create indices to `origin`, that changes the order of `origin`,
+    so that the order is the same as in `target`.
+
+    Indices for elements of `target` that are not in `origin`
+    are ignored.
+    Indices for elements of `origin` that are not in `target`
+    are appended to the end of the returned array.
+
+
+    Parameters
+    ----------
+    origin : ndarray, dtype=str
+        The atom names to reorder.
+    target : ndarray, dtype=str
+        The atom names in target order.
+
+    Returns
+    -------
+    indices : ndarray, dtype=int
+        Indices for `origin` that that changes the order of `origin`
+        to the order of `target`.
+    """
+    target_hits, origin_hits = np.where(target[:, np.newaxis] == origin[np.newaxis, :])
+
+    counts = np.bincount(target_hits, minlength=len(target))
+    if (counts > 1).any():
+        counts = np.bincount(target_hits, minlength=len(target))
+        # Identify which atom is duplicate
+        duplicate_i = np.where(counts > 1)[0][0]
+        duplicate_name = target[duplicate_i]
+        raise BadStructureError(
+            f"Input structure has duplicate atom '{duplicate_name}'"
+        )
+
+    if len(origin_hits) < len(origin):
+        # The origin structure has additional atoms
+        # to the target structure
+        # -> Identify which atoms are missing in the target structure
+        # and append these to the end of the residue
+        missing_atom_mask = np.bincount(origin_hits, minlength=len(origin)).astype(bool)
+        return np.concatenate([origin_hits, np.where(~missing_atom_mask)[0]])
+    else:
+        return origin_hits