Source code for graphein.protein.dssp_core

"""Tensor-based DSSP secondary structure assignment.

Optimised re-implementation of PyDSSP
(https://github.com/ShintaroMinami/PyDSSP; MIT License, Copyright (c) 2022
Shintaro Minami) for Graphein's tensor representation. Speedups come from:

* computing pairwise distances per component, never materialising
  ``(L, L, 3)`` arrays;
* for discrete assignment, evaluating the full H-bond energy only for O-N
  pairs within a provably sufficient radius (see :func:`_prune_radius`) and
  thresholding the energy directly instead of the smoothed H-bond map;
* replacing PyDSSP's ``(L, L, 3, 3)`` unfolded bridge maps with shifted slices
  of a boolean H-bond map.

Assignments match PyDSSP, except that PyDSSP drops H-bonds within ~1e-4
kcal/mol of the cutoff in float32 (its smoothed map rounds to 0 there); here
``E < -0.5`` is applied exactly.

NumPy (:func:`assign_dssp_np`, :func:`get_hbond_map_np`) and PyTorch
(:func:`assign_dssp`, :func:`get_hbond_map`) variants share one
implementation. The PyTorch variant runs on any device and
:func:`get_hbond_map` is differentiable.

:func:`assign_dssp8` (and :func:`assign_dssp8_np`) provide full 8-state DSSP
using mkdssp's own H-bond model and rules; output is identical to mkdssp
4.6.1 (polyproline aside). Since mkdssp keeps at most two H-bonds per donor,
everything after the H-bond energies works on an O(L) edge list.

:func:`accessibility` (and :func:`accessibility_np`) compute DSSP's solvent
accessible surface area per residue, identical to mkdssp 4.6.1.
"""

# Graphein
# Author: Arian Jamasb <arian@jamasb.io>
# License: MIT
# Project Website: https://github.com/a-r-j/graphein
# Code Repository: https://github.com/a-r-j/graphein
from __future__ import annotations

from typing import TYPE_CHECKING, Optional

import numpy as np
from loguru import logger as log
from scipy.spatial import cKDTree

from graphein.utils.dependencies import import_message

if TYPE_CHECKING:
    from graphein.protein.tensor.types import AtomTensor

try:
    import torch
except ImportError:
    message = import_message(
        "graphein.protein.tensor.dssp",
        package="torch",
        conda_channel="pytorch",
        pip_install=True,
    )
    log.debug(message)

CONST_Q1Q2 = 0.084
CONST_F = 332
DEFAULT_CUTOFF = -0.5
DEFAULT_MARGIN = 1.0


def _zeros(ref, shape, dtype=None):
    if isinstance(ref, np.ndarray):
        return np.zeros(shape, dtype=ref.dtype if dtype is None else dtype)
    return ref.new_zeros(shape, dtype=dtype)


def _unit(v, xp):
    return v / xp.sqrt((v * v).sum(-1))[..., None]


def _rsqrt(v, xp):
    # Fastest inverse sqrt per backend (np.power is ~7x slower than this).
    return 1 / np.sqrt(v) if xp is np else torch.rsqrt(v)


def _pdist2(a, b):
    # Summing per component avoids materialising an (..., L, L, 3) array.
    d2 = 0
    for i in range(3):
        d = a[..., :, None, i] - b[..., None, :, i]
        d2 = d2 + d * d
    return d2


def _check_shape(x):
    if x.ndim not in (3, 4) or x.shape[-1] != 3 or x.shape[-2] < 4:
        raise ValueError(
            "Expected coordinates of shape (L, A, 3) or (B, L, A, 3) with "
            f"A >= 4 (N, CA, C, O first), got {tuple(x.shape)}"
        )


def _backbone(x, xp):
    """N, pseudo-H of residues ``1..L-1``; C, O of residues ``0..L-2``."""
    _check_shape(x)
    n, ca = x[..., 1:, 0, :], x[..., 1:, 1, :]
    c, o = x[..., :-1, 2, :], x[..., :-1, 3, :]
    # Pseudo-H on the bisector of the C(i-1)->N and CA->N bonds (as in PyDSSP)
    h = n + 1.01 * _unit(_unit(n - c, xp) + _unit(n - ca, xp), xp)
    return n, h, c, o


def _hbond_energy(x, xp):
    """H-bond energy (kcal/mol) of shape ``(..., L-1, L-1)``.

    Entry ``[m, k]`` is the energy between the N-H of residue ``m + 1`` and
    the C=O of residue ``k``.
    """
    n, h, c, o = _backbone(x, xp)

    def inv(a, b):
        return _rsqrt(_pdist2(a, b), xp)

    return (CONST_Q1Q2 * CONST_F) * (
        inv(n, o) + inv(h, c) - inv(h, o) - inv(n, c)
    )


