de.unibi.techfak.jpredictor.motifs
Class MultiMotif

java.lang.Object
  de.unibi.techfak.jpredictor.motifs.MotifSearchAdapter
      de.unibi.techfak.jpredictor.motifs.Motif
          de.unibi.techfak.jpredictor.motifs.MultiMotif

All Implemented Interfaces:

MotifSearcher, SequenceWindowScorer, Markable, java.lang.Cloneable, java.lang.Comparable

Direct Known Subclasses:

DoubleMotif

public class MultiMotif
extends Motif

Superclass of all classes representing a pattern made of more then one motif. For the task of defining motif patterns, there are two 'add'-methods:

                add( Motif motif, int minDistance, int maxDistance )
                add( Motif motif  )
 

A DoubleMotif is declared like this:

                MultiMotif d = new MultiMotif;
                d.add( firstMotif, 0, 1000 );
                d.add( secondMotif );
 

If 'secondMotif' can be found within a radius of 1000 bases of 'firstMotif', this MultiMotif was found in the sequence. A MultiMotif is completed by giving the final motif without the distances.

When performing searches the MultiMotif has to be initialized by calling initSearch(CharSequence). This is the same procedure as initializing the single motifs. Doing so, there is no need to call initSearch(CharSequence)-method for every single motif. All search initializations have to be done on a completed MultiMotif, otherwise any single motif added later is not proper initialized. This can be a source of error.

Another source of error is this scenario: imagine a single motif, like a PHO-motif (PSSMotif), which occurs in 2 MultiMotifs. If both MultiMotifs are initialized with the same CharSequence, all will be well. If you got two different sequences to search on and initialize the two MultiMotifs each with another CharSequence, then the PHO is sought only on the second sequence. The same applies for stand- alone single motifs: motifs, respectivly the submotifs in a MultiMotif, remember always only the last CharSequence given to initialize the search.

The procedure for searching without performance loses is like this:

1. Define the needed SequenceMotif's, RegularExpressionMotif's, PSPMotif's and PSSMotif's
2. Combine these single motifs into as many MultiMotifs as you want
3. init all MultiMotifs with the same CharSequence to search on by calling their initSearch(CharSequence)-method.
4. Search for the MultiMotifs
5. Go back to point 3 to search on another sequence, or back to 1 or 2, respectively, to work a changed set of motifs.

Nested Class Summary

Nested classes/interfaces inherited from class de.unibi.techfak.jpredictor.motifs.MotifSearchAdapter

MotifSearchAdapter.SearchFields

Field Summary

protected int[]	distances The distances between the motifs.
protected MotifList	motifs Vector for storage of all motifs within this class

Fields inherited from class de.unibi.techfak.jpredictor.motifs.Motif

DNA_DEGENERATED_CODE, DNA_DEGENERATED_CODE_JOINING, MARK_USABLE

Fields inherited from class de.unibi.techfak.jpredictor.motifs.MotifSearchAdapter

searchFields

Fields inherited from interface de.unibi.techfak.jpredictor.motifs.MotifSearcher

SEARCH_ALL_ORIENTATIONS, SEARCH_DIRECTION_MAX, SEARCH_DIRECTION_MINUS, SEARCH_DIRECTION_PLUS

Fields inherited from interface de.unibi.techfak.misc.Markable

MARK_BASIC, MARK_DELETED, MARK_EXP, MARK_MOVED, MARK_REPLACED, MARK_SELECTED, MARK_TOBEDELETED, MARK_TOBEMOVED, MARK_TOBEREPLACED

Constructor Summary

MultiMotif(java.lang.String name, java.lang.String description)
Creates a MultiMotif with a name and a description.

Method Summary

