org.biojava.nbio.structure

Class Calc

java.lang.Object

org.biojava.nbio.structure.Calc

public class Calc
extends Object

Utility operations on Atoms, AminoAcids, Matrices, Point3d, etc.

Currently the coordinates of an Atom are stored as an array of size 3 (double[3]). It would be more powerful to use Point3d from javax.vecmath. Overloaded methods for Point3d operations exist in the CalcPoint Class.

Since:

1.4

Version:

%I% %G%

Author:

Andreas Prlic, Aleix Lafita

Constructor Summary

Constructors

Constructor and Description
Calc()

Method Summary

Modifier and Type	Method and Description
static Atom	add(Atom a, Atom b) add two atoms ( a + b).
static double	amount(Atom a) Gets the length of the vector (2-norm)
static double	angle(Atom a, Atom b) Gets the angle between two vectors
static javax.vecmath.Point3d[]	atomsToPoints(Atom[] atoms) Convert an array of atoms into an array of vecmath points
static List<javax.vecmath.Point3d>	atomsToPoints(Collection<Atom> atoms) Convert an array of atoms into an array of vecmath points
static double	calcRotationAngleInDegrees(Atom centerPt, Atom targetPt) Calculates the angle from centerPt to targetPt in degrees.
static Atom[]	centerAtoms(Atom[] atomSet) Center the atoms at the Centroid.
static Atom[]	centerAtoms(Atom[] atomSet, Atom centroid) Center the atoms at the Centroid, if the centroid is already know.
static Atom	centerOfMass(Atom[] points) Returns the center of mass of the set of atoms.
static Atom	createVirtualCBAtom(AminoAcid amino) creates a virtual C-beta atom. this might be needed when working with GLY thanks to Peter Lackner for a python template of this method.
static Atom	getCenterVector(Atom[] atomSet) Returns the Vector that needs to be applied to shift a set of atoms to the Centroid.
static Atom	getCenterVector(Atom[] atomSet, Atom centroid) Returns the Vector that needs to be applied to shift a set of atoms to the Centroid, if the centroid is already known
static Atom	getCentroid(Atom[] atomSet) Returns the centroid of the set of atoms.
static double	getDistance(Atom a, Atom b) calculate distance between two atoms.
static double	getDistanceFast(Atom a, Atom b) Will calculate the square of distances between two atoms.
static double	getPhi(AminoAcid a, AminoAcid b) Calculate the phi angle.
static double	getPsi(AminoAcid a, AminoAcid b) Calculate the psi angle.
static double	getTMScore(Atom[] atomSet1, Atom[] atomSet2, int len1, int len2) Calculate the TM-Score for the superposition.
static double	getTMScore(Atom[] atomSet1, Atom[] atomSet2, int len1, int len2, boolean normalizeMin) Calculate the TM-Score for the superposition.
static javax.vecmath.Matrix4d	getTransformation(Matrix rot, Atom trans) Convert JAMA rotation and translation to a Vecmath transformation matrix.
static Atom	getTranslationVector(javax.vecmath.Matrix4d transform) Extract the translational vector as an Atom of a transformation matrix.
static double[]	getXYZEuler(Matrix m) Convert a rotation Matrix to Euler angles.
static double[]	getZYZEuler(Matrix m) Gets euler angles for a matrix given in ZYZ convention.
static Atom	invert(Atom a)
static boolean	isConnected(AminoAcid a, AminoAcid b) Test if two amino acids are connected, i.e. if the distance from C to N < 2.5 Angstrom.
static void	main(String[] args)
static Matrix	matrixFromEuler(double heading, double attitude, double bank) This conversion uses NASA standard aeroplane conventions as described on page: http://www.euclideanspace.com/maths/geometry/rotations/euler/index.htm Coordinate System: right hand Positive angle: right hand Order of euler angles: heading first, then attitude, then bank. matrix row column ordering: [m00 m01 m02] [m10 m11 m12] [m20 m21 m22]
static void	plus(Structure s, Matrix matrix) calculate structure + Matrix coodinates ...
static double	rmsd(Atom[] x, Atom[] y) Calculate the RMSD of two Atom arrays, already superposed.
static void	rotate(Atom[] ca, Matrix matrix)
static void	rotate(Atom atom, double[][] m) Rotate a single Atom aroud a rotation matrix.
static void	rotate(Atom atom, Matrix m) Rotate an Atom around a Matrix object.
static void	rotate(Group group, double[][] rotationmatrix) Rotate a Group.
static void	rotate(Group group, Matrix m) Rotate a group object.
static void	rotate(Structure structure, double[][] rotationmatrix) Rotate a structure.
static void	rotate(Structure structure, Matrix m) Rotate a structure object.
static double	scalarProduct(Atom a, Atom b) Scalar product (dot product).
static Atom	scale(Atom a, double s) Multiply elements of a by s
static Atom	scaleAdd(double s, Atom x, Atom b) Perform linear transformation s*X+B, and store the result in b
static Atom	scaleEquals(Atom a, double s) Multiply elements of a by s (in place)
static void	shift(Atom[] ca, Atom b) Shift an array of atoms at once.
static void	shift(Atom a, Atom b) Shift a vector.
static void	shift(Group group, Atom a) Shift a Group with a vector.
static void	shift(Structure structure, Atom a) shift a structure with a vector.
static Atom	subtract(Atom a, Atom b) subtract two atoms ( a - b).
static double	torsionAngle(Atom a, Atom b, Atom c, Atom d) Calculate the torsion angle, i.e. the angle between the normal vectors of the two plains a-b-c and b-c-d.
static void	transform(Atom[] ca, javax.vecmath.Matrix4d t) Transform an array of atoms at once.
static void	transform(Atom atom, javax.vecmath.Matrix4d m) Transforms an atom object, given a Matrix4d (i.e. the vecmath library double-precision 4x4 rotation+translation matrix).
static void	transform(Chain chain, javax.vecmath.Matrix4d m) Transforms a chain object, given a Matrix4d (i.e. the vecmath library double-precision 4x4 rotation+translation matrix).
static void	transform(Group group, javax.vecmath.Matrix4d m) Transforms a group object, given a Matrix4d (i.e. the vecmath library double-precision 4x4 rotation+translation matrix).
static void	transform(Structure structure, javax.vecmath.Matrix4d m) Transforms a structure object, given a Matrix4d (i.e. the vecmath library double-precision 4x4 rotation+translation matrix).
static void	translate(Atom atom, javax.vecmath.Vector3d v) Translates an atom object, given a Vector3d (i.e. the vecmath library double-precision 3-d vector)
static void	translate(Chain chain, javax.vecmath.Vector3d v) Translates a chain object, given a Vector3d (i.e. the vecmath library double-precision 3-d vector)
static void	translate(Group group, javax.vecmath.Vector3d v) Translates a group object, given a Vector3d (i.e. the vecmath library double-precision 3-d vector)
static void	translate(Structure structure, javax.vecmath.Vector3d v) Translates a Structure object, given a Vector3d (i.e. the vecmath library double-precision 3-d vector)
static Atom	unitVector(Atom a) Returns the unit vector of vector a .
static Atom	vectorProduct(Atom a, Atom b) Vector product (cross product).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Calc

