geometry
Utility functions for computing 3D geometry of protein structures.
This module contains the following functions:
angle(a, b, c, to_degree=False): Compute planar angles between three points.dihedral(a, b, c, d, to_degree=False): Compute dihedral angle between four points.place_fourth_atom(a, b, c, length, planar, dihedral): Place a fourth atom X given three atoms (A, B and C) and the bond length (CX), planar angle (XCB), and dihedral angle (XCB vs ACB).
angle(a, b, c, to_degree=False)
Compute planar angles (0 ~ pi) between three (array of) points a, b and c.
Note
The planar angle is computed as the angle between the vectors ab and bc
using the dot product followed by torch.arccos. If to_degree is False, the
output is in radians between 0 and pi. Otherwise, the output is in degrees
between 0 and 180.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a |
Union[np.ndarray, torch.Tensor]
|
3D coordinates of atom a. Shape: (n, 3) |
required |
b |
Union[np.ndarray, torch.Tensor]
|
3D coordinates of atom b. Shape: (n, 3) |
required |
c |
Union[np.ndarray, torch.Tensor]
|
3D coordinates of atom c. Shape: (n, 3) |
required |
to_degree |
bool
|
Whether to return angles in degree. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
Union[np.array, torch.Tensor]
|
Planar angle between three points. Shape: (n,) |
dihedral(a, b, c, d, to_degree=False)
Compute dihedral angle (-pi ~ pi) between (array of) four points a, b, c and d.
Note
The dihedral angle is the angle in the clockwise direction of the fourth atom compared to the first atom, while looking down the axis of the second to the third.
The dihedral angle is computed as the angle between the plane defined by
vectors ba and bc and the plane defined by vectors bc and cd.
In short, the dihedral angle (theta) is obtained by first computing cos(theta) and sin(theta)
using dot and cross products of the normal vectors of the two planes, and then computing
theta using torch.atan2.
Tip
Here is a nice explanation of the computation of dihedral angles: https://leimao.github.io/blog/Dihedral-Angles
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a |
Union[np.ndarray, torch.Tensor]
|
3D coordinates of atom a (shape: (n, 3)) |
required |
b |
Union[np.ndarray, torch.Tensor]
|
3D coordinates of atom b (shape: (n, 3)) |
required |
c |
Union[np.ndarray, torch.Tensor]
|
3D coordinates of atom c (shape: (n, 3)) |
required |
d |
Union[np.ndarray, torch.Tensor]
|
3D coordinates of atom d (shape: (n, 3)) |
required |
to_degree |
bool
|
Whether to return dihedrals in degree. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
Union[np.array, torch.Tensor]
|
Dihedral angle between four points. (shape: (n,)) |
fix_chirality(coords)
Fix chirality of the backbone so that all the phi dihedrals are negative.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
coords |
np.array
|
Coordinates of backbone atoms (N, CA, C) (shape: (3, L, 3)). |
required |
Returns:
| Type | Description |
|---|---|
np.array
|
np.array: Fixed coordinates. |
gram_schmidt(a, b, c)
Given three xyz coordinates, compute the orthonormal basis using Gram-Schmidt process. Specifically, compute the orthonormal basis of the plane defined by vectors (c - b) and (a - b).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a |
torch.Tensor
|
xyz coordinates of three atoms (shape: (*, 3)) |
required |
b |
torch.Tensor
|
xyz coordinates of three atoms (shape: (*, 3)) |
required |
c |
torch.Tensor
|
xyz coordinates of three atoms (shape: (*, 3)) |
required |
Returns:
| Type | Description |
|---|---|
torch.FloatTensor
|
Orthonormal basis of the plane defined by vectors |
ideal_backbone_coordinates(size, include_cb=False)
Return a batch of ideal backbone coordinates (N, Ca, C and optionally Cb) with a given batch size and number of residues.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
size |
Union[Tuple[int], List[int]]
|
|
required |
include_cb |
bool
|
Whether to include Cb atom in the frame. Defaults to False. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
Union[np.array, torch.Tensor]
|
A batch of ideal backbone coordinates (N, Ca, C and optionally Cb). |
|
Shape |
Union[np.array, torch.Tensor]
|
(batch_size, num_residues, 3, 3) if |
ideal_local_frame()
Compute ideal local coordinate system of a residue centered at N
Returns:
| Type | Description |
|---|---|
Union[np.array, torch.Tensor]
|
Local coordinate system of a residue centered at N, with atom order N, CA, C, CB (shape: (4, 3)) |
initialize_backbone_with_mds(dist_mat, max_iter=500)
Given a pairwise distance matrix of backbone atoms, initialize the coordinates of the backbone atoms using multidimensional scaling.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dist_mat |
np.array
|
Pairwise distance matrix of backbone atoms (shape: (3, 3, L, L)). |
required |
max_iter |
int
|
Maximum number of iterations for MDS. Defaults to 500. |
500
|
Returns:
| Type | Description |
|---|---|
np.array
|
np.array: Coordinates of backbone atoms (N, CA, C) (shape: (3, L, 3)). |
place_fourth_atom(a, b, c, length, planar, dihedral)
Place a fourth atom X given three atoms (A, B and C) and the bond length (CX), planar angle (XCB), and dihedral angle (XCB vs ACB).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a |
np.array
|
3D coordinates of atom a (shape: (n, 3)) |
required |
b |
np.array
|
3D coordinates of atom b (shape: (n, 3)) |
required |
c |
np.array
|
3D coordinates of atom c (shape: (n, 3)) |
required |
length |
np.array
|
Length of the bond between atom c and the new atom (shape: (n, 1)) i.e., bond length CX |
required |
planar |
np.array
|
Planar angle between the new atom and the bond between atom c and the new atom (shape: (n, 1)) i.e., angle XCB |
required |
dihedral |
np.array
|
Dihedral angle between the new atom and the plane defined by atoms a, b, and c (shape: (n, 1)) i.e., dihedral angle between planes XCB and ACB |
required |
Returns:
| Type | Description |
|---|---|
Union[np.array, torch.Tensor]
|
3D coordinates of the new atom X (shape: (n, 3)) |
reconstruct_backbone_distmat_from_interresidue_geometry(d_cb, omega, theta, phi, mask=None, chain_breaks=None)
Reconstruct the backbone distance matrix from interresidue geometry
including Cb distance matrix (d_cb), Ca-Cb-Ca'-Cb' dihedral (omega),
N-Ca-Cb-Cb' dihedral (theta), and Ca-Cb-Cb' planar angle (phi).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
d_cb |
torch.Tensor
|
Cb distance matrix (shape: (L, L)) |
required |
omega |
torch.Tensor
|
Ca-Cb-Ca'-Cb' dihedral matrix (shape: (L, L)) |
required |
theta |
torch.Tensor
|
N-Ca-Cb-Cb' dihedral matrix (shape: (L, L)) |
required |
phi |
torch.Tensor
|
Ca-Cb-Cb' planar angle matrix (shape: (L, L)) |
required |
mask |
torch.Tensor
|
Mask for valid residue pairs, i.e., pairs of residues whose distance can be reconstructed from interresidue geometry (shape: (L, L)) |
None
|
chain_breaks |
list
|
List of chain breaks, i.e., indices of residues that are not in the same chain with the next one. |
None
|
Returns:
| Type | Description |
|---|---|
torch.Tensor
|
Backbone distance matrix representing the distance between N, Ca, C atoms between residues (shape: (3, 3, L, L)) |