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
022
023package org.biojava.bio.dp;
024
025import org.biojava.bio.dist.Distribution;
026import org.biojava.utils.ChangeType;
027import org.biojava.utils.ChangeVetoException;
028import org.biojava.utils.Changeable;
029
030/**
031 * <p>
032 * A state in a markov process that has an emission spectrum.
033 * </p>
034 *
035 * <p>
036 * These states have an associated Distribution. Within an HMM, these are the
037 * states that actualy make your observed sequence. They also must supply
038 * training behaviour to set the emission spectrum up.
039 * </p>
040 *
041 * @author Matthew Pocock
042 */
043public interface EmissionState extends State, Trainable, Changeable {
044  /**
045   * <p>
046   * This signals that the distribution associate with an EmissionState has
047   * been altered.
048   * </p>
049   *
050   * <p>
051   * If the distribution has changed its weights, then the event'e
052   * getChainedEvent method will return the event fired by the distribution. If
053   * one distribution has been replaced by another, then the new and old
054   * Distributions will be in current and previous, respectively.
055   * </p>
056   */
057  public static final ChangeType DISTRIBUTION = new ChangeType(
058    "The associated ditribution has changed",
059    "org.biojava.bio.dp.EmissionState",
060    "DISTRIBUTION"
061  );
062  
063  /**
064   * <p>
065   * This signals that the advance array has been altered.
066   * </p>
067   *
068   * <p>
069   * current and previous should hold the current and previous advances,
070   * respectively.
071   * </p>
072   */
073  public static final ChangeType ADVANCE = new ChangeType(
074    "The associated advance array has changed",
075    "org.biojava.bio.dp.EmissionState",
076    "ADVANCE"
077  );
078  
079  /**
080   * Determine the number of symbols this state advances along
081   * one or more symbol lists.  In the simple case, this method
082   * should almost always return {1} if it is a true `emmision'
083   * state, or {0} if it is a dot state which only emits a gap
084   * character.  For pairwise HMMs, it will normally return {1, 1}
085   * for match state, and {0, 1} or {1, 0} for a gap state.  Under
086   * some circumstances it may be valid to return values other
087   * than 1 or 0, but you should consider the consequences for
088   * HMM architecture very carefully, and contact the authors.
089   *
090   * Developers may wish to return a copy of some underlying array from this method
091   * as code outside could modify the array you give
092   */
093  public int[] getAdvance();
094  
095  /**
096   * Set the advance array.
097   *
098   * @param advance  an array of ints, specifying how many symbols are consumed
099   *        from each sequence
100   * @throws ChangeVetoException  if the implementation doesn't support setting
101   *         advance, or if the change is vetoed
102   */
103  public void setAdvance(int[] advance) throws ChangeVetoException;
104  
105  /**
106   * <p>
107   * Get the Distribution associated with this state.
108   * </p>
109   *
110   * <p>
111   * If the state is to be added to an HMM, then the state's emission spectrum
112   * must be compatible with the HMM - that is, their emission alphabets must
113   * match.
114   * </p>
115   *
116   * @return the current Distribution object used by this state
117   */
118  public Distribution getDistribution();
119  
120  /**
121   * Set the Distribution associated with this state.
122   * 
123   * @param dis the new Distribution to use
124   * @throws ChangeVetoException  if the implementation doesn't support setting
125   *         the distribution, or if the change is vetoed
126   */
127  public void setDistribution(Distribution dis)
128  throws ChangeVetoException;
129}