de.unibi.techfak.jpredictor.clustering
Class MatrixAlignment

java.lang.Object
  de.unibi.techfak.jpredictor.clustering.RelationMeasure
      de.unibi.techfak.jpredictor.clustering.MatrixRelationMeasure
          de.unibi.techfak.jpredictor.clustering.MatrixAlignment

All Implemented Interfaces:

Computable, java.lang.Comparable

public class MatrixAlignment
extends MatrixRelationMeasure

Class for aligning two matrices. There's no need for both matrices to be of the same size (length). It depends on the used MatrixSimilarity, whether the arrays must be of equal length. An alignment of two matrices means, that the first matrix is shifted against the second and for every shift value the relation measure is calculated. The shift value for the most optimal relation measure is taken as result.

At the beginning or the end of both matrices an array representing a gap must be provided by the user. Example: when dealing with nucleotide strings represented as position specific probability matrices the gap vector is usually the 'N' array: { 0.25, 0.25, 0.25, 0.25 }, which means every atomic nucleotide A,C,G,T has the same probability of 25% to occur at that position. Despite the gaps at the beginning and the end of both matrices the alignment is called gapless, since no gaps are inserted into the matrices.

Usage is like this: MatrixAlignment ma = new MatrixAlignment( new MatrixLoglikelihood ( new LikelihoodMeasure() ) ); ma.add( firstMatrix ); ma.add( secondMatrix ); ma.compute(); ma.result(); // returns the best relation measure ma.getShiftValue(); // returns how both matrices are aligned // to obtain such an result . For an alignment of two matrices to function a matrix relation measure must be given. This measure is to be optimized.

Field Summary

(package private) double[]	gaparray The array representing a gap.
(package private) MatrixSimilarity	ms Tells how both matrices are to be related to each other.
(package private) int	shiftValue After the aligment was computed, the shift value tells how the first is shifted against the second.

Fields inherited from class de.unibi.techfak.jpredictor.clustering.MatrixRelationMeasure

matrixList

Fields inherited from class de.unibi.techfak.jpredictor.clustering.RelationMeasure

computationResult

Fields inherited from interface de.unibi.techfak.jpredictor.clustering.Computable

COMPUTATION_FAILED, COMPUTATION_PENDING, COMPUTATION_SUCCESS, COMPUTATION_WAITING

Constructor Summary

MatrixAlignment(MatrixSimilarity ms, double[] gaparray)
Constructs this class with a relation measure between matrices and an array representing a gap.

Method Summary

double	atomicCombine(double rel0, double rel1) Two relations measures are combined to one result, which is not stored but returned.
double	atomicNormalize(double rel, double norm) A relations measures is normalized by a certain amount.
int	compute() Uses all internal informations available and starts and controlls the computational process.
double[][]	getConsensus() Calculates the average matrix over the last two given ones, after they were properly aligned.
double[][]	getConsensus(int normX, int normY) There are hard constraints for a consensus matrix to be calculated.
int	getShiftValue() Returns the shift value.
RelationMeasure	newInstance() Creates a copy of this relation measure as if it was newly instantiated through a call to the constructor.
int	optimum(double rel0, double rel1) Compares two relation measure results.
java.lang.String	toString() Creates a short string of this relation measure and maybe some results if available.

Methods inherited from class de.unibi.techfak.jpredictor.clustering.MatrixRelationMeasure

add, add, clear, length, lengthRow

Methods inherited from class de.unibi.techfak.jpredictor.clustering.RelationMeasure

atomicCombine, compareTo, optimum, result

Methods inherited from class java.lang.Object

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

Field Detail

shiftValue

int shiftValue

After the aligment was computed, the shift value tells how the first is shifted against the second. The initial value is Integer.MAX_VALUE.

ms

MatrixSimilarity ms

Tells how both matrices are to be related to each other. Set in the constructor. This measure is optimized while aligning the matrices.

gaparray

double[] gaparray

The array representing a gap. Both matrices are shifted against each other and at the end and the beginning this array is appent.

Constructor Detail

MatrixAlignment

public MatrixAlignment(MatrixSimilarity ms,
                       double[] gaparray)
                throws java.lang.NullPointerException

Constructs this class with a relation measure between matrices and an array representing a gap. Note, that no restriction to the gaparray are checked since there might be a VectorRelationMeasure that can handle what the user provides.

