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