org.biojava.bio.dist
Class TranslatedDistribution

java.lang.Object
  extended by org.biojava.utils.AbstractChangeable
      extended by org.biojava.bio.dist.TranslatedDistribution
All Implemented Interfaces:
java.io.Serializable, Distribution, Changeable

public class TranslatedDistribution
extends AbstractChangeable
implements Distribution, java.io.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.

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
For general use:
make these thigs via getDistribuiton.
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