de.jstacs.models.hmm.models
Class DifferentiableHigherOrderHMM

java.lang.Object
  extended by de.jstacs.models.hmm.AbstractHMM
      extended by de.jstacs.models.hmm.models.HigherOrderHMM
          extended by de.jstacs.models.hmm.models.DifferentiableHigherOrderHMM
All Implemented Interfaces:
Model, NormalizableScoringFunction, SamplingScoringFunction, ScoringFunction, Storable, Cloneable

public class DifferentiableHigherOrderHMM
extends HigherOrderHMM
implements SamplingScoringFunction

This class combines an HigherOrderHMM and a NormalizableScoringFunction by implementing some of the declared methods.

Author:
Jens Keilwagen

Nested Class Summary
 
Nested classes/interfaces inherited from class de.jstacs.models.hmm.models.HigherOrderHMM
HigherOrderHMM.Type
 
Field Summary
protected  double ess
          The equivalent sample size used for the prior
protected  double[][][] gradient
          Help array for the gradient
protected  int[][] index
          Index array used for computing the gradient
protected  IntList[] indicesState
          Help array for the indexes of the parameters of the states
protected  IntList[] indicesTransition
          Help array for the indexes of the parameters of the transition
protected  int numberOfParameters
          The number of parameters of this HMM
protected  DoubleList[] partDerState
          Help array for the derivatives of the parameters of the states
protected  DoubleList[] partDerTransition
          Help array for the derivatives of the parameters of the transition
protected  HigherOrderHMM.Type score
          The type of the score that is evaluated
 
Fields inherited from class de.jstacs.models.hmm.models.HigherOrderHMM
backwardIntermediate, container, logEmission, numberOfSummands, stateList
 
Fields inherited from class de.jstacs.models.hmm.AbstractHMM
bwdMatrix, con, emission, emissionIdx, finalState, forward, fwdMatrix, name, sostream, START_NODE, states, trainingParameter, transition
 
Fields inherited from interface de.jstacs.scoringFunctions.ScoringFunction
UNKNOWN
 
Constructor Summary
DifferentiableHigherOrderHMM(MaxHMMTrainingParameterSet trainingParameterSet, String[] name, int[] emissionIdx, boolean[] forward, DifferentiableEmission[] emission, boolean likelihood, double ess, TransitionElement... te)
          This is the main constructor.
DifferentiableHigherOrderHMM(StringBuffer xml)
          The standard constructor for the interface Storable.
 
Method Summary
 void addGradientOfLogPriorTerm(double[] grad, int start)
          This method computes the gradient of NormalizableScoringFunction.getLogPriorTerm() for each parameter of this model.
protected  void appendFurtherInformation(StringBuffer xml)
          This method appends further information to the XML representation.
 DifferentiableHigherOrderHMM clone()
          Creates a clone (deep copy) of the current Model instance.
protected  void createHelperVariables()
          This method instantiates all helper variables that are need inside the model for instance for filling forward and backward matrix, ...
protected  void createStates()
          This method creates states for the internal usage.
