de.unibi.techfak.jpredictor.clustering
Class SingleMotifAlignment

java.lang.Object
  de.unibi.techfak.jpredictor.clustering.RelationMeasure
      de.unibi.techfak.jpredictor.clustering.MotifAlignment
          de.unibi.techfak.jpredictor.clustering.SingleMotifAlignment

All Implemented Interfaces:

Computable, java.lang.Comparable

public class SingleMotifAlignment
extends MotifAlignment

Defines the Alignement between two single motifs. Single motifs are SequenceMotif, RegularExpressionMotif, PSPMotif, and PSSMotif.

Before an alignment is applied to the given motifs they are transformed into matrices. The procedure for motifs of sequences is simply that they are transformed into a PSPM motif through a call to PSPMotif.createPSPMotifFromSequenceMotif(SequenceMotif). PSPMs and PSSMs are not changed since they are already represented as matrices. But note, that mixing up scores and probabilities is not recommended. The underlying matrix alignment which must be provided when this class is constructed must be able to handle the generated matrices. Example: the nucleotide sequence ABCKM is transformed to:

 Pos    A       C       G       T
 1      1       0       0       0               # A
 2      0       1/3     1/3     1/3             # B
 3      0       1       0       0               # C
 4      0       1/2     0       1/2             # K
 5      1/2     1/2     0       0               # M
 

. Probabilities at every position sum-up to one.

How the two matrices are aligned depends on the given matrix alignment measure. Apart from that two motifs can be aligned in more than one way because they can occur in more than one way. It depends on the search direction whether two motifs are aligned in their plus strand way or in their minus strand (reversed complemented) way as well. One alignment is calculated only in case both motifs are restricted to be searched to only one direction. In all other cases two alignments are calculated. For instance, if both motifs are only searched in plus direction, only one alignment is calculated. If only one motif has a second search direction two alignments are calculated.

The result of the alignment must contain three informations. First, the orientation of the two motifs for which the best alignment was obtained. It can be got calling function getOrientation(int). Second, the best alignment result, which can be obtained invoking method result(). And third, the shift value, which states, how the first motif was shifted against the second one. This value can be obtained calling the method getShiftValue().

See Also:

SequenceMotif, RegularExpressionMotif, PSPMotif, PSSMotif, PSPMotif.createPSPMotifFromSequenceMotif(RegularExpressionMotif)

Field Summary

(package private) MatrixAlignment	ma The alignment class between two matrices which must be provided when the class is constructed.
(package private) double[][][]	matrices Stores the matrices which belong to the motifs.

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

ml, motifOrientation

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

SingleMotifAlignment(MatrixAlignment ma)
Inits this class with a matrix alignment used to align the single motifs after they were transformed to matrices.

SingleMotifAlignment(MatrixAlignment ma, Motif motif1, Motif motif2)
Inits this class with a matrix alignment and two motifs.

Method Summary

boolean	add(Motif m) Adds a motif to this alignment class.
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.
void	clear() Clears the list of motifs this class contains.
int	compute() Uses all internal informations available and starts and controlls the computational process.
Motif	consensus(int normX, int normY) { @inheritDoc } Note that the type of the returned motif depends on the type of the motifs most recently added to this alignment.
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.
double	result() After computation is done the result can be obtained through this method.
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.MotifAlignment

consensus, getOrientation

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

atomicCombine, compareTo, optimum

Methods inherited from class java.lang.Object

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

Field Detail

ma

MatrixAlignment ma

The alignment class between two matrices which must be provided when the class is constructed. Set in the constructor.

matrices

double[][][] matrices

Stores the matrices which belong to the motifs. First two indices are reserved for motif one, plus and minus oriented matrices. Second two indices are for motif two. Note that unused matrices are null. This does occur in every case since only 3 matrices are needed for 2 alignments. It may occur that two values are null if both motifs are restriced in their search direction.

Constructor Detail

SingleMotifAlignment

public SingleMotifAlignment(MatrixAlignment ma)
                     throws java.lang.NullPointerException

Inits this class with a matrix alignment used to align the single motifs after they were transformed to matrices. Note, that a new instance of the matrix alignment is used.

Parameters:

ma - The alignment between matrices.

Throws:

java.lang.NullPointerException - If the given MatrixAlignment is null.

SingleMotifAlignment

public SingleMotifAlignment(MatrixAlignment ma,
                            Motif motif1,
                            Motif motif2)
                     throws java.lang.NullPointerException,
                            java.lang.IllegalArgumentException

Inits this class with a matrix alignment and two motifs. The motifs are transformed to fit into matrices, and then the matrix alignment is used to align them. motifs after they were transformed to matrices.

Parameters:

ma - The alignment between matrices (a new instance is created from it and used in this class).

motif1 - The first motif to align against the second.

motif2 - The second motif to align against the first.

Throws:

java.lang.NullPointerException - If ma is null.

java.lang.IllegalArgumentException - If one of the two motifs could not be added.

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.

consensus

public Motif consensus(int normX,
                       int normY)

{ @inheritDoc } Note that the type of the returned motif depends on the type of the motifs most recently added to this alignment. If both motifs are equal (referring to the same motif) one of them is returned. If they are not equal either a PSPM motif or a PSSM motif is returned filled with the consensus matrix got from the alignment. If one of the added motifs is a PSSMotif such a motif is returned as well. Otherwise a PSPMotif is returned. The thresholds are in both cases set to the maximum, divided by 10 for PSPMs and divided by 2 for PSSM motifs, respectively.

Specified by:

consensus in class MotifAlignment

Parameters:

normX - The normalization for the first motif.

normY - The normalization for the second motif.

Returns:

The consensus motif over the last two aligned motifs.

add

public boolean add(Motif m)

Description copied from class: MotifAlignment

Adds a motif to this alignment class. The motif is always appent to the existing motifs. Depending on the used alignment class other motifs are accepted.

It is recommended that implementing classes should not perform any time consuming operations here, but rather doing them in the compute() method.

Specified by:

add in class MotifAlignment

Parameters:

m - The motif to appent to the list.

Returns:

true, if the motif was added, false otherwise, e.g. if the motif did not met the constraint, maybe a MultiMotif was given, where a single one was expected, or vice versa.

See Also:

MultiMotif, SequenceMotif, PSPMotif

clear

public void clear()

Description copied from class: MotifAlignment

Clears the list of motifs this class contains. After doing this every call to compute() will fail, nevertheless, previously computed results will not be cleared.

Overrides:

clear in class MotifAlignment

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

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.

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.

result

public double result()

Description copied from class: RelationMeasure

After computation is done the result can be obtained through this method. If the result was not computed yet, the compute()-method will be invoked.

Overrides:

result in class RelationMeasure

Returns:

The result of the computation, if its Double.NaN , the computation is not yet finished.

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.