## org.biojava.bio.dist
Interface Distribution

All Known Implementing Classes:
  ComplementaryDistribution, AbstractDistribution, GapDistribution

public interface Distribution

An encapsulation of a probability distribution over the Symbols within an alphabet.

A distribution is effectively a map from symbol to probability. You may choose to store odds instead ( p(x) / p(H_0) ), but it is not guaranteed that all algorithms will work correctly.

This interface should handle the case of emitting an ambiguity symbol. In classical statistics, this would be just the sum of the probabiltiy of emitting each matching symbol. However, in our domain, only one symbol can actualy be produced, and the ambiguity symbol means 'one of these', not 'each of these', you should take a weighted average:``

    P(A|S, Null) = [ sum_i P(a_i|S) * P(a_i|Null) ] / [ sum_i P(a_i|Null) ]

Author:
  Matthew Pocock

Method Summary
`Alphabet` `getAlphabet()` The alphabet from which this spectrum emits symbols.
`double` `getWeight(Symbol s)` Return the probability that Symbol s is emited by this spectrum.
`void` `registerWithTrainer(DistributionTrainerContext dtc)` Register this distribution with a training context.
`Symbol` `sampleSymbol()` Sample a symbol from this state's probability distribution.
`void` `setWeight(Symbol s, double w)` Set the probability or odds that Symbol s is emited by this state.

Method Detail

### getAlphabet

    public Alphabet getAlphabet()

  The alphabet from which this spectrum emits symbols.
  Returns:
    the Alphabet associated with this spectrum

### getWeight

    public double getWeight(Symbol s)
                     throws IllegalSymbolException

  Return the probability that Symbol s is emited by this spectrum.

  If the symbol is an AmbiguitySymbol, then it is the probability that exactly one of the symbols matching it was emitted.

  Parameters:
    `s` - the Symbol emitted
  Returns:
    the log probability of emitting that symbol
  Throws:
    IllegalSymbolException - if s is not from this state's alphabet

### setWeight

    public void setWeight(Symbol s,
                          double w)
                   throws IllegalSymbolException,
                          java.lang.UnsupportedOperationException

  Set the probability or odds that Symbol s is emited by this state.
  Parameters:
    `s` - the Symbol emitted
    `w` - the probability of emitting that symbol
  Throws:
    IllegalSymbolException - if s is not from this state's alphabet, or if it is an ambiguity symbol and the implementation can't handle this case
    java.lang.UnsupportedOperationException - if this state does not allow weights to be tampered with

### sampleSymbol

    public Symbol sampleSymbol()

  Sample a symbol from this state's probability distribution.
  Returns:
    the symbol sampled

### registerWithTrainer

    public void registerWithTrainer(DistributionTrainerContext dtc)

  Register this distribution with a training context.

  This should be invoked from within dtc.addDistribution(). This method is responsible for constructing a suitable DistributionTrainer instance and registering it by calling dtc.registerDistributionTrainer(this, trainer). If the distribution is a view onto another distribution, it can force the other to be registered by calling dtc.addDistribution(other), and can then get on with registering it's own trainer.

  Parameters:
    `dtc` - the DistributionTrainerContext with witch to register a trainer