org.biojava.bio.dp
Interface MarkovModel

All Known Implementing Classes:
ModelView, SimpleMarkovModel, WMAsMM

public interface MarkovModel
extends Trainable

A markov model.

All probablities are in log space.

This interface models a subset of hidden markov models with an explicit start and end state. In principle, these can be combined together, so that a state within one model may be an entire model in its own right, wired via container->start and end->container. For the sample methods to work, the log scores must be probabilities (sum to 1).


Method Summary
 void addState(State newState)
          Adds a state to the model.
 void addTransitionListener(TransitionListener tl)
          Register a TransitionListener with the model.
 boolean containsTransition(State from, State to)
          Returns whether a transition is possible in the model.
 void createTransition(State from, State to)
          Makes a transition between two states legal.
 void destroyTransition(State from, State to)
          Breaks a transition between two states legal.
 Alphabet emissionAlphabet()
          Alphabet that is emitted by the emission states.
 double getTransitionScore(State from, State to)
          Probability of the transition between from and to.
 int heads()
          The number of heads on this model.
 MagicalState magicalState()
          The MagicalState for this model.
 void removeState(State toGo)
          Remove a state from the model.
 void removeTransitionListener(TransitionListener tl)
          Unregister a TransitionListener with the model.
 State sampleTransition(State from)
          Sample a transition from the distribution of transitions.
 void setTransitionScore(State from, State to, double score)
          Set the transition score associated with a transition.
 FiniteAlphabet stateAlphabet()
          FiniteAlphabet of the states.
 java.util.Set transitionsFrom(State from)
          Returns a Set of all legal transitions from a state.
 java.util.Set transitionsTo(State to)
          Returns a Set of all legal transitions to a state.
 
Methods inherited from interface org.biojava.bio.dp.Trainable
registerWithTrainer
 

Method Detail

emissionAlphabet

public Alphabet emissionAlphabet()
Alphabet that is emitted by the emission states.

stateAlphabet

public FiniteAlphabet stateAlphabet()
FiniteAlphabet of the states.

We are modeling a finite-state-machine, so there will be a finite set of states.

The MagicalState returned by getMagicalState is always contained within this as the start/end state.

Returns:
the alphabet over states

magicalState

public MagicalState magicalState()
The MagicalState for this model.

heads

public int heads()
The number of heads on this model.

Each head consumes a single SymbolList. A single-head model just consumes/ emits a single sequence. A two-head model performs alignment between two sequences (e.g. smith-waterman). Models with more heads do more interesting things.


getTransitionScore

public double getTransitionScore(State from,
                                 State to)
                          throws IllegalSymbolException,
                                 IllegalTransitionException
Probability of the transition between from and to.
Parameters:
from - the State currently occupied
to - the State to move to
Returns:
the transition score from->to
Throws:
IllegalSymbolException - if either from or to are not legal states
IllegalTransitionException - if there is no transition between the states

containsTransition

public boolean containsTransition(State from,
                                  State to)
                           throws IllegalSymbolException
Returns whether a transition is possible in the model.
Parameters:
from - the State currently occupied
to - the State to move to
Throws:
IllegalSymbolException - if either from or to are not legal states

createTransition

public void createTransition(State from,
                             State to)
                      throws IllegalSymbolException,
                             java.lang.UnsupportedOperationException,
                             ModelVetoException
Makes a transition between two states legal.

This should inform each TransitionListener that a transition is to be created using preCreateTransition, and if none of the listeners fire a ModelVetoException, it should create the transition, and then inform each TransitionListener with postCreateTransition.

Parameters:
from - the State currently occupied
to - the State to move to
Throws:
IllegalSymbolException - if either from or to are not legal states
java.lang.UnsupportedOperationException - if an implementation does not allow transitions to be created
ModelVetoException - if creating the transition is vetoed

destroyTransition

public void destroyTransition(State from,
                              State to)
                       throws IllegalSymbolException,
                              java.lang.UnsupportedOperationException,
                              ModelVetoException
Breaks a transition between two states legal.

This should inform each TransitionListener that a transition is to be broken using preDestroyTransition, and if none of the listeners fire a ModelVetoException, it should break the transition, and then inform each TransitionListener with postDestroyTransition.

Parameters:
from - the State currently occupied
to - the State to move to
Throws:
IllegalSymbolException - if either from or to are not legal states
java.lang.UnsupportedOperationException - if an implementation does not allow transitions to be destroyed
ModelVetoException - if breaking the transition is vetoed

setTransitionScore

public void setTransitionScore(State from,
                               State to,
                               double score)
                        throws IllegalSymbolException,
                               IllegalTransitionException,
                               java.lang.UnsupportedOperationException,
                               ModelVetoException
Set the transition score associated with a transition.

This method should inform each TransitionListener that the score is to be changed by calling preChangeTransitionScore, and if the change is not vetoed, it should update the score and then call postChangeTransitionScore on each listener.

Parameters:
from - the source State
to - the destination State
score - the new score for the transition
Throws:
IllegalSymbolException - if either from or to are not states in the model
IllegalTransitionException - if the transition does not exist in the model
java.lang.UnsupportedOperationException - if an implementation does not allow transition scores to be altered
ModelVetoException - if the new score is vetoed

sampleTransition

public State sampleTransition(State from)
                       throws IllegalSymbolException
Sample a transition from the distribution of transitions.

This will give eroneous results if the scores are not log-probabilities.

Parameters:
from - the starting state
Returns:
a State sampled from all states reachable from 'from'
Throws:
IllegalSymbolException - if 'from' is not a state within this model

transitionsFrom

public java.util.Set transitionsFrom(State from)
                              throws IllegalSymbolException
Returns a Set of all legal transitions from a state.
Parameters:
from - the starting state
Returns:
a List of State objects

transitionsTo

public java.util.Set transitionsTo(State to)
                            throws IllegalSymbolException
Returns a Set of all legal transitions to a state.
Parameters:
from - the destination state
Returns:
a List of State objects

addState

public void addState(State newState)
              throws java.lang.UnsupportedOperationException,
                     IllegalSymbolException,
                     ModelVetoException
Adds a state to the model.
Parameters:
newState - the state to add
Throws:
java.lang.UnsupportedOperationException - if this MarkovModel doesn't allow states to be added
IllegalSymbolException - if the state is not valid or is a MagicalState

removeState

public void removeState(State toGo)
                 throws java.lang.UnsupportedOperationException,
                        IllegalTransitionException,
                        IllegalSymbolException,
                        ModelVetoException
Remove a state from the model.

States should not be removed untill they are involved in no transitions. This is to avoid producing corrupted models by accident.

Parameters:
toGo - the state to remove
Throws:
java.lang.UnsupportedOperationException - if the MarkovModel doesn't allow states to be removed
IllegalSymbolException - if the symbol is not part of this model or a MagicalState
IllegalTransitionException - if the state is currently involved in any transitions

addTransitionListener

public void addTransitionListener(TransitionListener tl)
Register a TransitionListener with the model.
Parameters:
tl - a TransitionListener to notify when transitions are created, destroyed or the probabilities changed

removeTransitionListener

public void removeTransitionListener(TransitionListener tl)
Unregister a TransitionListener with the model.
Parameters:
tl - a TransitionListener to no longer notify when transitions are created, destroyed or the probabilities changed