## org.biojava.bio.chromatogram
Class AbstractChromatogram

    java.lang.Object
      org.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()` `int`s 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 `SymbolList`s 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.