int	add(Motif motif) Adds a motif to this MultiMotif.
int	add(Motif motif, int minDistance, int maxDistance) Adds a motif and the distances to the next motif to this MultiMotif.
boolean	checkMultiMotif() Checks for this MultiMotif to be complete.
boolean	checkMultiMotifForCycles() Checks for this MultiMotif to contain a cycle.
java.lang.Object	clone() Clones the motif by creating the same motif again and copying all importent fields.
int	compareTo(java.lang.Object o) Compares this motif with the specified object.
Motif	createReversedComplement() The structure of this MultiMotif is reversed and also the motifs stored are reversed and complemented.
int[]	getDistances() The distances are returned as an integer array.
Motif	getMotif(int index) Returns a motif within this container.
(package private) MotifList	getMotifs() Returns the motif list, the MultiMotif is built upon.
java.lang.String	getRegularExpression() Generates the regular expression represented by the motif.
int	initSearch(java.lang.CharSequence sequ) Inits the search on the underlying single motifs combined in this MultiMotif.
int	length() Returns the number of motifs within this MultiMotif.
void	print(java.io.PrintStream out) Prints this MultiMotif via a PrintStream.
java.lang.String	replaceMotif(Motif motif, int index) Replaces a motif in this MultiMotif with the given one.
FoundMotifStruct	search(int seqStart, int seqWidth) Runs through the sequence already given in the initialization method initSearch and matches the motif on this CharSequence with respect to the search mode and the search window determined by the two parameters seqStart and seqWidth.
java.util.LinkedList	searchAll(int seqStart, int seqWidth) Searches this motif on a sequence.
protected java.util.LinkedList	searchChoose(int seqStart, int seqWidth, boolean all) Searches this multi motif on a sequence.
boolean	testDist(int[] starts, int[] ends, int index) Tests, whether the distance between motifs is in the min-max-range.
boolean	testDistRevComp(int[] starts, int[] ends, int index) Tests, whether the distance between motifs is in the min-max-range, if this motif is read reversed/complementary.

Methods inherited from class de.unibi.techfak.jpredictor.motifs.Motif

clearMark, clearMark, equals, getConsensusSequence, getDescription, getMark, getName, getWeight, isMarked, isMarked, print, scoreSequenceWindow, setDescription, setMark, setName, setWeight, toString

Methods inherited from class de.unibi.techfak.jpredictor.motifs.MotifSearchAdapter

getSearchMode, setSearchMode

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.unibi.techfak.jpredictor.motifs.MotifSearcher

getSearchMode, setSearchMode

Field Detail

motifs

protected MotifList motifs

Vector for storage of all motifs within this class

distances

protected int[] distances

The distances between the motifs. This vector is of length 2*(this.motifs.size()-1)

Constructor Detail

MultiMotif

public MultiMotif(java.lang.String name,
                  java.lang.String description)

Creates a MultiMotif with a name and a description. All other intern variables are set to defaults. Now motifs can be added using add(Motif, int, int) or add(Motif).

Parameters:

name - The name of the multi motif.

description - A short description of this motif.

Method Detail

getRegularExpression

public java.lang.String getRegularExpression()

Generates the regular expression represented by the motif.

Overrides:

getRegularExpression in class Motif

Returns:

The motif as a regular expression using the degenerated DNA code.

checkMultiMotif

public boolean checkMultiMotif()

Checks for this MultiMotif to be complete. No new motifs can be added to a finished MultiMotif. A MultiMotif is complete, if one more motif is present then distance pairs.

Returns:

true if this motif is completed properly, false otherwise (then single motifs can be added).

checkMultiMotifForCycles

public boolean checkMultiMotifForCycles()

Checks for this MultiMotif to contain a cycle. A cycle can be constructed if one motif within this MultiMotif is this MultiMotif itself, or is a motif higher in the hierarchie, or is another MultiMotif referring back to this MultiMotif.

Returns:

true if this motif contains cycles, false otherwise.

add

public int add(Motif motif,
               int minDistance,
               int maxDistance)
        throws CycleInMultiMotifExeption

Adds a motif and the distances to the next motif to this MultiMotif. If minDistance>maxDistance both are exchanged. Sets a description of the new motif to reflect this change.

