## org.biojava.bio.dp
Class DP

    java.lang.Object
      org.biojava.bio.dp.DP

Direct Known Subclasses:
  PairwiseDP, SingleDP

    public abstract class DP

extends Object

Objects that can perform dymamic programming operations upon sequences with HMMs.

The three main DP operations are Forwards, Backwards and Viterbi. Forwards and Backwards calculate the probability of the sequences having been made in any way by the model. Viterbi finds the most supported way that the sequence could have been made.

Each of the functions can return the dynamic-programming matrix containing the intermediate results. This may be useful for model training, or for visualisation.

Each of the funcitons can be calculated using the model probabilities, the null-model probabilities or the odds (ratio between the two). For Forwards and Backwards, the odds calculations produce numbers with questionable basis in reality. For Viterbi with odds, you will recieve the path through the model that is most different from the null model, and supported by the probabilities.

Author:
  Matthew Pocock, Thomas Down

Nested Class Summary
`static class` `DP.ReverseIterator`

Constructor Summary
`DP()` This method will result in a DP with no model.
`DP(MarkovModel model)`

Method Summary
`abstract double` `backward(SymbolList[] symList, ScoreType scoreType)`
`abstract DPMatrix` `backwardMatrix(SymbolList[] symList, DPMatrix matrix, ScoreType scoreType)`
`abstract DPMatrix` `backwardMatrix(SymbolList[] symList, ScoreType scoreType)`
`static int[][]` `backwardTransitions(MarkovModel model, State[] states)`
`static double[][]` `backwardTransitionScores(MarkovModel model, State[] states, int[][] transitions, ScoreType scoreType)`
`static MarkovModel` `flatView(MarkovModel model)`
`abstract double` `forward(SymbolList[] symList, ScoreType scoreType)`
`abstract DPMatrix` `forwardMatrix(SymbolList[] symList, DPMatrix matrix, ScoreType scoreType)`
`abstract DPMatrix` `forwardMatrix(SymbolList[] symList, ScoreType scoreType)`
`DPMatrix` `forwardsBackwards(SymbolList[] symList, ScoreType scoreType)`
`static int[][]` `forwardTransitions(MarkovModel model, State[] states)` Returns a matrix for the specified States describing all valid Transitions between those States.
`static double[][]` `forwardTransitionScores(MarkovModel model, State[] states, int[][] transitions, ScoreType scoreType)` Compute the log(score) of all transitions between the specified States.
`StatePath` `generate(int length)` Generates an alignment from a model.
`int[][]` `getBackwardTransitions()`
`double[][]` `getBackwardTransitionScores(ScoreType scoreType)`
`int` `getDotStatesIndex()`
`int[][]` `getForwardTransitions()`
`double[][]` `getForwardTransitionScores(ScoreType scoreType)`
`MarkovModel` `getModel()`
`State[]` `getStates()`
`void` `lockModel()`
`static double` `scoreWeightMatrix(WeightMatrix matrix, SymbolList symList, int start)` Scores the SymbolList from symbol start to symbol (start+columns) with a weight matrix.
`static double` `scoreWeightMatrix(WeightMatrix matrix, SymbolList symList, ScoreType scoreType, int start)` Scores the SymbolList from symbol start to symbol (start+columns) with a weight matrix using a particular ScoreType.
`void` `setModel(MarkovModel model)`
`State[]` `stateList(MarkovModel mm)`
`void` `unlockModel()`
`void` `update()`
`abstract StatePath` `viterbi(SymbolList[] symList, ScoreType scoreType)`

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

Constructor Detail

### DP

    public DP(MarkovModel model)

### DP

    public DP()

  This method will result in a DP with no model. Use the setModel() method to set the model before use.

Method Detail

### scoreWeightMatrix

    public static double scoreWeightMatrix(WeightMatrix matrix,
                                           SymbolList symList,
                                           int start)
                                    throws IllegalSymbolException

  Scores the SymbolList from symbol start to symbol (start+columns) with a weight matrix.

  Parameters:
    `matrix` - the weight matrix used to evaluate the sequences
    `symList` - the SymbolList to assess
    `start` - the index of the first symbol in the window to evaluate
  Returns:
    the log probability or likelyhood of this weight matrix having generated symbols start to (start + columns) of symList
  Throws:
    `IllegalSymbolException`

### scoreWeightMatrix

    public static double scoreWeightMatrix(WeightMatrix matrix,
                                           SymbolList symList,
                                           ScoreType scoreType,
                                           int start)
                                    throws IllegalSymbolException

  Scores the SymbolList from symbol start to symbol (start+columns) with a weight matrix using a particular ScoreType.

  This method allows you to use score types such as ScoreType.ODDS. The other scoreWeightMatrix methods gives a result similar or identical to ScoreType.PROBABILITY.

  Parameters:
    `matrix` - the weight matrix used to evaluate the sequences
    `symList` - the SymbolList to assess
    `scoreType` - the score type to apply
    `start` - the index of the first symbol in the window to evaluate
  Returns:
    the sum of log scores of this weight matrix having generated symbols start to (start + columns) of symList
  Throws:
    `IllegalSymbolException`
  Since:
    1.4

### flatView

    public static MarkovModel flatView(MarkovModel model)
                                throws IllegalAlphabetException,
                                       IllegalSymbolException

  Throws:
    `IllegalAlphabetException`
    `IllegalSymbolException`

### stateList

    public State[] stateList(MarkovModel mm)
                      throws IllegalSymbolException,
                             IllegalTransitionException,
                             BioException

  Throws:
    `IllegalSymbolException`
    `IllegalTransitionException`
    `BioException`

