Package org.biojava.nbio.structure.geometry

Class SuperPositionQCP

java.lang.Object
org.biojava.nbio.structure.geometry.SuperPositionAbstract
org.biojava.nbio.structure.geometry.SuperPositionQCP
All Implemented Interfaces:
SuperPosition
public final class SuperPositionQCP extends SuperPositionAbstract
Implementation of the Quaternion-Based Characteristic Polynomial algorithm for RMSD and Superposition calculations.

Usage:

The input consists of 2 Point3d arrays of equal length. The input coordinates are not changed. 

    Point3d[] x = ...
    Point3d[] y = ...
    SuperPositionQCP qcp = new SuperPositionQCP();
    qcp.set(x, y);

or with weighting factors [0 - 1]] 

    double[] weights = ...
    qcp.set(x, y, weights);

For maximum efficiency, create a SuperPositionQCP object once and reuse it.

A. Calculate rmsd only 

 double rmsd = qcp.getRmsd();

B. Calculate a 4x4 transformation (rotation and translation) matrix 

 Matrix4d rottrans = qcp.getTransformationMatrix();

C. Get transformated points (y superposed onto the reference x) 

 Point3d[] ySuperposed = qcp.getTransformedCoordinates();

Citations:

Liu P, Agrafiotis DK, & Theobald DL (2011) Reply to comment on: "Fast determination of the optimal rotation matrix for macromolecular superpositions." Journal of Computational Chemistry 32(1):185-186. [http://dx.doi.org/10.1002/jcc.21606]

Liu P, Agrafiotis DK, & Theobald DL (2010) "Fast determination of the optimal rotation matrix for macromolecular superpositions." Journal of Computational Chemistry 31(7):1561-1563. [http://dx.doi.org/10.1002/jcc.21439]

Douglas L Theobald (2005) "Rapid calculation of RMSDs using a quaternion-based characteristic polynomial." Acta Crystallogr A 61(4):478-480. [http://dx.doi.org/10.1107/S0108767305015266 ]

This is an adoption of the original C code QCProt 1.4 (2012, October 10) to Java. The original C source code is available from http://theobald.brandeis.edu/qcp/ and was developed by

Douglas L. Theobald Department of Biochemistry MS 009 Brandeis University 415 South St Waltham, MA 02453 USA

dtheobald@brandeis.edu

Pu Liu Johnson & Johnson Pharmaceutical Research and Development, L.L.C. 665 Stockton Drive Exton, PA 19341 USA

pliu24@its.jnj.com

Author:
Douglas L. Theobald (original C code), Pu Liu (original C code), Peter Rose (adopted to Java), Aleix Lafita (adopted to Java)

  • Constructor Summary

    Constructors
    Constructor
    Description
    SuperPositionQCP(boolean centered)
    Default constructor for the quaternion based superposition algorithm.
    SuperPositionQCP(boolean centered, double evec_prec, double eval_prec)
    Constructor with option to set the precision values.

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    getRmsd(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved)
    Calculate the RMSD between two arrays of equivalent points that are not superposed.
    double
    getWeightedRmsd(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved, double[] weight)
     
    javax.vecmath.Matrix4d
    superpose(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved)
    Obtain the superposition matrix that minimizes the RMSD between two arrays of equivalent points.
    javax.vecmath.Matrix4d
    superposeAfterRmsd()
    The QCP method can be used as a two-step calculation: first compute the RMSD (fast) and then compute the superposition.
    javax.vecmath.Matrix4d
    weightedSuperpose(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved, double[] weight)
    Weighted superposition.

    Methods inherited from class org.biojava.nbio.structure.geometry.SuperPositionAbstract

    checkInput, setCentered, superposeAndTransform

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • SuperPositionQCP

      public SuperPositionQCP(boolean centered)
      Default constructor for the quaternion based superposition algorithm.
      Parameters:
      centered - true if the point arrays are centered at the origin (faster), false otherwise

    • SuperPositionQCP

      public SuperPositionQCP(boolean centered, double evec_prec, double eval_prec)
      Constructor with option to set the precision values.
      Parameters:
      centered - true if the point arrays are centered at the origin (faster), false otherwise
      evec_prec - required eigenvector precision
      eval_prec - required eigenvalue precision

  • Method Details

    • weightedSuperpose

      public javax.vecmath.Matrix4d weightedSuperpose(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved, double[] weight)
      Weighted superposition.
      Parameters:
      fixed -
      moved -
      weight - array of weigths for each equivalent point position
      Returns:

    • getRmsd

      public double getRmsd(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved)
      Description copied from interface: SuperPosition
      Calculate the RMSD between two arrays of equivalent points that are not superposed.

      This is equivalent to first superposing the point arrays with SuperPosition.superposeAndTransform(Point3d[], Point3d[]) and then calculating the RMSD of the superposed point arrays with CalcPoint.rmsd(Point3d[], Point3d[]), but it will be faster when the transformation matrix is not needed.

      The two point arrays have to be of the same length and the order of points have to be the same, so that a specific position in the one array is equivalent to the same position in the other array.

      Parameters:
      fixed - an array of points. Original coordinates will not be modified.
      moved - an array of points. Original coordinates will not be modified.
      Returns:
      the minimum RMSD between the equivalent point arrays (after superposition)

    • superpose

      public javax.vecmath.Matrix4d superpose(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved)
      Description copied from interface: SuperPosition
      Obtain the superposition matrix that minimizes the RMSD between two arrays of equivalent points.

      The two point arrays have to be of the same length and the order of points have to be the same, so that a specific position in the one array is equivalent to the same position in the other array.

      Parameters:
      fixed - point array as reference, onto which the other point array is superposed. Original coordinates will not be modified.
      moved - point array to which the resulting transformation matrix is applied. Original coordinates will not be modified.
      Returns:
      transformation matrix as a Matrix4d to superpose moved onto fixed point arrays

    • getWeightedRmsd

      public double getWeightedRmsd(javax.vecmath.Point3d[] fixed, javax.vecmath.Point3d[] moved, double[] weight)
      Parameters:
      fixed -
      moved -
      weight - array of weights for each equivalent point position
      Returns:
      weighted RMSD.

    • superposeAfterRmsd

      public javax.vecmath.Matrix4d superposeAfterRmsd()
      The QCP method can be used as a two-step calculation: first compute the RMSD (fast) and then compute the superposition.

      This method assumes that the RMSD of two arrays of points has been already calculated using getRmsd(Point3d[], Point3d[]) method and calculates the transformation of the same two point arrays.

      Returns:
      transformation matrix as a Matrix4d to superpose moved onto fixed point arrays