def _prune_radius(b: float, cutoff: float) -> float:
    """O-N distance beyond which ``|E| <= |cutoff|``, so no H-bond exists.

    With ``b`` the longest C=O bond and ``|N-H| = 1.01``, the triangle
    inequality bounds ``|E| / K`` by ``b / (r (r - b)) + b / ((r - 1.01)
    (r - 1.01 - b))``, which decreases in ``r``. ~13 Angstrom for real
    proteins.
    """
    K, s = CONST_Q1Q2 * CONST_F, b + 1.01

    def bound(r):
        return K * b * (1 / (r * (r - b)) + 1 / ((r - 1.01) * (r - s)))

    lo, hi = s, s + 1.0
    while bound(hi) > abs(cutoff):
        lo, hi = hi, 2 * hi
    for _ in range(50):
        mid = (lo + hi) / 2
        lo, hi = (mid, hi) if bound(mid) > abs(cutoff) else (lo, mid)
    return hi * 1.01  # headroom for floating point error in E


def _hbonds(x, xp, cutoff=DEFAULT_CUTOFF):
    """Boolean ``E < cutoff`` of shape ``(..., L-1, L-1)`` (see
    :func:`_hbond_energy`), evaluating the full energy only for O-N pairs
    within :func:`_prune_radius`. Exactly equal to the dense computation."""
    n, h, c, o = _backbone(x, xp)
    d2 = _pdist2(n, o)
    if d2.shape[-1] == 0:  # L < 2: no pairs
        return d2 < cutoff
    b = float(xp.nan_to_num(xp.sqrt(((c - o) ** 2).sum(-1))).max())
    near = d2 < _prune_radius(b, cutoff) ** 2
    idx = np.nonzero(near) if xp is np else torch.nonzero(near, as_tuple=True)
    don, acc = idx[:-1], idx[:-2] + idx[-1:]

    def inv(a, b):
        return _rsqrt(((a - b) ** 2).sum(-1), xp)

    e = (CONST_Q1Q2 * CONST_F) * (
        _rsqrt(d2[idx], xp)
        + inv(h[don], c[acc])
        - inv(h[don], o[acc])
        - inv(n[don], c[acc])
    )
    near[idx] = e < cutoff
    return near


def _allowed(ref, donor_mask):
    """``(..., L, L)`` bool mask [donor, acceptor] excluding local pairs
    (``0 <= donor - acceptor <= 2``) and masked donors (e.g. proline)."""
    L = ref.shape[-1]
    m = _zeros(ref, ref.shape, dtype=bool)
    m[..., 1:, :-1] = True
    for k in (0, 1, 2):
        m[..., range(k, L), range(L - k)] = False
    if donor_mask is not None:
        m &= donor_mask[..., :, None]
    return m


def _hbond_map(x, xp, donor_mask, cutoff, margin, return_e):
    e = _hbond_energy(x, xp)
    L = x.shape[-3]
    out = _zeros(e, e.shape[:-2] + (L, L))
    out[..., 1:, :-1] = e
    if return_e:
        return out
    hb = xp.clip(cutoff - margin - out, -margin, margin)
    hb = (xp.sin(hb / margin * (xp.pi / 2)) + 1.0) / 2
    return hb * _allowed(out, donor_mask)


def _spread(h, xp, n):
    """``out[i] = h[i] | h[i-1] | ... | h[i-n+1]``."""
    out = xp.zeros_like(h)
    for s in range(n):
        out[..., s:] |= h[..., : h.shape[-1] - s]
    return out


def _bridges(hb):
    """Parallel and antiparallel bridges between residues ``I`` (rows) and
    ``J`` (cols), both in ``[1, L-2]``, from ``hb[acceptor, donor]``."""
    hbT = hb.swapaxes(-1, -2)
    c = slice(1, -1)
    parallel = (hb[..., :-2, c] & hbT[..., 2:, c]) | (
        hbT[..., c, :-2] & hb[..., c, 2:]
    )
    antiparallel = (hb[..., c, c] & hbT[..., c, c]) | (
        hb[..., :-2, 2:] & hbT[..., 2:, :-2]
    )
    return parallel, antiparallel


