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.biojava.bio.dist;
022
023import java.util.Collection;
024
025import org.biojava.bio.symbol.Alphabet;
026import org.biojava.bio.symbol.IllegalAlphabetException;
027import org.biojava.bio.symbol.IllegalSymbolException;
028import org.biojava.bio.symbol.Symbol;
029
030/**
031 * Provides an N'th order distribution.  This is a distribution over one
032 * alphabet which is conditioned on having previously observed one or
033 * more other symbols (potentially from different alphabets).
034 *
035 * <p>
036 * Order-N distributions are always over a CrossProductAlphabet.
037 * </p>
038 *
039 * <p>
040 * <strong>Note:</strong> Unlike normal distributions, the total weights for
041 * all symbols in the overall alphabet do <em>not</em> sum to 1.0.  Instead,
042 * the weights of each sub-distribution should sum to 1.0.
043 * </p>
044 *
045 * <p>
046 * This would typically be used in conjunction with an OrderNSymbolList.
047 * </p>
048 *
049 * @author Thomas Down
050 * @author Samiul Hasan
051 * @author Matthew Pocock
052 * @since 1.0
053 */
054
055public interface OrderNDistribution extends Distribution {
056    /**
057     * Get the conditioning alphabet of this distribution.  If the `overall'
058     * alphabet is a cross-product of two alphabets, this will be the first 
059     * of those alphabets.  If it is a cross-product of more than two alphabets,
060     * the conditioning alphabet is the cross-product of all but the last
061     * alphabet.
062     *
063     * @return the conditioning Alphabet
064     */
065
066    public Alphabet getConditioningAlphabet();
067
068    /**
069     * Get the conditioned alphabet.  This is the last alphabet in the
070     * distribution's overall cross-product.  It will be the alphabet of
071     * all the sub-distributions contained within this OrderNDistribution.
072     *
073     * @return the conditioned Alphabet
074     */
075
076    public Alphabet getConditionedAlphabet();
077
078  /**
079   * Get the conditioned distributions.
080   *
081   * @return  the conditioned distributions
082   */
083  //fixme: I'm sure this should return a list
084    public Collection conditionedDistributions();
085
086  /**
087   * Set the distribution assocated with a symbol.
088   *
089   * @param sym   the symbol in the conditioning Alphabet
090   * @param dist  a distribution over the conditioned Alphabet
091   * @throws IllegalSymbolException   if sym is not in the conditioning Alphabet
092   * @throws IllegalAlphabetException if dist is not over the conditioned
093   *    Alphabet
094   */
095      public abstract void setDistribution(Symbol sym, Distribution dist)
096      throws IllegalSymbolException, IllegalAlphabetException;
097  
098  public abstract Distribution getDistribution(Symbol sym)
099      throws IllegalSymbolException;
100}