Parameters:

motif - The motif to be added to this MultiMotif.

minDistance - The minimal distance to the still not present next motif.

maxDistance - The maximal distance to the still not present next motif.

Returns:

Zero in case of no error, -1 in case of parameter error (e.g. motif==null), -2 if this MultiMotif is already completed

Throws:

CycleInMultiMotifExeption - If adding the motif would lead to a cycle in the motif.

add

public int add(Motif motif)
        throws CycleInMultiMotifExeption

Adds a motif to this MultiMotif. The added motif finishes this MultiMotif. A new description of this motif is generated to reflect the changes made.

Parameters:

motif - The last motif to be added.

Returns:

Zero in case of no error, -1 in case of parameter error (e.g. if motif==null, -2 if this method was already succesfully called.

Throws:

CycleInMultiMotifExeption - If adding the motif would lead to a cycle in the motif.

replaceMotif

public java.lang.String replaceMotif(Motif motif,
                                     int index)
                              throws java.lang.NullPointerException,
                                     java.lang.IndexOutOfBoundsException,
                                     CycleInMultiMotifExeption

Replaces a motif in this MultiMotif with the given one. The method generates a new description but does not set it.

Parameters:

motif - The motif to be inserted.

index - The position of the motif to be replaced.

Returns:

The newly generated description.

Throws:

java.lang.NullPointerException - If motif is null.

java.lang.IndexOutOfBoundsException - If index is less than zero and greater or equal than this.length().

CycleInMultiMotifExeption - If replacing the motif would lead to a cycle in the motif.

initSearch

public int initSearch(java.lang.CharSequence sequ)
               throws MotifNotCompleteException

Inits the search on the underlying single motifs combined in this MultiMotif. For all stored single motifs their specific initSearch() is called. Note, that this MultiMotif should be fully assambled when calling this method, otherwise an exception is thrown. In this case no initialization is done.

Specified by:

initSearch in interface MotifSearcher

Overrides:

initSearch in class MotifSearchAdapter

Parameters:

sequ - the sequence for all search methods to search on.

Returns:

Zero.

Throws:

MotifNotCompleteException - If the MultiMotif is not fully completed.

See Also:

MotifSearcher.initSearch(CharSequence)

search

public FoundMotifStruct search(int seqStart,
                               int seqWidth)
                        throws MissingCharSequenceException,
                               MissingMotifException

Description copied from interface: MotifSearcher

Runs through the sequence already given in the initialization method initSearch and matches the motif on this CharSequence with respect to the search mode and the search window determined by the two parameters seqStart and seqWidth.
The first occurance of the motif on the sequence is returned as FoundMotifStruct with positions absolute to the sequence window. Note, that this method verifies no previous searches, instead it searches always new. If the motif was not found, null is returned.
The id of the returned struct is misused as a flag determining the search direction (search mode) the found motif was (any combination of SEARCH_DIRECTION_PLUS and SEARCH_DIRECTION_MINUS). Note, that it is possible, that a motif can occur more than once at the same position, e.g. the regular expression motif CNGCCATNDNND and its reversed complemented part HNNHNATGGCTG can both be matched on the sequence CGGCCATGGCTG. In case both search direction occur, the motif start and end position is always for plus direction. For a reversed complemented motif end is less than start.
If an error occured reading the sequence or if this method tried to read further than the sequence's size or if the motif could not be found on the sequence, null is returned.

Parameters:

seqStart - Search starts with this index.

seqWidth - The width of the subsequence to search on.

Returns:

The first occurance of the motif on the subsequence or null if the motif could not be found on the sequence.

Throws:

MissingCharSequenceException - If no sequence to search on was set.

MissingMotifException - If no motif to search for was set.

See Also:

MotifSearcher.initSearch(CharSequence), MotifSearcher.SEARCH_DIRECTION_PLUS, MotifSearcher.SEARCH_DIRECTION_MINUS

searchAll

public java.util.LinkedList searchAll(int seqStart,
                                      int seqWidth)
                               throws MissingCharSequenceException,
                                      MissingMotifException

Searches this motif on a sequence. All this method does is checking for the sequence window given and then calling searchChoose(int, int, true)>/code>.

Specified by:

searchAll in interface MotifSearcher

Overrides:

searchAll in class MotifSearchAdapter

Parameters:

seqStart - The search start index on the sequence.

seqWidth - The width of the sequence window.

Returns:

A linked list of FoundMotifStruct-objects.

Throws:

MissingCharSequenceException - If one of the used single motifs was not proper initialzed with a search sequence.

MissingMotifException - If the MultiMotif is of length 0 or if one underlying single motif's search-method throws this.

See Also:

searchChoose(int, int, boolean)

searchChoose

protected java.util.LinkedList searchChoose(int seqStart,
                                            int seqWidth,
                                            boolean all)
                                     throws MissingCharSequenceException,
                                            MissingMotifException

Searches this multi motif on a sequence. The sequence was previously given by calling initSearch(CharSequence).
This method functions the following: First, the single motifs search(int, int)-method is called, then the returned occurrences are calculated to distances and matched with the minimal and maximal distances set for this multi motif.
The linked list returned contains FoundMotifStruct- objects, which for every hit hold the start and end-positions of all single motifs.

Parameters:

seqStart - The search start index on the sequence.

seqWidth - The width of the sequence window.

all - Decides whether the method stores all hits in the list befor returning (all==true) or if it returns right after the first one.

Returns:

A linked list of FoundMotifStruct-objects.

Throws:

MissingCharSequenceException - If one of the used single motifs was not proper initialzed with a search sequence.

MissingMotifException - If the MultiMotif is of length 0 or if one underlying single motif's search-method throws this.

testDist

public boolean testDist(int[] starts,
                        int[] ends,
                        int index)
                 throws java.lang.ArrayIndexOutOfBoundsException,
                        java.lang.NullPointerException

Tests, whether the distance between motifs is in the min-max-range.

The distance is calculated from the indexed motif's start position to the end of the previous motif:

starts[index]-ends[index-1]-1

. The order of the arrays is always assumed to be ascending.

The minimum and maximum are taken from this MultiMotif. Again, index names the subsequent motif, and index-1 names the preceding motif. The minimum and maximum distance of these two motifs are compared against the calculated distance.

Parameters:

starts - The start positions of the motifs.

ends - The end positions of the motifs.

index - The index of the motif which distance to the previous motif is tested.

Returns:

true, if the distance is greater or equal to the minimum and less or equal than the maximum

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the arrays are accessed with an index greater or equal its length and smaller than zero.

java.lang.NullPointerException - If one of the accessed arrays is null.

testDistRevComp

public boolean testDistRevComp(int[] starts,
                               int[] ends,
                               int index)
                        throws java.lang.ArrayIndexOutOfBoundsException,
                               java.lang.NullPointerException

Tests, whether the distance between motifs is in the min-max-range, if this motif is read reversed/complementary.

The distance is calculated from the indexed motif's start position to the end of the previous motif:

starts[index]-ends[index-1]-1

. The order of the arrays is always assumed to be ascending.

The minimum and maximum are taken from this MultiMotif. Here, len-index names the subsequent motif, and len-index-1 names the preceding motif. The minimum and maximum distance of these two motifs are compared against the calculated distance.

Parameters:

starts - The start positions of the motifs.

ends - The end positions of the motifs.

index - The index of the motif which distance to the previous motif is tested.

Returns:

true, if the distance is greater or equal to the minimum and less or equal than the maximum

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the arrays are accessed with an index greater or equal its length and smaller than zero.

java.lang.NullPointerException - If one of the accessed arrays is null.

length

public int length()

Returns the number of motifs within this MultiMotif. This behavior differs from the meaning of length, but it is unclear, whats the length for a multi motif is.

Specified by:

length in class MotifSearchAdapter

Returns:

The number of motifs within this MultiMotif.

print

public void print(java.io.PrintStream out)

Prints this MultiMotif via a PrintStream. Each single motif is printed by calling their print(out)-method, inbetween the minimal and maximal distance in a new line.

Specified by:

print in class Motif

Parameters:

out - The stream to print this motif to.

createReversedComplement

public Motif createReversedComplement()

The structure of this MultiMotif is reversed and also the motifs stored are reversed and complemented. The normal case looks like this:

        befor:  motif1 - distance1 - motif2 - distance2 - motif3 + score
        after:  motif3 - distance2 - motif2 - distance1 - motif1 + score
 

All other cases of motif order (if this motif is not completed properly) are not computed and thus null is returned.
The name and description are set from this MultiMotif by adding a 'c' as prefix to the name and a 'reversed ' as prefix to the description.

Specified by:

createReversedComplement in class Motif

Returns:

The newly created MultiMotif, null in case of error

See Also:

Motif.createReversedComplement()

getDistances

public int[] getDistances()

The distances are returned as an integer array. The content of the array is designed the way, that every two positions hold a minimum and a maximum distance between two adjacent motifs:

 [min_1, max_1, min_2, max_2, ..., min_N, max_N]

, where N is either this.length(), if this MultiMotif is not completed yet or this.length()-1.

Note, that the returned distances are also the ones this class works with, so do not change them.

Returns:

An array of integer with the motif's distances.

getMotif

public Motif getMotif(int index)

Returns a motif within this container. Note, that the returned motif is not cloned before it is returned. Thus, changing it will affect the stored instance, too, but also every MultiMotif where an instance of this motif is used.

Returns:

One of the motifs that are comprised in this MultiMotif. Returns null if an error occured (e.g. index>=this.length()).

getMotifs

MotifList getMotifs()

Returns the motif list, the MultiMotif is built upon. Its the same list this class works with, so do not change it unless you know exactly what you do.

Returns:

The internal motif list.

clone

public java.lang.Object clone()

Description copied from class: Motif

Clones the motif by creating the same motif again and copying all importent fields. The result is at least of class Motif. When cloning a MultiMotif the referred single motifs are not cloned.

The fields that are copied are: Name, Description, the Motif itself, errorNumberAllowedForMatch or Threshold, respectively, Weight and searchMode (altogether 6 fields by now). What is not copied are the fields of the MotifSearchAdapter.

Note, that any matrices are not cloned. Thus, if cloning a PSPMotif or a PSSMotif the cloned motif does contain a reference to the matrix of the old motif. This was done to preserve memory.

Specified by:

clone in class Motif

Returns:

The Motif itself as a doubled copy.

See Also:

Object.clone()

compareTo

public int compareTo(java.lang.Object o)

Description copied from class: Motif

Compares this motif with the specified object. The Object given must be a Motif and must not be null, otherwise a ClassCastException is thrown. If for this motif or the given one, the motif representation was not set, a ClassCastException is thrown as well.

Two motifs are compared for their representations, both plus and minus depending on the search direction. Both motifs must be of the same type, otherwise the following relation is considered: SequenceMotif < PSPMotif < MultiMotif and returned without further investigations. Note, that RegularExpressionMotif s count as SequenceMotifs and that PSSMotif s count as PSPMotifs. In case of comparing two MultiMotifs, after comparing the comprised single motifs the distance informations are taken into account: first minimum vs. first minimum, then first maximum, second minimum, and so on. In the last instance two sequence motifs are compared for their error number allowed for match, whereas two position specific matrix motifs are compared for their threshold.

More formaly, this motif is less than the specified one if this reg-exp string is less than the one from the specified motif.

Specified by:

compareTo in interface java.lang.Comparable

Specified by:

compareTo in class Motif

Parameters:

o - The motif this method is compared to.

Returns:

Minus one, zero or one as this motif is less than, equal or greater than the specified motif.