org.biojava.bio.chromatogram
Class AbstractChromatogram

java.lang.Object
  extended byorg.biojava.bio.chromatogram.AbstractChromatogram
All Implemented Interfaces:
Chromatogram
Direct Known Subclasses:
ABIFChromatogram, SCF, SimpleChromatogram

public abstract class AbstractChromatogram
extends java.lang.Object
implements Chromatogram

A basic, abstract implementation of Chromatogram. Provides protected setters so that subclasses may set the value of the various properties of a chromatogram.

Author:
Rhett Sutphin (UI CBCB)
For general use:
Chromatograms should be created using {@link ChromatogramFactory} or a parser for a particular file format.

Field Summary
 
Fields inherited from interface org.biojava.bio.chromatogram.Chromatogram
DNA, OFFSETS
 
Constructor Summary
AbstractChromatogram()
           
 
Method Summary
protected  void clearTraces()
          Sets the trace data structures to null.
protected  Alignment createImmutableAlignment(java.util.Map labelsToSymLists)
          A factory method for creating new immutable alignments, particularly for use as base call alignments.
protected  SymbolList createImmutableSymbolList(Alphabet alpha, java.util.List syms)
          A factory method for creating new symbol lists with a given alphabet.
 Alignment getBaseCalls()
          Returns an alignment that describes the base calls for this chromatogram.
 int getMax()
          Gets the max intensity from all the traces.
 int getMax(AtomicSymbol nucleotide)
          Gets the max intensity on the trace for the specified nucleotide.
 int getSequenceLength()
          Returns the number of bases called by whatever base-calling software analyzed the chromatogram as loaded.
 int getSignificantBits()
          Returns the number of bits of the traces which are significant.
 int[] getTrace(AtomicSymbol nucleotide)
          Returns an array containing the intensities of the sampled waveform representing the chromatogram trace for base nucleotide.
 int getTraceLength()
          Returns the length of the trace of the Chromatogram.
protected static int[] reverse(int[] src)
          Utility method for reversing an int[] array.
 Chromatogram reverseComplement()
          Returns a new Chromatogram representing the reverse complement of this one.
protected  SymbolList reverseComplementBaseCallList(java.lang.Object label)
          Return a symbol list containing the reverse complement of the base call data for the given label.
protected  Alignment reverseComplementBaseCalls()
          Returns a new base call alignment that is the reverse complement of one in this chromatogram.
protected abstract  AbstractChromatogram reverseComplementInstance()
          Returns a new instance of this AbstractChromatogram subclass for use in reverseComplement().
protected  void setBaseCallAlignment(Alignment align)
          Provides the list of base calls.
protected  void setBits(int bits)
          Sets the number of significant bits in the trace samples.
protected  void setTrace(AtomicSymbol nuc, int[] trace, int maxVal)
          Provides the trace samples for a particular nucleotide.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractChromatogram

public AbstractChromatogram()
Method Detail

getTrace

public int[] getTrace(AtomicSymbol nucleotide)
               throws IllegalSymbolException
Description copied from interface: Chromatogram
Returns an array containing the intensities of the sampled waveform representing the chromatogram trace for base nucleotide. This may be a reference the actual internal representation of the samples, so callers must not modify it.

The resulting array for each nucleotide must be Chromatogram.getTraceLength() ints long.

Specified by:
getTrace in interface Chromatogram
Parameters:
nucleotide - the trace to examine. Must be the symbol for A, C, G, or T as provided by DNATools
Returns:
an array of integers representing the values of a particular chromatogram trace.
Throws:
IllegalSymbolException - if nucleotide isn't in the DNA alphabet

getTraceLength

public int getTraceLength()
Description copied from interface: Chromatogram
Returns the length of the trace of the Chromatogram.

Specified by:
getTraceLength in interface Chromatogram
Returns:
the number of samples in the trace
See Also:
Chromatogram.getTrace(AtomicSymbol)

getMax

public int getMax()
Description copied from interface: Chromatogram
Gets the max intensity from all the traces. Must be equivalent to the max of calling Chromatogram.getMax(AtomicSymbol) on each of the four non-ambiguous DNA nucleotides.

Specified by:
getMax in interface Chromatogram
Returns:
the max intensity

getMax

public int getMax(AtomicSymbol nucleotide)
           throws IllegalSymbolException
Description copied from interface: Chromatogram
Gets the max intensity on the trace for the specified nucleotide.

Specified by:
getMax in interface Chromatogram
Parameters:
nucleotide - the trace to examine. Must be a concrete (non-ambiguous) nucleotide from the DNA alphabet
Returns:
the max intensity
Throws:
IllegalSymbolException - when the nucleotide isn't from the DNA alphabet

getBaseCalls

public Alignment getBaseCalls()
Description copied from interface: Chromatogram
Returns an alignment that describes the base calls for this chromatogram. All of the SymbolLists in this alignment must be the same length and that length must equal Chromatogram.getSequenceLength().

The alignment must contain, at the least, two sequences:

  1. A sequence containing the called bases. The alphabet of this list must be DNATools.getDNA(). The label for this list in the alignment must be Chromatogram.DNA
  2. A sequence containing the trace offsets at which the called bases were called. The alphabet of this list must be an IntegerAlphabet or a IntegerAlphabet.SubIntegerAlphabet. The label for this list in the alignment must be Chromatogram.OFFSETS.

Implementors may provide other sequences as they see fit.

Specified by:
getBaseCalls in interface Chromatogram
Returns:
an alignment of at least two sequences, as described above.

