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.mixture
Class AbstractMixtureModel

    java.lang.Object
      de.jstacs.models.AbstractModel
          de.jstacs.models.mixture.AbstractMixtureModel

All Implemented Interfaces:
  Model, Storable, Cloneable

Direct Known Subclasses:
  HiddenMotifMixture, MixtureModel, StrandModel

    public abstract class AbstractMixtureModel

extends AbstractModel

This is the abstract class for all kinds of mixture models. It enables the user to train the parameters using `AbstractMixtureModel.Algorithm.EM` or `AbstractMixtureModel.Algorithm.GIBBS_SAMPLING`. If this instance is trained using `AbstractMixtureModel.Algorithm.GIBBS_SAMPLING` the internal models that will be adjusted have to implement `GibbsSamplingComponent`. If you use Gibbs sampling temporary files will be created in the Java temp folder. These files will be deleted if no reference to the current instance exists and the Garbage Collector is called. Therefore it is recommended to call the Garbage Collector explicitly at the end of any application.
The model stores a reference to the last sample used in `train`. This enables the user to estimate the parameters iteratively beginning with the current set of parameters. Therefore you can use the method `continueIterations(double[], double[][], int, int)` .
The method `setOutputStream(OutputStream)` enables the user to get comments from the `train(Sample, double[])` method or to repress them.
The method `getScoreForBestRun()` enables the user to optimize different instances of the same model ( `clone()`) using the EM-algorithm on different CPUs, to compare the results and to select the best trained model. This might be useful to get the results faster (measured in real time).
The reference to the internal sample is not stored if the model is stored in a `StringBuffer`. So you can use these methods only after training the parameters after (re)creating a model.

Author:
  Jens Keilwagen, Berit Haldemann
See Also:
  `GibbsSamplingComponent`, `System.gc()`

Nested Class Summary
`static class` | `AbstractMixtureModel.Algorithm` This `enum` defines the different types of algorithms that can be used in an `AbstractMixtureModel`.
`static class` | `AbstractMixtureModel.Parameterization` This `enum` defines the different types of parameterization for a probability that can be used in an `AbstractMixtureModel`.

Field Summary
`protected AbstractMixtureModel.Algorithm` | `algorithm` The type of algorithm.
`protected boolean` | `algorithmHasBeenRun` A switch which indicates that the algorithm for determining the parameters has been run.
`protected Model[]` | `alternativeModel` The alternative models for the EM.
`protected double` | `best`
`protected BurnInTest` | `burnInTest` The `BurnInTest` that is used to stop the sampling.
`protected double[]` | `componentHyperParams` The hyperparameters for estimating the probabilities of the components.
`protected double[]` | `compProb` This array is used while training to avoid creating many new objects.
`protected int[]` | `counter` The current index of the parameter set while adjustment (optimization).
`protected int` | `dimension` The number of dimensions.
`protected boolean` | `estimateComponentProbs` The switch for estimating the component probabilities or not.
`protected File[]` | `file` The file in which the component probabilities are stored.
`protected BufferedReader` | `filereader` Reading component probabilities from a file.
`protected BufferedWriter` | `filewriter` Saving component probabilities in a file.
`protected int` | `initialIteration` The number of initial iterations.
`protected double[]` | `logWeights` The log probabilities for each component.
`protected Model[]` | `model` The model for the sequences.
`protected boolean[]` | `optimizeModel` A switch for each model whether to optimize/adjust or not.
`protected Sample[]` | `sample` The sample that was used in the last training.
`protected int` | `samplingIndex` The current index of the sampling.
`protected double[][]` | `seqWeights`
`protected SafeOutputStream` | `sostream` This is the stream for writing information while training.
`protected int` | `starts` The number of starts.
`protected int` | `stationaryIteration` The number of (stationary) iterations of the Gibbs Sampler.
`protected double[]` | `weights` The probabilities for each component.

Fields inherited from class de.jstacs.models.AbstractModel
`alphabets, length`

Constructor Summary
`protected` | `AbstractMixtureModel(int length, Model[] models, boolean[] optimizeModel, int dimension, int starts, boolean estimateComponentProbs, double[] componentHyperParams, double[] weights, AbstractMixtureModel.Algorithm algorithm, double alpha, TerminationCondition tc, AbstractMixtureModel.Parameterization parametrization, int initialIteration, int stationaryIteration, BurnInTest burnInTest)` Creates a new `AbstractMixtureModel`.
`protected` | `AbstractMixtureModel(StringBuffer xml)` The standard constructor for the interface `Storable`.