protected  void extractFurtherInformation(StringBuffer xml)
          This method extracts further information from the XML representation.
 double[] getCurrentParameterValues()
          Returns a double array of dimension ScoringFunction.getNumberOfParameters() containing the current parameter values.
 double getEss()
          Returns the equivalent sample size (ess) of this model, i.e. the equivalent sample size for the class or component that is represented by this model.
 double getInitialClassParam(double classProb)
          Returns the initial class parameter for the class this ScoringFunction is responsible for, based on the class probability classProb.
 String getInstanceName()
          Should return a short instance name such as iMM(0), BN(2), ...
 double getLogNormalizationConstant()
          Returns the logarithm of the sum of the scores over all sequences of the event space.
 double getLogPartialNormalizationConstant(int parameterIndex)
          Returns the logarithm of the partial normalization constant for the parameter with index parameterIndex.
 double getLogScore(Sequence seq)
          Returns the logarithmic score for the Sequence seq.
 double getLogScore(Sequence seq, int start)
          Returns the logarithmic score for the Sequence seq beginning at position start in the Sequence.
 double getLogScoreAndPartialDerivation(Sequence seq, int startPos, IntList indices, DoubleList partialDer)
          Returns the logarithmic score for a Sequence beginning at position start in the Sequence and fills lists with the indices and the partial derivations.
 double getLogScoreAndPartialDerivation(Sequence seq, IntList indices, DoubleList partialDer)
          Returns the logarithmic score for a Sequence seq and fills lists with the indices and the partial derivations.
 int getNumberOfParameters()
          Returns the number of parameters in this ScoringFunction.
 int getNumberOfRecommendedStarts()
          This method returns the number of recommended optimization starts.
 int[][] getSamplingGroups(int parameterOffset)
          Returns groups of indexes of parameters that shall be drawn together in a sampling procedure
 int getSizeOfEventSpaceForRandomVariablesOfParameter(int index)
          Returns the size of the event space of the random variables that are affected by parameter no.
 void initializeFunction(int index, boolean freeParams, Sample[] data, double[][] weights)
          This method creates the underlying structure of the ScoringFunction.
 void initializeFunctionRandomly(boolean freeParams)
          This method initializes the ScoringFunction randomly.
 boolean isInitialized()
          This method can be used to determine whether the model is initialized.
 boolean isNormalized()
          This method indicates whether the implemented score is already normalized to 1 or not.
 void setParameters(double[] params, int start)
          This method sets the internal parameters to the values of params between start and start + ScoringFunction.getNumberOfParameters() - 1
 void train(Sample data, double[] weights)
          Trains the Model object given the data as Sample using the specified weights.
 
Methods inherited from class de.jstacs.models.hmm.models.HigherOrderHMM
baumWelch, emitSample, estimateFromStatistics, fillBwdMatrix, fillBwdOrViterbiMatrix, fillFwdMatrix, fillLogStatePosteriorMatrix, finalize, getCharacteristics, getLength, getLogPriorTerm, getLogProbFor, getLogProbFor, getLogProbForPath, getMaximalMarkovOrder, getNumericalCharacteristics, getViterbiPathFor, getXMLTag, initializeRandomly, isTrained, resetStatistics, samplePath, viterbi
 
Methods inherited from class de.jstacs.models.hmm.AbstractHMM
createMatrixForStatePosterior, decodeStatePosterior, determineFinalStates, fromXML, getAlphabetContainer, getFinalStatePosterioriMatrix, getGraphvizRepresentation, getGraphvizRepresentation, getGraphvizRepresentation, getLogProbFor, getLogProbFor, getLogProbFor, getLogStatePosteriorMatrixFor, getLogStatePosteriorMatrixFor, getNumberOfStates, getPriorTerm, getProbFor, getProbFor, getProbFor, getRunTimeException, getStatePosteriorMatrixFor, getStatePosteriorMatrixFor, getViterbiPathFor, getViterbiPathsFor, initTransition, logProb, provideMatrix, setNewAlphabetContainerInstance, setOutputStream, toString, toXML, train
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface de.jstacs.scoringFunctions.NormalizableScoringFunction
getLogPriorTerm
 
Methods inherited from interface de.jstacs.scoringFunctions.ScoringFunction
getAlphabetContainer, getLength
 
Methods inherited from interface de.jstacs.Storable
toXML
 

Field Detail

numberOfParameters

protected int numberOfParameters
The number of parameters of this HMM


ess

protected double ess
The equivalent sample size used for the prior


score

protected HigherOrderHMM.Type score
The type of the score that is evaluated


index

protected int[][] index
Index array used for computing the gradient


gradient

protected double[][][] gradient
Help array for the gradient


indicesState

protected IntList[] indicesState
Help array for the indexes of the parameters of the states


indicesTransition

protected IntList[] indicesTransition
Help array for the indexes of the parameters of the transition


partDerState

protected DoubleList[] partDerState
Help array for the derivatives of the parameters of the states


partDerTransition

protected DoubleList[] partDerTransition
Help array for the derivatives of the parameters of the transition

Constructor Detail

DifferentiableHigherOrderHMM

public DifferentiableHigherOrderHMM(MaxHMMTrainingParameterSet trainingParameterSet,
                                    String[] name,
                                    int[] emissionIdx,
                                    boolean[] forward,
                                    DifferentiableEmission[] emission,
                                    boolean likelihood,
                                    double ess,
                                    TransitionElement... te)
                             throws Exception
This is the main constructor.

