org.broadinstitute.hellbender.utils.hmm

Interface ForwardBackwardAlgorithm.Result<D,T,S>

Type Parameters:

D - the observed data type.

T - the observation time/position type.

S - the hidden state type.

Enclosing class:

ForwardBackwardAlgorithm

public static interface ForwardBackwardAlgorithm.Result<D,T,S>

The forward-backward algorithm result query interface.

Method Summary

Modifier and Type	Method and Description
java.util.List<D>	data() Returns the data passed to the forward-backward algorithm.
double	logBackwardProbability(int position, S state) Returns the backward probability of the hidden state at certain position.
double	logBackwardProbability(T position, S state) Returns the backward probability of the hidden state at certain position.
double	logChainPosteriorProbability() Returns the posterior probability of the hidden chain, defined as: \log \pi_i E[z_{i,0}] + \log T_{t, t+1}^{i, j} E[z_{i,t} z_{j,t+1}] This quantity is the logDataLikelihood excluding the emission probability
double	logConstrainedProbability(int from, java.util.List<java.util.Set<S>> stateConstraints) Return the posterior probability of a sequence of hidden state constraints.
double	logConstrainedProbability(T from, java.util.List<java.util.Set<S>> stateConstraints) Return the posterior probability of a sequence of hidden state constraints.
double	logDataLikelihood() Returns the likelihood of the original data given the model.
double	logDataLikelihood(int position) Returns the likelihood of the original data given the model as evaluated at a particular position.
double	logDataLikelihood(T target) Returns the likelihood of the original data given the model as evaluated at a particular position.
double	logForwardProbability(int position, S state) Returns the forward probability of the hidden state at certain position.
double	logForwardProbability(T position, S state) Returns the forward probability of the hidden state at certain position.
default double	logJointProbability(int from, int to, S fromState, S toState) Return the posterior joint probability of going from one state to another in a specified interval
default double	logProbability(int from, int to, S state) Returns the posterior probability that the hidden state takes on a constant value along a position interval.
double	logProbability(int from, java.util.List<S> states) Returns the posterior probability of a sequence of hidden states starting at a particular position.
double	logProbability(int position, S state) Returns the posterior probability of the hidden state at certain position.
double	logProbability(java.util.List<S> states) Returns the posterior probability of a full sequence of hidden states given the original data and position sequences.
double	logProbability(T from, java.util.List<S> states) Returns the posterior probability of a sequence of hidden states starting at a particular position.
double	logProbability(T position, S state) Returns the posterior probability of the hidden state at certain position.
HMM<D,T,S>	model() Returns the model passed to the forward-backward algorithm.
java.util.List<T>	positions() Returns the list of positions passed to the forward-backward algorithm

Method Detail

data

java.util.List<D> data()

Returns the data passed to the forward-backward algorithm.

Returns:

never null.

positions

java.util.List<T> positions()

Returns the list of positions passed to the forward-backward algorithm

Returns:

never null.

model

HMM<D,T,S> model()

Returns the model passed to the forward-backward algorithm.

Returns:

never null.

logForwardProbability

double logForwardProbability(int position,
                             S state)

Returns the forward probability of the hidden state at certain position.

Parameters:

position - the query position index.

state - the query hidden state.

Returns:

a valid probability in log scale (from -Inf to 0).

Throws:

java.lang.IllegalArgumentException - if either the state or the position are not recognized by the model or were not passed to the forward-backward algorithm.

logForwardProbability

double logForwardProbability(T position,
                             S state)

Returns the forward probability of the hidden state at certain position.

Parameters:

position - the query position.

state - the query hidden state.

Returns:

a valid probability in log scale (from -Inf to 0).

Throws:

java.lang.IllegalArgumentException - if either the state or the position are not recognized by the model or were not passed to the forward-backward algorithm.

logBackwardProbability

double logBackwardProbability(int position,
                              S state)

Returns the backward probability of the hidden state at certain position.

Parameters:

position - the query position index.

state - the query hidden state.

Returns:

a valid probability in log scale (from -Inf to 0)

Throws:

java.lang.IllegalArgumentException - if either the state or the position are not recognized by the model or were not passed to the forward-backward algorithm.

logBackwardProbability

double logBackwardProbability(T position,
                              S state)

Returns the backward probability of the hidden state at certain position.

Parameters:

position - the query position.

state - the query hidden state.

Returns:

a valid probability in log scale (from -Inf to 0)

Throws:

java.lang.IllegalArgumentException - if either the state or the position are not recognized by the model or were not passed to the forward-backward algorithm.

logProbability

double logProbability(int position,
                      S state)

Returns the posterior probability of the hidden state at certain position.

Parameters:

position - the query position index.

state - the query hidden state.

Returns:

a valid probability in log scale (from -Inf to 0)

Throws:

java.lang.IllegalArgumentException - if either the state or the position are not recognized by the model or were not passed to the forward-backward algorithm.

logProbability

double logProbability(T position,
                      S state)

Returns the posterior probability of the hidden state at certain position.

Parameters:

position - the query position.

state - the query hidden state.

Returns:

a valid probability in log scale (from -Inf to 0)

Throws:

java.lang.IllegalArgumentException - if either the state or the position are not recognized by the model or were not passed to the forward-backward algorithm.

