001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021
022package org.biojava.bio.chromatogram;
023
024import org.biojava.bio.symbol.IntegerAlphabet;
025import org.biojava.bio.symbol.SymbolList;
026
027/**
028 * Utility class for dealing with {@link Chromatogram}s.
029 *
030 * @author Rhett Sutphin (<a href="http://genome.uiowa.edu/">UI CBCB</a>)
031 * @author Matthew Pocock
032 * @since 1.3
033 */
034public class ChromatogramTools {
035    /** Static utility class - don't allow it to be instantiated. */
036    private ChromatogramTools() { }
037    
038    /**
039     * Get the called DNA sequence from a chromatogram.  A synonym for
040     * <code>chromat.getBaseCalls().symbolListForLabel(Chromatogram.DNA)</code>.
041     *
042     * @param chromat  the Chromatogram to process
043     * @return a SymbolList containing the DNA
044     */
045    public static final SymbolList getDNASequence(Chromatogram chromat) {
046        return chromat.getBaseCalls().symbolListForLabel(Chromatogram.DNA);
047    }
048    
049    /**
050     * Get the peak offsets for the called bases of a chromatogram.  A synonym 
051     * for <code>chromat.getBaseCalls().symbolListForLabel(Chromatogram.OFFSETS)</code>.
052     *
053     * @param chromat  the Chromatogram to process
054     * @return a SymbolList of offsets
055     */
056    public static final SymbolList getTraceOffsets(Chromatogram chromat) {
057        return chromat.getBaseCalls().symbolListForLabel(Chromatogram.OFFSETS);
058    }
059    
060    /**
061     * Converts the peak offsets list of the given chromatogram
062     * into a new <code>int</code> array.
063     * <p>
064     * The array is, of course, allocated and initialized at each call,
065     * so using this method like this:
066     * <pre>
067     * for (int i = m ; i < n ; i++)
068     *    doSomething(getTraceOffsetArray(c)[i]);
069     * </pre>
070     * is not recommended.
071     *
072     * @param chromat the Chromatogram to process
073     * @return an array of integers representing peak offsets
074     */
075    public static final int[] getTraceOffsetArray(Chromatogram chromat) {
076        int[] array = new int[chromat.getSequenceLength()];
077        for (int i = 0 ; i < array.length ; i++) {
078            array[i] = getTraceOffset(chromat, i+1);
079        }
080        return array;
081    }
082    
083    /**
084     * Get a specific value from the trace offset sequence in the given
085     * chromatogram and extract its <code>int</code> value.
086     * 
087     * @param chromat the chromatogram to examine
088     * @param which which symbol in the trace offset sequence to
089     *        get.  1-based index.
090     * @return the offset for that peak
091     */
092    public static final int getTraceOffset(Chromatogram chromat, int which) {
093        return getIntFromSymbolList(chromat.getBaseCalls().symbolListForLabel(Chromatogram.OFFSETS), which);
094    }
095    
096    /**
097     * Retrieves, unwraps, and returns an <code>int</code> from a
098     * SymbolList containing {@link org.biojava.bio.symbol.IntegerAlphabet.IntegerSymbol}s.
099     * @param list the target list
100     * @param which which symbol to unwrap and return.  1-based index.
101     * @return the integer represented by the symbol at that position
102     */
103    public static final int getIntFromSymbolList(SymbolList list, int which) {
104        return ((IntegerAlphabet.IntegerSymbol) list.symbolAt(which)).intValue();
105    }
106    
107}