Method Summary
`boolean` | `algorithmHasBeenRun()` This method indicates whether the parameters of the model has been determined by the internal algorithm.
`protected void` | `checkLength(int index, int l)` This method checks if the length `l` of the model with index `index` is capable for the current instance.
`protected void` | `checkModelsForGibbsSampling()` This method can be used to check whether the necessary models have implemented the `GibbsSamplingComponent`.
`AbstractMixtureModel` | `clone()` Follows the conventions of `Object`'s `clone()`-method.
`protected double` | `continueIterations(double[] dataWeights, double[][] seqweights)` This method will run the train algorithm for the current model on the internal sample.
`protected double` | `continueIterations(double[] dataWeights, double[][] seqweights, int iterations, int start)` This method will run the train algorithm for the current model on the internal sample.
`protected double[][]` | `createSeqWeightsArray()` Creates an array that can be used for weighting sequences in the algorithm.
`protected abstract double[][]` | `doFirstIteration(double[] dataWeights, MultivariateRandomGenerator m, MRGParams[] params)` This method will do the first step in the train algorithm for the current model on the internal sample.
`protected double[][]` | `doFirstIteration(Sample data, double[] dataWeights)` This method will do the first step in the train algorithm for the current model.
`protected double[][]` | `doFirstIteration(Sample data, double[] dataWeights, MultivariateRandomGenerator m, MRGParams[] params)` This method will do the first step in the train algorithm for the current model.
`static int` | `draw(double[] w, int start)` This method draws an index of an array corresponding to the probabilities encoded in the entries of the array.
`Sample` | `emitSample(int n, int... lengths)` This method returns a `Sample` object containing artificial sequence(s).
`protected abstract Sequence[]` | `emitSampleUsingCurrentParameterSet(int n, int... lengths)` The method returns an array of sequences using the current parameter set.
`protected void` | `extendSampling(int sampling)` This method prepares the model to extend an existing sampling.
`protected void` | `extractFurtherInformation(StringBuffer xml)` This method is used in the subclasses to extract further information from the XML representation and to set these as values of the instance.
`protected void` | `finalize()`
`protected void` | `fromXML(StringBuffer representation)` This method should only be used by the constructor that works on a `StringBuffer`.
`ResultSet` | `getCharacteristics()` Returns some information characterizing or describing the current instance of the model.
`protected StringBuffer` | `getFurtherInformation()` This method is used in the subclasses to append further information to the XML representation.
`int` | `getIndexOfMaximalComponentFor(Sequence s)` Returns the index `i` of the component with `P(i|s)`maximal.``
`String` | `getInstanceName()` Should return a short instance name such as iMM(0), BN(2), ...
`double` | `getLogPriorTerm()` Returns a value that is proportional to the log of the prior.
`protected double` | `getLogPriorTermForComponentProbs()` This method computes the part of the prior that comes from the component probabilities.
`double` | `getLogProbFor(int component, Sequence s)` Returns the logarithmic probability for the sequence and the given component.
`double[]` | `getLogProbFor(Sample data)` This method computes the logarithm of the probabilities of all sequences in the given sample.
`double` | `getLogProbFor(Sequence sequence, int startpos, int endpos)` Returns the logarithm of the probability of (a part of) the given sequence given the model.
`protected abstract double` | `getLogProbUsingCurrentParameterSetFor(int component, Sequence s, int start, int end)` Returns the logarithmic probability for the sequence and the given component using the current parameter set.
`Model` | `getModel(int i)` Returns a deep copy of the `i`-th model.
`Model[]` | `getModels()` Returns a deep copy of the models.
`protected MultivariateRandomGenerator` | `getMRG()` This method creates the multivariate random generator that will be used during initialization.
`protected MRGParams` | `getMRGParams()` This method creates the parameters used in a multivariate random generator while initialization.
`String` | `getNameOfAlgorithm()` Returns the name of the used algorithm.
`protected void` | `getNewComponentProbs(double[] weights)` Estimates the weights of each component.
`protected void` | `getNewParameters(int iteration, double[][] seqWeights, double[] w)` This method trains the internal models on the internal sample and the given weights.
`protected void` | `getNewParametersForModel(int modelIndex, int iteration, int sampleIndex, double[] seqWeights)` This method trains the internal model with index `modelIndex` on the internal sample and the given weights.
`protected abstract double` | `getNewWeights(double[] dataWeights, double[] w, double[][] seqweights)` Computes sequence weights and returns the score.
`int` | `getNumberOfComponents()` Returns the number of components the are modeled by this `AbstractMixtureModel`.
`NumericalResultSet` | `getNumericalCharacteristics()` Returns the subset of numerical values that are also returned by `Model.getCharacteristics()`.
`double` | `getProbFor(Sequence sequence, int startpos, int endpos)` Returns the probability of (a part of) the given sequence given the model.
`double` | `getScoreForBestRun()` Returns the value of the optimized function from the best run of the last training.
`protected Time` | `getTime()` This method returns an instance of `Time` that is used for the `TerminationCondition` in the EM.
`double[]` | `getWeights()` This method returns a deep copy of the weights for each component.
`protected void` | `initModelForSampling(int starts)` This method initializes the model for the sampling.
`protected void` | `initWithPrior(double[] w)` This method sets the initial weights before counting the usage of each component.
`protected boolean` | `isInSamplingMode()` This method returns `true` if the object is currently used in a sampling, otherwise `false`.
`boolean` | `isTrained()` Returns `true` if the model has been trained successfully, `false` otherwise.
`protected double` | `iterate(int start, double[] dataWeights, MultivariateRandomGenerator m, MRGParams[] params)` This method runs the train algorithm for the current model and the internal data set.
`double` | `iterate(Sample data, double[] dataWeights, MultivariateRandomGenerator m, MRGParams[] params)` This method runs the train algorithm for the current model.
`static int` | `max(double[] w, int start, int end)` This method returns the index of a maximal entry in the array `w` between index `start` and `end`.
`protected double` | `modifyWeights(double[] w)` This method modifies the computed weights for one sequence and returns the score.
`protected boolean` | `parseNextParameterSet()` This method allows the user to parse the next set of parameters (from a file).
`protected boolean` | `parseParameterSet(int sampling, int burnInIteration)` This method allows the user to parse the set of parameters with index `burnInIteration` of a specific `sampling` (from a file).
`protected void` | `samplingStopped()` This method is the opposite of the method `initModelForSampling(int)`.
`protected void` | `set(AlphabetContainer abc)` This method should only be invoked by the method `AbstractModel.setNewAlphabetContainerInstance(AlphabetContainer)` and not be made public.
`void` | `setAlpha(double alpha)` Sets the parameter of the Dirichlet distribution which is used when you invoke `train` to init the gammas.
`void` | `setOutputStream(OutputStream o)` Sets the `OutputStream` that is used e.g. for writing information while training.
`protected abstract void` | `setTrainData(Sample data)` This method is invoked by the `train`-method and sets for a given sample the sample that should be used for `train`.
`protected void` | `setWeights(double... weights)` Sets the weights of each component.
`protected void` | `swap()` This method swaps the current component models with the alternative model.
`StringBuffer` | `toXML()` This method returns an XML representation as `StringBuffer` of an instance of the implementing class.
`void` | `train(Sample data, double[] dataWeights)` Trains the `Model` object given the data as `Sample` using the specified weights.

