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 */
021package org.biojavax.ga.functions;
022
023import org.biojava.bio.dist.OrderNDistribution;
024import org.biojava.bio.symbol.IllegalAlphabetException;
025import org.biojava.bio.symbol.IllegalSymbolException;
026import org.biojava.bio.symbol.SymbolList;
027import org.biojava.utils.ChangeListener;
028import org.biojava.utils.ChangeType;
029import org.biojava.utils.ChangeVetoException;
030import org.biojava.utils.Changeable;
031
032/**
033 * <p>A class that mutates a <code>SymbolList</code></p>
034 * @author Mark Schreiber
035 * @version 1.0
036 * @since 1.5
037 */
038
039public interface MutationFunction extends Changeable{
040   public static final double[] DEFAULT_MUTATION_PROBS = {0.0};
041
042   public static final ChangeType MUTATION_PROBS =
043      new ChangeType("mutation probabilities",MutationFunction.class,"MUTATION_PROBS");
044   public static final ChangeType MUTATION_SPECTRUM =
045      new ChangeType("mutation spectrum",MutationFunction.class,"MUTATION_SPECTRUM");
046
047   public static final MutationFunction NO_MUTATION = new NoMutation();
048
049  /**
050   * Produces a new SymbolList by mutation. Each position <em>i</em> in the SymbolList <code>seq</code>
051   * is mutated with probability <code>getMutationProbs[i]</code>. The new residue is selected at random
052   * from the <code>Distribution mutation</code>. The use of an array of probabilities
053   * allows the modelling of mutational hotspots. Position 0 in the array corresponds to the
054   * probability of the first residue of <code>seq</code> mutating.
055   *
056   * If the length of the array defined in <code>getMutationProbs()</code> is shorter
057   * than the length of the sequence the default behaivour of implementations will
058   * be to apply the last probability to each subsequence residue. A single member
059   * array will mutate all bases with equal probability.
060   *
061   * @param seq the sequence to mutate
062   * @return The mutated sequence.
063   * @throws IllegalAlphabetException If the <code>mutationSpectrum Distribution</code> is not
064   * emitting Symbols from the same <code>Alphabet</code> as <code>seq</code>.
065   * @throws IllegalSymbolException if the <code>mutationSpectrum Distribution</code> is not
066   * conditioned with the same <code>Alphabet</code> as the <code>seq Alphabet</code>.
067   * @throws ChangeVetoException if <code>seq</code> is unmodifiable
068   */
069  public SymbolList mutate(SymbolList seq)
070    throws IllegalAlphabetException, ChangeVetoException, IllegalSymbolException;
071
072  /**
073   * Set the probability of a mutation occuring at a certain position
074   * Position 0 in the array corresponds to the
075   * probability of the first residue of <code>seq</code> mutating.
076   *
077   * If the length of the array defined in <code>getMutationProbs()</code> is shorter
078   * than the length of the sequence the default behaivour of implementations will
079   * be to apply the last probability to each subsequence residue. A single member
080   * array will mutate all bases with equal probability.
081   * @param mutationProbs an array of double values representing mutation probabilities
082   * @throws ChangeVetoException if a ChangeListener vetoes the change.
083   */
084  public void setMutationProbs(double[] mutationProbs) throws ChangeVetoException;
085  public double[] getMutationProbs();
086
087  /**
088   * Sets the <code>Distribution</code> of <code>Symbols</code> that will be selected
089   * from when a mutation occurs. An <code>OrderNDistribution</code> is
090   * used so that you can model a situation where the
091   * identity of the 'mutant' <code>Symbol</code> is dependent on the original
092   * <code>Symbol</code>. The primary use is to prevent <code>Symbols</code> mutating to
093   * themselves. Another use would be to model transitions and transversions.
094   *
095   * @param mutationSpectrum the Distribution of 'mutant' bases to choose from.
096   * @throws ChangeVetoException if a ChangeListener vetoes the change.
097   */
098  public void setMutationSpectrum(org.biojava.bio.dist.OrderNDistribution mutationSpectrum)throws ChangeVetoException;
099
100  /**
101   *
102   * @return null if the Distribution has not been set.
103   */
104  public org.biojava.bio.dist.OrderNDistribution getMutationSpectrum();
105
106  /**
107   *
108   * <p> Place Holder class that doesn't mutate its SymbolLists</p>
109   * @author Mark Schreiber
110   * @version 1.0
111   */
112  public static final class NoMutation implements MutationFunction{
113    public double[] getMutationProbs(){return DEFAULT_MUTATION_PROBS;}
114    public OrderNDistribution getMutationSpectrum(){return null;}
115    public SymbolList mutate(SymbolList syml){return syml;}
116    public void setMutationProbs(double[] muts) throws ChangeVetoException{
117      throw new ChangeVetoException("Cannot setMutationProbs for a NoMutation function");
118    }
119    public void setMutationSpectrum(OrderNDistribution odn) throws ChangeVetoException{
120      throw new ChangeVetoException("Cannot set a Mutation spectrum for a NoMutation function");
121    }
122
123    public boolean isUnchanging(ChangeType ct){return true;}
124    public void removeChangeListener(ChangeListener c){};
125    public void addChangeListener(ChangeListener cl){};
126    public void addChangeListener(ChangeListener cl, ChangeType ct){};
127    public void removeChangeListener(ChangeListener cl, ChangeType ct){};
128  }
129}