de.jstacs.sequenceScores.statisticalModels.trainable.hmm.transitions
Class BasicHigherOrderTransition.AbstractTransitionElement

java.lang.Object
  de.jstacs.sequenceScores.statisticalModels.trainable.hmm.transitions.BasicHigherOrderTransition.AbstractTransitionElement

All Implemented Interfaces:

Storable, Cloneable

Direct Known Subclasses:

BasicTransitionElement

Enclosing class:

BasicHigherOrderTransition

public abstract static class BasicHigherOrderTransition.AbstractTransitionElement
extends Object
implements Cloneable, Storable

This class declares the probability distribution for a given context, i.e. it contains all possible transition and the corresponding probabilities for a given set offset previously visited states.

Author:

Jan Grau, Jens Keilwagen

Field Summary

protected int[]	context The context, i.e. the visited states, of the BasicHigherOrderTransition.AbstractTransitionElement
protected int[]	descendants The indices for the descendant transition elements that can be visited following the states.
protected double[]	hyperParameters The hyperparameters of the prior over the parameters.
protected double	logNorm The log normalization constant based on the parameters.
protected double[]	parameters The parameters defining the distribution over all states that can be visited.
protected int[]	states The states that can be visited
protected double[]	statistic The sufficient statistic for determining the parameters during sampling, viterbi or Baum-Welch training.

Constructor Summary

BasicHigherOrderTransition.AbstractTransitionElement(int[] context, int[] states, double[] hyperParameters)
This is the main constructor creating a new instance with given context, descendant states, and hyper parameters.

BasicHigherOrderTransition.AbstractTransitionElement(int[] context, int[] states, double[] hyperParameters, double[] weight)
This is the main constructor creating a new instance with given context, descendant states, and hyper parameters.

BasicHigherOrderTransition.AbstractTransitionElement(StringBuffer xml)
The standard constructor for the interface Storable.

Method Summary

void	addToStatistic(int childIdx, double weight, Sequence sequence, int sequencePosition) This method adds a given weight to the sufficient statistic for the parameters.
protected abstract void	appendFurtherInformation(StringBuffer xml) This method appends further information to the XML representation.
void	appendGraphvizDescription(StringBuffer representation, NumberFormat nf, String arrowOption, boolean graphical) This method appends the current transition element to a Graphviz representation of the structure that can be used to create an image.
protected void	appendTransitions(StringBuffer representation, String contextNodeRepresentation, NumberFormat nf, String arrowOption, boolean graphical) This method appends all edges of the transition element to a given Graphviz representation.
BasicHigherOrderTransition.AbstractTransitionElement	clone()
void	drawParametersFromStatistic() This method draws new parameters from the sufficient statistics.
void	estimateFromStatistic() This method estimates the parameters from the sufficient statistic.
protected abstract void	extractFurtherInformation(StringBuffer xml) This method extracts further information from the XML representation.
protected static String	getArrowOption(NumberFormat nf, double prob, double weight, String arrowOption, boolean graphical) This method returns the option for an edge in Graphviz.
int	getChild(int index) This method returns the state index encoded by the child index.
protected String	getContext(String[] stateNames) This method returns a String representation of the context.
int	getDescendant(int index) This method returns the index of the descendant transition element when following the child with index index
protected double	getGraphvizEdgeWeight(int s) This method returns the edge weight for plotting the edge with Graphviz.
protected String	getLabel(String[] stateNames, int stateIdx) This method returns a label for the state.
double	getLogGammaScoreFromStatistic() This method calculates a score for the current statistics, which is independent from the current parameters In general the gamma-score is a product of gamma-functions parameterized with the current statistics
double	getLogPriorTerm() Returns a value that is proportional to the log of the prior.
double	getLogScoreFor(int index, Sequence sequence, int sequencePosition) This method returns the score for the transition from the current context to the state with index index.
int[]	getNextContext(int index, int maximalMarkovOrder) This method returns the next context that will be visited when visiting the child with index index.
int	getNumberOfChildren() This method returns the number of states that can be visited.
int	getNumberOfParameters() This method returns the number of parameters in this transition element.
protected String	getXMLTag() This method returns the xml tag used in toXML().
protected void	init() This method initializes internal fields.
void	initializeRandomly() This method draws new parameters from the prior.
void	joinStatistics(BasicHigherOrderTransition.AbstractTransitionElement... te) This method joins the statistics of different instances and sets this joined statistic as statistic of each instance.
protected void	precompute() This method precomputes internal fields as for instance the normalization constant.
void	resetStatistic() This method resets the sufficient statistic for the parameters.
void	setIndexOfDescendantTransitionElement(int index, int descendant) This method sets the index of the descendant transition element for the child with index index.
void	setParameters(BasicHigherOrderTransition.AbstractTransitionElement t) Set values of parameters of the instance to the value of the parameters of the given instance.
String	toString()
String	toString(String[] stateNames) This method returns a String representation of the transition element using the given names of the states.
StringBuffer	toXML() This method returns an XML representation as StringBuffer of an instance of the implementing class.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