Parameters:
trainingParameterSet - the ParameterSet that determines the training algorithm and contains the necessary Parameters
name - the names of the states
emissionIdx - the indices of the emissions that should be used for each state, if null state i will use emission i
forward - a boolean array that indicates whether the symbol on the forward or the reverse complementary strand should be used, if null all states use the forward strand
emission - the emissions
likelihood - if true the likelihood is return by getLogScore(Sequence) otherwise the viterbi score
ess - the ess of the model
te - the TransitionElements used for creating a Transition
Throws:
Exception - if
  • some component could not be cloned
  • some the length of name, emissionIdx, or forward is not equal to the number of states
  • not all emissions use the same AlphabetContainer
  • the states can not be handled by the transition

DifferentiableHigherOrderHMM

public DifferentiableHigherOrderHMM(StringBuffer xml)
                             throws NonParsableException
The standard constructor for the interface Storable. Constructs an DifferentiableHigherOrderHMM out of an XML representation.

Parameters:
xml - the XML representation as StringBuffer
Throws:
NonParsableException - if the DifferentiableHigherOrderHMM could not be reconstructed out of the StringBuffer xml
Method Detail

appendFurtherInformation

protected void appendFurtherInformation(StringBuffer xml)
Description copied from class: AbstractHMM
This method appends further information to the XML representation. It allows subclasses to save further parameters that are not defined in the superclass.

Overrides:
appendFurtherInformation in class HigherOrderHMM
Parameters:
xml - the XML representation

extractFurtherInformation

protected void extractFurtherInformation(StringBuffer xml)
                                  throws NonParsableException
Description copied from class: HigherOrderHMM
This method extracts further information from the XML representation. It allows subclasses to cast further parameters that are not defined in the superclass.

Overrides:
extractFurtherInformation in class HigherOrderHMM
Parameters:
xml - the XML representation
Throws:
NonParsableException - if the information could not be reconstructed out of the StringBuffer xml

createHelperVariables

protected void createHelperVariables()
Description copied from class: AbstractHMM
This method instantiates all helper variables that are need inside the model for instance for filling forward and backward matrix, ...

Overrides:
createHelperVariables in class HigherOrderHMM

createStates

protected void createStates()
Description copied from class: AbstractHMM
This method creates states for the internal usage.

Overrides:
createStates in class HigherOrderHMM

clone

public DifferentiableHigherOrderHMM clone()
                                   throws CloneNotSupportedException
Description copied from interface: Model
Creates a clone (deep copy) of the current Model instance.

Specified by:
clone in interface Model
Specified by:
clone in interface ScoringFunction
Overrides:
clone in class HigherOrderHMM
Returns:
the cloned instance
Throws:
CloneNotSupportedException - if something went wrong while cloning

getEss

public double getEss()
Description copied from interface: NormalizableScoringFunction
Returns the equivalent sample size (ess) of this model, i.e. the equivalent sample size for the class or component that is represented by this model.

Specified by:
getEss in interface NormalizableScoringFunction
Returns:
the equivalent sample size.

addGradientOfLogPriorTerm

public void addGradientOfLogPriorTerm(double[] grad,
                                      int start)
                               throws Exception
Description copied from interface: NormalizableScoringFunction
This method computes the gradient of NormalizableScoringFunction.getLogPriorTerm() for each parameter of this model. The results are added to the array grad beginning at index start.

Specified by:
addGradientOfLogPriorTerm in interface NormalizableScoringFunction
Parameters:
grad - the array of gradients
start - the start index in the grad array, where the partial derivations for the parameters of this models shall be entered
Throws:
Exception - if something went wrong with the computing of the gradients
See Also:
NormalizableScoringFunction.getLogPriorTerm()

getNumberOfParameters

public int getNumberOfParameters()
Description copied from interface: ScoringFunction
Returns the number of parameters in this ScoringFunction. If the number of parameters is not known yet, the method returns ScoringFunction.UNKNOWN.

Specified by:
getNumberOfParameters in interface ScoringFunction
Returns:
the number of parameters in this ScoringFunction
See Also:
ScoringFunction.UNKNOWN

getNumberOfRecommendedStarts

public int getNumberOfRecommendedStarts()
Description copied from interface: ScoringFunction
This method returns the number of recommended optimization starts. The standard implementation returns 1.

Specified by:
getNumberOfRecommendedStarts in interface ScoringFunction
Returns:
the number of recommended optimization starts