public Calc()

Method Detail

getDistance

public static final double getDistance(Atom a,
                                       Atom b)

calculate distance between two atoms.

Parameters:

a - an Atom object

b - an Atom object

Returns:

a double

getDistanceFast

public static double getDistanceFast(Atom a,
                                     Atom b)

Will calculate the square of distances between two atoms. This will be faster as it will not perform the final square root to get the actual distance. Use this if doing large numbers of distance comparisons - it is marginally faster than getDistance().

Parameters:

a - an Atom object

b - an Atom object

Returns:

a double

invert

public static final Atom invert(Atom a)

add

public static final Atom add(Atom a,
                             Atom b)

add two atoms ( a + b).

Parameters:

a - an Atom object

b - an Atom object

Returns:

an Atom object

subtract

public static final Atom subtract(Atom a,
                                  Atom b)

subtract two atoms ( a - b).

Parameters:

a - an Atom object

b - an Atom object

Returns:

n new Atom object representing the difference

vectorProduct

public static final Atom vectorProduct(Atom a,
                                       Atom b)

Vector product (cross product).

Parameters:

a - an Atom object

b - an Atom object

Returns:

an Atom object

scalarProduct

public static final double scalarProduct(Atom a,
                                         Atom b)

Scalar product (dot product).

Parameters:

