biotite.structure.superimpose

biotite.structure.superimpose(fixed, mobile, atom_mask=None)[source]

Superimpose structures onto each other, minimizing the RMSD between them. 12.

More precisely, the mobile structure is rotated and translated onto the fixed structure.

Parameters
fixedAtomArray, shape(n,) or AtomArrayStack, shape(m,n) or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float

The fixed structure(s). Alternatively coordinates can be given.

mobile: AtomArray, shape(n,) or AtomArrayStack, shape(m,n) or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float

The structure(s) which is/are superimposed on the fixed structure. Each atom at index i in mobile must correspond the atom at index i in fixed to obtain correct results. Furthermore, if both fixed and mobile are AtomArrayStack objects, they must have the same number of models. Alternatively coordinates can be given.

atom_mask: ndarray, dtype=bool, optional

If given, only the atoms covered by this boolean mask will be considered for superimposition. This means that the algorithm will minimize the RMSD based on the covered atoms instead of all atoms. The returned superimposed structure will contain all atoms of the input structure, regardless of this parameter.

Returns
fittedAtomArray or AtomArrayStack or ndarray, shape(n,), dtype=float or ndarray, shape(m,n), dtype=float

A copy of the mobile structure(s), superimposed on the fixed structure(s). Only coordinates are returned, if coordinates were given in mobile.

transformationAffineTransformation

The affine transformation(s) that were applied on mobile. AffineTransformation.apply() can be used to transform another AtomArray in the same way.

See also

superimpose_without_outliers

Superimposition with outlier removal

superimpose_homologs

Superimposition of homologous structures

Notes

The transformation can come in handy, in case you want to superimpose two structures with different amount of atoms. Often the two structures need to be filtered in order to obtain the same size and annotation arrays. After superimposition the transformation can be applied on the original structure using AffineTransformation.apply().

References

1

W. Kabsch, “A solution for the best rotation to relate two sets of vectors,” Acta Crystallographica Section A: Crystal Physics, Diffraction, Theoretical and General Crystallography, vol. 32, pp. 922–923, September 1976. doi: 10.1107/S0567739476001873

2

W. Kabsch, “A discussion of the solution for the best rotation to relate two sets of vectors,” Acta Crystallographica Section A: Crystal Physics, Diffraction, Theoretical and General Crystallography, vol. 34, pp. 827–828, September 1978. doi: 10.1107/S0567739478001680

Examples

At first two models of a structure are taken and one of them is randomly rotated/translated. Consequently the RMSD is quite large:

>>> array1 = atom_array_stack[0]
>>> array2 = atom_array_stack[1]
>>> array2 = translate(array2, [1,2,3])
>>> array2 = rotate(array2, [1,2,3])
>>> print("{:.3f}".format(rmsd(array1, array2)))
11.260

RMSD decreases after superimposition of only CA atoms:

>>> array2_fit, transformation = superimpose(
...     array1, array2, atom_mask=(array2.atom_name == "CA")
... )
>>> print("{:.3f}".format(rmsd(array1, array2_fit)))
1.961

RMSD is even lower when all atoms are considered in the superimposition:

>>> array2_fit, transformation = superimpose(array1, array2)
>>> print("{:.3f}".format(rmsd(array1, array2_fit)))
1.928