context

protected int[] context

The context, i.e. the visited states, of the BasicHigherOrderTransition.AbstractTransitionElement

states

protected int[] states

The states that can be visited

hyperParameters

protected double[] hyperParameters

The hyperparameters of the prior over the parameters. The order of the elements is the same as for states.

See Also:

getLogPriorTerm(), parameters

parameters

protected double[] parameters

The parameters defining the distribution over all states that can be visited. The order of the elements is the same as for states.

See Also:

states

statistic

protected double[] statistic

The sufficient statistic for determining the parameters during sampling, viterbi or Baum-Welch training. The order of the elements is the same as for states.

See Also:

addToStatistic(int, double, Sequence, int), resetStatistic(), parameters

logNorm

protected double logNorm

The log normalization constant based on the parameters.

See Also:

parameters

descendants

protected int[] descendants

The indices for the descendant transition elements that can be visited following the states. The order of the elements is the same as for states.

See Also:

states

Constructor Detail

BasicHigherOrderTransition.AbstractTransitionElement

public BasicHigherOrderTransition.AbstractTransitionElement(int[] context,
                                                            int[] states,
                                                            double[] hyperParameters)

This is the main constructor creating a new instance with given context, descendant states, and hyper parameters.

Parameters:

context - the context (=previously visited state indices); last entry corresponds to the last state visited

states - the transitions to all possible states; if null then no transition allowed

hyperParameters - the hyper parameters for the transitions; if null then no prior is used

See Also:

BasicHigherOrderTransition.AbstractTransitionElement(int[], int[], double[], double[])

BasicHigherOrderTransition.AbstractTransitionElement

public BasicHigherOrderTransition.AbstractTransitionElement(int[] context,
                                                            int[] states,
                                                            double[] hyperParameters,
                                                            double[] weight)

This is the main constructor creating a new instance with given context, descendant states, and hyper parameters.

Parameters:

context - the context (=previously visited state indices); last entry corresponds to the last state visited

states - the transitions to all possible states; if null then no transition allowed

hyperParameters - the hyper parameters for the transitions; if null then no prior is used

weight - the weight for plotting the edges in Graphviz, enables to modify the edge length, larger weights imply shorter edges (default: 1)

BasicHigherOrderTransition.AbstractTransitionElement

public BasicHigherOrderTransition.AbstractTransitionElement(StringBuffer xml)
                                                     throws NonParsableException

The standard constructor for the interface Storable. Constructs a BasicHigherOrderTransition.AbstractTransitionElement out of an XML representation.

Parameters:

xml - the XML representation as StringBuffer

Throws:

NonParsableException - if the BasicHigherOrderTransition.AbstractTransitionElement could not be reconstructed out of the StringBuffer xml

Method Detail

appendFurtherInformation

protected abstract void appendFurtherInformation(StringBuffer xml)

This method appends further information to the XML representation. It allows subclasses to save further parameters that are not defined in the superclass.

Parameters:

xml - the XML representation

extractFurtherInformation

protected abstract void extractFurtherInformation(StringBuffer xml)
                                           throws NonParsableException

This method extracts further information from the XML representation. It allows subclasses to cast further parameters that are not defined in the superclass.

Parameters:

xml - the XML representation

Throws:

NonParsableException - if the information could not be reconstructed out of the StringBuffer xml

getXMLTag

protected String getXMLTag()

This method returns the xml tag used in toXML().

Returns:

the xml tag used in toXML()

toXML

public StringBuffer toXML()

Description copied from interface: Storable

This method returns an XML representation as StringBuffer of an instance of the implementing class.

Specified by:

toXML in interface Storable

Returns:

the XML representation

init

protected void init()

This method initializes internal fields.

clone

public BasicHigherOrderTransition.AbstractTransitionElement clone()
                                                           throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

precompute

protected void precompute()

This method precomputes internal fields as for instance the normalization constant.

See Also:

logNorm

appendGraphvizDescription

public void appendGraphvizDescription(StringBuffer representation,
                                      NumberFormat nf,
                                      String arrowOption,
                                      boolean graphical)

This method appends the current transition element to a Graphviz representation of the structure that can be used to create an image.

Parameters:

representation - the current Graphviz representation

nf - the NumberFormat used for the probabilities, if null no probabilities will we written

arrowOption - this parameter gives the possibility to set some arrow option

graphical - represent transition probabilities as thickness of edges instead of textual output

See Also:

Transition.getGraphizNetworkRepresentation(NumberFormat, String, boolean), appendTransitions(StringBuffer, String, NumberFormat, String, boolean)

appendTransitions

protected void appendTransitions(StringBuffer representation,
                                 String contextNodeRepresentation,
                                 NumberFormat nf,
                                 String arrowOption,
                                 boolean graphical)

This method appends all edges of the transition element to a given Graphviz representation.

Parameters:

representation - the current Graphviz representation

contextNodeRepresentation - the String representation of the context node(s)

nf - the NumberFormat used for the probabilities, if null no probabilities will we written

arrowOption - this parameter gives the possibility to set some arrow option

graphical - represent transition probabilities as thickness of edges instead of textual output

See Also:

appendGraphvizDescription(StringBuffer, NumberFormat, String, boolean), getArrowOption(NumberFormat, double, double, String, boolean)

getGraphvizEdgeWeight

protected final double getGraphvizEdgeWeight(int s)

This method returns the edge weight for plotting the edge with Graphviz. Larger weights imply shorter edges.

Parameters:

s - the index of the states (child)

Returns:

the weight for the edge

getArrowOption

protected static String getArrowOption(NumberFormat nf,
                                       double prob,
                                       double weight,
                                       String arrowOption,
                                       boolean graphical)

This method returns the option for an edge in Graphviz. Given a probability and a format it returns a String that is used in the Graphviz notation to quantify a specific transition.

Parameters:

nf - the NumberFormat for formating the probability

prob - the probability of a certain transition

weight - the weight for plotting the edges in Graphviz, enables to modify the edge length, larger weights imply shorter edges (default: 1)

arrowOption - further arrow options (e.g. color, ...)

graphical - represent transition probabilities as thickness of edges instead of textual output

Returns:

a String that is used in the Graphviz notation to quantify a specific transition

See Also:

Transition.getGraphizNetworkRepresentation(NumberFormat, String, boolean), appendTransitions(StringBuffer, String, NumberFormat, String, boolean)

getChild

public int getChild(int index)

This method returns the state index encoded by the child index.

Parameters:

index - the index of the child

Returns:

the state index

See Also:

states

getDescendant

public int getDescendant(int index)

This method returns the index of the descendant transition element when following the child with index index

Parameters:

index - the child index

Returns:

the index of the descendant transition element

See Also:

descendants, setIndexOfDescendantTransitionElement(int, int)

setIndexOfDescendantTransitionElement

public void setIndexOfDescendantTransitionElement(int index,
                                                  int descendant)

This method sets the index of the descendant transition element for the child with index index.

Parameters:

index - the index of the child

descendant - the index of the descendant transition element

See Also:

descendants, getDescendant(int)

getNextContext

public int[] getNextContext(int index,
                            int maximalMarkovOrder)

This method returns the next context that will be visited when visiting the child with index index.

Parameters:

index - the index of the child

maximalMarkovOrder - the maximal Markov order to be used

Returns:

the next context that will be visited

getLogScoreFor

public double getLogScoreFor(int index,
                             Sequence sequence,
                             int sequencePosition)

This method returns the score for the transition from the current context to the state with index index.

Parameters:

index - the index of the child

sequence - the sequence, which might be used to retrieve SequenceAnnotation

sequencePosition - the position within the sequence

Returns:

the score for the transition from the current context to the state with index index

getLogPriorTerm

public double getLogPriorTerm()

Returns a value that is proportional to the log of the prior. For maximum likelihood (ML) 0 should be returned.

Returns:

a value that is proportional to the log of the prior

See Also:

Transition.getLogPriorTerm()

getNumberOfChildren

public final int getNumberOfChildren()

This method returns the number of states that can be visited.

Returns:

the number of states that can be visited

See Also:

states

addToStatistic

public void addToStatistic(int childIdx,
                           double weight,
                           Sequence sequence,
                           int sequencePosition)

This method adds a given weight to the sufficient statistic for the parameters.

Parameters:

childIdx - the index of the descendant state

weight - the weight to be added

sequence - the sequence, which might be used to retrieve SequenceAnnotation

sequencePosition - the position within the sequence

See Also:

TransitionWithSufficientStatistic.addToStatistic(int, int, int, double, Sequence, int), statistic, resetStatistic(), estimateFromStatistic(), drawParametersFromStatistic()

joinStatistics

public void joinStatistics(BasicHigherOrderTransition.AbstractTransitionElement... te)

This method joins the statistics of different instances and sets this joined statistic as statistic of each instance. This method might be used for instance in a multi-threaded optimization to join partial statistics.

Parameters:

te - the transition elements to be joined

getNumberOfParameters

public int getNumberOfParameters()

This method returns the number of parameters in this transition element.

Returns:

the number of parameters in this transition element

See Also:

parameters

drawParametersFromStatistic

public void drawParametersFromStatistic()

This method draws new parameters from the sufficient statistics.

See Also:

statistic, resetStatistic(), addToStatistic(int, double, Sequence, int)

estimateFromStatistic

public void estimateFromStatistic()

This method estimates the parameters from the sufficient statistic.

See Also:

statistic, resetStatistic(), addToStatistic(int, double, Sequence, int), TrainableTransition.estimateFromStatistic()

resetStatistic

public void resetStatistic()

This method resets the sufficient statistic for the parameters.

See Also:

statistic, estimateFromStatistic(), drawParametersFromStatistic(), addToStatistic(int, double, Sequence, int), TransitionWithSufficientStatistic.resetStatistic()

initializeRandomly

public void initializeRandomly()

This method draws new parameters from the prior.

getLogGammaScoreFromStatistic

public double getLogGammaScoreFromStatistic()

This method calculates a score for the current statistics, which is independent from the current parameters In general the gamma-score is a product of gamma-functions parameterized with the current statistics

Returns:

the logarithm of the gamma-score for the current statistics

toString

public final String toString()

Overrides:

toString in class Object

toString

public String toString(String[] stateNames)

This method returns a String representation of the transition element using the given names of the states.

Parameters:

stateNames - the names of the states, can be null

Returns:

a String representation of the transition element using the given names of the states

getContext

protected String getContext(String[] stateNames)

This method returns a String representation of the context.

Parameters:

stateNames - the names of the states, can be null

Returns:

a String representation of the context

See Also:

toString(), toString(String[])

getLabel

protected final String getLabel(String[] stateNames,
                                int stateIdx)

This method returns a label for the state.

Parameters:

stateNames - the names of the states, can be null

stateIdx - the index of the states

Returns:

the label for the state

See Also:

toString(String[]), getContext(String[])

setParameters

public void setParameters(BasicHigherOrderTransition.AbstractTransitionElement t)
                   throws IllegalArgumentException

Set values of parameters of the instance to the value of the parameters of the given instance. It can be assumed that the given instance and the current instance are from the same class. This method might be used for instance in a multi-threaded optimization to broadcast the parameters.

Parameters:

t - the transition element with the parameters to be set

Throws:

IllegalArgumentException - if the assumption about the same class for given and current instance is wrong