a - an Atom object

b - an Atom object

Returns:

a double

amount

public static final double amount(Atom a)

Gets the length of the vector (2-norm)

Parameters:

a - an Atom object

Returns:

Square root of the sum of the squared elements

angle

public static final double angle(Atom a,
                                 Atom b)

Gets the angle between two vectors

Parameters:

a - an Atom object

b - an Atom object

Returns:

Angle between a and b in degrees, in range [0,180]. If either vector has length 0 then angle is not defined and NaN is returned

unitVector

public static final Atom unitVector(Atom a)

Returns the unit vector of vector a .

Parameters:

a - an Atom object

Returns:

an Atom object

torsionAngle

public static final double torsionAngle(Atom a,
                                        Atom b,
                                        Atom c,
                                        Atom d)

Calculate the torsion angle, i.e. the angle between the normal vectors of the two plains a-b-c and b-c-d. See http://en.wikipedia.org/wiki/Dihedral_angle

Parameters:

a - an Atom object

b - an Atom object

c - an Atom object

d - an Atom object

Returns:

the torsion angle in degrees, in range +-[0,180]. If either first 3 or last 3 atoms are colinear then torsion angle is not defined and NaN is returned

getPhi

public static final double getPhi(AminoAcid a,
                                  AminoAcid b)
                           throws StructureException

Calculate the phi angle.

Parameters:

a - an AminoAcid object

b - an AminoAcid object

Returns:

a double

Throws:

StructureException - if aminoacids not connected or if any of the 4 needed atoms missing

getPsi

public static final double getPsi(AminoAcid a,
                                  AminoAcid b)
                           throws StructureException

Calculate the psi angle.

Parameters:

a - an AminoAcid object

b - an AminoAcid object

Returns:

a double

Throws:

StructureException - if aminoacids not connected or if any of the 4 needed atoms missing

isConnected

public static final boolean isConnected(AminoAcid a,
                                        AminoAcid b)

Test if two amino acids are connected, i.e. if the distance from C to N < 2.5 Angstrom. If one of the AminoAcids has an atom missing, returns false.

Parameters:

a - an AminoAcid object

b - an AminoAcid object

Returns:

true if ...

rotate

public static final void rotate(Atom atom,
                                double[][] m)

Rotate a single Atom aroud a rotation matrix. The rotation Matrix must be a pre-multiplication 3x3 Matrix. If the matrix is indexed m[row][col], then the matrix will be pre-multiplied (y=atom*M)

Parameters:

atom - atom to be rotated

m - a rotation matrix represented as a double[3][3] array

rotate

public static final void rotate(Structure structure,
                                double[][] rotationmatrix)
                         throws StructureException

Rotate a structure. The rotation Matrix must be a pre-multiplication Matrix.

Parameters:

structure - a Structure object

rotationmatrix - an array (3x3) of double representing the rotation matrix.

Throws:

StructureException - ...

rotate

public static final void rotate(Group group,
                                double[][] rotationmatrix)
                         throws StructureException

Rotate a Group. The rotation Matrix must be a pre-multiplication Matrix.

