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.AtomicSymbol;
026import org.biojava.bio.symbol.IllegalSymbolException;
027import org.biojava.utils.ChangeVetoException;
028
029/**
030 * <p>
031 * An object that can be used to train a distribution up.
032 * </p>
033 *
034 * <p>
035 * This lets the distribution implementation handle counts or distributions
036 * in the best way possible.
037 * </p>
038 *
039 * @author Matthew Pocock
040 * @since 1.0
041 */
042public interface DistributionTrainer {
043  /**
044   * <p>
045   * Registers that sym was counted in this state.
046   * </p>
047   *
048   * <p>
049   * This method may be called multiple times with the same symbol. In this
050   * case, the times should be summed.
051   * </p>
052   *
053   * @param dtc the DistributionTrainerContext within which the count was added
054   * @param sym the Symbol seen
055   * @param times the number of times to add
056   * @throws IllegalSymbolException if sym is not recognised
057   */
058  void addCount(DistributionTrainerContext dtc, AtomicSymbol sym, double times)
059  throws IllegalSymbolException;
060  
061  /**
062   * <p>
063   * Get the current count for this state.
064   * </p>
065   *
066   * <p>
067   * This method may be called multiple times with the same symbol. Each time
068   * it should return the agregate of the counts added with addCount since the
069   * last invocation of clearCounts.
070   * </p>
071   *
072   * @param dtc the DistributionTrainerContext within which the count was added
073   * @param sym the Symbol seen
074   * @return the agregate of the counts
075   * @throws IllegalSymbolException  if sym is not recognised
076   */
077  double getCount(DistributionTrainerContext dtc, AtomicSymbol sym)
078  throws IllegalSymbolException;
079  
080  /**
081   * <p>
082   * Trains the Distribution, given a null model.
083   * </p>
084   *
085   * <p>
086   * This will use the information collected with multiple addCount calls, and
087   * the null model to generate the new weights.
088   * </p>
089   *
090   * <p>
091   * This method should not modify the underlying counts.
092   * </p>
093   *
094   * @param dtc     the context to use
095   * @param weight  how many lots of the null model to add
096   * @throws ChangeVetoException if the distribution could not have its weights
097   *         modified
098   */
099  void train(DistributionTrainerContext dtc, double weight)
100  throws ChangeVetoException;
101  
102  /**
103   * Clears all of the counts to zero.
104   */
105  void clearCounts(DistributionTrainerContext dtc);
106}