logProbability

double logProbability(java.util.List<S> states)

Returns the posterior probability of a full sequence of hidden states given the original data and position sequences.

Parameters:

states - the list of states.

Returns:

a valid probability in log scale (from -Inf to 0)

Throws:

java.lang.IllegalArgumentException - if states, is null, contains some value not recognized as a hidden state by the model, or is not of the same length as the original data.

logProbability

default double logProbability(int from,
                              int to,
                              S state)

Returns the posterior probability that the hidden state takes on a constant value along a position interval.

Parameters:

from - the starting position index for the query interval (inclusive).

to - the stop position index for the query interval (exclusive).

state - the query constant hidden state.

Returns:

a valid probability in log scale (from -Inf to 0)

Throws:

java.lang.IllegalArgumentException - if state, is not a valid state in the underlying model or the from and to do not represent a valid position index range.

logProbability

double logProbability(int from,
                      java.util.List<S> states)

Returns the posterior probability of a sequence of hidden states starting at a particular position.

Parameters:

from - the starting position index, so that the first element in states corresponds to the state at this position.

states - the list of states.

Returns:

a valid probability in log scale (from -Inf to 0)

Throws:

java.lang.IllegalArgumentException - if states, is null, contains some value not recognized as a hidden state by the model, or the states sequence is too long and would go beyond the last position.

logProbability

double logProbability(T from,
                      java.util.List<S> states)

Returns the posterior probability of a sequence of hidden states starting at a particular position.

Parameters:

from - the starting position, so that the first element in states corresponds to the state at this position.

states - the list of states.

Returns:

a valid probability in log scale (from -Inf to 0)

Throws:

java.lang.IllegalArgumentException - if states, is null, contains some value not recognized as a hidden state by the model, or the states sequence is too long and would go beyond the last position.

logConstrainedProbability

double logConstrainedProbability(int from,
                                 java.util.List<java.util.Set<S>> stateConstraints)

Return the posterior probability of a sequence of hidden state constraints.

Parameters:

from - the first position index, that corresponds to the first constraint in stateConstraints

stateConstraints - the query constrain sequence.

Returns:

a log scaled probability between 0 and -Inf.

Throws:

java.lang.IllegalArgumentException - if stateConstraints is null, it contains a null set or any of the states in any of the sets in stateConstraints is not recognized by the model or from is not a valid position in the original data/position sequence.

logConstrainedProbability

double logConstrainedProbability(T from,
                                 java.util.List<java.util.Set<S>> stateConstraints)

Return the posterior probability of a sequence of hidden state constraints.

Parameters:

from - the first target, that corresponds to the first constraint in stateConstraints

stateConstraints - the query constrain sequence.

Returns:

a log scaled probability between 0 and -Inf.

Throws:

java.lang.IllegalArgumentException - if stateConstraints is null, it contains a null set or any of the states in any of the sets in stateConstraints is not recognized by the model or from is not a valid position in the original data/position sequence.

logJointProbability

default double logJointProbability(int from,
                                   int to,
                                   S fromState,
                                   S toState)

Return the posterior joint probability of going from one state to another in a specified interval

Parameters:

from - the starting position (inclusive)

to - the stop position (inclusive)

fromState - the initial state

toState - the final state

Returns:

a valid probability in log scale (from -Inf to 0)

Throws:

java.lang.IllegalArgumentException - if fromState or toState are not valid states in the underlying model or the from and to do not represent a valid position index range.

logDataLikelihood

double logDataLikelihood()

Returns the likelihood of the original data given the model.

Returns:

a valid probability in log scale (from -Inf to 0)

logDataLikelihood

double logDataLikelihood(int position)

Returns the likelihood of the original data given the model as evaluated at a particular position.

Although in theory one does not need to indicate a position to evaluate the data-likelihood in practice, lack of float point precision may make those small differences important (e.g. some computations with small probabilities may result in a probability just over 1.0 which makes no sense).

As a rule of thumb, to avoid such problems you should request the data-likelihood at the target from which you evaluate the backward probability.

Parameters:

position - the position.

Returns:

a valid log scaled probability from -Inf to 0.

Throws:

java.lang.IllegalArgumentException - if target is unknown to the model.

logDataLikelihood

double logDataLikelihood(T target)

Returns the likelihood of the original data given the model as evaluated at a particular position.

Although in theory one does not need to indicate a position to evaluate the data-likelihood in practice, lack of float point precision may make those small differences important (e.g. some computations with small probabilities may result in a probability just over 1.0 which makes no sense).

As a rule of thumb, to avoid such problems you should request the data-likelihood at the target from which you evaluate the backward probability.

Parameters:

target - the position.

Returns:

a valid log scaled probability from -Inf to 0.

Throws:

java.lang.IllegalArgumentException - if target is unknown to the model.

logChainPosteriorProbability

double logChainPosteriorProbability()

Returns the posterior probability of the hidden chain, defined as: \log \pi_i E[z_{i,0}] + \log T_{t, t+1}^{i, j} E[z_{i,t} z_{j,t+1}] This quantity is the logDataLikelihood excluding the emission probability

Returns:

a log scaled probability from -Inf to 0.