antibody_utils.geometry¶

Structural geometry of antibodies: superposition, RMSD and VH/VL orientation.

class antibody_utils.geometry.OrientationAngles(hl, hc1, lc1, hc2, lc2, dc)[source]¶

Bases: object

The ABangle measures of an Fv.

hl¶: The torsion angle HL, in degrees, from -180 to 180.

hc1¶: The bend angle HC1, in degrees.

lc1¶: The bend angle LC1, in degrees.

hc2¶: The twist angle HC2, in degrees.

lc2¶: The twist angle LC2, in degrees.

dc¶: The distance dc between the domains, in angstroms.

as_dict()[source]¶

The measures, keyed by the symbols used in the paper and by legacy ABDB.

Return type:: dict[str, float]
Returns:: The measures, keyed “HL”, “HC1”, “LC1”, “HC2”, “LC2” and “dc”.

>>> OrientationAngles(-60.0, 70.0, 120.0, 110.0, 80.0, 16.0).as_dict()
{'HL': -60.0, 'HC1': 70.0, 'LC1': 120.0, 'HC2': 110.0, 'LC2': 80.0, 'dc': 16.0}

class antibody_utils.geometry.Superposition(rotation, translation, rmsd)[source]¶

Bases: object

A rigid-body transformation that superposes one set of points on another.

rotation¶: The 3 x 3 rotation matrix.

translation¶: The translation, applied after the rotation.

rmsd¶: The RMSD between the superposed points and the target points.

apply(coordinates)[source]¶

Transform coordinates: rotate them, then translate them.

Parameters:: coordinates (ArrayLike) – A point, or an n x 3 array of points.
Return type:: ndarray
Returns:: The transformed coordinates, in the same shape.

antibody_utils.geometry.abangle(fv)[source]¶

Calculate the ABangle orientation measures of an Fv.

Parameters:: fv (Fv) – The Fv, numbered in the Chothia or IMGT scheme.
Return type:: OrientationAngles
Returns:: The angles and distance.
Raises:: ValueError – If the Fv is numbered in another scheme, or either domain has CA atoms at fewer than three core positions.

antibody_utils.geometry.orientation_rmsd(a, b, *, definition)[source]¶

Measure how differently two Fvs orient their VH and VL domains.

The VH frameworks of a and b are superposed, and a’s VL framework is moved with them. Separately, the VL frameworks are superposed. The result is the RMSD between the two placements of a’s VL framework (CA atoms). This follows legacy ABDB’s calculate_orientation_rmsd.

The measure is not quite symmetric: swapping a and b can give a slightly different value, so consider averaging both.

Parameters:

a (Fv) – An Fv.
b (Fv) – Another Fv, numbered in the same scheme.
definition (Definition | str) – The region definition that delimits the frameworks.

Return type:

float

Returns:

The orientation RMSD, in angstroms.

Raises:

ValueError – If the Fvs are numbered in different schemes, or share fewer than three framework CA atoms in either domain.

antibody_utils.geometry.region_rmsd(a, b, regions=('fv',), *, definition, atoms=('CA',), superposed=True)[source]¶

Calculate the RMSD between antibody structures over chosen regions.

Atoms are matched by chain type, numbered position and name, and only those present in both structures are compared. Regions are assigned as by antibody_utils.structure.AntibodyChain.region_residues.

Parameters:

a (AntibodyChain | Fv) – An antibody chain or Fv.
b (AntibodyChain | Fv) – Another, numbered in the same scheme.
regions (Iterable[Region | str]) – The regions, or region groups such as “cdrs”, to compare. By default, the whole variable domain (“fv”).
definition (Definition | str) – The region definition to apply.
atoms (Iterable[str]) – The names of the atoms to compare. By default, CA atoms only.
superposed (bool) – Superpose a on b over the selected atoms first, as is usual. If false, compare the coordinates as they are.

Return type:

float

Returns:

The RMSD, in angstroms.

Raises:

ValueError – If the structures are numbered in different schemes, have no selected atoms in common, or have fewer than three when superposing, or a region name is not recognised.

antibody_utils.geometry.rmsd(a, b)[source]¶

Calculate the RMSD between two sets of equivalent points, as they are.

Parameters:

a (ArrayLike) – An n x 3 array of points.
b (ArrayLike) – The equivalent n x 3 array of points.

Return type:

float

Returns:

The root-mean-square deviation.

Raises:

ValueError – If the arrays are not n x 3 arrays of the same shape, or are empty.

>>> rmsd([[0, 0, 0], [1, 0, 0]], [[0, 0, 1], [1, 0, 1]])
1.0

antibody_utils.geometry.superpose(mobile, target)[source]¶

Find the superposition of one set of points on another (Kabsch).

Parameters:

mobile (ArrayLike) – An n x 3 array of points, to be moved.
target (ArrayLike) – The equivalent n x 3 array of points, held fixed.

Return type:

Superposition

Returns:

The rotation and translation that minimise the RMSD between the moved mobile points and the target points.

Raises:

ValueError – If the arrays are not n x 3 arrays of the same shape, or hold fewer than three points.

>>> import numpy as np
>>> target = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]])
>>> mobile = target @ [[0, -1, 0], [1, 0, 0], [0, 0, 1]] + [5, 5, 5]
>>> superposition = superpose(mobile, target)
>>> round(superposition.rmsd, 6)
0.0
>>> np.allclose(superposition.apply(mobile), target)
True

Modules

`orientation`	Measure the relative orientation of the VH and VL domains with ABangle.
`superposition`	Superpose antibody structures and measure their RMSD.