org.biojava.nbio.structure.symmetry.utils

Class SymmetryTools

java.lang.Object

org.biojava.nbio.structure.symmetry.utils.SymmetryTools

public class SymmetryTools
extends Object

Utility methods for the internal symmetry identification and manipulation.

Methods include: blank out regions of DP Matrix, build symmetry graphs, get rotation symmetry angles, split repeats in quaternary structure chains, convert between symmetry formats (full, repeats, rotations), determine if two symmetry axes are equivalent, get groups from representative Atoms.

Author:

Spencer Bliven, Aleix Lafita

Method Summary

Modifier and Type	Method and Description
static boolean[][]	blankOutBreakFlag(AFPChain afpChain, Atom[] ca2, int rows, int cols, CECalculator calculator, boolean[][] breakFlag, int blankWindowSize)
static Matrix	blankOutCEOrig(Atom[] ca2, int rows, int cols, CECalculator calculator, Matrix origM, int blankWindowSize)
static Matrix	blankOutPreviousAlignment(AFPChain afpChain, Atom[] ca2, int rows, int cols, CECalculator calculator, Matrix max, int blankWindowSize)
static org.jgrapht.UndirectedGraph<Integer,org.jgrapht.graph.DefaultEdge>	buildSymmetryGraph(AFPChain selfAlignment) Converts a self alignment into a directed jGraphT of aligned residues, where each vertex is a residue and each edge means the equivalence between the two residues in the self-alignment.
static List<List<Integer>>	buildSymmetryGraph(List<AFPChain> afps, Atom[] atoms, boolean undirected) Converts a set of AFP alignments into a Graph of aligned residues, where each vertex is a residue and each edge means the connection between the two residues in one of the alignments.
static boolean	equivalentAxes(javax.vecmath.Matrix4d axis1, javax.vecmath.Matrix4d axis2, double epsilon) Determines if two symmetry axis are equivalent inside the error threshold.
static MultipleAlignment	fromAFP(AFPChain symm, Atom[] atoms) Converts a refined symmetry AFPChain alignment into the standard representation of symmetry in a MultipleAlignment, that contains the entire Atom array of the strcuture and the symmetric repeats are orgaized in different rows in a single Block.
static double	getAngle(AFPChain afpChain, Atom[] ca1, Atom[] ca2) Returns the magnitude of the angle between the first and second blocks of afpChain, measured in degrees.
Matrix	getDkMatrix(Atom[] ca1, Atom[] ca2, int fragmentLength, double[] dist1, double[] dist2, int rows, int cols)
static Matrix	getDkMatrix(Atom[] ca1, Atom[] ca2, int k, int fragmentLength)
static List<Group>	getGroups(Atom[] rAtoms) Returns the List of Groups of the corresponding representative Atom array.
static Structure	getQuaternaryStructure(CeSymmResult symmetry) Method that converts the symmetric units of a structure into different chains, so that internal symmetry can be translated into quaternary.
static QuatSymmetryResults	getQuaternarySymmetry(CeSymmResult result) Given a symmetry result, it calculates the overall global symmetry, factoring out the alignment and detection steps of QuatSymmetryDetector algorithm.
static Matrix	grayOutCEOrig(Atom[] ca2, int rows, int cols, CECalculator calculator, Matrix origM, int blankWindowSize, double[] gradientPolyCoeff, double gradientExpCoeff) Grays out the main diagonal of a duplicated distance matrix.
static Matrix	grayOutPreviousAlignment(AFPChain afpChain, Atom[] ca2, int rows, int cols, CECalculator calculator, Matrix max, int blankWindowSize, double[] gradientPolyCoeff, double gradientExpCoeff)
static boolean	isRefined(MultipleAlignment symm) Returns true a symmetry multiple alignment has been refined, false otherwise.
static boolean	isSignificant(MultipleAlignment msa, double symmetryThreshold) Returns true if the symmetry alignment is significant, false otherwise.
static MultipleAlignment	toFullAlignment(CeSymmResult symm) Method that converts a repeats symmetric alignment into an alignment of whole structures.
static MultipleAlignment	toRepeatsAlignment(CeSymmResult result) Method that converts a symmetry alignment into an alignment of the repeats only, as new independent structures.
static void	updateSymmetryScores(MultipleAlignment symm) Update the scores (TM-score and RMSD) of a symmetry multiple alignment.
static void	updateSymmetryTransformation(SymmetryAxes axes, MultipleAlignment msa, Atom[] atoms) Calculates the set of symmetry operation Matrices (transformations) of the new alignment, based on the symmetry relations in the SymmetryAxes object.

