antibody_utils.geometry.superposition

Superpose antibody structures and measure their RMSD.

Coordinates are compared atom by atom at equivalent numbered positions, so the structures being compared must be numbered in the same scheme. Only positions present in both structures are used.

Functions

orientation_rmsd(a, b, *, definition)

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

region_rmsd(a, b[, regions, atoms, superposed])

Calculate the RMSD between antibody structures over chosen regions.

rmsd(a, b)

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

superpose(mobile, target)

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

Classes

Superposition(rotation, translation, rmsd)

A rigid-body transformation that superposes one set of points on another.
class antibody_utils.geometry.superposition.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.superposition.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.superposition.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.superposition.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.superposition.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