de.jstacs.models.mixture.motif
Class SingleHiddenMotifMixture

java.lang.Object
  de.jstacs.models.AbstractModel
      de.jstacs.models.mixture.AbstractMixtureModel
          de.jstacs.models.mixture.motif.HiddenMotifMixture
              de.jstacs.models.mixture.motif.SingleHiddenMotifMixture

All Implemented Interfaces:

Model, MotifDiscoverer, Storable, Cloneable

public class SingleHiddenMotifMixture
extends HiddenMotifMixture

This class enables the user to search for a single motif in a sequence. The user is enabled to train the model either "one occurrence per sequence" (=OOPS) or "zero or one occurrence per sequence" (=ZOOPS).

If EM is used for training the parameters are trained in a MEME-like manner.

Currently only EM is implemented.

Author:

Jens Keilwagen

Nested Class Summary

Nested classes/interfaces inherited from class de.jstacs.models.mixture.AbstractMixtureModel

AbstractMixtureModel.Algorithm, AbstractMixtureModel.Parameterization

Nested classes/interfaces inherited from interface de.jstacs.motifDiscovery.MotifDiscoverer

MotifDiscoverer.KindOfProfile

Field Summary

Fields inherited from class de.jstacs.models.mixture.motif.HiddenMotifMixture

bgMaxMarkovOrder, posPrior, trainOnlyMotifModel

Fields inherited from class de.jstacs.models.mixture.AbstractMixtureModel

algorithm, algorithmHasBeenRun, alternativeModel, burnInTest, componentHyperParams, compProb, counter, dimension, estimateComponentProbs, file, filereader, filewriter, initialIteration, logWeights, model, optimizeModel, sample, samplingIndex, sostream, starts, stationaryIteration, weights

Fields inherited from class de.jstacs.models.AbstractModel

alphabets, length

Constructor Summary

protected	SingleHiddenMotifMixture(Model motif, Model bg, boolean trainOnlyMotifModel, int starts, double[] componentHyperParams, double[] weights, PositionPrior posPrior, AbstractMixtureModel.Algorithm algorithm, double alpha, double eps, AbstractMixtureModel.Parameterization parametrization, int initialIteration, int stationaryIteration, BurnInTest burnInTest) Creates a new SingleHiddenMotifMixture.
	SingleHiddenMotifMixture(Model motif, Model bg, boolean trainOnlyMotifModel, int starts, double[] componentHyperParams, PositionPrior posPrior, double alpha, double eps, AbstractMixtureModel.Parameterization parametrization) Creates a single hidden motif mixture using EM and estimating the probability for finding a motif.
	SingleHiddenMotifMixture(Model motif, Model bg, boolean trainOnlyMotifModel, int starts, double motifProb, PositionPrior posPrior, double alpha, double eps, AbstractMixtureModel.Parameterization parametrization) Creates a single hidden motif mixture using EM and fixed probability for finding a motif.
	SingleHiddenMotifMixture(StringBuffer xml) The standard constructor for the interface Storable.

Method Summary

protected double[][]	createSeqWeightsArray() Creates an array that can be used for weighting sequences in the algorithm.
protected 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.
int	getGlobalIndexOfMotifInComponent(int component, int motif) Returns the global index of the motif used in component.
protected double	getLogProbUsingCurrentParameterSetFor(int component, Sequence seq, int start, int end) Returns the log probability for the sequence and the given component using the current parameter set.
int	getMinimalSequenceLength() Returns the minimal length a sequence respectively a sample has to have.
int	getMotifLength(int motif) This method returns the length of the motif with index motif.
protected double	getNewWeights(double[] dataWeights, double[] w, double[][] seqweights) Computes sequence weights and returns the score.
int	getNumberOfMotifs() Returns the number of motifs for this MotifDiscoverer
int	getNumberOfMotifsInComponent(int component) Returns the number of motifs that are used in the component component of this motif discoverer.
double[]	getProfileOfScoresFor(int component, int motif, Sequence sequence, int startpos, MotifDiscoverer.KindOfProfile kind) Returns the profile of the scores for component component and motif motif at all possible start-positions of the motif in the sequence sequence.
StrandedLocatedSequenceAnnotationWithLength.Strand	getStrandFor(int component, int motif, Sequence sequence, int startpos) This method returns the strand for a given subsequence if it is consider as site of the motif model in a specific component.
protected double	modify(double[] containsMotif, double[] startpos, int start, int end) This method modifies the computed weights for one sequence and returns the score.
protected void	setTrainData(Sample data) This method is invoked by the train method and set for a given sample the sample that should be used for train.

