org.biojava.bio.seq
Class SequenceTools

java.lang.Object
  extended by org.biojava.bio.seq.SequenceTools

public final class SequenceTools
extends java.lang.Object

Methods for manipulating sequences.

Author:
Matthew Pocock

Method Summary
static void addAllFeatures(Sequence seq, FeatureHolder fh)
          Add features to a sequence that contain the same information as all those in a feature holder.
static Sequence createDummy(Alphabet alpha, int length, Symbol sym, java.lang.String uri, java.lang.String name)
          Create a new Sequence that contains a single symbol repeated over and over.
static Sequence createDummy(java.lang.String uri, java.lang.String name)
          Create a new Sequence that has no annotation, no features and a zero-length symbol list.
static Sequence createSequence(SymbolList syms, java.lang.String uri, java.lang.String name, Annotation ann)
           
static GappedSequence gappedView(Sequence seq)
          Create a new gapped sequence for a sequence.
static Sequence maskSequence(Sequence seq, RangeLocation loc)
          Mask of a sequence.
static Sequence reverseComplement(Sequence seq)
          Reverse-complement a sequence, and flip all of its features.
static Sequence subSequence(Sequence seq, int start, int end)
          Extract a sub-sequence from a sequence.
static Sequence subSequence(Sequence seq, int start, int end, java.lang.String name)
          Extract a sub-sequence from a sequence.
static Sequence subSequence(Sequence seq, int start, int end, java.lang.String name, StrandedFeature.Strand strand)
          Extract a sub-sequence from a sequence.
static ViewSequence view(Sequence seq)
          Create a new sequence that has all of the data in the original, but allows new features and top-level annotations to be added independantly.
static ViewSequence view(Sequence seq, FeatureRealizer fr)
          Creates a new Sequence with the data of the old but with a different FeatureRealizer that will be applied to new Features.
static ViewSequence view(Sequence seq, java.lang.String name)
          Create a new sequence that has all of the data in the original, but allows new features and top-level annotations to be added independantly.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

createSequence

public static Sequence createSequence(SymbolList syms,
                                      java.lang.String uri,
                                      java.lang.String name,
                                      Annotation ann)

subSequence

public static Sequence subSequence(Sequence seq,
                                   int start,
                                   int end)
                            throws java.lang.IndexOutOfBoundsException
Extract a sub-sequence from a sequence.

The sub-sequence will be indexed from 1 through to (end-start+1). An index of i in the sub-sequence corresponds to (i+start-1) in the original. All features from the original sequence will be projected down into this co-ordinate system. All features overlapping the edges will be given fuzzy locations.

Parameters:
seq - the sequence to sub-sequence
start - the first index to include in the sub-sequence
end - the last index to include in the sub-sequence
Returns:
a view Sequence for this region
Throws:
java.lang.IndexOutOfBoundsException - if start or end are not in seq, or if end < start

subSequence

public static Sequence subSequence(Sequence seq,
                                   int start,
                                   int end,
                                   java.lang.String name)
                            throws java.lang.IndexOutOfBoundsException
Extract a sub-sequence from a sequence.

The sub-sequence will be indexed from 1 through to (end-start+1). An index of i in the sub-sequence corresponds to (i+start-1) in the original. All features from the original sequence will be projected down into this co-ordinate system. All features overlapping the edges will be given fuzzy locations.

Parameters:
seq - the sequence to sub-sequence
start - the first index to include in the sub-sequence
end - the last index to include in the sub-sequence
name - a new name to give to this sub-sequence
Returns:
a view Sequence for this region
Throws:
java.lang.IndexOutOfBoundsException - if start or end are not in seq, or if end < start

subSequence

public static Sequence subSequence(Sequence seq,
                                   int start,
                                   int end,
                                   java.lang.String name,
                                   StrandedFeature.Strand strand)
                            throws java.lang.IndexOutOfBoundsException,
                                   IllegalAlphabetException
Extract a sub-sequence from a sequence.

The sub-sequence will be indexed from 1 through to (end-start+1). If the strand is NEGATIVE, all features will be flipped in the same manner as the reverseComplement method. If it is UNKNOWN or POSITIVE, then this is identical to the other subSequence methods.