Methods inherited from class de.jstacs.models.AbstractModel
`getAlphabetContainer, getLength, getLogProbFor, getLogProbFor, getLogProbFor, getMaximalMarkovOrder, getPriorTerm, getProbFor, getProbFor, setNewAlphabetContainerInstance, train`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface de.jstacs.models.Model
`toString`

Field Detail

### weights

    protected double[] weights

  The probabilities for each component.

### logWeights

    protected double[] logWeights

  The log probabilities for each component.

### componentHyperParams

    protected double[] componentHyperParams

  The hyperparameters for estimating the probabilities of the components.

### model

    protected Model[] model

  The model for the sequences.

### alternativeModel

    protected Model[] alternativeModel

  The alternative models for the EM.

### starts

    protected int starts

  The number of starts.

### dimension

    protected int dimension

  The number of dimensions.

### best

    protected double best

### sostream

    protected SafeOutputStream sostream

  This is the stream for writing information while training.

### sample

    protected Sample[] sample

  The sample that was used in the last training. Will not be stored in the `StringBuffer` when invoking `toXML()`.

### estimateComponentProbs

    protected boolean estimateComponentProbs

  The switch for estimating the component probabilities or not.

### optimizeModel

    protected boolean[] optimizeModel

  A switch for each model whether to optimize/adjust or not.

### algorithm

    protected AbstractMixtureModel.Algorithm algorithm

  The type of algorithm.

### algorithmHasBeenRun

    protected boolean algorithmHasBeenRun

  A switch which indicates that the algorithm for determining the parameters has been run.

### initialIteration

    protected int initialIteration

  The number of initial iterations.

### stationaryIteration

    protected int stationaryIteration

  The number of (stationary) iterations of the Gibbs Sampler.

### burnInTest

    protected BurnInTest burnInTest

  The `BurnInTest` that is used to stop the sampling.

### filewriter

    protected BufferedWriter filewriter

  Saving component probabilities in a file.

### filereader

    protected BufferedReader filereader

  Reading component probabilities from a file.

### file

    protected File[] file

  The file in which the component probabilities are stored.

### counter

    protected int[] counter

  The current index of the parameter set while adjustment (optimization).

### samplingIndex

    protected int samplingIndex

  The current index of the sampling.

### compProb

    protected double[] compProb

  This array is used while training to avoid creating many new objects.

### seqWeights

    protected double[][] seqWeights

Constructor Detail

### AbstractMixtureModel

    protected AbstractMixtureModel(int length,
                                   Model[] models,
                                   boolean[] optimizeModel,
                                   int dimension,
                                   int starts,
                                   boolean estimateComponentProbs,
                                   double[] componentHyperParams,
                                   double[] weights,
                                   AbstractMixtureModel.Algorithm algorithm,
                                   double alpha,
                                   TerminationCondition tc,
                                   AbstractMixtureModel.Parameterization parametrization,
                                   int initialIteration,
                                   int stationaryIteration,
                                   BurnInTest burnInTest)
                            throws CloneNotSupportedException,
                                   IllegalArgumentException,
                                   WrongAlphabetException

  Creates a new `AbstractMixtureModel`. This constructor can be used for any algorithm since it takes all necessary values as parameters.

  Parameters:
    `length` - the length used in this model
    `models` - the single models building the `AbstractMixtureModel`, if the model is trained using `AbstractMixtureModel.Algorithm.GIBBS_SAMPLING` the models that will be adjusted have to implement `GibbsSamplingComponent`
    `optimizeModel` - an array of switches to determine whether a model should be optimized or not
    `dimension` - the number of components
    `starts` - the number of times the algorithm will be started in the `train`-method, at least 1
    `estimateComponentProbs` - the switch for estimating the component probabilities in the algorithm or to hold them fixed; if the component parameters are fixed, the values of `weights` will be used, otherwise the `componentHyperParams` will be incorporated in the adjustment
    `componentHyperParams` - the hyperparameters for the component assignment prior
    - will only be used if `estimateComponentProbs == true`
    - the array has to be `null` or has to have length `dimension`
    - `null` or an array with all values zero (0) then ML
    - otherwise (all values positive) a prior is used (MAP, MP, ...)
    - depends on the `parameterization`
    `weights` - `null` or the weights for the components (then `weights.length == dimension`)
    `algorithm` - either `AbstractMixtureModel.Algorithm.EM` or `AbstractMixtureModel.Algorithm.GIBBS_SAMPLING`
    `alpha` - only for `AbstractMixtureModel.Algorithm.EM`
    the positive parameter for the Dirichlet distribution which is used when you invoke `train` to initialize the gammas. It is recommended to use `alpha = 1` (uniform distribution on a simplex).
    `tc` - only for `AbstractMixtureModel.Algorithm.EM`
    the `TerminationCondition` for stopping the EM-algorithm, `tc` has to return `true` from `TerminationCondition.isSimple()`
    `parametrization` - only for `AbstractMixtureModel.Algorithm.EM`
    the type of the component probability parameterization;
    - `AbstractMixtureModel.Parameterization.THETA` or `AbstractMixtureModel.Parameterization.LAMBDA`
    - the parameterization of a component is determined by the component model
    - it is recommended to use the same parameterization for the components and the component assignment probabilities
    - it is recommended to use `AbstractMixtureModel.Parameterization.LAMBDA`
    `initialIteration` - only for `AbstractMixtureModel.Algorithm.GIBBS_SAMPLING`
    the positive length of the initial sampling phase (at least 1, at most `stationaryIteration/starts`)
    `stationaryIteration` - only for `AbstractMixtureModel.Algorithm.GIBBS_SAMPLING`
    the positive length of the stationary phase (at least 1) (summed over all starts), i.e. the number of parameter sets that is used for approximation
    `burnInTest` - only for `AbstractMixtureModel.Algorithm.GIBBS_SAMPLING`
    the test that will be used to determine the length of the burn-in phase
  Throws:
    `IllegalArgumentException` - if
    - the models are not able to score the sequence of length `length`
    - `dimension < 1`
    - `weights != null && weights.length != dimension`
    - `weights != null` and it exists an `i` where `weights[i] < 0`
    - `starts < 1`
    - `componentHyperParams` are not correct
    - the algorithm specific parameters are not correct
    `WrongAlphabetException` - if not all `models` work on the same alphabet
    `CloneNotSupportedException` - if the `models` can not be cloned