Methods inherited from class java.lang.Object

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

Method Detail

grayOutCEOrig

public static Matrix grayOutCEOrig(Atom[] ca2,
                                   int rows,
                                   int cols,
                                   CECalculator calculator,
                                   Matrix origM,
                                   int blankWindowSize,
                                   double[] gradientPolyCoeff,
                                   double gradientExpCoeff)

Grays out the main diagonal of a duplicated distance matrix.

Parameters:

ca2 -

rows - Number of rows

cols - Number of original columns

calculator - Used to get the matrix if origM is null

origM - starting matrix. If null, uses CECalculator.getMatMatrix()

blankWindowSize - Width of section to gray out

gradientPolyCoeff -

gradientExpCoeff -

Returns:

grayOutPreviousAlignment

public static Matrix grayOutPreviousAlignment(AFPChain afpChain,
                                              Atom[] ca2,
                                              int rows,
                                              int cols,
                                              CECalculator calculator,
                                              Matrix max,
                                              int blankWindowSize,
                                              double[] gradientPolyCoeff,
                                              double gradientExpCoeff)

getDkMatrix

public Matrix getDkMatrix(Atom[] ca1,
                          Atom[] ca2,
                          int fragmentLength,
                          double[] dist1,
                          double[] dist2,
                          int rows,
                          int cols)

blankOutPreviousAlignment

public static Matrix blankOutPreviousAlignment(AFPChain afpChain,
                                               Atom[] ca2,
                                               int rows,
                                               int cols,
                                               CECalculator calculator,
                                               Matrix max,
                                               int blankWindowSize)

blankOutCEOrig

public static Matrix blankOutCEOrig(Atom[] ca2,
                                    int rows,
                                    int cols,
                                    CECalculator calculator,
                                    Matrix origM,
                                    int blankWindowSize)

getDkMatrix

public static Matrix getDkMatrix(Atom[] ca1,
                                 Atom[] ca2,
                                 int k,
                                 int fragmentLength)

blankOutBreakFlag

public static boolean[][] blankOutBreakFlag(AFPChain afpChain,
                                            Atom[] ca2,
                                            int rows,
                                            int cols,
                                            CECalculator calculator,
                                            boolean[][] breakFlag,
                                            int blankWindowSize)

getAngle

public static double getAngle(AFPChain afpChain,
                              Atom[] ca1,
                              Atom[] ca2)

Returns the magnitude of the angle between the first and second blocks of afpChain, measured in degrees. This is always a positive value (unsigned).

Parameters:

afpChain -

ca1 -

ca2 -

Returns:

buildSymmetryGraph

public static List<List<Integer>> buildSymmetryGraph(List<AFPChain> afps,
                                                     Atom[] atoms,
                                                     boolean undirected)

Converts a set of AFP alignments into a Graph of aligned residues, where each vertex is a residue and each edge means the connection between the two residues in one of the alignments.

Parameters:

afps - List of AFPChains

atoms - Atom array of the symmetric structure

undirected - if true, the graph is undirected

Returns:

adjacency List of aligned residues

buildSymmetryGraph

public static org.jgrapht.UndirectedGraph<Integer,org.jgrapht.graph.DefaultEdge> buildSymmetryGraph(AFPChain selfAlignment)

Converts a self alignment into a directed jGraphT of aligned residues, where each vertex is a residue and each edge means the equivalence between the two residues in the self-alignment.

Parameters:

selfAlignment - AFPChain

Returns:

alignment Graph

getQuaternaryStructure

public static Structure getQuaternaryStructure(CeSymmResult symmetry)

Method that converts the symmetric units of a structure into different chains, so that internal symmetry can be translated into quaternary.

Application: obtain the internal symmetry axis with the quaternary symmetry code in biojava or calculate independent repeat properties.

Parameters:

symmetry - CeSymmResult

Returns:

Structure with different chains for every symmetric unit

toFullAlignment

public static MultipleAlignment toFullAlignment(CeSymmResult symm)

Method that converts a repeats symmetric alignment into an alignment of whole structures.