def _assign(x, xp, donor_mask):
    L = x.shape[-3]
    # hb[i, j]: C=O of residue i accepts an H-bond from N-H of residue j.
    # Thresholding the energy is equivalent to PyDSSP's ``hbond_map > 0``.
    hb = _zeros(x, x.shape[:-3] + (L, L), dtype=bool)
    hb[..., :-1, 1:] = _hbonds(x, xp).swapaxes(-1, -2)
    for k in (0, 1, 2):
        hb[..., range(L - k), range(k, L)] = False
    if donor_mask is not None:
        hb &= donor_mask[..., None, :]

    # Helices: consecutive n-turns, with alpha (4) taking priority over 3/5.
    def helix_starts(k):
        t = xp.diagonal(hb, k, -2, -1)
        h = xp.zeros_like(hb[..., 0, :])
        h[..., 1 : L - k] = t[..., :-1] & t[..., 1:]
        return h

    helix4 = _spread(helix_starts(4), xp, 4)
    free = ~helix4
    free[..., :-1] &= ~helix4[..., 1:]
    helix = (
        helix4
        | _spread(helix_starts(3) & free, xp, 3)
        | _spread(helix_starts(5) & free, xp, 5)
    )

    parallel, antiparallel = _bridges(hb)
    strand = xp.zeros_like(helix)
    strand[..., 1:-1] = (parallel | antiparallel).any(-1)

    return xp.stack([~helix & ~strand, helix, strand], -1)


# 8-state DSSP, following mkdssp 4.x (https://github.com/PDB-REDO/dssp).
DSSP8_STATES = "-HBEGITS"
"""8-state codes, indexed by the output of :func:`assign_dssp8`. ``"-"`` is
loop; ``H``: alpha helix, ``B``: isolated bridge, ``E``: strand, ``G``: 3-10
helix, ``I``: pi helix, ``T``: turn, ``S``: bend."""
_L, _H, _B, _E, _G, _I, _T, _S = range(8)
# mkdssp constants (float32 in the original)
_DSSP_K = float(np.float32(27.888))
_DSSP_MAX_CA = 9.0
_DSSP_MIN_DIST = 0.5
_DSSP_MIN_E = -9.9
_DSSP_MAX_PEPTIDE = 2.5


def _dssp_energies(x, xp, donor_mask):
    """H-bond energies of every pair mkdssp evaluates, as NumPy ``(donor,
    acceptor, energy)`` sorted by donor, energy, then acceptor (mkdssp's tie
    order).

    Unlike PyDSSP: H lies 1 Angstrom from N along the preceding C=O; only
    pairs with CA-CA <= 9 Angstrom are evaluated; and energies are rounded to
    0.001 kcal/mol.
    """
    n, ca, c, o = (x[:, k] for k in range(4))
    h = n * 1
    h[1:] = h[1:] + _unit(c[:-1] - o[:-1], xp)

    # CA pairs within 9 Angstrom from a KD-tree (O(L) memory), then the
    # exact cutoff with the distance summed per component as mkdssp.
    ca_np = _to_np(ca)
    a, b = (
        cKDTree(ca_np)
        .query_pairs(_DSSP_MAX_CA + 1e-3, output_type="ndarray")
        .reshape(-1, 2)
        .T
    )
    d = ca_np[a] - ca_np[b]
    near = d[:, 0] * d[:, 0] + d[:, 1] * d[:, 1] + d[:, 2] * d[:, 2]
    near = near <= _DSSP_MAX_CA**2
    don = np.concatenate([a[near], b[near]])
    acc = np.concatenate([b[near], a[near]])
    # Donor/acceptor pairs mkdssp evaluates; it skips donor == acceptor + 1.
    keep = don != acc + 1
    if donor_mask is not None:
        keep &= _to_np(donor_mask)[don]
    don, acc = don[keep], acc[keep]
    if xp is not np:
        don = torch.as_tensor(don, device=x.device)
        acc = torch.as_tensor(acc, device=x.device)

    def dist(a, b):  # float32 like mkdssp, then promoted to float64
        d = a[don] - b[acc]
        d2 = d[:, 0] * d[:, 0] + d[:, 1] * d[:, 1] + d[:, 2] * d[:, 2]
        return _to_np(xp.sqrt(d2)).astype(np.float64)

    # mkdssp's operation order and float64 energy, so the 0.001 rounding
    # (and the -0.5 cutoff) match it exactly.
    ho, hc, nc, no = dist(h, o), dist(h, c), dist(n, c), dist(n, o)
    k = -_DSSP_K
    e = k / ho - k / hc + k / nc - k / no
    too_close = np.minimum(np.minimum(ho, hc), np.minimum(nc, no))
    e = np.where(too_close < _DSSP_MIN_DIST, _DSSP_MIN_E, e)
    e = np.sign(e) * np.floor(np.abs(e) * 1000 + 0.5) / 1000  # C++ round
    e = np.clip(e, _DSSP_MIN_E, None)

    don, acc = _to_np(don), _to_np(acc)
    order = np.lexsort((acc, e, don))
    return don[order], acc[order], e[order]


def _rank(group: np.ndarray) -> np.ndarray:
    """Position of each entry within its run of equal (sorted) ``group``."""
    return np.arange(len(group)) - np.searchsorted(group, group)