### AbstractMixtureModel

    protected AbstractMixtureModel(StringBuffer xml)
                            throws NonParsableException

  The standard constructor for the interface `Storable`. Creates a new `AbstractMixtureModel` out of its XML representation.

  Parameters:
    `xml` - the XML representation of the model as `StringBuffer`
  Throws:
    `NonParsableException` - if the `StringBuffer` can not be parsed

Method Detail

### clone

    public AbstractMixtureModel clone()
                               throws CloneNotSupportedException

  Description copied from class: `AbstractModel`
  Follows the conventions of `Object`'s `clone()`-method.

  Specified by:
    `clone` in interface `Model`
  Overrides:
    `clone` in class `AbstractModel`
  Returns:
    an object, that is a copy of the current `AbstractModel` (the member-`AlphabetContainer` isn't deeply cloned since it is assumed to be immutable). The type of the returned object is defined by the class `X` directly inherited from `AbstractModel`. Hence `X`'s `clone()`-method should work as:
    1. `Object o = (X)super.clone();`
    2. all additional member variables of `o` defined by `X` that are not of simple data-types like `int`, `double`, ... have to be deeply copied
    3. `return o`
  Throws:
    `CloneNotSupportedException` - if something went wrong while cloning

### getMRG

    protected MultivariateRandomGenerator getMRG()

  This method creates the multivariate random generator that will be used during initialization.

  Returns:
    a multivariate random generator
  See Also:
    `getMRGParams()`

### getMRGParams

    protected MRGParams getMRGParams()

  This method creates the parameters used in a multivariate random generator while initialization.

  Returns:
    the parameters for the multivariate random generator
  See Also:
    `getMRG()`

### train

    public void train(Sample data,
                      double[] dataWeights)
               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.

  Parameters:
    `data` - the given sequences as `Sample`
    `dataWeights` - 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`

### swap

    protected void swap()

  This method swaps the current component models with the alternative model.
  This method should NOT be made public and should ONLY be used in the `train`-method.

### setTrainData

    protected abstract void setTrainData(Sample data)
                                  throws Exception

  This method is invoked by the `train`-method and sets for a given sample the sample that should be used for `train`.

  Parameters:
    `data` - the given sample of sequences
  Throws:
    `Exception` - if something went wrong

### createSeqWeightsArray

    protected double[][] createSeqWeightsArray()

  Creates an array that can be used for weighting sequences in the algorithm.

  Returns:
    an array that can be used for weighting sequences in the algorithm

### iterate

    public double iterate(Sample data,
                          double[] dataWeights,
                          MultivariateRandomGenerator m,
                          MRGParams[] params)
                   throws Exception

  This method runs the train algorithm for the current model.

  Parameters:
    `data` - the sample of sequences
    `dataWeights` - the weights for each sequence or `null`
    `m` - the random generator for initiating the algorithm
    `params` - the parameters for the sequences
  Returns:
    the score
  Throws:
    `Exception` - if something went wrong
  See Also:
    `doFirstIteration(Sample, double[], MultivariateRandomGenerator, MRGParams[])`, `continueIterations(double[], double[][])`, `continueIterations(double[], double[][], int, int)`

### iterate

    protected double iterate(int start,
                             double[] dataWeights,
                             MultivariateRandomGenerator m,
                             MRGParams[] params)
                      throws Exception

  This method runs the train algorithm for the current model and the internal data set.

  Parameters:
    `start` - the index of the training
    `dataWeights` - the weights for each sequence or `null`
    `m` - the random generator for initiating the algorithm
    `params` - the parameters for the sequences
  Returns:
    the score
  Throws:
    `Exception` - if something went wrong
  See Also:
    `doFirstIteration(Sample, double[], MultivariateRandomGenerator, MRGParams[])`, `continueIterations(double[], double[][])`, `continueIterations(double[], double[][], int, int)`

### doFirstIteration

    protected double[][] doFirstIteration(Sample data,
                                          double[] dataWeights)
                                   throws Exception

  This method will do the first step in the train algorithm for the current model. The initialization will be done by randomly setting the component membership. This is useful when nothing is known about the problem.

  Parameters:
    `data` - the sample of sequences
    `dataWeights` - `null` or the weights of each element of the sample
  Returns:
    the weighting array used to initialize, this array can be reused in the following iterations
  Throws:
    `Exception` - if something went wrong

### doFirstIteration

    protected double[][] doFirstIteration(Sample data,
                                          double[] dataWeights,
                                          MultivariateRandomGenerator m,
                                          MRGParams[] params)
                                   throws Exception

  This method will do the first step in the train algorithm for the current model. The initialization will be done by randomly setting the component membership. This is useful when nothing is known about the problem.

  Parameters:
    `data` - the sample of sequences
    `dataWeights` - `null` or the weights of each element of the sample
    `m` - the multivariate random generator
    `params` - the parameters for the multivariate random generator
  Returns:
    the weighting array used to initialize, this array can be reused in the following iterations
  Throws:
    `Exception` - if something went wrong

### doFirstIteration

    protected abstract double[][] doFirstIteration(double[] dataWeights,
                                                   MultivariateRandomGenerator m,
                                                   MRGParams[] params)
                                            throws Exception

  This method will do the first step in the train algorithm for the current model on the internal sample. The initialization will be done by randomly setting the component membership. This is useful when nothing is known about the problem.

  Parameters:
    `dataWeights` - `null` or the weights of each element of the sample
    `m` - the multivariate random generator
    `params` - the parameters for the multivariate random generator
  Returns:
    the weighting array used to initialize, this array can be reused in the following iterations
  Throws:
    `Exception` - if something went wrong

### getTime

    protected Time getTime()

  This method returns an instance of `Time` that is used for the `TerminationCondition` in the EM.

  Returns:
    an instance of `Time` that is used during the EM

### continueIterations

    protected double continueIterations(double[] dataWeights,
                                        double[][] seqweights)
                                 throws Exception

  This method will run the train algorithm for the current model on the internal sample. The initialization will be done by using the models of the `AbstractMixtureModel`. So in this case the models have to be trained already. This method is useful for restarting the train algorithm at a certain point. The algorithm will stop if the difference between the optimized functions for two iterations is smaller than the specified threshold.
  If the difference becomes significant negative an exception is thrown.

  Parameters:
    `dataWeights` - `null` or the weights of each element of the internal sample (last sample the `AbstractMixtureModel` was trained on)
    `seqweights` - `null` or an array for weighting the sequences, see `createSeqWeightsArray()`
  Returns:
    a score for the model
  Throws:
    `Exception` - if something went wrong

### continueIterations

    protected double continueIterations(double[] dataWeights,
                                        double[][] seqweights,
                                        int iterations,
                                        int start)
                                 throws Exception

  This method will run the train algorithm for the current model on the internal sample. The initialization will be done by using the models of the `AbstractMixtureModel`. So in this case the models have to be trained already. This method is useful for restarting the algorithm at a certain point. The algorithm will stop after the number of iterations.

  Parameters:
    `dataWeights` - `null` or the weights of each element of the internal sample (last sample the `AbstractMixtureModel` was trained on)
    `seqweights` - `null` or an array for weighting the sequences, see `createSeqWeightsArray()`
    `iterations` - the number of iterations that should be done
    `start` - the index of the run in a `Model.train(Sample)`-call
  Returns:
    the current score (likelihood or posterior)
  Throws:
    `Exception` - if something went wrong

### getNewParameters

    protected void getNewParameters(int iteration,
                                    double[][] seqWeights,
                                    double[] w)
                             throws Exception

  This method trains the internal models on the internal sample and the given weights.

  Parameters:
    `iteration` - the number of times this method has been invoked
    `seqWeights` - the weights for each model and sequence
    `w` - the weights for the components
  Throws:
    `Exception` - if the training of the internal models went wrong

### getNewParametersForModel

    protected void getNewParametersForModel(int modelIndex,
                                            int iteration,
                                            int sampleIndex,
                                            double[] seqWeights)
                                     throws Exception

  This method trains the internal model with index `modelIndex` on the internal sample and the given weights.

  Parameters:
    `modelIndex` - the index of the model
    `iteration` - the number of times this method has been invoked for this model
    `sampleIndex` - the index of the internal sample that should be used
    `seqWeights` - the weights for each sequence
  Throws:
    `Exception` - if the training of the internal model went wrong

### getNewWeights

    protected abstract double getNewWeights(double[] dataWeights,
                                            double[] w,
                                            double[][] seqweights)
                                     throws Exception

  Computes sequence weights and returns the score.

  Parameters:
    `dataWeights` - the weights for the internal sample (should not be changed)
    `w` - the array for the statistic of the component parameters (shall be filled)
    `seqweights` - an array containing for each component the weights for each sequence (shall be filled)
  Returns:
    the score
  Throws:
    `Exception` - if something went wrong

### modifyWeights

    protected double modifyWeights(double[] w)

  This method modifies the computed weights for one sequence and returns the score.

  Parameters:
    `w` - the weights
  Returns:
    the score

### initWithPrior

    protected void initWithPrior(double[] w)

  This method sets the initial weights before counting the usage of each component. For ML the weights are set to 0 and for MAP they are set to the component hyperparameters.

  Parameters:
    `w` - the array of weights

### getLogProbFor

    public double getLogProbFor(int component,
                                Sequence s)
                         throws Exception

  Returns the logarithmic probability for the sequence and the given component.

  Parameters:
    `component` - the index of the component
    `s` - the sequence
  Returns:
    `log P(s,component) = log P(s|component) + log P(component)`
  Throws:
    `Exception` - if the model was not trained yet or something else went wrong
  See Also:
    `getNumberOfComponents()`

### getLogProbUsingCurrentParameterSetFor

    protected abstract double getLogProbUsingCurrentParameterSetFor(int component,
                                                                    Sequence s,
                                                                    int start,
                                                                    int end)
                                                             throws Exception

  Returns the logarithmic probability for the sequence and the given component using the current parameter set.

  Parameters:
    `component` - the index of the component
    `s` - the sequence
    `start` - the start position in the sequence
    `end` - the end position in the sequence
  Returns:
    `log P(s,component) = log P(s|component) + log P(component)`
  Throws:
    `Exception` - if not trained yet or something else went wrong
  See Also:
    `getNumberOfComponents()`

### getProbFor

    public double getProbFor(Sequence sequence,
                             int startpos,
                             int endpos)
                      throws Exception

  Description copied from interface: `Model`
  Returns the probability of (a part of) the given sequence given the model. If at least one random variable is continuous the value of density function is returned.
  It extends the possibility given by the method `Model.getProbFor(Sequence, int)` by the fact, that the model could be e.g. homogeneous and therefore the length of the sequences, whose probability should be returned, is not fixed. Additionally the end position of the part of the given sequence is given and the probability of the part from position `startpos` to `endpos` (inclusive) should be returned.
  The `length` and the `alphabets` define the type of data that can be modeled and therefore both has to be checked.

  Parameters:
    `sequence` - the given sequence
    `startpos` - the start position within the given sequence
    `endpos` - the last position to be taken into account
  Returns:
    the probability or the value of the density function of (the part of) the given sequence given the model
  Throws:
    `Exception` - if the sequence could not be handled (e.g. `startpos > endpos`, `endpos > sequence.length`, ...) by the model
    `NotTrainedException` - if the model is not trained yet

### getLogProbFor

    public final double getLogProbFor(Sequence sequence,
                                      int startpos,
                                      int endpos)
                               throws Exception

  Description copied from interface: `Model`
  Returns the logarithm of the probability of (a part of) the given sequence given the model. If at least one random variable is continuous the value of density function is returned.
  For more details see `Model.getProbFor(Sequence, int, int)`

  Specified by:
    `getLogProbFor` in interface `Model`
  Overrides:
    `getLogProbFor` in class `AbstractModel`
  Parameters:
    `sequence` - the given sequence
    `startpos` - the start position within the given sequence
    `endpos` - the last position to be taken into account
  Returns:
    the logarithm of the probability or the value of the density function of (the part of) the given sequence given the model
  Throws:
    `Exception` - if the sequence could not be handled (e.g. `startpos >` , `endpos > sequence.length`, ...) by the model
    `NotTrainedException` - if the model is not trained yet
  See Also:
    `Model.getProbFor(Sequence, int, int)`

### getLogProbFor

    public final double[] getLogProbFor(Sample data)
                                 throws Exception

  Description copied from interface: `Model`
  This method computes the logarithm of the probabilities of all sequences in the given sample. The values are stored in an array according to the index of the respective sequence in the sample.
  The probability for any sequence shall be computed independent of all other sequences in the sample. So the result should be exactly the same as for the method `Model.getLogProbFor(Sequence)`.

  Specified by:
    `getLogProbFor` in interface `Model`
  Overrides:
    `getLogProbFor` in class `AbstractModel`
  Parameters:
    `data` - the sample of sequences
  Returns:
    an array containing the logarithm of the probabilities of all sequences of the sample
  Throws:
    `Exception` - if something went wrong
  See Also:
    `Model.getLogProbFor(Sequence)`

### getLogPriorTerm

    public double getLogPriorTerm()
                           throws Exception

  Description copied from interface: `Model`
  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
  Throws:
    `Exception` - if something went wrong
  See Also:
    `Model.getPriorTerm()`

### getLogPriorTermForComponentProbs

    protected final double getLogPriorTermForComponentProbs()

  This method computes the part of the prior that comes from the component probabilities.

  Returns:
    the part of the prior that comes from the component probabilities

### getScoreForBestRun

    public final double getScoreForBestRun()
                                    throws NotTrainedException,
                                           OperationNotSupportedException

  Returns the value of the optimized function from the best run of the last training.

  Returns:
    the value of the optimized function from the best run of the last training
  Throws:
    `NotTrainedException` - if the training algorithm has not been run
    `OperationNotSupportedException` - if this method is used for an instance that does not use the EM
  See Also:
    `train(Sample, double[])`, `algorithmHasBeenRun()`

### getInstanceName

    public String getInstanceName()

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

  Returns:
    a short instance name

### getIndexOfMaximalComponentFor

    public int getIndexOfMaximalComponentFor(Sequence s)
                                      throws Exception

  Returns the index `i` of the component with `P(i|s)`maximal. Therefore it computes
  This method can be helpful for clustering.

  ``
  Parameters:
    `s` - the sequence
  Returns:
    the index of the component
  Throws:
    `Exception` - if the model was not trained yet or something else went wrong
  See Also:
    `getLogProbFor(int, Sequence)`

### getModels

    public final Model[] getModels()
                            throws CloneNotSupportedException

  Returns a deep copy of the models.

  Returns:
    an array of `AbstractModel`s
  Throws:
    `CloneNotSupportedException` - if at least one model can not be cloned
  See Also:
    `getModel(int)`

### getModel

    public final Model getModel(int i)
                         throws CloneNotSupportedException

  Returns a deep copy of the `i`-th model.

  Parameters:
    `i` - the index
  Returns:
    a deep copy of the `i`-th model
  Throws:
    `CloneNotSupportedException` - if at least one model can not be cloned
  See Also:
    `getModels()`

### getNameOfAlgorithm

    public String getNameOfAlgorithm()

  Returns the name of the used algorithm.

  Returns:
    the name of the used algorithm

### getNumberOfComponents

    public final int getNumberOfComponents()

  Returns the number of components the are modeled by this `AbstractMixtureModel`.

  Returns:
    the number of components

### getCharacteristics

    public ResultSet getCharacteristics()
                                 throws Exception

  Description copied from interface: `Model`
  Returns some information characterizing or describing the current instance of the model. This could be e.g. the number of edges for a Bayesian network or an image showing some representation of the model. The set of characteristics should always include the XML-representation of the model. The corresponding result type is `StorableResult`.

  Specified by:
    `getCharacteristics` in interface `Model`
  Overrides:
    `getCharacteristics` in class `AbstractModel`
  Returns:
    the characteristics of the current instance of the model
  Throws:
    `Exception` - if some of the characteristics could not be defined
  See Also:
    `StorableResult`

### getNumericalCharacteristics

    public NumericalResultSet getNumericalCharacteristics()
                                                   throws Exception

  Description copied from interface: `Model`
  Returns the subset of numerical values that are also returned by `Model.getCharacteristics()`.

  Returns:
    the numerical characteristics of the current instance of the model
  Throws:
    `Exception` - if some of the characteristics could not be defined

### getWeights

    public final double[] getWeights()

  This method returns a deep copy of the weights for each component.

  Returns:
    the weight for each component

### algorithmHasBeenRun

    public boolean algorithmHasBeenRun()

  This method indicates whether the parameters of the model has been determined by the internal algorithm.

  Returns:
    `true` if the internal algorithm has been used to determine the parameters of the model

### isTrained

    public boolean isTrained()

  Description copied from interface: `Model`
  Returns `true` if the model has been trained successfully, `false` otherwise.

  Returns:
    `true` if the model has been trained successfully, `false` otherwise

### setAlpha

    public final void setAlpha(double alpha)
                        throws IllegalArgumentException

  Sets the parameter of the Dirichlet distribution which is used when you invoke `train` to init the gammas. It is recommended to use `alpha = 1` (uniform distribution on a simplex).

  Parameters:
    `alpha` - the parameter of the Dirichlet distribution with `alpha > 0`
  Throws:
    `IllegalArgumentException` - if `alpha <= 0`

### setOutputStream

    public final void setOutputStream(OutputStream o)

  Sets the `OutputStream` that is used e.g. for writing information while training. It is possible to set `o=null`, than nothing will be written.

  Parameters:
    `o` - the `OutputStream`

### getNewComponentProbs

    protected void getNewComponentProbs(double[] weights)
                                 throws Exception

  Estimates the weights of each component.

  Parameters:
    `weights` - the array of weights, every element has to be non-negative and the dimension has to be `dimension`
  Throws:
    `Exception` - a weight is less than 0
  See Also:
    `getNumberOfComponents()`

### setWeights

    protected void setWeights(double... weights)
                       throws IllegalArgumentException

  Sets the weights of each component.

  Parameters:
    `weights` - every element has to be non-negative, the sum of all weights has to be 1 and the dimension of `weights` has to be `dimension`
  Throws:
    `IllegalArgumentException` - a weight is less than 0, the sum is not equal to 1 or the dimension is incorrect
  See Also:
    `getNumberOfComponents()`

### toXML

    public StringBuffer toXML()

  Description copied from interface: `Storable`
  This method returns an XML representation as `StringBuffer` of an instance of the implementing class.

  Returns:
    the XML representation

### getFurtherInformation

    protected StringBuffer getFurtherInformation()

  This method is used in the subclasses to append further information to the XML representation.

  Returns:
    a part of the XML representation
  See Also:
    `extractFurtherInformation(StringBuffer)`

### fromXML

    protected void fromXML(StringBuffer representation)
                    throws NonParsableException

  Description copied from class: `AbstractModel`
  This method should only be used by the constructor that works on a `StringBuffer`. It is the counter part of `Storable.toXML()`.

  Specified by:
    `fromXML` in class `AbstractModel`
  Parameters:
    `representation` - the XML representation of the model
  Throws:
    `NonParsableException` - if the `StringBuffer` is not parsable or the representation is conflicting
  See Also:
    `AbstractModel.AbstractModel(StringBuffer)`

### extractFurtherInformation

    protected void extractFurtherInformation(StringBuffer xml)
                                      throws NonParsableException

  This method is used in the subclasses to extract further information from the XML representation and to set these as values of the instance.

  Parameters:
    `xml` - the XML representation
  Throws:
    `NonParsableException` - if the XML representation is not parsable
  See Also:
    `getFurtherInformation()`

### set

    protected void set(AlphabetContainer abc)

  Description copied from class: `AbstractModel`
  This method should only be invoked by the method `AbstractModel.setNewAlphabetContainerInstance(AlphabetContainer)` and not be made public.
  It enables you to do more with the method `AbstractModel.setNewAlphabetContainerInstance(AlphabetContainer)`, e.g. setting a new `AlphabetContainer` instance for subcomponents.

  Overrides:
    `set` in class `AbstractModel`
  Parameters:
    `abc` - the new instance

### checkModelsForGibbsSampling

    protected void checkModelsForGibbsSampling()

  This method can be used to check whether the necessary models have implemented the `GibbsSamplingComponent`.

### checkLength

    protected void checkLength(int index,
                               int l)

  This method checks if the length `l` of the model with index `index` is capable for the current instance. Otherwise an `IllegalArgumentException` is thrown.

  Parameters:
    `index` - the index of the model
    `l` - the length of the model
  Throws:
    `IllegalArgumentException` - if the model instance can not be used

### emitSample

    public Sample emitSample(int n,
                             int... lengths)
                      throws Exception

  Description copied from interface: `Model`
  This method returns a `Sample` object containing artificial sequence(s).
  There are two different possibilities to create a sample for a model with length 0 (homogeneous models).
  1. `emitSample( int n, int l )` should return a sample with `n` sequences of length `l`.
  2. `emitSample( int n, int[] l )` should return a sample with `n` sequences which have a sequence length corresponding to the entry in the given array `l`.
  There are two different possibilities to create a sample for a model with length greater than 0 (inhomogeneous models).
  `emitSample( int n )` and `emitSample( int n, null )` should return a sample with `n` sequences of length of the model ( `Model.getLength()`).
  The standard implementation throws an `Exception`.

  Specified by:
    `emitSample` in interface `Model`
  Overrides:
    `emitSample` in class `AbstractModel`
  Parameters:
    `n` - the number of sequences that should be contained in the returned sample
    `lengths` - the length of the sequences for a homogeneous model; for an inhomogeneous model this parameter should be `null` or an array of size 0.
  Returns:
    a `Sample` containing the artificial sequence(s)
  Throws:
    `Exception` - if the emission did not succeed
    `NotTrainedException` - if the model is not trained yet
  See Also:
    `Sample`

### emitSampleUsingCurrentParameterSet

    protected abstract Sequence[] emitSampleUsingCurrentParameterSet(int n,
                                                                     int... lengths)
                                                              throws Exception

  The method returns an array of sequences using the current parameter set.

  Parameters:
    `n` - the number of sequences to be sampled
    `lengths` - the corresponding lengths
  Returns:
    an array of sequences
  Throws:
    `Exception` - if it was impossible to sample the sequences
  See Also:
    `AbstractModel.emitSample(int, int...)`

### parseParameterSet

    protected boolean parseParameterSet(int sampling,
                                        int burnInIteration)
                                 throws Exception

  This method allows the user to parse the set of parameters with index `burnInIteration` of a specific `sampling` (from a file).

  Parameters:
    `sampling` - the index of the sampling
    `burnInIteration` - the number of iterations that should be skipped
  Returns:
    `true` if the parameter set could be parsed
  Throws:
    `Exception` - if something went wrong while reading or parsing the parameter set

### parseNextParameterSet

    protected boolean parseNextParameterSet()
                                     throws Exception

  This method allows the user to parse the next set of parameters (from a file).

  Returns:
    `true` if the parameter set could be parsed
  Throws:
    `Exception` - if something went wrong while reading or parsing the parameter set

### initModelForSampling

    protected void initModelForSampling(int starts)
                                 throws IOException

  This method initializes the model for the sampling. For instance this method can be used to create new files where all parameter sets will be stored.

  Parameters:
    `starts` - the number of sampling starts
  Throws:
    `IOException` - if the files could not be handled properly

### extendSampling

    protected void extendSampling(int sampling)
                           throws Exception

  This method prepares the model to extend an existing sampling.

  Parameters:
    `sampling` - the index of the sampling
  Throws:
    `Exception` - if the internal files could not be handled properly

### samplingStopped

    protected void samplingStopped()
                            throws IOException

  This method is the opposite of the method `initModelForSampling(int)`. It can be used for closing any streams of writer, ...

  Throws:
    `IOException` - if the `FileWriter` could not be closed properly

### isInSamplingMode

    protected boolean isInSamplingMode()

  This method returns `true` if the object is currently used in a sampling, otherwise `false`.

  Returns:
    `true` if the object is currently used in a sampling

### finalize

    protected void finalize()
                     throws Throwable

  Overrides:
    `finalize` in class `Object`
  Throws:
    `Throwable`

### draw

    public static final int draw(double[] w,
                                 int start)

  This method draws an index of an array corresponding to the probabilities encoded in the entries of the array.

  Parameters:
    `w` - an array containing probabilities starting at position `start`
    `start` - the start index
  Returns:
    the drawn index

### max

    public static final int max(double[] w,
                                int start,
                                int end)

  This method returns the index of a maximal entry in the array `w` between index `start` and `end`.

  Parameters:
    `w` - an array
    `start` - the start index (inclusive)
    `end` - the end index (exclusive)
  Returns:
    the index of the maximal entry

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