## org.biojava.bio.dist
Class TranslatedDistribution

    java.lang.Object
      org.biojava.utils.AbstractChangeable
          org.biojava.bio.dist.TranslatedDistribution

All Implemented Interfaces:
  Serializable, Distribution, Changeable

    public class TranslatedDistribution

extends AbstractChangeable
implements Distribution, Serializable

A translated view of some underlying distribution. The `getWeight` method returns the result of calling `getWeight` on the underlying distribution, having first translated the `Symbol` parameter using the supplied `ReversibleTranslationTable`. All changes to the underlying distribution are reflected by the `TranslatedDistribution`.

The `TranslatedDistribution` is not directly mutable: calling `setWeight` will result in a `ChangeVetoException`. However, a `DistributionTrainer` may be registered for a `TranslatedDistribution`. Any counts received by this trainer are untranslated then forwarded to the underlying distribution. It is valid to add counts to both a `TranslatedDistribution` and its underlying distribution in a single training session, so `TranslatedDistribution` objects are useful for tying parameters together when training Markov Models.

## Example usage

     Distribution d = DistributionFactory.DEFAULT.createDistribution(DNATools.getDNA());
     d.setWeight(DNATools.a(), 0.7);
     d.setWeight(DNATools.c(), 0.1);
     d.setWeight(DNATools.g(), 0.1);
     d.setWeight(DNATools.t(), 0.1);
     Distribution complemented = new TranslatedDistribution(
         DNATools.complementTable(),
         d,
         DistributionFactory.DEFAULT
     );
     System.out.println(
        "complemented.getWeight(DNATools.t()) = " +
        complemented.getWeight(DNATools.t())
     );  // Should print 0.7

Since:
  1.1
Author:
  Matthew Pocock, Thomas Down
See Also:
  Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.biojava.bio.dist.Distribution
`Distribution.NullModelForwarder`

Field Summary

Fields inherited from interface org.biojava.bio.dist.Distribution
`NULL_MODEL, WEIGHTS`

Constructor Summary
`TranslatedDistribution(ReversibleTranslationTable table, Distribution other, DistributionFactory distFact)` Create a new TranslatedDistribution.

Method Summary
`Alphabet` `getAlphabet()` The alphabet from which this spectrum emits symbols.
`protected ChangeSupport` `getChangeSupport(ChangeType ct)` Called to retrieve the ChangeSupport for this object.
`Distribution` `getNullModel()` Retrieve the null model Distribution that this Distribution recognizes.
`ReversibleTranslationTable` `getTable()` Retrieve the translation table encapsulating the map from this emission spectrum to the underlying one.
`double` `getWeight(Symbol sym)` 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 dist)` Set the null model Distribution that this Distribution recognizes.
`void` `setWeight(Symbol sym, double weight)` Set the probability or odds that Symbol s is emitted by this state.

Methods inherited from class org.biojava.utils.AbstractChangeable
`addChangeListener, addChangeListener, generateChangeSupport, hasListeners, hasListeners, isUnchanging, removeChangeListener, removeChangeListener`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

Constructor Detail

### TranslatedDistribution

    public TranslatedDistribution(ReversibleTranslationTable table,
                                  Distribution other,
                                  DistributionFactory distFact)
                           throws IllegalAlphabetException

  Create a new TranslatedDistribution. Make these things via getDistribuiton.

  Parameters:
    `table` - a ReversibleTranslationTable used to map the symbols
    `other` - the underlying ditribution
    `distFact` - a DistributionFactory used to create a delegate for stooring mapped weights
  Throws:
    `IllegalAlphabetException`

Method Detail

### getAlphabet

    public Alphabet getAlphabet()

  Description copied from interface: `Distribution`
  The alphabet from which this spectrum emits symbols.

  Specified by:
    `getAlphabet` in interface `Distribution`
  Returns:
    the Alphabet associated with this spectrum

### getWeight

    public double getWeight(Symbol sym)
                     throws IllegalSymbolException

  Description copied from interface: `Distribution`

  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.

  Specified by:
    `getWeight` in interface `Distribution`
  Parameters:
    `sym` - the Symbol emitted
  Returns:
    the probability of emitting that symbol
  Throws:
    `IllegalSymbolException` - if s is not from this state's alphabet

### setWeight

    public void setWeight(Symbol sym,
                          double weight)
                   throws IllegalSymbolException,
                          ChangeVetoException

  Description copied from interface: `Distribution`
  Set the probability or odds that Symbol s is emitted by this state.

  Specified by:
    `setWeight` in interface `Distribution`
  Parameters:
    `sym` - the Symbol emitted
    `weight` - 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

    public Symbol sampleSymbol()

  Description copied from interface: `Distribution`
  Sample a symbol from this state's probability distribution.

  Specified by:
    `sampleSymbol` in interface `Distribution`
  Returns:
    the symbol sampled

### getNullModel

    public Distribution getNullModel()

  Description copied from interface: `Distribution`
  Retrieve the null model Distribution that this Distribution recognizes.

  Specified by:
    `getNullModel` in interface `Distribution`
  Returns:
    the apropriate null model

### setNullModel

    public void setNullModel(Distribution dist)
                      throws IllegalAlphabetException,
                             ChangeVetoException

  Description copied from interface: `Distribution`
  Set the null model Distribution that this Distribution recognizes.

  Specified by:
    `setNullModel` in interface `Distribution`
  Parameters:
    `dist` - 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

### getTable

    public ReversibleTranslationTable getTable()

  Retrieve the translation table encapsulating the map from this emission spectrum to the underlying one.

  Returns:
    a ReversibleTranslationtTable

### registerWithTrainer

    public void registerWithTrainer(DistributionTrainerContext dtc)

  Description copied from interface: `Distribution`

  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.

  Specified by:
    `registerWithTrainer` in interface `Distribution`
  Parameters:
    `dtc` - the DistributionTrainerContext with witch to register a trainer

### getChangeSupport

    protected ChangeSupport getChangeSupport(ChangeType ct)

  Description copied from class: `AbstractChangeable`
  Called to retrieve the ChangeSupport for this object.

  Your implementation of this method should have the following structure: ``

       ChangeSupport cs = super.getChangeSupport(ct);

       if(someForwarder == null && ct.isMatching(SomeInterface.SomeChangeType)) {
         someForwarder = new ChangeForwarder(...

         this.stateVariable.addChangeListener(someForwarder, VariableInterface.AChange);
       }

       return cs;

  It is usual for the forwarding listeners (someForwarder in this example) to be transient and lazily instantiated. Be sure to register & unregister the forwarder in the code that does the ChangeEvent handling in setter methods.

  Overrides:
    `getChangeSupport` in class `AbstractChangeable`