Parameters:

ms - The relation measure between the two matrices to be aligned.

gaparray - The array to be appent at the beginning and the end of both matrices.

Throws:

java.lang.NullPointerException - If mrm is null.

Method Detail

getShiftValue

public int getShiftValue()

Returns the shift value. This value is only valid after computation was done. A value of Integer.MAX_VALUE indicates that either no computation was done yet or that it failed.

Returns:

Returns the shift value.

getConsensus

public double[][] getConsensus(int normX,
                               int normY)

There are hard constraints for a consensus matrix to be calculated. First is, that all arrays (rows) within both matrices must be of the same size. If gaparray is non-null it too must be of that size.

Parameters:

normX - The normalization for the first matrix.

normY - The normalization for the second matrix.

Returns:

The consensus matrix over two matrices, after they were aligned.

getConsensus

public double[][] getConsensus()

Calculates the average matrix over the last two given ones, after they were properly aligned.

Returns:

The consensus matrix over two matrices without normalization and only after an alignment was done.

See Also:

getConsensus(int, int)

optimum

public int optimum(double rel0,
                   double rel1)

Description copied from class: RelationMeasure

Compares two relation measure results. Returns -1, zero or 1, if the first (rel0) measure is worse, equal, or better than the second one (rel1). The terms worse and better depend on the implementation of the RelationMeasure inheriting this method. Usually, when dealing with distances, the lower the better. On the other side, when dealing with likelihoods the higher the better.

Note, that it is possible to mix up optimization of different relation measures, e.g. distances and likelihoods, since this method works on any numbers.

Specified by:

optimum in class RelationMeasure

Parameters:

rel0 - The first relation measure to be compared to the second.

rel1 - The second relation measure to be compared to the first.

Returns:

-1, zero or 1 in case the first result is worse, equal or better than the second one.

compute

public int compute()

Description copied from interface: Computable

Uses all internal informations available and starts and controlls the computational process. In its simplest case it is a method to calculate a formula, a more complicate way would be to run e.g. a whole clustering through this method.

Returns:

A status code about the process, e.g. COMPUTATION_SUCCESS.

See Also:

Computable.COMPUTATION_SUCCESS, Computable.COMPUTATION_FAILED

atomicCombine

public double atomicCombine(double rel0,
                            double rel1)

Description copied from class: RelationMeasure

Two relations measures are combined to one result, which is not stored but returned. This method provides a way to calculate the combined result, when the way how to do this is not known. For instance, distance relation measures normally sum up over single results while likelihood/probabilities are multiplied.

Note, that it is possible to mix up optimization of different relation measures, e.g. distances and likelihoods, since this method works on any numbers.

Specified by:

atomicCombine in class RelationMeasure

Parameters:

rel0 - The first relation measure to be compared to the second.

rel1 - The second relation measure to be compared to the first.

Returns:

The result of combining two relation measures, e.g. through adding them up, or multiplying them or such.

atomicNormalize

public double atomicNormalize(double rel,
                              double norm)

Description copied from class: RelationMeasure

A relations measures is normalized by a certain amount. This method provides a way to normalize a relation measure after numbers of them were combined. For instance, distance relation measures normally are normalized by dividing through the count, while likelihoods are rooted.

Note, that it is possible to mix up optimization of different relation measures, e.g. distances and likelihoods, since this method works on any numbers.

Specified by:

atomicNormalize in class RelationMeasure

Parameters:

rel - The relation measure to be normalized.

norm - The normalization value.

Returns:

The result of normalizing a relation measures. Or Double.NaN in case of error.

newInstance

public RelationMeasure newInstance()

Description copied from class: RelationMeasure

Creates a copy of this relation measure as if it was newly instantiated through a call to the constructor. Note: if a class relies on really unique relation measures that are never shared with other instances it should call this method in the constructor. This might be the case, if a class uses a relation measures to store results of partially results.

Specified by:

newInstance in class RelationMeasure

Returns:

A copy of the relation measure as if it was newly instantiated.

toString

public java.lang.String toString()

Description copied from class: RelationMeasure

Creates a short string of this relation measure and maybe some results if available.

Specified by:

toString in class RelationMeasure

Returns:

A string with a short description of the class.