Methods inherited from class de.jstacs.models.mixture.motif.HiddenMotifMixture

checkLength, clone, emitSampleUsingCurrentParameterSet, extractFurtherInformation, getFurtherInformation, getInstanceName, getLogPriorTerm, getNewParameters, toString, train, trainBgModel

Methods inherited from class de.jstacs.models.mixture.AbstractMixtureModel

algorithmHasBeenRun, checkModelsForGibbsSampling, continueIterations, continueIterations, doFirstIteration, doFirstIteration, draw, emitSample, extendSampling, finalize, fromXML, getCharacteristics, getIndexOfMaximalComponentFor, getLogPriorTermForComponentProbs, getLogProbFor, getLogProbFor, getLogProbFor, getModel, getModels, getMRG, getMRGParams, getNameOfAlgorithm, getNewComponentProbs, getNewParametersForModel, getNumberOfComponents, getNumericalCharacteristics, getProbFor, getScoreForBestRun, getWeights, initModelForSampling, initWithPrior, isInSamplingMode, isTrained, iterate, iterate, max, modifyWeights, parseNextParameterSet, parseParameterSet, samplingStopped, set, setAlpha, setOutputStream, setThreshold, setWeights, swap, toXML

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, wait, wait, wait

Methods inherited from interface de.jstacs.motifDiscovery.MotifDiscoverer

getIndexOfMaximalComponentFor, getNumberOfComponents

Methods inherited from interface de.jstacs.Storable

toXML

Constructor Detail

SingleHiddenMotifMixture

protected SingleHiddenMotifMixture(Model motif,
                                   Model bg,
                                   boolean trainOnlyMotifModel,
                                   int starts,
                                   double[] componentHyperParams,
                                   double[] weights,
                                   PositionPrior posPrior,
                                   AbstractMixtureModel.Algorithm algorithm,
                                   double alpha,
                                   double eps,
                                   AbstractMixtureModel.Parameterization parametrization,
                                   int initialIteration,
                                   int stationaryIteration,
                                   BurnInTest burnInTest)
                            throws CloneNotSupportedException,
                                   IllegalArgumentException,
                                   WrongAlphabetException

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

Parameters:

motif - the motif model, if the model is trained using AbstractMixtureModel.Algorithm.GIBBS_SAMPLING the model has to implement GibbsSamplingComponent.

bg - the background model for the flanking sequences and for those sequences that do not contain a binding site, if trainOnlyMotifModel=false and algorithm=AbstractMixtureModel.Algorithm.GIBBS_SAMPLING the model has to implement GibbsSamplingComponent The model has to be able to score sequences of arbitrary length.

starts - the number of times the algorithm will be started in the train method, at least 1

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) than ML
• otherwise (all values positive) a prior is used (MAP, MP, ...)
• depends on the parameterization

weights - null or the weights for the components (than weights.length == dimension)

posPrior - this object determine the positional distribution that shall be used

trainOnlyMotifModel - a switch whether to train only the motif model

algorithm - either AbstractMixtureModel.Algorithm.EM or AbstractMixtureModel.Algorithm.GIBBS_SAMPLING

alpha - only for AbstractMixtureModel.Algorithm.EM
the positive parameter for the Dirichlet which is used when you invoke train to initialize the gammas. It is recommended to use alpha = 1 (uniform distribution on a simplex).

eps - only for AbstractMixtureModel.Algorithm.EM
the non-negative threshold for stopping the EM-algorithm

parametrization - only for AbstractMixtureModel.Algorithm.EM
the type of the component probability parameterization;

• AbstractMixtureModel.Parameterization.THETA or AbstractMixtureModel.Parameterization.LAMBDA
• the parameterization of in 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 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 in 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 the corresponding length
  • weights != null && weights.length != 2
  • 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 simple alphabet
  CloneNotSupportedException - if the models can not be cloned

SingleHiddenMotifMixture