Parameters:
seq - the sequence to sub-sequence
start - the first index to include in the sub-sequence
end - the last index to include in the sub-sequence
name - a new name to give to this sub-sequence
strand - a StrandedFeature.Strand indicating which strand the sub-sequence should be on
Returns:
a view Sequence for this region
Throws:
java.lang.IndexOutOfBoundsException - if start or end are not in seq, or if end < start
IllegalAlphabetException

reverseComplement

public static Sequence reverseComplement(Sequence seq)
                                  throws IllegalAlphabetException
Reverse-complement a sequence, and flip all of its features.

Parameters:
seq - the Sequence to reverse-complement
Returns:
the flipped Sequence
Throws:
IllegalAlphabetException - if the symbols in the sequence can not be complemented

view

public static ViewSequence view(Sequence seq)
Create a new sequence that has all of the data in the original, but allows new features and top-level annotations to be added independantly. Use this as a scratch-space.

Parameters:
seq - the Sequence to view
Returns:
a new ViewSequence

view

public static ViewSequence view(Sequence seq,
                                java.lang.String name)
Create a new sequence that has all of the data in the original, but allows new features and top-level annotations to be added independantly. Use this as a scratch-space.

Parameters:
seq - the Sequence to view
name - a new name for the sequence
Returns:
a new ViewSequence with the new name

view

public static ViewSequence view(Sequence seq,
                                FeatureRealizer fr)
Creates a new Sequence with the data of the old but with a different FeatureRealizer that will be applied to new Features.

Parameters:
seq - the Sequence to wrap
fr - the new FeatureRealizer
Returns:
the new ViewSequence

gappedView

public static GappedSequence gappedView(Sequence seq)
Create a new gapped sequence for a sequence.

The gapped sequence can be used to insert gaps. The features on the underlying sequence will be projected onto the view taking the gaps into account.

Parameters:
seq -
Returns:
a GappedSequence view of seq

maskSequence

public static Sequence maskSequence(Sequence seq,
                                    RangeLocation loc)
                             throws java.lang.IndexOutOfBoundsException,
                                    java.lang.IllegalArgumentException
Mask of a sequence.

This will return a view of a sequence where everything outside loc is dropped. This includes all symbols, which become gaps, and all features, which behave in a similar manner to those produced by subSequence().

Parameters:
seq - the Sequence to mask
loc - the region to retain
Returns:
a Sequence viewing just the retained portion of seq
Throws:
java.lang.IndexOutOfBoundsException - if loc is not totaly within seq
java.lang.IllegalArgumentException - fixme: not sure where this comes from

createDummy

public static Sequence createDummy(java.lang.String uri,
                                   java.lang.String name)
Create a new Sequence that has no annotation, no features and a zero-length symbol list.

Parameters:
uri - the URI to give the dummy sequence
name - the name of the dummy sequence
Returns:
a dummy Sequence
For general use:
Instantiate this if an API requres a sequence, but you can't be bothered or are not able to provide full sequence information.
For advanced users:
It is sometimes usefull to create a dummy sequence and then wrap this in a view.

createDummy

public static Sequence createDummy(Alphabet alpha,
                                   int length,
                                   Symbol sym,
                                   java.lang.String uri,
                                   java.lang.String name)
                            throws IllegalSymbolException
Create a new Sequence that contains a single symbol repeated over and over.

Parameters:
alpha - the Alphabet this sequence is over
length - the length of the sequence
sym - the symbol returned by every call to symbolAt
uri - the URI of the sequence
name - the name of the sequence
Returns:
a new sequence of the right length
Throws:
IllegalSymbolException - if sym is not in alpha
Since:
1.4

addAllFeatures

public static void addAllFeatures(Sequence seq,
                                  FeatureHolder fh)
                           throws ChangeVetoException,
                                  BioException
Add features to a sequence that contain the same information as all those in a feature holder.

Parameters:
seq - the Sequence to add features to
fh - the features to add
Throws:
ChangeVetoException - if the sequence could not be modified
BioException - if there was an error creating the features