Example: if the structure has repeats A,B and C, the original alignment is A-B-C, and the returned alignment is ABC-BCA-CAB.

Parameters:

symm - CeSymmResult

Returns:

MultipleAlignment of the full structure superpositions

toRepeatsAlignment

public static MultipleAlignment toRepeatsAlignment(CeSymmResult result)
                                            throws StructureException

Method that converts a symmetry alignment into an alignment of the repeats only, as new independent structures.

This method changes the structure identifiers, the Atom arrays and re-scles the aligned residues in the Blocks corresponding to those changes.

Application: display superimposed repeats in Jmol.

Parameters:

result - CeSymmResult of symmetry

Returns:

MultipleAlignment of the repeats

Throws:

StructureException

fromAFP

public static MultipleAlignment fromAFP(AFPChain symm,
                                        Atom[] atoms)
                                 throws StructureException

Converts a refined symmetry AFPChain alignment into the standard representation of symmetry in a MultipleAlignment, that contains the entire Atom array of the strcuture and the symmetric repeats are orgaized in different rows in a single Block.

Parameters:

symm - AFPChain created with a symmetry algorithm and refined

atoms - Atom array of the entire structure

Returns:

MultipleAlignment format of the symmetry

Throws:

StructureException

equivalentAxes

public static boolean equivalentAxes(javax.vecmath.Matrix4d axis1,
                                     javax.vecmath.Matrix4d axis2,
                                     double epsilon)

Determines if two symmetry axis are equivalent inside the error threshold. It only takes into account the direction of the vector where the rotation is made: the angle and translation are not taken into account.

Parameters:

axis1 -

axis2 -

epsilon - error allowed in the axis comparison

Returns:

true if equivalent, false otherwise

getQuaternarySymmetry

public static QuatSymmetryResults getQuaternarySymmetry(CeSymmResult result)
                                                 throws StructureException

Given a symmetry result, it calculates the overall global symmetry, factoring out the alignment and detection steps of QuatSymmetryDetector algorithm.

Parameters:

result - symmetry result

Returns:

global symmetry results

Throws:

StructureException

isRefined

public static boolean isRefined(MultipleAlignment symm)

Returns true a symmetry multiple alignment has been refined, false otherwise.

For a refined alignment only one Block with no repeated residues is necessary. Sufficient condition is not tested (only known from the algorithm or CeSymmResult).

Parameters:

symm - the symmetry alignment

Returns:

true if the alignment is refined

isSignificant

public static boolean isSignificant(MultipleAlignment msa,
                                    double symmetryThreshold)
                             throws StructureException

Returns true if the symmetry alignment is significant, false otherwise.

For a symmetry alignment to be significant, the alignment has to be refined and the TM-score has to be higher than the threshold.

It is recommended to use the CeSymmResult.isSignificant() method instead.

Parameters:

msa -

symmetryThreshold -

Returns:

Throws:

StructureException

getGroups

public static List<Group> getGroups(Atom[] rAtoms)

Returns the List of Groups of the corresponding representative Atom array. The representative Atom array needs to fulfill: no two Atoms are from the same Group and Groups are sequential (connected in the original Structure), except if they are from different Chains.

Parameters:

rAtoms - array of representative Atoms (CA, P, etc).

Returns:

List of Groups

updateSymmetryTransformation

public static void updateSymmetryTransformation(SymmetryAxes axes,
                                                MultipleAlignment msa,
                                                Atom[] atoms)
                                         throws StructureException

Calculates the set of symmetry operation Matrices (transformations) of the new alignment, based on the symmetry relations in the SymmetryAxes object. It sets the transformations to the input MultipleAlignment and SymmetryAxes objects. If the SymmetryAxes object is null, the superposition of the repeats is done without symmetry constraints.

This method also sets the scores (RMSD and TM-score) after the new superposition has been updated.

Parameters:

axes - SymmetryAxes object. It will be modified.

msa - MultipleAlignment. It will be modified.

atoms - Atom array of the structure

Throws:

StructureException

updateSymmetryScores

public static void updateSymmetryScores(MultipleAlignment symm)
                                 throws StructureException

Update the scores (TM-score and RMSD) of a symmetry multiple alignment. This method does not redo the superposition of the alignment.

Parameters:

symm - Symmetry Multiple Alignment of Repeats

Throws:

StructureException