public SingleHiddenMotifMixture(Model motif,
                                Model bg,
                                boolean trainOnlyMotifModel,
                                int starts,
                                double[] componentHyperParams,
                                PositionPrior posPrior,
                                double alpha,
                                double eps,
                                AbstractMixtureModel.Parameterization parametrization)
                         throws CloneNotSupportedException,
                                IllegalArgumentException,
                                WrongAlphabetException

Creates a single hidden motif mixture using EM and estimating the probability for finding a motif.

Parameters:

motif - the motif model

bg - the background model for the flanking sequences and for those sequences that do not contain a binding site. The model has to be able to score sequences of arbitrary length.

starts - the number of times the algorithm will be started in the train method, at least 1

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) than ML
• otherwise (all values positive) a prior is used (MAP, MP, ...)
• depends on the parameterization

posPrior - this object determine the positional distribution that shall be used

trainOnlyMotifModel - a switch whether to train only the motif model

alpha - the positive parameter for the Dirichlet which is used when you invoke train to initialize the gammas. It is recommended to use alpha = 1 (uniform distribution on a simplex).

eps - the non-negative threshold for stopping the EM-algorithm

parametrization - the type of the component probability parameterization;

• AbstractMixtureModel.Parameterization.THETA or AbstractMixtureModel.Parameterization.LAMBDA
• the parameterization of in 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 LAMBDA
  Throws:
  IllegalArgumentException - if
  • the models are not able to score the sequence of the corresponding length
  • starts < 1
  • componentHyperParams are not correct
  WrongAlphabetException - if not all models work on the same simple alphabet
  CloneNotSupportedException - if the models can not be cloned
  WrongAlphabetException - if not all models work on the same alphabet
  CloneNotSupportedException - if the models can not be cloned
  See Also:
  SingleHiddenMotifMixture(de.jstacs.models.Model, de.jstacs.models.Model, boolean, int, double[], double[], de.jstacs.models.mixture.motif.positionprior.PositionPrior, de.jstacs.models.mixture.AbstractMixtureModel.Algorithm, double, double, de.jstacs.models.mixture.AbstractMixtureModel.Parameterization, int, int, de.jstacs.models.mixture.gibbssampling.BurnInTest), AbstractMixtureModel.Algorithm.EM

SingleHiddenMotifMixture

public SingleHiddenMotifMixture(Model motif,
                                Model bg,
                                boolean trainOnlyMotifModel,
                                int starts,
                                double motifProb,
                                PositionPrior posPrior,
                                double alpha,
                                double eps,
                                AbstractMixtureModel.Parameterization parametrization)
                         throws CloneNotSupportedException,
                                IllegalArgumentException,
                                WrongAlphabetException

Creates a single hidden motif mixture using EM and fixed probability for finding a motif.

Parameters:

motif - the motif model

bg - the background model for the flanking sequences and for those sequences that do not contain a binding site. The model has to be able to score sequences of arbitrary length.

starts - the number of times the algorithm will be started in the train method, at least 1

motifProb - the probability of finding a motif in a sequence (in [0,1])

posPrior - this object determine the positional distribution that shall be used

trainOnlyMotifModel - a switch whether to train only the motif model

alpha - the positive parameter for the Dirichlet which is used when you invoke train to initialize the gammas. It is recommended to use alpha = 1 (uniform distribution on a simplex).

eps - the non-negative threshold for stopping the EM-algorithm

parametrization - the type of the component probability parameterization;

• AbstractMixtureModel.Parameterization.THETA or AbstractMixtureModel.Parameterization.LAMBDA
• the parameterization of in 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 LAMBDA
  Throws:
  IllegalArgumentException - if
  • the models are not able to score the sequence of the corresponding length
  • motifProb < 0 or motifProb > 1
  • starts < 1
  WrongAlphabetException - if not all models work on the same simple alphabet
  CloneNotSupportedException - if the models can not be cloned
  See Also:
  SingleHiddenMotifMixture(de.jstacs.models.Model, de.jstacs.models.Model, boolean, int, double[], double[], de.jstacs.models.mixture.motif.positionprior.PositionPrior, de.jstacs.models.mixture.AbstractMixtureModel.Algorithm, double, double, de.jstacs.models.mixture.AbstractMixtureModel.Parameterization, int, int, de.jstacs.models.mixture.gibbssampling.BurnInTest), AbstractMixtureModel.Algorithm.EM

SingleHiddenMotifMixture

public SingleHiddenMotifMixture(StringBuffer xml)
                         throws NonParsableException