Parameters:

group - a group object

rotationmatrix - an array (3x3) of double representing the rotation matrix.

Throws:

StructureException - ...

rotate

public static final void rotate(Atom atom,
                                Matrix m)

Rotate an Atom around a Matrix object. The rotation Matrix must be a pre-multiplication Matrix.

Parameters:

atom - atom to be rotated

m - rotation matrix to be applied to the atom

rotate

public static final void rotate(Group group,
                                Matrix m)

Rotate a group object. The rotation Matrix must be a pre-multiplication Matrix.

Parameters:

group - a group to be rotated

m - a Matrix object representing the rotation matrix

rotate

public static final void rotate(Structure structure,
                                Matrix m)

Rotate a structure object. The rotation Matrix must be a pre-multiplication Matrix.

Parameters:

structure - the structure to be rotated

m - rotation matrix to be applied

transform

public static void transform(Atom[] ca,
                             javax.vecmath.Matrix4d t)

Transform an array of atoms at once. The transformation Matrix must be a post-multiplication Matrix.

Parameters:

ca - array of Atoms to shift

t - transformation Matrix4d

transform

public static final void transform(Atom atom,
                                   javax.vecmath.Matrix4d m)

Transforms an atom object, given a Matrix4d (i.e. the vecmath library double-precision 4x4 rotation+translation matrix). The transformation Matrix must be a post-multiplication Matrix.

Parameters:

atom -

m -

transform

public static final void transform(Group group,
                                   javax.vecmath.Matrix4d m)

Transforms a group object, given a Matrix4d (i.e. the vecmath library double-precision 4x4 rotation+translation matrix). The transformation Matrix must be a post-multiplication Matrix.

Parameters:

group -

m -

transform

public static final void transform(Structure structure,
                                   javax.vecmath.Matrix4d m)

Transforms a structure object, given a Matrix4d (i.e. the vecmath library double-precision 4x4 rotation+translation matrix). The transformation Matrix must be a post-multiplication Matrix.

Parameters:

structure -

m -

transform

public static final void transform(Chain chain,
                                   javax.vecmath.Matrix4d m)

Transforms a chain object, given a Matrix4d (i.e. the vecmath library double-precision 4x4 rotation+translation matrix). The transformation Matrix must be a post-multiplication Matrix.

Parameters:

chain -

m -

translate

public static final void translate(Atom atom,
                                   javax.vecmath.Vector3d v)

Translates an atom object, given a Vector3d (i.e. the vecmath library double-precision 3-d vector)

Parameters:

atom -

v -

translate

public static final void translate(Group group,
                                   javax.vecmath.Vector3d v)

Translates a group object, given a Vector3d (i.e. the vecmath library double-precision 3-d vector)

Parameters:

group -

v -

translate

public static final void translate(Chain chain,
                                   javax.vecmath.Vector3d v)

Translates a chain object, given a Vector3d (i.e. the vecmath library double-precision 3-d vector)

Parameters:

chain -

v -

translate

public static final void translate(Structure structure,
                                   javax.vecmath.Vector3d v)

Translates a Structure object, given a Vector3d (i.e. the vecmath library double-precision 3-d vector)

Parameters:

structure -

v -

plus

public static final void plus(Structure s,
                              Matrix matrix)

calculate structure + Matrix coodinates ...

Parameters:

s - the structure to operate on

matrix - a Matrix object

shift

public static final void shift(Structure structure,
                               Atom a)

shift a structure with a vector.

Parameters:

structure - a Structure object

a - an Atom object representing a shift vector

shift

public static final void shift(Atom a,
                               Atom b)

Shift a vector.

Parameters:

a - vector a

b - vector b

shift

public static final void shift(Group group,
                               Atom a)

Shift a Group with a vector.

Parameters:

group - a group object

a - an Atom object representing a shift vector

getCentroid

public static final Atom getCentroid(Atom[] atomSet)