def _dssp_hbonds(don, acc, e):
    """H-bonds (``E < -0.5`` among each donor's two lowest-energy acceptors)
    as ``(acceptor, donor)`` index arrays."""
    keep = (_rank(don) < 2) & (e < DEFAULT_CUTOFF)
    return acc[keep], don[keep]


def _dssp_partners(don, acc, e, L):
    """mkdssp's two lowest-energy acceptors per donor (``N-H-->O``) and
    donors per acceptor (``O-->H-N``); only negative energies are kept.

    :return: ``((L, 2) acceptor indices, (L, 2) energies), ((L, 2) donor
        indices, (L, 2) energies)``; index ``-1`` and energy ``0`` if none.
    """

    def top2(key, other, en):  # arrays sorted by (key, energy, other)
        r = _rank(key)
        k = r < 2
        idx, out = np.full((L, 2), -1), np.zeros((L, 2))
        idx[key[k], r[k]], out[key[k], r[k]] = other[k], en[k]
        return idx, out

    neg = e < 0
    don, acc, e = don[neg], acc[neg], e[neg]
    order = np.lexsort((don, e, acc))
    return top2(don, acc, e), top2(acc[order], don[order], e[order])


def _to_np(a):
    return a if isinstance(a, np.ndarray) else a.cpu().numpy()


def _dssp_breaks(x: np.ndarray) -> np.ndarray:
    """``(L-1,)`` chain breaks between consecutive residues (C-N > 2.5)."""
    d = x[1:, 0] - x[:-1, 2]
    return d[:, 0] ** 2 + d[:, 1] ** 2 + d[:, 2] ** 2 > _DSSP_MAX_PEPTIDE**2


def _dssp_numbers(
    x: np.ndarray, breaks: Optional[np.ndarray] = None
) -> np.ndarray:
    """mkdssp residue numbers: 1-based, skipping one at each chain break
    (``breaks``, default :func:`_dssp_breaks`)."""
    if breaks is None:
        breaks = _dssp_breaks(x)
    return np.arange(1, len(x) + 1) + np.r_[0, np.cumsum(breaks)]


def _dihedral(p1, p2, p3, p4):
    """mkdssp's float32 dihedral angle (degrees); 360 if undefined."""

    def cross(a, b):
        return np.stack(
            [
                a[:, 1] * b[:, 2] - b[:, 1] * a[:, 2],
                a[:, 2] * b[:, 0] - b[:, 2] * a[:, 0],
                a[:, 0] * b[:, 1] - b[:, 0] * a[:, 1],
            ],
            -1,
        )

    def dot(a, b):
        return a[:, 0] * b[:, 0] + a[:, 1] * b[:, 1] + a[:, 2] * b[:, 2]

    z = p2 - p3
    p, x = cross(z, p1 - p2), cross(z, p4 - p3)
    y = cross(z, x)
    u, v = dot(x, x), dot(y, y)
    with np.errstate(divide="ignore", invalid="ignore"):
        u2, v2 = dot(p, x) / np.sqrt(u), dot(p, y) / np.sqrt(v)
        angle = np.arctan2(v2, u2) * np.float32(180) / np.float32(np.pi)
    ok = (u > 0) & (v > 0) & ((u2 != 0) | (v2 != 0))
    return np.where(ok, angle, np.float32(360))


def _dssp_phi_psi(x: np.ndarray, breaks: Optional[np.ndarray] = None):
    """mkdssp phi and psi (degrees, 360 where undefined, e.g. across chain
    ``breaks``) of a float32 ``(L, 4, 3)`` backbone."""
    phi = np.full(len(x), np.float32(360))
    psi = np.full(len(x), np.float32(360))
    ok = ~(_dssp_breaks(x) if breaks is None else breaks)
    n, ca, c = x[:, 0], x[:, 1], x[:, 2]
    phi[1:] = np.where(ok, _dihedral(c[:-1], n[1:], ca[1:], c[1:]), 360)
    psi[:-1] = np.where(ok, _dihedral(n[:-1], ca[:-1], c[:-1], n[1:]), 360)
    return phi, psi