getCurrentParameterValues

public double[] getCurrentParameterValues()
                                   throws Exception
Description copied from interface: ScoringFunction
Returns a double array of dimension ScoringFunction.getNumberOfParameters() containing the current parameter values. If one likes to use these parameters to start an optimization it is highly recommended to invoke ScoringFunction.initializeFunction(int, boolean, Sample[], double[][]) before. After an optimization this method can be used to get the current parameter values.

Specified by:
getCurrentParameterValues in interface ScoringFunction
Returns:
the current parameter values
Throws:
Exception - if no parameters exist (yet)

isInitialized

public boolean isInitialized()
Description copied from interface: ScoringFunction
This method can be used to determine whether the model is initialized. If the model is not initialized you should invoke the method ScoringFunction.initializeFunction(int, boolean, Sample[], double[][]).

Specified by:
isInitialized in interface ScoringFunction
Returns:
true if the model is initialized, false otherwise

setParameters

public void setParameters(double[] params,
                          int start)
Description copied from interface: ScoringFunction
This method sets the internal parameters to the values of params between start and start + ScoringFunction.getNumberOfParameters() - 1

Specified by:
setParameters in interface ScoringFunction
Parameters:
params - the new parameters
start - the start index in params

initializeFunctionRandomly

public void initializeFunctionRandomly(boolean freeParams)
                                throws Exception
Description copied from interface: ScoringFunction
This method initializes the ScoringFunction randomly. It has to create the underlying structure of the ScoringFunction.

Specified by:
initializeFunctionRandomly in interface ScoringFunction
Parameters:
freeParams - indicates whether the (reduced) parameterization is used
Throws:
Exception - if something went wrong

initializeFunction

public void initializeFunction(int index,
                               boolean freeParams,
                               Sample[] data,
                               double[][] weights)
                        throws Exception
Description copied from interface: ScoringFunction
This method creates the underlying structure of the ScoringFunction.

Specified by:
initializeFunction in interface ScoringFunction
Parameters:
index - the index of the class the ScoringFunction models
freeParams - indicates whether the (reduced) parameterization is used
data - the samples
weights - the weights of the sequences in the samples
Throws:
Exception - if something went wrong

train

public void train(Sample data,
                  double[] weights)
           throws Exception
Description copied from interface: Model
Trains the Model object given the data as Sample using the specified weights. The weight at position i belongs to the element at position i. So the array weight should have the number of sequences in the sample as dimension. (Optionally it is possible to use weight == null if all weights have the value one.)
This method should work non-incrementally. That means the result of the following series: train(data1); train(data2) should be a fully trained model over data2 and not over data1+data2. All parameters of the model were given by the call of the constructor.

Specified by:
train in interface Model
Overrides:
train in class HigherOrderHMM
Parameters:
data - the given sequences as Sample
weights - the weights of the elements, each weight should be non-negative
Throws:
Exception - if the training did not succeed (e.g. the dimension of weights and the number of sequences in the sample do not match)
See Also:
Sample.getElementAt(int), Sample.ElementEnumerator

isNormalized

public boolean isNormalized()
Description copied from interface: NormalizableScoringFunction
This method indicates whether the implemented score is already normalized to 1 or not. The standard implementation returns false.

Specified by:
isNormalized in interface NormalizableScoringFunction
Returns:
true if the implemented score is already normalized to 1, false otherwise

getLogNormalizationConstant

public double getLogNormalizationConstant()
Description copied from interface: NormalizableScoringFunction
Returns the logarithm of the sum of the scores over all sequences of the event space.

Specified by:
getLogNormalizationConstant in interface NormalizableScoringFunction
Returns:
the logarithm of the normalization constant Z

getLogPartialNormalizationConstant

public double getLogPartialNormalizationConstant(int parameterIndex)
                                          throws Exception
Description copied from interface: NormalizableScoringFunction
Returns the logarithm of the partial normalization constant for the parameter with index parameterIndex. This is the logarithm of the partial derivation of the normalization constant for the parameter with index parameterIndex,
\[\log \frac{\partial Z(\underline{\lambda})}{\partial \lambda_{parameterindex}}\]
.

Specified by:
getLogPartialNormalizationConstant in interface NormalizableScoringFunction
Parameters:
parameterIndex - the index of the parameter
Returns:
the logarithm of the partial normalization constant
Throws:
Exception - if something went wrong with the normalization
See Also:
NormalizableScoringFunction.getLogNormalizationConstant()