The standard constructor for the interface Storable.

Parameters:

xml - the StringBuffer containing the model

Throws:

NonParsableException - if the StringBuffer can not be parsed

Method Detail

setTrainData

protected void setTrainData(Sample data)
                     throws Exception

Description copied from class: AbstractMixtureModel

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

Specified by:

setTrainData in class AbstractMixtureModel

Parameters:

data - the given sample

Throws:

Exception

createSeqWeightsArray

protected double[][] createSeqWeightsArray()

Description copied from class: AbstractMixtureModel

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

Overrides:

createSeqWeightsArray in class AbstractMixtureModel

Returns:

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

doFirstIteration

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

Description copied from class: AbstractMixtureModel

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 usefull when nothing is known about the problem.

Specified by:

doFirstIteration in class AbstractMixtureModel

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

getNewWeights

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

Description copied from class: AbstractMixtureModel

Computes sequence weights and returns the score.

Specified by:

getNewWeights in class AbstractMixtureModel

Parameters:

dataWeights - the weights for 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

modify

protected double modify(double[] containsMotif,
                        double[] startpos,
                        int start,
                        int end)

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

Parameters:

containsMotif - an array to return the weights for containing a motif (index 0) or containing no motif (index 1)

startpos - the array containing the scores for each start position (including no motif in the sequence)

start - the start index

end - the end index

Returns:

the score

getLogProbUsingCurrentParameterSetFor

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

Description copied from class: AbstractMixtureModel

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

Specified by:

getLogProbUsingCurrentParameterSetFor in class AbstractMixtureModel

Parameters:

component - the index of the component

seq - 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:

AbstractMixtureModel.getNumberOfComponents()

getProfileOfScoresFor

public double[] getProfileOfScoresFor(int component,
                                      int motif,
                                      Sequence sequence,
                                      int startpos,
                                      MotifDiscoverer.KindOfProfile kind)
                               throws Exception

Description copied from interface: MotifDiscoverer

Returns the profile of the scores for component component and motif motif at all possible start-positions of the motif in the sequence sequence. This array should be of length sequence.length() - startpos - motifs[motif].length() + 1.
A high score should encode for a probable start position.

Parameters:

component - the component

motif - the index of the motif in the component

sequence - the sequence

startpos - the start position

kind - indicates the kind of profile

Returns:

the profile of scores

Throws:

Exception - if the score could not be computed for any reasons

getMinimalSequenceLength

public int getMinimalSequenceLength()

Description copied from class: HiddenMotifMixture

Returns the minimal length a sequence respectively a sample has to have.

Specified by:

getMinimalSequenceLength in class HiddenMotifMixture

Returns:

the minimal length a sequence respectively a sample has to have

getMotifLength

public int getMotifLength(int motif)

Description copied from interface: MotifDiscoverer

This method returns the length of the motif with index motif.

Parameters:

motif - the index of the motif

Returns:

the length of the motif with index motif

getNumberOfMotifs

public int getNumberOfMotifs()

Description copied from interface: MotifDiscoverer

Returns the number of motifs for this MotifDiscoverer

Returns:

the number of motifs

getNumberOfMotifsInComponent

public int getNumberOfMotifsInComponent(int component)

Description copied from interface: MotifDiscoverer

Returns the number of motifs that are used in the component component of this motif discoverer.

Parameters:

component - the component

Returns:

the number of motifs

getStrandFor

public StrandedLocatedSequenceAnnotationWithLength.Strand getStrandFor(int component,
                                                                       int motif,
                                                                       Sequence sequence,
                                                                       int startpos)
                                                                throws Exception

Description copied from interface: MotifDiscoverer

This method returns the strand for a given subsequence if it is consider as site of the motif model in a specific component.

Parameters:

component - the component

motif - the index of the motif in the component

sequence - the sequence

startpos - the start position in the sequence

Returns:

the predicted strand annotation

Throws:

Exception - if the strand could not be computed for any reasons

getGlobalIndexOfMotifInComponent

public int getGlobalIndexOfMotifInComponent(int component,
                                            int motif)

Description copied from interface: MotifDiscoverer

Returns the global index of the motif used in component. The index returned must be at least 0 and less than getNumberOfMotifs().

Parameters:

component - the component index

motif - the motif index in the component

Returns:

the global index of the motif in component