def _assign8(x, xp, donor_mask, energies=None, breaks=None):
    # Everything after the H-bonds is O(L) (at most 2 bonds per donor), so
    # it runs in NumPy on the H-bond edge list rather than dense maps.
    L = x.shape[0]
    if energies is None:
        energies = _dssp_energies(x, xp, donor_mask)
    acc, don = _dssp_hbonds(*energies)
    keys = np.sort(acc * L + don)
    x = _to_np(x)

    def hb(a, d):  # vectorised Hbond(a, d): C=O of a accepts from N-H of d
        valid = (a >= 0) & (a < L) & (d >= 0) & (d < L)
        return valid & np.isin(a * L + d, keys)

    # Chain breaks: C(i-1)-N(i) > 2.5 Angstrom unless given (e.g. also at
    # chain changes). seg[i] is i's segment id.
    if breaks is None:
        breaks = _dssp_breaks(x)
    seg = np.concatenate([[0], np.cumsum(breaks)])

    def nobreak(a, b):
        return seg[a] == seg[b]

    # Bridges (i < j). Each bridge pattern contains a specific H-bond, so
    # candidates come from the edge list: for H-bond (a, d), parallel
    # Hbond(i-1, j) & Hbond(j, i+1) gives (a+1, d); Hbond(j-1, i) &
    # Hbond(i, j+1) gives (d, a+1); antiparallel Hbond(i, j) & Hbond(j, i)
    # gives (a, d); Hbond(i-1, j+1) & Hbond(j-1, i+1) gives (a+1, d-1).
    i = np.concatenate([acc + 1, don, acc, acc + 1])
    j = np.concatenate([don, acc + 1, don, don - 1])
    k = np.unique(np.minimum(i, j) * L + np.maximum(i, j))  # sorted (i, j)
    i, j = k // L, k % L
    d = x[i, 1] - x[j, 1]  # CA-CA, summed as in _pdist2
    ok = (i >= 1) & (i < j) & (j <= L - 2)
    ok &= d[:, 0] ** 2 + d[:, 1] ** 2 + d[:, 2] ** 2 <= _DSSP_MAX_CA**2
    i, j = i[ok], j[ok]
    ok = nobreak(i - 1, i + 1) & nobreak(j - 1, j + 1)
    par = ok & ((hb(i - 1, j) & hb(j, i + 1)) | (hb(j - 1, i) & hb(i, j + 1)))
    anti = (ok & ~par) & (
        (hb(i, j) & hb(j, i)) | (hb(i - 1, j + 1) & hb(j - 1, i + 1))
    )
    is_bridge = par | anti
    i, j = i[is_bridge].tolist(), j[is_bridge].tolist()
    is_par = par[is_bridge].tolist()

    # Ladders: consecutive bridges of one type. Bridges arrive sorted by
    # (i, j), so each ladder has a unique next (type, i, j) it can absorb.
    ladders, nxt = [], {}
    for bi, bj, p in zip(i, j, is_par):
        k = nxt.pop((p, bi, bj), None)
        if k is None:
            ladders.append((p, [bi], [bj]))
            k = len(ladders) - 1
        else:
            ladders[k][1].append(bi)
            ladders[k][2].append(bj) if p else ladders[k][2].insert(0, bj)
        J = ladders[k][2]
        nxt[(p, bi + 1, J[-1] + 1 if p else J[0] - 1)] = k

    # Join ladders across beta-bulges (mkdssp uses unsigned differences).
    def udiff(a, b):
        return a - b if a >= b else float("inf")

    ladders.sort(key=lambda lad: lad[1][0])
    a = 0
    while a < len(ladders):
        b = a + 1
        while b < len(ladders):
            p, I, J = ladders[a]
            p2, I2, J2 = ladders[b]
            if I2[0] >= I[-1] + 6:
                break  # sorted by start, so no later ladder can join
            di = udiff(I2[0], I[-1])
            dj = udiff(J2[0], J[-1]) if p else udiff(J[0], J2[-1])
            if (
                p != p2
                or not nobreak(min(I[0], I2[0]), max(I[-1], I2[-1]))
                or not nobreak(min(J[0], J2[0]), max(J[-1], J2[-1]))
                or di >= 6
                or (I[-1] >= I2[0] and I[0] <= I2[-1])
                or not ((dj < 6 and di < 3) or dj < 3)
            ):
                b += 1
                continue
            ladders[a] = (p, I + I2, J + J2 if p else J2 + J)
            del ladders[b]
        a += 1

    ss = np.zeros(L, dtype=np.int64)
    for _, I, J in ladders:
        code = _E if len(I) > 1 else _B
        for lo, hi in ((I[0], I[-1]), (J[0], J[-1])):
            r = ss[lo : hi + 1]
            r[r != _E] = code

    # n-turns at i: Hbond(i, i + n) within one segment.
    idx = np.arange(L)
    turn = {}
    for k in (3, 4, 5):
        t = np.zeros(L, dtype=bool)
        t[: max(L - k, 0)] = hb(idx[:-k], idx[k:]) & nobreak(idx[:-k], idx[k:])
        turn[k] = t

    def starts(k):  # consecutive n-turns at i - 1 and i
        s = np.zeros(L, dtype=bool)
        s[1:] = turn[k][1:] & turn[k][:-1]
        return s

    def window_any(m, k):  # any(m[i : i + k])
        return _spread(m[::-1].copy(), np, k)[::-1]

    ss[_spread(starts(4), np, 4)] = _H
    for k, code, blocked in ((3, _G, (_H, _B, _E)), (5, _I, (_B, _E, _G))):
        ok = starts(k) & ~window_any(np.isin(ss, blocked), k)
        ss[_spread(ok, np, k)] = code

    # Turns (inside an n-turn) and bends (kappa > 70) on remaining loops.
    in_turn = np.zeros(L, dtype=bool)
    for k in (3, 4, 5):
        in_turn[1:] |= _spread(turn[k], np, k - 1)[:-1]
    ca = x[:, 1]
    v1, v2 = ca[2:-2] - ca[:-4], ca[4:] - ca[2:-2]
    norm2 = (v1 * v1).sum(-1) * (v2 * v2).sum(-1)
    with np.errstate(divide="ignore", invalid="ignore"):
        cos = np.where(norm2 > 0, (v1 * v2).sum(-1) / np.sqrt(norm2), 0)
        kappa = np.degrees(np.arctan2(np.sqrt(1 - cos * cos), cos))
    bend = np.zeros(L, dtype=bool)
    bend[2:-2] = (kappa > 70) & nobreak(idx[:-4], idx[4:])
    loop = ss == _L
    loop[[0, -1]] = False
    ss[loop & in_turn] = _T
    ss[loop & ~in_turn & bend] = _S
    return ss


