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

java.lang.Object
  extended by 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.
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, NumberFormat nf)
          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,
                       NumberFormat nf)
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
nf - the NumberFormat for the String representation of probabilities
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[],NumberFormat)

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[], NumberFormat), 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