### forwardTransitions

    public static int[][] forwardTransitions(MarkovModel model,
                                             State[] states)
                                      throws IllegalSymbolException

  Returns a matrix for the specified States describing all valid Transitions between those States.

  The matrix is 2-dimensional. The primary array has an element corresponding to every State in the states argument. That element is itself an array the elements of which identify the States that can reach that State. The source States are identified by their index within the states [] array.

  Parameters:
    `model` - MarkovModel to be analysed.
    `states` - The States for which the transition matrix is to be determined.
  Throws:
    `IllegalSymbolException`

### forwardTransitionScores

    public static double[][] forwardTransitionScores(MarkovModel model,
                                                     State[] states,
                                                     int[][] transitions,
                                                     ScoreType scoreType)

  Compute the log(score) of all transitions between the specified States. The layout of the array is identical to that of the transitions array.

  Note that all parameters MUST be consistent with each other!!!!

  Parameters:
    `model` - The model for which the data is to be computed.
    `states` - The States within that model for which scores are required.
    `transitions` - The transition matrix obtained by calling forwardTransitions() with the above argument values.
    `scoreType` - The type of score to be evaluated.

### backwardTransitions

    public static int[][] backwardTransitions(MarkovModel model,
                                              State[] states)
                                       throws IllegalSymbolException

  Throws:
    `IllegalSymbolException`

### backwardTransitionScores

    public static double[][] backwardTransitionScores(MarkovModel model,
                                                      State[] states,
                                                      int[][] transitions,
                                                      ScoreType scoreType)

### getDotStatesIndex

    public int getDotStatesIndex()

### getModel

    public MarkovModel getModel()

### getStates

    public State[] getStates()

### getForwardTransitions

    public int[][] getForwardTransitions()

### getForwardTransitionScores

    public double[][] getForwardTransitionScores(ScoreType scoreType)

### getBackwardTransitions

    public int[][] getBackwardTransitions()

### getBackwardTransitionScores

    public double[][] getBackwardTransitionScores(ScoreType scoreType)

### lockModel

    public void lockModel()

### unlockModel

    public void unlockModel()

### update

    public void update()

### setModel

    public void setModel(MarkovModel model)

### forward

    public abstract double forward(SymbolList[] symList,
                                   ScoreType scoreType)
                            throws IllegalSymbolException,
                                   IllegalAlphabetException,
                                   IllegalTransitionException

  Throws:
    `IllegalSymbolException`
    `IllegalAlphabetException`
    `IllegalTransitionException`

### backward

    public abstract double backward(SymbolList[] symList,
                                    ScoreType scoreType)
                             throws IllegalSymbolException,
                                    IllegalAlphabetException,
                                    IllegalTransitionException

  Throws:
    `IllegalSymbolException`
    `IllegalAlphabetException`
    `IllegalTransitionException`

### forwardMatrix

    public abstract DPMatrix forwardMatrix(SymbolList[] symList,
                                           ScoreType scoreType)
                                    throws IllegalSymbolException,
                                           IllegalAlphabetException,
                                           IllegalTransitionException

  Throws:
    `IllegalSymbolException`
    `IllegalAlphabetException`
    `IllegalTransitionException`

### backwardMatrix

    public abstract DPMatrix backwardMatrix(SymbolList[] symList,
                                            ScoreType scoreType)
                                     throws IllegalSymbolException,
                                            IllegalAlphabetException,
                                            IllegalTransitionException

  Throws:
    `IllegalSymbolException`
    `IllegalAlphabetException`
    `IllegalTransitionException`

### forwardMatrix

    public abstract DPMatrix forwardMatrix(SymbolList[] symList,
                                           DPMatrix matrix,
                                           ScoreType scoreType)
                                    throws IllegalArgumentException,
                                           IllegalSymbolException,
                                           IllegalAlphabetException,
                                           IllegalTransitionException

  Throws:
    `IllegalArgumentException`
    `IllegalSymbolException`
    `IllegalAlphabetException`
    `IllegalTransitionException`

### backwardMatrix

    public abstract DPMatrix backwardMatrix(SymbolList[] symList,
                                            DPMatrix matrix,
                                            ScoreType scoreType)
                                     throws IllegalArgumentException,
                                            IllegalSymbolException,
                                            IllegalAlphabetException,
                                            IllegalTransitionException

  Throws:
    `IllegalArgumentException`
    `IllegalSymbolException`
    `IllegalAlphabetException`
    `IllegalTransitionException`

### viterbi

    public abstract StatePath viterbi(SymbolList[] symList,
                                      ScoreType scoreType)
                               throws IllegalSymbolException,
                                      IllegalArgumentException,
                                      IllegalAlphabetException,
                                      IllegalTransitionException

  Throws:
    `IllegalSymbolException`
    `IllegalArgumentException`
    `IllegalAlphabetException`
    `IllegalTransitionException`

### forwardsBackwards

    public DPMatrix forwardsBackwards(SymbolList[] symList,
                                      ScoreType scoreType)
                               throws BioException

  Throws:
    `BioException`

### generate

    public StatePath generate(int length)
                       throws IllegalSymbolException,
                              BioException

  Generates an alignment from a model.

  If the length is set to -1 then the model length will be sampled using the model's transition to the end state. If the length is fixed using length, then the transitions to the end state are implicitly invoked.

  Parameters:
    `length` - the length of the sequence to generate
  Returns:
    a StatePath generated at random
  Throws:
    `IllegalSymbolException`
    `BioException`