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.symbol;
023
024/**
025 * <p>Encapsulates the mapping from a source to a destination
026 * alphabet.</p>
027 *
028 * <p>A TranslationTable is in effect a map or function with the
029 * source domain being getSourceAlphabet() and the target domain being
030 * getTargetAlphabet().  The method translate() maps a single symbol
031 * from source to target.</p>
032 *
033 * <p>It is presumed that there will be some explicit declaration of
034 * the mapping for attomic symbols, and that the mapping for all other
035 * symbols will be infered from these.</p>
036 *
037 * <p>If you wish to translate every symbol in a symbol list then use
038 * TranslatedSymbolList to automate the job. If you want to translate
039 * windowed regions then first construct a WindowedSymbolList from the
040 * original sequence and then build a TranslatedSymbolList from this
041 * windowed view.</p>
042 *
043 * <p>There are a range of named tables available. Their names are
044 * specified by the public static final fields in this interface. Each
045 * table can be retrieved by calling the static method
046 * RNATools.getGeneticCode(name) which will return the appropriate
047 * TanslationTable instance.</p>
048 *
049 * @author Matthew Pocock
050 * @author Keith James
051 */
052public interface TranslationTable {
053    /**
054     * Translation table name for the universal genetic code.
055     */
056    public static final String UNIVERSAL = "UNIVERSAL";
057
058    /**
059     * Translation table name for the vertebrate mitochondrial genetic
060     * code.
061     */
062    public static final String VERT_MITO = "VERTEBRATE_MITOCHONDRIAL";
063
064    /**
065     * Translation table name for the yeast mitochondrial genetic
066     * code.
067     */
068    public static final String YEAST_MITO = "YEAST_MITOCHONDRIAL";
069
070    /**
071     * Translation table name for the mold mitochondrial genetic code.
072     */
073    public static final String MOLD_MITO = "MOLD_MITOCHONDRIAL";
074
075    /**
076     * Translation table name for the invertebrate mitochondrial
077     * genetic code.
078     */
079    public static final String INVERT_MITO = "INVERTEBRATE_MITOCHONDRIAL";
080
081    /**
082     * Translation table name for the ciliate nuclear genetic code.
083     */
084    public static final String CILIATE_NUC = "CILIATE_NUCLEAR";
085
086    /**
087     * Translation table name for the echinoderm mitochondrial genetic
088     * code.
089     */
090    public static final String ECHIN_MITO = "ECHINODERM_MITOCHONDRIAL";
091
092    /**
093     * Translation table name for the euplotid nuclear genetic code.
094     */
095    public static final String EUPL_NUC = "EUPLOTID_NUCLEAR";
096    
097    /**
098     * Translation table name for the bacterial and plant plastid genetic code.
099     */
100    public static final String BACTERIAL = "BACTERIAL";
101
102    /**
103     * Translation table name for the alternative yeast nuclear
104     * genetic code.
105     */
106    public static final String ALT_YEAST_NUC = "ALTERNATIVE_YEAST_NUCLEAR";
107
108    /**
109     * Translation table name for the ascidian mitochondrial genetic
110     * code.
111     */
112    public static final String ASCID_MITO = "ASCIDIAN_MITOCHONDRIAL";
113
114    /**
115     * Translation table name for the flatworm mitochondrial genetic
116     * code.
117     */
118    public static final String FWORM_MITO = "FLATWORM_MITOCHONDRIAL";
119
120    /**
121     * Translation table name for the blepharisma macronuclear genetic
122     * code.
123     */
124    public static final String BLEPH_MNUC = "BLEPHARISMA_MACRONUCLEAR";
125    /**
126     * Translation table name for the chlorophycean mitochondrial genetic
127     * code.
128     */
129    public static final String CHLORO_MITO = "CHLOROPHYCEAN_MITOCHONDRIAL";
130    /**
131     * Translation table name for the trematode mitochondrial genetic
132     * code.
133     */
134    public static final String TREMA_MITO = "TREMATODE_MITOCHONDRIAL";
135    /**
136     * Translation table name for the scenedesmus obliquus mitochondrial genetic
137     * code.
138     */
139    public static final String SCENE_MITO = "SCENEDESMUS_MITOCHONDRIAL";
140
141  /**
142   * The alphabet of Symbols that can be translated.
143   *
144   * @return the source Alphabet
145   */
146  public Alphabet getSourceAlphabet();
147  
148  /**
149   * The alphabet of Symbols that will be produced.
150   *
151   * @return the target Alphabet
152   */
153  public Alphabet getTargetAlphabet();
154  
155  /**
156   * Translate a single symbol from source alphabet to the target alphabet.
157   *
158   * @param sym the Symbol to translate (member of source alphabet)
159   * @return the translated version of sym (member of target alphabet)
160   * @throws IllegalSymbolException if sym is not a member of the source
161   *         alphabet
162   */
163  public Symbol translate(Symbol sym) throws IllegalSymbolException;
164}