getInitialClassParam

public double getInitialClassParam(double classProb)
Description copied from interface: ScoringFunction
Returns the initial class parameter for the class this ScoringFunction is responsible for, based on the class probability classProb.

Specified by:
getInitialClassParam in interface NormalizableScoringFunction
Specified by:
getInitialClassParam in interface ScoringFunction
Parameters:
classProb - the class probability
Returns:
the initial class parameter

getLogScore

public double getLogScore(Sequence seq)
Description copied from interface: ScoringFunction
Returns the logarithmic score for the Sequence seq.

Specified by:
getLogScore in interface ScoringFunction
Parameters:
seq - the sequence
Returns:
the logarithmic score for the sequence

getLogScore

public double getLogScore(Sequence seq,
                          int start)
Description copied from interface: ScoringFunction
Returns the logarithmic score for the Sequence seq beginning at position start in the Sequence.

Specified by:
getLogScore in interface ScoringFunction
Parameters:
seq - the Sequence
start - the start position in the Sequence
Returns:
the logarithmic score for the Sequence

getLogScoreAndPartialDerivation

public double getLogScoreAndPartialDerivation(Sequence seq,
                                              IntList indices,
                                              DoubleList partialDer)
Description copied from interface: ScoringFunction
Returns the logarithmic score for a Sequence seq and fills lists with the indices and the partial derivations.

Specified by:
getLogScoreAndPartialDerivation in interface ScoringFunction
Parameters:
seq - the Sequence
indices - an IntList of indices, after method invocation the list should contain the indices i where $\frac{\partial \log score(seq)}{\partial \lambda_i}$ is not zero
partialDer - a DoubleList of partial derivations, after method invocation the list should contain the corresponding $\frac{\partial \log score(seq)}{\partial \lambda_i}$ that are not zero
Returns:
the logarithmic score for the Sequence

getLogScoreAndPartialDerivation

public double getLogScoreAndPartialDerivation(Sequence seq,
                                              int startPos,
                                              IntList indices,
                                              DoubleList partialDer)
Description copied from interface: ScoringFunction
Returns the logarithmic score for a Sequence beginning at position start in the Sequence and fills lists with the indices and the partial derivations.

Specified by:
getLogScoreAndPartialDerivation in interface ScoringFunction
Parameters:
seq - the Sequence
startPos - the start position in the Sequence
indices - an IntList of indices, after method invocation the list should contain the indices i where $\frac{\partial \log score(seq)}{\partial \lambda_i}$ is not zero
partialDer - a DoubleList of partial derivations, after method invocation the list should contain the corresponding $\frac{\partial \log score(seq)}{\partial \lambda_i}$ that are not zero
Returns:
the logarithmic score for the Sequence

getSizeOfEventSpaceForRandomVariablesOfParameter

public int getSizeOfEventSpaceForRandomVariablesOfParameter(int index)
Description copied from interface: NormalizableScoringFunction
Returns the size of the event space of the random variables that are affected by parameter no. index, i.e. the product of the sizes of the alphabets at the position of each random variable affected by parameter index. For DNA alphabets this corresponds to 4 for a PWM, 16 for a WAM except position 0, ...

Specified by:
getSizeOfEventSpaceForRandomVariablesOfParameter in interface NormalizableScoringFunction
Parameters:
index - the index of the parameter
Returns:
the size of the event space

getSamplingGroups

public int[][] getSamplingGroups(int parameterOffset)
Description copied from interface: SamplingScoringFunction
Returns groups of indexes of parameters that shall be drawn together in a sampling procedure

Specified by:
getSamplingGroups in interface SamplingScoringFunction
Parameters:
parameterOffset - a global offset on the parameter indexes
Returns:
the groups of indexes. The first dimension represents the different groups while the second dimension contains the parameters that shall be sampled together. Internal parameter indexes need to be increased by parameterOffset.

getInstanceName

public String getInstanceName()
Description copied from interface: Model
Should return a short instance name such as iMM(0), BN(2), ...

Specified by:
getInstanceName in interface Model
Specified by:
getInstanceName in interface ScoringFunction
Overrides:
getInstanceName in class HigherOrderHMM
Returns:
a short instance name