Returns the centroid of the set of atoms.

Parameters:

atomSet - a set of Atoms

Returns:

an Atom representing the Centroid of the set of atoms

centerOfMass

public static Atom centerOfMass(Atom[] points)

Returns the center of mass of the set of atoms. Atomic masses of the Atoms are used.

Parameters:

points - a set of Atoms

Returns:

an Atom representing the center of mass

scaleEquals

public static Atom scaleEquals(Atom a,
                               double s)

Multiply elements of a by s (in place)

Parameters:

a -

s -

Returns:

the modified a

scale

public static Atom scale(Atom a,
                         double s)

Multiply elements of a by s

Parameters:

a -

s -

Returns:

A new Atom with s*a

scaleAdd

public static Atom scaleAdd(double s,
                            Atom x,
                            Atom b)

Perform linear transformation s*X+B, and store the result in b

Parameters:

s - Amount to scale x

x - Input coordinate

b - Vector to translate (will be modified)

Returns:

b, after modification

getCenterVector

public static final Atom getCenterVector(Atom[] atomSet)

Returns the Vector that needs to be applied to shift a set of atoms to the Centroid.

Parameters:

atomSet - array of Atoms

Returns:

the vector needed to shift the set of atoms to its geometric center

getCenterVector

public static final Atom getCenterVector(Atom[] atomSet,
                                         Atom centroid)

Returns the Vector that needs to be applied to shift a set of atoms to the Centroid, if the centroid is already known

Parameters:

atomSet - array of Atoms

Returns:

the vector needed to shift the set of atoms to its geometric center

centerAtoms

public static final Atom[] centerAtoms(Atom[] atomSet)
                                throws StructureException

Center the atoms at the Centroid.

Parameters:

atomSet - a set of Atoms

Returns:

an Atom representing the Centroid of the set of atoms

Throws:

StructureException

centerAtoms

public static final Atom[] centerAtoms(Atom[] atomSet,
                                       Atom centroid)
                                throws StructureException

Center the atoms at the Centroid, if the centroid is already know.

Parameters:

atomSet - a set of Atoms

Returns:

an Atom representing the Centroid of the set of atoms

Throws:

StructureException

createVirtualCBAtom

public static final Atom createVirtualCBAtom(AminoAcid amino)
                                      throws StructureException

creates a virtual C-beta atom. this might be needed when working with GLY thanks to Peter Lackner for a python template of this method.

Parameters:

amino - the amino acid for which a "virtual" CB atom should be calculated

Returns:

a "virtual" CB atom

Throws:

StructureException

getZYZEuler

public static final double[] getZYZEuler(Matrix m)

Gets euler angles for a matrix given in ZYZ convention. (as e.g. used by Jmol)

Parameters:

m - the rotation matrix

Returns:

the euler values for a rotation around Z, Y, Z in degrees...

getXYZEuler

public static final double[] getXYZEuler(Matrix m)

Convert a rotation Matrix to Euler angles. This conversion uses conventions as described on page: http://www.euclideanspace.com/maths/geometry/rotations/euler/index.htm Coordinate System: right hand Positive angle: right hand Order of euler angles: heading first, then attitude, then bank

Parameters:

m - the rotation matrix

Returns:

a array of three doubles containing the three euler angles in radians

matrixFromEuler

public static final Matrix matrixFromEuler(double heading,
                                           double attitude,
                                           double bank)

This conversion uses NASA standard aeroplane conventions as described on page: http://www.euclideanspace.com/maths/geometry/rotations/euler/index.htm Coordinate System: right hand Positive angle: right hand Order of euler angles: heading first, then attitude, then bank. matrix row column ordering: [m00 m01 m02] [m10 m11 m12] [m20 m21 m22]

Parameters:

heading - in radians

attitude - in radians

bank - in radians

Returns:

the rotation matrix

calcRotationAngleInDegrees

public static double calcRotationAngleInDegrees(Atom centerPt,
                                                Atom targetPt)

Calculates the angle from centerPt to targetPt in degrees. The return should range from [0,360), rotating CLOCKWISE, 0 and 360 degrees represents NORTH, 90 degrees represents EAST, etc... Assumes all points are in the same coordinate space. If they are not, you will need to call SwingUtilities.convertPointToScreen or equivalent on all arguments before passing them to this function.

Parameters:

centerPt - Point we are rotating around.

targetPt - Point we want to calculate the angle to.

Returns:

angle in degrees. This is the angle from centerPt to targetPt.

main

public static void main(String[] args)

rotate

public static void rotate(Atom[] ca,
                          Matrix matrix)

shift

public static void shift(Atom[] ca,
                         Atom b)

Shift an array of atoms at once.

Parameters:

ca - array of Atoms to shift

b - reference Atom vector

getTransformation

public static javax.vecmath.Matrix4d getTransformation(Matrix rot,
                                                       Atom trans)

Convert JAMA rotation and translation to a Vecmath transformation matrix. Because the JAMA matrix is a pre-multiplication matrix and the Vecmath matrix is a post-multiplication one, the rotation matrix is transposed to ensure that the transformation they produce is the same.

Parameters:

rot - 3x3 Rotation matrix

trans - 3x1 translation vector in Atom coordinates

Returns:

4x4 transformation matrix

getTranslationVector

public static Atom getTranslationVector(javax.vecmath.Matrix4d transform)

Extract the translational vector as an Atom of a transformation matrix.

Parameters:

transform - Matrix4d

Returns:

Atom shift vector

atomsToPoints

public static javax.vecmath.Point3d[] atomsToPoints(Atom[] atoms)

Convert an array of atoms into an array of vecmath points

Parameters:

atoms - list of atoms

Returns:

list of Point3ds storing the x,y,z coordinates of each atom

atomsToPoints

public static List<javax.vecmath.Point3d> atomsToPoints(Collection<Atom> atoms)

Convert an array of atoms into an array of vecmath points

Parameters:

atoms - list of atoms

Returns:

list of Point3ds storing the x,y,z coordinates of each atom

rmsd

public static double rmsd(Atom[] x,
                          Atom[] y)

Calculate the RMSD of two Atom arrays, already superposed.

Parameters:

x - array of Atoms superposed to y

y - array of Atoms superposed to x

Returns:

RMSD

getTMScore

public static double getTMScore(Atom[] atomSet1,
                                Atom[] atomSet2,
                                int len1,
                                int len2)
                         throws StructureException

Calculate the TM-Score for the superposition. Normalizes by the minimum-length structure (that is, min\{len1,len2\}). Atom sets must be pre-rotated.

Citation:
Zhang Y and Skolnick J (2004). "Scoring function for automated assessment of protein structure template quality". Proteins 57: 702 - 710.

Parameters:

atomSet1 - atom array 1

atomSet2 - atom array 2

len1 - The full length of the protein supplying atomSet1

len2 - The full length of the protein supplying atomSet2

Returns:

The TM-Score

Throws:

StructureException

getTMScore

public static double getTMScore(Atom[] atomSet1,
                                Atom[] atomSet2,
                                int len1,
                                int len2,
                                boolean normalizeMin)
                         throws StructureException

Calculate the TM-Score for the superposition. Atom sets must be pre-rotated.

Citation:
Zhang Y and Skolnick J (2004). "Scoring function for automated assessment of protein structure template quality". Proteins 57: 702 - 710.

Parameters:

atomSet1 - atom array 1

atomSet2 - atom array 2

len1 - The full length of the protein supplying atomSet1

len2 - The full length of the protein supplying atomSet2

normalizeMin - Whether to normalize by the minimum-length structure, that is, min\{len1,len2\}. If false, normalized by the max\{len1,len2\}).

Returns:

The TM-Score

Throws:

StructureException