Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## de.jstacs.models.hmm.models
Class DifferentiableHigherOrderHMM

    java.lang.Object
      de.jstacs.models.hmm.AbstractHMM
          de.jstacs.models.hmm.models.HigherOrderHMM
              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 `Parameter`s
    `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 `TransitionElement`s 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`,
  .

  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 is not zero
    `partialDer` - a `DoubleList` of partial derivations, after method invocation the list should contain the corresponding 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 is not zero
    `partialDer` - a `DoubleList` of partial derivations, after method invocation the list should contain the corresponding 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD