## org.biojava.bio.dist
Interface Distribution

All Superinterfaces:
  Changeable

All Known Subinterfaces:
  OrderNDistribution

All Known Implementing Classes:
  AbstractDistribution, AbstractOrderNDistribution, GapDistribution, PairDistribution, SimpleDistribution, TranslatedDistribution, UniformDistribution, UntrainableDistribution

    public interface Distribution

extends Changeable

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

A distribution can be implemented as a map from symbol to probability. It is more correct to think of them as being integrals or sums over probability dencity funcitons. In this world view, getWeight should look at the getMatches of the symbol it is given and then perform the apropreate sum or integral to return the probability of something within that set of symbols being emitted.

This interface should handle the case of emitting an ambiguity symbol. This should be just the sum of the probabiltiy of emitting each matching symbol. It is up to the code using the Distribution instance to divide out the null model appropreately.

Since:
  1.0
Author:
  Matthew Pocock

Nested Class Summary
`static class` `Distribution.NullModelForwarder` Deprecated. use `new ChangeForwarder.Retyper(this, cs, Annotation.PROPERTY)` instead

Field Summary
`static ChangeType` `NULL_MODEL` Whenever the null model distribution changes the values that would be returned by getWeight, either by being edited or by being replaced, a ChangeEvent with this object as the type should be thrown.
`static ChangeType` `WEIGHTS` Whenever a distribution changes the values that would be returned by getWeight, they should fire a ChangeEvent with this object as the type.

Method Summary
`Alphabet` `getAlphabet()` The alphabet from which this spectrum emits symbols.
`Distribution` `getNullModel()` Retrieve the null model Distribution that this Distribution recognizes.
`double` `getWeight(Symbol s)` Return the probability that Symbol s is emitted 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` `setNullModel(Distribution nullDist)` Set the null model Distribution that this Distribution recognizes.
`void` `setWeight(Symbol s, double w)` Set the probability or odds that Symbol s is emitted by this state.

Methods inherited from interface org.biojava.utils.Changeable
`addChangeListener, addChangeListener, isUnchanging, removeChangeListener, removeChangeListener`

Field Detail

### WEIGHTS

    static final ChangeType WEIGHTS

  Whenever a distribution changes the values that would be returned by getWeight, they should fire a ChangeEvent with this object as the type.

  If the whole distribution changes, then the change and previous fields of the ChangeEvent should be left null. If only a single weight is modified, then change should be of the form Object[] { symbol, new Double(newVal) } and previous should be of the form Object[] { symbol, new Double(oldVal) }

### NULL_MODEL

    static final ChangeType NULL_MODEL

  Whenever the null model distribution changes the values that would be returned by getWeight, either by being edited or by being replaced, a ChangeEvent with this object as the type should be thrown.

  If the null model has changed its weights, then the ChangeEvent should refer back to the ChangeEvent from the null model.

Method Detail

### getAlphabet

    Alphabet getAlphabet()

  The alphabet from which this spectrum emits symbols.

  Returns:
    the Alphabet associated with this spectrum

### getWeight

    double getWeight(Symbol s)
                     throws IllegalSymbolException

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

  If the symbol is ambiguou, then it is the sum of the probability that each one of the matching symbols was emitted.

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

### setWeight

    void setWeight(Symbol s,
                   double w)
                   throws IllegalSymbolException,
                          ChangeVetoException

  Set the probability or odds that Symbol s is emitted 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
    `ChangeVetoException` - if this state does not allow weights to be tampered with, or if one of the listeners vetoed this change

### sampleSymbol

    Symbol sampleSymbol()

  Sample a symbol from this state's probability distribution.

  Returns:
    the symbol sampled

### getNullModel

    Distribution getNullModel()

  Retrieve the null model Distribution that this Distribution recognizes.

  Returns:
    the apropriate null model

### setNullModel

    void setNullModel(Distribution nullDist)
                      throws IllegalAlphabetException,
                             ChangeVetoException

  Set the null model Distribution that this Distribution recognizes.

  Parameters:
    `nullDist` - the new null model Distribution
  Throws:
    `IllegalAlphabetException` - if the null model has the wrong alphabet
    `ChangeVetoException` - if this Distirbution doesn't support setting the null model, or if one of its listeners objects

### registerWithTrainer

    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