def _assign8_batched(x, xp, donor_mask):
    _check_shape(x)
    if x.ndim == 3:
        return _assign8(x, xp, donor_mask)
    masks = [None] * len(x) if donor_mask is None else donor_mask
    return np.stack([_assign8(xi, xp, m) for xi, m in zip(x, masks)])


[docs] def get_hbond_map( x: AtomTensor, donor_mask: Optional[torch.Tensor] = None, cutoff: float = DEFAULT_CUTOFF, margin: float = DEFAULT_MARGIN, return_e: bool = False, ) -> torch.Tensor: """Computes PyDSSP's continuous (differentiable) backbone H-bond map. .. code-block:: python import graphein.protein.tensor as gpt from graphein.protein.tensor.dssp import get_hbond_map protein = gpt.Protein().from_pdb_code("1lds") hbmap = get_hbond_map(protein.coords) # (L, L) :param x: Atom coordinates of shape ``(L, A, 3)`` or ``(B, L, A, 3)``. The first four atoms must be ``N, CA, C, O`` (as in Graphein's ``AtomTensor``); remaining atoms are ignored. Hydrogens are placed from backbone geometry. :type x: AtomTensor :param donor_mask: Optional ``(..., L)`` mask of residues that can donate an H-bond (e.g. ``False`` for proline). Default ``None`` (all). :type donor_mask: Optional[torch.Tensor] :param cutoff: Energy cutoff (kcal/mol). Default ``-0.5``. :type cutoff: float :param margin: Smoothing margin around ``cutoff``. Default ``1.0``. :type margin: float :param return_e: Return the raw energy map instead. Default ``False``. :type return_e: bool :return: ``(..., L, L)`` map indexed ``[donor (N-H), acceptor (C=O)]``. :rtype: torch.Tensor """ if donor_mask is not None: donor_mask = torch.as_tensor( donor_mask, dtype=torch.bool, device=x.device ) return _hbond_map( x[..., :4, :], torch, donor_mask, cutoff, margin, return_e )
[docs] def assign_dssp( x: AtomTensor, donor_mask: Optional[torch.Tensor] = None ) -> torch.Tensor: """Assigns 3-state (loop, helix, strand) secondary structure with DSSP. .. code-block:: python import graphein.protein.tensor as gpt from graphein.protein.tensor.dssp import assign_dssp protein = gpt.Protein().from_pdb_code("1lds") ss = assign_dssp(protein.coords) # (L, 3) bool ss_idx = ss.int().argmax(-1) # 0: loop, 1: helix, 2: strand :param x: Atom coordinates of shape ``(L, A, 3)`` or ``(B, L, A, 3)``. The first four atoms must be ``N, CA, C, O``. :type x: AtomTensor :param donor_mask: Optional ``(..., L)`` mask of residues that can donate an H-bond (e.g. ``False`` for proline). Default ``None`` (all). :type donor_mask: Optional[torch.Tensor] :return: Boolean tensor of shape ``(..., L, 3)`` ordered ``(loop, helix, strand)``. As in PyDSSP, a residue may be flagged as both helix and strand; loop is set when it is neither. :rtype: torch.Tensor """ if donor_mask is not None: donor_mask = torch.as_tensor( donor_mask, dtype=torch.bool, device=x.device ) with torch.no_grad(): return _assign(x[..., :4, :], torch, donor_mask)
[docs] def get_hbond_map_np( x: np.ndarray, donor_mask: Optional[np.ndarray] = None, cutoff: float = DEFAULT_CUTOFF, margin: float = DEFAULT_MARGIN, return_e: bool = False, ) -> np.ndarray: """NumPy variant of :func:`get_hbond_map`.""" if donor_mask is not None: donor_mask = np.asarray(donor_mask, dtype=bool) return _hbond_map( np.asarray(x)[..., :4, :], np, donor_mask, cutoff, margin, return_e )
[docs] def assign_dssp_np( x: np.ndarray, donor_mask: Optional[np.ndarray] = None ) -> np.ndarray: """NumPy variant of :func:`assign_dssp`.""" if donor_mask is not None: donor_mask = np.asarray(donor_mask, dtype=bool) return _assign(np.asarray(x)[..., :4, :], np, donor_mask)
[docs] def assign_dssp8( x: AtomTensor, donor_mask: Optional[torch.Tensor] = None ) -> torch.Tensor: """Assigns 8-state DSSP secondary structure, following mkdssp 4.x. Unlike :func:`assign_dssp` (PyDSSP), this uses DSSP's own H-bond model and rules (see :func:`_dssp_hbonds`), including chain breaks (C-N > 2.5 Angstrom), beta-bulges, turns and bends. Polyproline (``P``, new in DSSP 4) is reported as loop. .. code-block:: python import graphein.protein.tensor as gpt from graphein.protein.tensor.dssp import DSSP8_STATES, assign_dssp8 from graphein.protein.resi_atoms import STANDARD_AMINO_ACIDS protein = gpt.Protein().from_pdb_code("1lds") # DSSP never treats proline N as an H-bond donor not_pro = protein.residue_type != STANDARD_AMINO_ACIDS.index("P") ss = assign_dssp8(protein.coords, donor_mask=not_pro) # (L,) "".join(DSSP8_STATES[i] for i in ss) # "--EEEEE-SS..." To match mkdssp, ``x`` should only contain residues with all backbone atoms (mkdssp discards incomplete residues) and prolines should be excluded with ``donor_mask``. :param x: Atom coordinates of shape ``(L, A, 3)`` or ``(B, L, A, 3)``. The first four atoms must be ``N, CA, C, O``. :type x: AtomTensor :param donor_mask: Optional ``(..., L)`` mask of residues that can donate an H-bond (``False`` for proline). Default ``None`` (all). :type donor_mask: Optional[torch.Tensor] :return: ``(..., L)`` long tensor of indices into :data:`DSSP8_STATES`. :rtype: torch.Tensor """ if donor_mask is not None: donor_mask = torch.as_tensor( donor_mask, dtype=torch.bool, device=x.device ) with torch.no_grad(): return torch.as_tensor( _assign8_batched(x[..., :4, :], torch, donor_mask), device=x.device, )
[docs] def assign_dssp8_np( x: np.ndarray, donor_mask: Optional[np.ndarray] = None ) -> np.ndarray: """NumPy variant of :func:`assign_dssp8`.""" if donor_mask is not None: donor_mask = np.asarray(donor_mask, dtype=bool) return _assign8_batched(np.asarray(x)[..., :4, :], np, donor_mask)
# Solvent accessibility, following mkdssp 4.x. The arithmetic mirrors its # float32/float64 mix so that results match it exactly. _ASA_RADII = np.array([1.65, 1.87, 1.76, 1.4], dtype=np.float32) # N CA C O _ASA_RADIUS_SIDE = np.float32(1.8) _ASA_RADIUS_WATER = np.float32(1.4) _ASA_CHUNK = 4096 # atoms per batch of (atom, dot) pairs def _surface_dots(n: int = 200): """mkdssp's Fibonacci sphere: ``(2n + 1, 3)`` unit dots, and the float32 area fraction after ``k`` free dots (mkdssp sums the weight per dot).""" P = 2 * n + 1 i = np.arange(-n, n + 1) phi = np.float32((1 + 5**0.5) / 2) lat = np.arcsin(np.float32(2.0) * i.astype(np.float32) / np.float32(P)) lon = np.fmod(i, np.float64(phi)) * 2 * np.pi / np.float64(phi) lon = lon.astype(np.float32) dots = np.stack( [np.sin(lon) * np.cos(lat), np.cos(lon) * np.cos(lat), np.sin(lat)], -1, ) weight = np.full(P, 4 * np.pi / P, dtype=np.float32) area = np.concatenate([[0], np.cumsum(weight, dtype=np.float32)]) return dots, area.astype(np.float32) def _accessibility(x: np.ndarray, present: np.ndarray) -> np.ndarray: res, atom = np.nonzero(present) if not len(res): return np.zeros(present.shape[0], dtype=np.float32) xyz = x[res, atom].astype(np.float32) r = np.where(atom < 4, _ASA_RADII[np.minimum(atom, 3)], _ASA_RADIUS_SIDE) # atom radius + water, in float64 as mkdssp r_probe = r.astype(np.float64) + np.float64(_ASA_RADIUS_WATER) # Occluding neighbours: centres closer than both probe-extended radii. a, b = ( cKDTree(xyz) .query_pairs(2 * r_probe.max() + 1e-3, output_type="ndarray") .T ) d = xyz[a] - xyz[b] dist2 = d[:, 0] * d[:, 0] + d[:, 1] * d[:, 1] + d[:, 2] * d[:, 2] near = (dist2 < (r_probe[a] + r_probe[b]) ** 2) & (dist2 > 0.0001) a, b, dist2 = a[near], b[near], dist2[near] i, j = np.concatenate([a, b]), np.concatenate([b, a]) # Neighbour table, nearest first (as mkdssp), padded with -1. order = np.lexsort((np.concatenate([dist2, dist2]), i)) i, j = i[order], j[order] first = np.searchsorted(i, np.arange(len(xyz))) degree = np.bincount(i, minlength=len(xyz)) table = np.full((len(xyz), max(degree.max(initial=0), 1)), -1) table[i, np.arange(len(i)) - first[i]] = j r2 = r_probe**2 # Track still-free (atom, dot) pairs and test them against each atom's # k-th nearest neighbour in turn: most dots are buried within a few # neighbours, so the work shrinks quickly (mkdssp exits early likewise). dots, area = _surface_dots() radius = (r + _ASA_RADIUS_WATER).astype(np.float32) n_dots = len(dots) # Dot positions per distinct probe radius, and neighbour offsets b - a. radii, kind = np.unique(radius, return_inverse=True) xx = (dots[None] * radii[:, None, None]).reshape(-1, 3).T.copy() loc = xyz[table] - xyz[:, None] # (M, max degree, 3); padding unused loc = np.moveaxis(loc, -1, 0).reshape(3, -1) width = table.shape[1] n_free = np.zeros(len(xyz), dtype=np.int64) for s in range(0, len(xyz), _ASA_CHUNK): atoms = np.arange(s, min(s + _ASA_CHUNK, len(xyz))) free_here = n_free[s : s + len(atoms)] # view fa = np.repeat(atoms, n_dots) fx = kind[fa] * n_dots + np.tile(np.arange(n_dots), len(atoms)) for k in range(width): nb = table[fa, k] done = nb < 0 # no more neighbours: dot is free free_here += np.bincount(fa[done] - s, minlength=len(atoms)) fa, fx, nb = fa[~done], fx[~done], nb[~done] if not len(fa): break fl = fa * width + k d2 = 0 for c in range(3): diff = xx[c, fx] - loc[c, fl] d2 = diff * diff if c == 0 else d2 + diff * diff free = r2[nb] < d2 fa, fx = fa[free], fx[free] free_here += np.bincount(fa - s, minlength=len(atoms)) atom_area = area[n_free] * radius * radius acc = np.zeros(present.shape[0], dtype=np.float32) np.add.at(acc, res, atom_area) # in order: N, CA, C, O, side chain return acc
[docs] def accessibility(x: AtomTensor, fill_value: float = 1e-5) -> torch.Tensor: """Solvent accessible surface area per residue, following mkdssp 4.x. Uses DSSP's radii (N 1.65, CA 1.87, C 1.76, O 1.4, other heavy atoms 1.8, water 1.4 Angstrom) and its 401-dot Fibonacci sphere. Every heavy atom in ``x`` occludes, so to match mkdssp ``x`` should hold only protein residues with complete backbones (it ignores ligands, waters and incomplete residues). .. code-block:: python import graphein.protein.tensor as gpt from graphein.protein.tensor.dssp import accessibility protein = gpt.Protein().from_pdb_code("1lds") asa = accessibility(protein.coords) # (L,) Angstrom^2 :param x: Atom coordinates of shape ``(L, A, 3)``. The first four atoms must be ``N, CA, C, O``; any others are treated as side chain. :type x: AtomTensor :param fill_value: Value marking missing atoms. Default ``1e-5``. :type fill_value: float :return: ``(L,)`` accessible surface area in square Angstrom. :rtype: torch.Tensor """ return torch.as_tensor( accessibility_np(x.detach().cpu().numpy(), fill_value), device=x.device, )
[docs] def accessibility_np(x: np.ndarray, fill_value: float = 1e-5) -> np.ndarray: """NumPy variant of :func:`accessibility`.""" x = np.asarray(x) _check_shape(x) if x.ndim != 3: raise ValueError("accessibility expects a single protein (L, A, 3)") return _accessibility(x, x[..., 0] != fill_value)