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.IllegalSymbolException;
026import org.biojava.bio.symbol.Symbol;
027import org.biojava.utils.ChangeVetoException;
028
029/**
030 * A context within a group of DistributionTrainers can be trained together.
031 *
032 * @author Matthew Pocock
033 * @since 1.0
034 */
035public interface DistributionTrainerContext {
036    /**
037     * Return the number of pseudocounts added to the distribution when training.
038     *
039     * @return the null model weight
040     */
041
042  public double getNullModelWeight();
043  
044    /**
045     * Set the number of pseudocounts to add when training the distribution.
046     * These counts are added in proportion to the null model of the distribution
047     * being trained.
048     *
049     * @param weight the new null model weight
050     */
051
052  public void setNullModelWeight(double weight);
053  
054  /**
055   * <p>
056   * Register a distribution object with this context.
057   * </p>
058   *
059   * <p>
060   * This method is a request to the context to register dist. If dist is already
061   * registered then this method should do nothing. If it is not registered, then
062   * it should invoke dist.registerWithTrainer
063   * </p>
064   *
065   * @param dist the Distribution to register
066   */
067  void registerDistribution(Distribution dist);
068  
069  /**
070   * <p>
071   * Register a Distribution and an associated DistributionTrainer object.
072   * </p>
073   *
074   * <p>
075   * In the registerWithTrainer method of a Distribution, it should associate
076   * itself with a trainer using this method.
077   * </p>
078   *
079   * @param dist the distribution to be registered.
080   * @param trainer the distribution's trainer object to be registered.
081   */
082  void registerTrainer(Distribution dist, DistributionTrainer trainer);
083  
084  /**
085  * Return the Distribution trainer object from the current context.
086  *
087  * @param dist the Distribution whose trainer is required
088  * @return the DistributionTrainer for the distribution
089  */
090   DistributionTrainer getTrainer(Distribution dist);
091  
092  /**
093   * <p>
094   * Registers that sym was counted in this state.
095   * </p>
096   *
097   * <p>
098   * This method may be called multiple times with the same symbol. In this
099   * case, the times should be summed.
100   * </p>
101   *
102   * @param dist the Distribution that the symbol was associated with
103   * @param sym the Symbol seen
104   * @param times the number of times to add
105   * @throws IllegalSymbolException if sym is not recognised by dist
106   */
107  void addCount(Distribution dist, Symbol sym, double times)
108  throws IllegalSymbolException;
109  
110  /**
111   * Return the number of counts of a particular symbol which will be used
112   * to train the specified distribution.
113   *
114   * @param dist  the Distribution to return counts for
115   * @param sym   the symbol to get the count for
116   * @return the number of counts
117   * @throws IllegalSymbolException if the symbol is not accepted by the
118   *     distribution
119   */
120  
121  double getCount(Distribution dist, Symbol sym)
122  throws IllegalSymbolException;
123  
124  /**
125   * <p>
126   * Trains the Distribution, given a null model.
127   * </p>
128   *
129   * <p>
130   * This will use the information collected with multiple addCount calls, and
131   * the null model to generate the new weights.
132   * </p>
133   *
134   * @throws ChangeVetoException  if any of the distributions can't be trained
135   */
136  void train() throws ChangeVetoException;
137  
138  /**
139   * Clears all of the counts to zero.
140   */
141  void clearCounts();
142}