"""Utilities for computing various protein angles."""
# 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 functools import lru_cache
import numpy as np
from loguru import logger as log
from graphein.utils.dependencies import import_message
from ..resi_atoms import ATOM_NUMBERING_MODIFIED, CHI_ANGLES_ATOMS
from .types import AtomTensor, CoordTensor, DihedralTensor, TorsionTensor
try:
from torch_geometric.utils import to_dense_batch
except ImportError:
message = import_message(
"graphein.protein.tensor.angles",
"torch_geometric",
"pyg",
pip_install=True,
)
try:
import torch
import torch.nn.functional as F
except ImportError:
message = import_message(
"graphein.protein.tensor.angles",
"torch",
conda_channel="pytorch",
pip_install=True,
)
log.warning(message)
# Row of each residue type in the chi atom table; the extra last row is for
# residues without chi angles
_CHI_ROWS = {res: i for i, res in enumerate(CHI_ANGLES_ATOMS)}
_NO_CHI = len(_CHI_ROWS)
@lru_cache(maxsize=None)
def _chi_atom_table(
device: torch.device,
) -> tuple[torch.Tensor, torch.Tensor]:
"""Returns the atom indices of the (up to) four chi angles of each residue
type (``(num types + 1) x 4 x 4``) and a mask of which chi angles exist
(``(num types + 1) x 4``). Rows follow ``_CHI_ROWS``.
"""
index = torch.zeros(_NO_CHI + 1, 4, 4, dtype=torch.long)
mask = torch.zeros(_NO_CHI + 1, 4, dtype=torch.bool)
for res, row in _CHI_ROWS.items():
for k, group in enumerate(CHI_ANGLES_ATOMS[res]):
index[row, k] = torch.tensor(
[ATOM_NUMBERING_MODIFIED[a] for a in group]
)
mask[row, k] = True
return index.to(device), mask.to(device)
[docs]
def sidechain_torsion(
coords: AtomTensor,
res_types: list[str],
rad: bool = True,
embed: bool = False,
return_mask: bool = False,
) -> TorsionTensor | tuple[TorsionTensor, torch.Tensor]:
"""
Computes sidechain torsion angles for a protein.
Atom groups used to define each chi angle are specified in
:ref:`graphein.protein.resi_atoms.CHI_ANGLES_ATOMS`. Missing chi angles
are ``0`` (``[1, 0]`` if ``embed=True``) and ``False`` in the mask.
:param coords: Tensor of shape ``(L, N, 3)`` where ``L`` is the number of
residues, ``N`` is the number of atoms per residue (Default is 37;
problems may occur with differing selections). With ``N = 38``,
selenocysteine (``SEC``) has a chi angle (``SE`` at index 37).
:type coords: AtomTensor
:param res_types: List of three-letter residue types.
:type res_types: List[str]
:param rad: If ``True``, returns angles in radians, else in degrees.
Defaults to ``True``.
:type rad: bool, optional
:param embed: If ``True``, returns ``[cos(chi1), sin(chi1), ...]``
(``L x 8``). Defaults to ``False``.
:type embed: bool, optional
:param return_mask: Whether to also return a boolean mask of the chi angles
that exist, defaults to ``False``.
:type return_mask: bool, optional
:return: Torsion tensor of shape ``(L, 4)`` (``(L, 8)`` if ``embed=True``)
and, if ``return_mask=True``, the mask of the same shape.
:rtype: Union[TorsionTensor, Tuple[TorsionTensor, torch.Tensor]]
"""
if embed and not rad:
raise ValueError("Cannot embed torsion angles in degrees.")
for res in sorted(set(res_types) - _CHI_ROWS.keys()):
log.warning(
f"Can't determine chi angle groups for non-standard residue: {res}. These will be set to 0"
)
# Without Se atoms (38th atom type), SEC has no chi angles
no_chi = {"PYL"} if coords.shape[1] == 38 else {"PYL", "SEC"}
rows = torch.tensor(
[
_NO_CHI if res in no_chi else _CHI_ROWS.get(res, _NO_CHI)
for res in res_types
],
device=coords.device,
)
index, mask = _chi_atom_table(coords.device)
index, mask = index[rows], mask[rows]
# (L, 4 chi angles, 4 atoms, 3)
chi_coords = coords[
torch.arange(len(rows), device=coords.device).view(-1, 1, 1), index
]
angles = _dihedral_angle(*chi_coords.unbind(2)).masked_fill(~mask, 0.0)
if not rad:
angles = angles * 180 / torch.pi
if embed:
angles = angle_to_unit_circle(angles)
mask = mask.repeat_interleave(2, dim=1)
return (angles, mask) if return_mask else angles
def chi1():
raise NotImplementedError
def chi2():
raise NotImplementedError
def chi3():
raise NotImplementedError
def chi4():
raise NotImplementedError
[docs]
def kappa(
x: AtomTensor | CoordTensor,
batch: torch.Tensor | None = None,
rad: bool = True,
sparse: bool = True,
ca_idx: int = 1,
embed: bool = False,
) -> torch.Tensor:
"""
Computes virtual bond angle (bend angle) defined by three Ca atoms of
residues ``i-2``, ``i`` and ``i+2``. The first and last two angles are zero
padded.
.. seealso::
:meth:`graphein.protein.tensor.angles.alpha`
:meth:`graphein.protein.tensor.angles.dihedrals`
:param x: Tensor of atomic positions or tensor of CA positions.
:type x: Union[AtomTensor, CoordTensor]
:param ca_idx: If ``x`` is an AtomTensor, this is the index of the CA atoms
in dimension 1, defaults to 1
:type ca_idx: int, optional
:return: Tensor of bend angles
:rtype: torch.Tensor
"""
if not rad and embed:
raise ValueError("Cannot embed kappa angles in degrees.")
if x.ndim == 3:
x = x[:, ca_idx, :]
if batch is None:
batch = torch.zeros(x.shape[0], dtype=torch.long, device=x.device)
x, mask = to_dense_batch(x, batch)
ca_prev = x[:, :-4, :]
ca = x[:, 2:-2, :]
ca_next = x[:, 4:, :]
angles = np.pi - to_ang(
# ca_next.view(-1, 3), ca.view(-1, 3), ca_prev.view(-1, 3)
ca_next,
ca,
ca_prev,
)
# Zero pad first two and last two angles
angles = F.pad(angles, (2, 2))
if not rad:
angles = torch.rad2deg(angles)
if sparse:
angles = angles[mask]
if embed:
angles = torch.stack([torch.cos(angles), torch.sin(angles)], dim=-1)
return angles
[docs]
def alpha(
x: AtomTensor | CoordTensor,
batch: torch.Tensor | None = None,
sparse: bool = True,
rad: bool = True,
ca_idx: int = 1,
embed: bool = True,
) -> torch.Tensor:
"""
Computes virtual bond dihedral angle defined by four Ca atoms of residues
``i-1``, ``i``, ``i+1``, ``i+2``. The first angle and last two angles are
zero padded.
.. seealso::
:meth:`graphein.protein.tensor.angles.kappa`
:meth:`graphein.protein.tensor.angles.dihedrals`
:param x: Tensor of atomic positions or tensor of CA positions.
:type x: Union[AtomTensor, CoordTensor]
:param batch: Tensor of batch indices, defaults to ``None``.
:type batch: Optional[torch.Tensor], optional
:param sparse: Whether or not to return the output in sparse or dense format
, defaults to ``True``.
:type sparse: bool, optional
:param rad: _description_, defaults to ``True``.
:type rad: bool, optional
:param ca_idx: If ``x`` is an AtomTensor, this argument specifies the index
of the CA atoms in dimension 1, defaults to ``1``.
:type ca_idx: int, optional
:param embed: Whether or not to embed the angles on the unit circle,
defaults to ``True``.
:type embed: bool, optional
:return: Tensor of dihedral angles
:rtype: torch.Tensor
"""
if not rad and embed:
raise ValueError(
"Cannot embed angles on unit circle if not in radians."
)
if x.ndim == 3:
x = x[:, ca_idx, :]
if batch is None:
batch = torch.zeros(x.shape[0], dtype=torch.long, device=x.device)
x, mask = to_dense_batch(x, batch)
ca_prev = x[:, :-3, :]
ca = x[:, 1:-2, :]
ca_next = x[:, 2:-1, :]
ca_next_next = x[:, 3:, :]
angles = _dihedral_angle(ca_prev, ca, ca_next, ca_next_next)
angles = F.pad(angles, (1, 2))
if not rad:
angles = torch.rad2deg(angles)
if sparse:
angles = angles[mask]
if embed:
angles = torch.stack([torch.cos(angles), torch.sin(angles)], dim=-1)
return angles
[docs]
def to_ang(a: CoordTensor, b: CoordTensor, c: CoordTensor) -> torch.Tensor:
"""Compute the angle between vectors ``ab`` and ``bc``.
:param a: Coordinates of point ``a`` ``(L x 3)``.
:type a: graphein.protein.tensor.types.CoordTensor
:param b: Coordinates of point ``b`` ``(L x 3)``.
:type b: graphein.protein.tensor.types.CoordTensor
:param c: Coordinates of point ``c`` ``(L x 3)``.
:type c: graphein.protein.tensor.types.CoordTensor
:return: Angle between vectors ab and bc in radians.
:rtype: torch.Tensor
"""
if a.ndim == 1:
a = a.unsqueeze(0)
if b.ndim == 1:
b = b.unsqueeze(0)
if c.ndim == 1:
c = c.unsqueeze(0)
ba = b - a
bc = b - c
return torch.acos(
(ba * bc).sum(dim=-1)
/ (torch.norm(ba, dim=-1) * torch.norm(bc, dim=-1))
)
# @torch.jit.script
[docs]
def get_backbone_bond_lengths(x: AtomTensor) -> torch.Tensor:
"""
Compute the bond lengths between backbone atoms.
Returns the a tensor of shape ``(N, 3)`` where ``N`` is the number of
residues in protein. Dimension 1 contains the bond lengths between Ca and
C, C and N, and N and Ca.
:param x: Tensor of atomic positions.
:type x: AtomTensor
:return: Tensor of backbone bond lengths.
:rtype: torch.Tensor
"""
n, a, c = x[:, 0, :], x[:, 1, :], x[:, 2, :]
n_a = torch.norm(n - a, dim=1)
a_c = torch.norm(a - c, dim=1)
c_n = torch.norm(c[:-1, :] - n[1:, :], dim=1)
c_n = torch.cat([c_n, torch.tensor([1.32], device=x.device)])
# Fill missing values with ideal bond lengths
a_c = torch.nan_to_num(a_c, nan=1.523)
c_n = torch.nan_to_num(c_n, nan=1.320)
n_a = torch.nan_to_num(n_a, nan=1.458)
return torch.stack([a_c, c_n, n_a], dim=1)
# @torch.jit.script
[docs]
def get_backbone_bond_angles(x: AtomTensor) -> torch.Tensor:
"""Compute the bond angles between backbone atoms:
``[C-N-Ca, N-Ca-C, Ca-C,N]``.
.. seealso:: :meth:`graphein.protein.tensor.angles.to_ang`
:param x: Tensor of atomic positions.
:type x: AtomTensor
:return: Tensor of backbone bond angles ``[L x 3]``.
:rtype: torch.Tensor
"""
n, a, c = x[:, 0, :], x[:, 1, :], x[:, 2, :]
n_a_c = to_ang(n, a, c)
a_c_n = to_ang(a[:-1, :], c[:-1, :], n[1:, :])
c_n_a = to_ang(c[:-1, :], n[1:, :], a[1:, :])
a_c_n = torch.cat([a_c_n, torch.tensor([2.0], device=x.device)])
c_n_a = torch.cat([c_n_a, torch.tensor([2.1], device=x.device)])
# Fill missing values with ideal bond angles
c_n_a = torch.nan_to_num(c_n_a, nan=2.124)
n_a_c = torch.nan_to_num(n_a_c, nan=1.941)
a_c_n = torch.nan_to_num(a_c_n, nan=2.028)
# This (below line) works!!, Orig AlQ order
return torch.stack([c_n_a, n_a_c, a_c_n], dim=1)
[docs]
def angle_to_unit_circle(x: torch.Tensor) -> torch.Tensor:
"""Encodes an angle in radians to a unit circle.
I.e. returns a tensor or the form:
``[cos(x1), sin(x1), cos(x2), sin(x2), ...]``.
:param x: Tensor of angles in radians.
:type x: torch.Tensor
:return: Tensor of angles encoded on a unit circle.
:rtype: torch.Tensor
"""
if x.ndim == 1:
x = x.unsqueeze(0)
return torch.stack([torch.cos(x), torch.sin(x)], dim=-1).flatten(-2)
def _dihedral_angle(
a: torch.Tensor,
b: torch.Tensor,
c: torch.Tensor,
d: torch.Tensor,
eps: float = 1e-7,
) -> torch.Tensor:
"""computes dihedral angle between 4 points.
:param a: First point. Shape: ``(L x 3)``
:type a: torch.Tensor
:param b: Second point. Shape: ``(L x 3)``
:type b: torch.Tensor
:param c: Third point. Shape: ``(L x 3)``
:type c: torch.Tensor
:param d: Fourth point. Shape: ``(L x 3)``
:type d: torch.Tensor
:param eps: Jitter value, defaults to 1e-7
:type eps: float, optional
:return: Tensor of dihedral angles in radians.
:rtype: torch.Tensor
"""
bc = F.normalize(b - c, dim=-1)
n1 = torch.linalg.cross(F.normalize(a - b, dim=-1), bc)
n2 = torch.linalg.cross(bc, F.normalize(c - d, dim=-1))
x = (n1 * n2).sum(dim=-1)
x = torch.clamp(x, -1 + eps, 1 - eps)
x[x.abs() < eps] = eps
y = (torch.linalg.cross(n1, bc) * n2).sum(dim=-1)
return torch.atan2(y, x)
def dihedrals(
coords: torch.Tensor,
batch: torch.Tensor | None = None,
rad: bool = True,
sparse: bool = True,
embed: bool = True,
n_idx: int = 0,
ca_idx: int = 1,
c_idx: int = 2,
) -> DihedralTensor:
length = coords.shape[0]
if embed and not rad:
raise ValueError(
"Cannot embed angles in degrees. Use embed=True and rad=True."
)
if batch is None:
batch = torch.zeros(length, device=coords.device).long()
X, mask = to_dense_batch(coords, batch)
C_curr = X[:, :-1, c_idx, :]
N_curr = X[:, :-1, n_idx, :]
Ca_curr = X[:, :-1, ca_idx, :]
N_next = X[:, 1:, n_idx, :]
Ca_next = X[:, 1:, ca_idx, :]
C_next = X[:, 1:, c_idx, :]
# phi, psi, omega; the first phi and last psi/omega are zero
angles = X.new_zeros(*X.shape[:2], 3)
angles[:, 1:, 0] = _dihedral_angle(C_curr, N_next, Ca_next, C_next)
angles[:, :-1, 1] = _dihedral_angle(N_curr, Ca_curr, C_curr, N_next)
angles[:, :-1, 2] = _dihedral_angle(Ca_curr, C_curr, N_next, Ca_next)
if not rad:
angles = angles * 180 / np.pi
if sparse:
angles = angles[mask]
if embed:
angles = angle_to_unit_circle(angles)
return angles
[docs]
def dihedrals_to_rad(
x_dihedrals: DihedralTensor,
concat: bool = False,
) -> DihedralTensor | tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
"""
Converts dihedrals to radians.
:param x_dihedrals: Dihedral tensor of shape ``(L, 6)``.
:type x_dihedrals: DihedralTensor
:param concat: Whether to concatenate the angles into a single tensor, or
to return a tuple of tensors (``phi``, ``psi``, ``omega``), defaults to
``False``.
:type concat: bool, optional
:return: Dihedral tensor of shape ``(L, 3)`` or a tuple of tensors
:rtype: Union[DihedralTensor, Tuple[torch.Tensor, torch.Tensor, torch.Tensor]]
"""
angles = torch.atan2(x_dihedrals[:, 1::2], x_dihedrals[:, 0::2])
return angles if concat else angles.unbind(1)
[docs]
def torsion_to_rad(
x_torsion: TorsionTensor,
concat: bool = True,
) -> (
TorsionTensor
| tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]
):
"""
Converts sidechain torsions in
``(sin(chi1), sin(chi1), cos(chi2), sin(chi2), ...)`` format to radians.
:param x_torsion: Torsion tensor of shape ``(L, 8)``.
:type x_torsion: graphein.protein.tensor.types.TorsionTensor
:param concat: Whether to concatenate the torsions into a single tensor.
If ``False``, this function returns a tuple of tensors for chi1-4
, defaults to ``True``.
:type concat: bool
:return: Torsion tensor of shape ``(L, 4)`` if ``concat=True``, otherwise
a tuple of tensors for chi1-4 in radians.
:rtype: Union[graphein.protein.tensor.types.TorsionTensor,
Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]]
"""
angles = torch.atan2(x_torsion[:, 1::2], x_torsion[:, 0::2])
return angles if concat else angles.unbind(1)