# biotite.structure.orient_principal_components¶

biotite.structure.orient_principal_components(atoms, order=None)[source]

Translate and rotate the atoms to be centered at the origin with the principal axes aligned to the Cartesian axes, as specified by the order parameter. By default, x, y, z.

By default, the resulting coordinates have the highest variance in the x-axis and the lowest variance on the z-axis. Setting the order parameter will change the direction of the highest variance. For example, `order=(2, 1, 0)` results in highest variance along the z-axis and lowest along the x-axis.

Parameters
atomsAtomArray or ndarray, shape=(n,3)

The atoms of which the coordinates are transformed. The coordinates can be directly provided as `ndarray`.

orderarray-like, length=3

The order of decreasing variance. Setting order to `(2, 0, 1)` results in highest variance along the y-axis and lowest along the x-axis. Default = `(0, 1, 2)`.

Returns
AtomArray or ndarray, shape=(n,3)

The atoms with coordinates centered at the orgin and aligned with xyz axes.

Examples

Align principal components to xyz axes (default), or specify the order of variance.

```>>> print("original variance =", atom_array.coord.var(axis=0))
original variance = [26.517 20.009  9.325]
>>> moved = orient_principal_components(atom_array)
>>> print("moved variance =", moved.coord.var(axis=0))
moved variance = [28.906 18.495  8.450]
>>> # Note the increase in variance along the x-axis
>>> # Specifying the order keyword changes the orientation
>>> moved_z = orient_principal_components(atom_array, order=(2, 1, 0))
>>> print("moved (zyx) variance =", moved_z.coord.var(axis=0))
moved (zyx) variance = [ 8.450 18.495 28.906]
```