getSequenceLength

public int getSequenceLength()
Description copied from interface: Chromatogram
Returns the number of bases called by whatever base-calling software analyzed the chromatogram as loaded. Must equal Chromatogram.getBaseCalls().length().

Specified by:
getSequenceLength in interface Chromatogram
Returns:
the number of bases

getSignificantBits

public int getSignificantBits()
Description copied from interface: Chromatogram
Returns the number of bits of the traces which are significant. For instance, if the chromatogram were originally encoded with a single byte per trace sample, this method must return 8.

Specified by:
getSignificantBits in interface Chromatogram
Returns:
the number of significant bits

setBaseCallAlignment

protected final void setBaseCallAlignment(Alignment align)
                                   throws IllegalAlphabetException,
                                          java.lang.IllegalArgumentException,
                                          java.util.NoSuchElementException
Provides the list of base calls.

Parameters:
align - the base call alignment
Throws:
java.util.NoSuchElementException - when align doesn't contain alignments with the required DNA and OFFSETS labels
java.lang.IllegalArgumentException - the lists in align aren't all the same length.
IllegalAlphabetException - if the required lists don't have the correct alphabets. See the documentation of Chromatogram.getBaseCalls() for details.
See Also:
Chromatogram.getBaseCalls()

clearTraces

protected final void clearTraces()
Sets the trace data structures to null. If a subclass needs to replace the traces with new traces of a different length, this method must be called first to avoid provoking an IllegalArgumentException from setTrace due to a length mismatch.


setTrace

protected final void setTrace(AtomicSymbol nuc,
                              int[] trace,
                              int maxVal)
                       throws java.lang.IllegalArgumentException,
                              IllegalSymbolException
Provides the trace samples for a particular nucleotide.

Parameters:
nuc - A DNA nucleotide
trace - the trace samples themselves
maxVal - the maximum value in the trace array. If this value is Integer.MIN_VALUE, this method will do a linear search of trace to determine the max.
Throws:
java.lang.IllegalArgumentException - when trace.length is different from any of the existing (non-null) traces
IllegalSymbolException - when nuc is not a concrete DNA nucleotide

setBits

protected final void setBits(int bits)
                      throws java.lang.IllegalArgumentException
Sets the number of significant bits in the trace samples.

Parameters:
bits - a non-negative integer indicating the number of significant bits in each trace sample
Throws:
java.lang.IllegalArgumentException - when bits is negative

reverseComplementInstance

protected abstract AbstractChromatogram reverseComplementInstance()
Returns a new instance of this AbstractChromatogram subclass for use in reverseComplement().


reverseComplement

public Chromatogram reverseComplement()
Description copied from interface: Chromatogram
Returns a new Chromatogram representing the reverse complement of this one.

Implementors should copy the metadata about the chromatogram (i.e., base calls) as is appropriate to their formats.

Specified by:
reverseComplement in interface Chromatogram
Returns:
a new chromatogram that is the reverse complement of this one

reverseComplementBaseCalls

protected Alignment reverseComplementBaseCalls()
Returns a new base call alignment that is the reverse complement of one in this chromatogram. This is achieved by calling reverseComplementBaseCallList(java.lang.Object) for each label in the current base call alignment. When that method returns null, no list will appear in reverse complement base call alignment with the null-provoking label. For this reason, subclasses are encouraged to override reverseComplementBaseCallList(java.lang.Object) to handle any additional per-base metadata that they store.

This implementation should be safely inheritable for all chromatogram implementations, unless one just doesn't want base calls on its reverse complement output. If this is the case, it should override this method to return null.

Returns:
a new Alignment that is the reverse complement of the one in the current chromatogram

reverseComplementBaseCallList

protected SymbolList reverseComplementBaseCallList(java.lang.Object label)
Return a symbol list containing the reverse complement of the base call data for the given label. The returned list will be stored in the reverse complement's base call alignment under the same label.

Implementation note: subclasses which do not use an IntegerAlphabet for their offsets lists must override this method, at least for the case where label == Chromatogram.OFFSETS.

Returns:
an appropriately reverse-complemented SymbolList, or null if the label is unhandled.

createImmutableSymbolList

protected SymbolList createImmutableSymbolList(Alphabet alpha,
                                               java.util.List syms)
                                        throws IllegalSymbolException,
                                               java.lang.ClassCastException
A factory method for creating new symbol lists with a given alphabet. The default implementation should be fine for nearly all cases, but the option is given in case a developer wishes to use a more memory efficient implementation.

Parameters:
alpha - the Alphabet for the new list
syms - the symbols to put in the new list
Returns:
a new immutable SymbolList containing all the given symbols using the given Alphabet
Throws:
IllegalSymbolException - when alpha and syms are incompatible
java.lang.ClassCastException - when any object in syms isn't a Symbol

createImmutableAlignment

protected Alignment createImmutableAlignment(java.util.Map labelsToSymLists)
                                      throws java.lang.IllegalArgumentException,
                                             java.lang.ClassCastException
A factory method for creating new immutable alignments, particularly for use as base call alignments. The default implementation should be fine for nearly all cases.

Parameters:
labelsToSymLists - a Map whose keys are desired labels for the alignment and whose values are the SymbolLists. All the SymbolLists must be the same length.
Throws:
java.lang.IllegalArgumentException - if the lists aren't all the same length
java.lang.ClassCastException - if any of the values in the map aren't SymbolLists

reverse

protected static final int[] reverse(int[] src)
Utility method for reversing an int[] array. Visible for subclass use.