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.dist;
024
025import org.biojava.bio.symbol.Alphabet;
026import org.biojava.bio.symbol.AtomicSymbol;
027import org.biojava.bio.symbol.IllegalAlphabetException;
028import org.biojava.bio.symbol.IllegalSymbolException;
029import org.biojava.utils.ChangeType;
030import org.biojava.utils.ChangeVetoException;
031import org.biojava.utils.Changeable;
032
033/**
034 * <p>
035 * An encapsulation of a count over the Symbols within an alphabet.
036 * </p>
037 *
038 * <p>
039 * A Count is effectively a vector of counts from an Alphabet.
040 * </p>
041 *
042 * @author Matthew Pocock
043 * @since 1.1
044 */
045public interface Count extends Changeable {
046  /**
047   * <p>
048   * Whenever a component count changes the values that would be returned by
049   * getCount, they should fire a ChangeEvent with this object as the type.
050   * </p>
051   *
052   * <p>
053   * If the whole count changes, then the change and previous fields of
054   * the ChangeEvent should be left null. If only a single weight is modified,
055   * then change should be of the form Object[] { symbol, new Double(newVal) }
056   * and previous should be of the form Object[] { symbol, new Double(oldVal) }
057   * </p>
058   */
059  public static final ChangeType COUNTS = new ChangeType(
060    "distribution weights changed",
061    "org.biojava.bio.dist.Count",
062    "COUNTS"
063  );
064  
065  /**
066   * The alphabet from which this Count is over.
067   *
068   * @return  the Alphabet associated with this Count
069   */
070  Alphabet getAlphabet();
071    
072  /**
073   * Return the counts for a given Symbol.
074   *
075   * @param s the Symbol
076   * @return  the number of counts for this symbol
077   * @throws IllegalSymbolException if s is not from this Count's alphabet
078   */
079  double getCount(AtomicSymbol s) throws IllegalSymbolException;
080  
081  /**
082   * Set the count for the Symbol s.
083   *
084   * @param s the Symbol emitted
085   * @param c  the new count for the Symbol
086   * @throws IllegalSymbolException if s is not from this state's alphabet, or
087   *         if it is an ambiguity symbol and the implementation can't handle
088   *         this case
089   * @throws ChangeVetoException if this distribution does not allow counts
090   *         to be tampered with, or if one of the listeners vetoed this change
091   */
092  void setCount(AtomicSymbol s, double c)
093  throws IllegalSymbolException, ChangeVetoException;
094  
095  
096  /**
097   * Set the probability or odds that Symbol s is emitted by this state.
098   *
099   * @param s the Symbol emitted
100   * @param c  the delta to add to the count for the Symbol
101   * @throws IllegalSymbolException if s is not from this state's alphabet, or
102   *         if it is an ambiguity symbol and the implementation can't handle
103   *         this case
104   * @throws ChangeVetoException if this Count does not allow counts
105   *         to be tampered with, or if one of the listeners vetoed this change
106   */
107  void increaseCount(AtomicSymbol s, double c)
108  throws IllegalSymbolException, ChangeVetoException;
109  
110  /**
111   * Set the counts in this Counts to be equal to the counts in c.
112   *
113   * @param c  the Count object to copy the counts from
114   * @throws IllegalAlphabetException if c has a different Alphabet to this
115   *         Count
116   * @throws ChangeVetoException if this Count does not allow the counts to be
117   *         tampered with, or if one of the listeners vetoed this change
118   */
119  void setCounts(Count c)
120  throws IllegalAlphabetException, ChangeVetoException;
121  
122  /**
123   * Reset all the counts to zero.
124   *
125   * @throws ChangeVetoException if this Count does not allow the counts to be
126   *         tampered with, or if one of the listeners vetoed this change
127   */
128  void zeroCounts()
129  throws ChangeVetoException;
130}