de.jstacs.sequenceScores.statisticalModels.trainable

Class PFMWrapperTrainSM

java.lang.Object

de.jstacs.sequenceScores.statisticalModels.trainable.AbstractTrainableStatisticalModel

de.jstacs.sequenceScores.statisticalModels.trainable.PFMWrapperTrainSM

All Implemented Interfaces:

PWMSupplier, SequenceScore, StatisticalModel, TrainableStatisticalModel, Storable, Cloneable

public class PFMWrapperTrainSM
extends AbstractTrainableStatisticalModel
implements PWMSupplier

A wrapper class for representing position weight matrices or position frequency matrices from databases as TrainableStatisticalModels.

Author:

Jan Grau

Field Summary

Fields inherited from class de.jstacs.sequenceScores.statisticalModels.trainable.AbstractTrainableStatisticalModel

alphabets, length

Constructor Summary

Constructors

Constructor and Description
PFMWrapperTrainSM(AlphabetContainer alphabets, String name, double[][] pssm) Creates a new wrapper for a given position frequency matrix.
PFMWrapperTrainSM(AlphabetContainer alphabets, String name, double[][] pfm, double ess) Creates a new wrapper for a given position frequency matrix.
PFMWrapperTrainSM(StringBuffer stringBuff) Creates a wrapper from its XML representation

Method Summary

Modifier and Type	Method and Description
protected void	fromXML(StringBuffer xml) This method should only be used by the constructor that works on a StringBuffer.
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.
double	getLogProbFor(Sequence sequence, int startpos, int endpos) Returns the logarithm of the probability of (a part of) the given sequence given the model.
String	getName() Returns a name (e.g., an identifier from a database) for the PWM.
NumericalResultSet	getNumericalCharacteristics() Returns the subset of numerical values that are also returned by SequenceScore.getCharacteristics().
double[][]	getPFM() Returns a deep copy of the internal PFM.
double[][]	getPWM() Returns the position weight matrix.
boolean	isInitialized() This method can be used to determine whether the instance is initialized.
String	toString(NumberFormat nf) This method returns a String representation of the instance.
StringBuffer	toXML() This method returns an XML representation as StringBuffer of an instance of the implementing class.
void	train(DataSet data, double[] weights) Trains the TrainableStatisticalModel object given the data as DataSet using the specified weights.

Methods inherited from class de.jstacs.sequenceScores.statisticalModels.trainable.AbstractTrainableStatisticalModel

check, clone, emitDataSet, getAlphabetContainer, getCharacteristics, getLength, getLogProbFor, getLogProbFor, getLogScoreFor, getLogScoreFor, getLogScoreFor, getLogScoreFor, getLogScoreFor, getMaximalMarkovOrder, toString, train

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PFMWrapperTrainSM

public PFMWrapperTrainSM(AlphabetContainer alphabets,
                         String name,
                         double[][] pfm,
                         double ess)
                  throws CloneNotSupportedException

Creates a new wrapper for a given position frequency matrix.

Parameters:

alphabets - the alphabet

name - the name of the matrix

pfm - the position frequency matrix (may also be a position weight matrix, but ess should typically be zero in that case)

ess - the equivalent sample size (divided by the size of the alphabet to determine pseudo counts)

Throws:

CloneNotSupportedException - if the PFM could not be cloned

PFMWrapperTrainSM

public PFMWrapperTrainSM(AlphabetContainer alphabets,
                         String name,
                         double[][] pssm)
                  throws CloneNotSupportedException

Creates a new wrapper for a given position frequency matrix.

Parameters:

alphabets - the alphabet

name - the name of the matrix

pssm - the position specific scoring matrix

Throws:

CloneNotSupportedException - if the PSSM could not be cloned

PFMWrapperTrainSM

public PFMWrapperTrainSM(StringBuffer stringBuff)
                  throws NonParsableException

Creates a wrapper from its XML representation

Parameters:

stringBuff - the XML representation

Throws:

NonParsableException - if the XML could not be parsed

Method Detail

toXML

public StringBuffer toXML()

Description copied from interface: Storable

This method returns an XML representation as StringBuffer of an instance of the implementing class.

Specified by:

toXML in interface Storable

Returns:

the XML representation

train

public void train(DataSet data,
                  double[] weights)
           throws Exception

Description copied from interface: TrainableStatisticalModel

Trains the TrainableStatisticalModel object given the data as DataSet 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 data set 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 TrainableStatisticalModel

Parameters:

data - the given sequences as DataSet

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 data set do not match)

See Also:

DataSet.getElementAt(int), DataSet.ElementEnumerator

getLogProbFor

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

Description copied from interface: StatisticalModel

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.

It extends the possibility given by the method StatisticalModel.getLogProbFor(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.

Specified by:

getLogProbFor in interface StatisticalModel

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

getLogPriorTerm

public double getLogPriorTerm()
                       throws Exception

Description copied from interface: StatisticalModel

Returns a value that is proportional to the log of the prior. For maximum likelihood (ML) 0 should be returned.

Specified by:

getLogPriorTerm in interface StatisticalModel

Returns:

a value that is proportional to the log of the prior

Throws:

Exception - if something went wrong

getInstanceName

public String getInstanceName()

Description copied from interface: SequenceScore

Should return a short instance name such as iMM(0), BN(2), ...

Specified by:

getInstanceName in interface SequenceScore

Returns:

a short instance name

getName

public String getName()

Description copied from interface: PWMSupplier

Returns a name (e.g., an identifier from a database) for the PWM.

Specified by:

getName in interface PWMSupplier

Returns:

the name

getNumericalCharacteristics

public NumericalResultSet getNumericalCharacteristics()
                                               throws Exception

Description copied from interface: SequenceScore

Returns the subset of numerical values that are also returned by SequenceScore.getCharacteristics().

Specified by:

getNumericalCharacteristics in interface SequenceScore

Returns:

the numerical characteristics of the current instance

Throws:

Exception - if some of the characteristics could not be defined

isInitialized

public boolean isInitialized()

Description copied from interface: SequenceScore

This method can be used to determine whether the instance is initialized. If the instance is initialized you should be able to invoke SequenceScore.getLogScoreFor(Sequence).

Specified by:

isInitialized in interface SequenceScore

Returns:

true if the instance is initialized, false otherwise

toString

public String toString(NumberFormat nf)

Description copied from interface: SequenceScore

This method returns a String representation of the instance.

Specified by:

toString in interface SequenceScore

Parameters:

nf - the NumberFormat for the String representation of parameters or probabilities

Returns:

a String representation of the instance

fromXML

protected void fromXML(StringBuffer xml)
                throws NonParsableException

Description copied from class: AbstractTrainableStatisticalModel

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 AbstractTrainableStatisticalModel

Parameters:

xml - the XML representation of the model

Throws:

NonParsableException - if the StringBuffer is not parsable or the representation is conflicting

See Also:

AbstractTrainableStatisticalModel.AbstractTrainableStatisticalModel(StringBuffer)

getPFM

public double[][] getPFM()
                  throws CloneNotSupportedException

Returns a deep copy of the internal PFM.

Returns:

the PFM

Throws:

CloneNotSupportedException - if the PFM could not be cloned

getPWM

public double[][] getPWM()

Description copied from interface: PWMSupplier

Returns the position weight matrix. Rows are positions, columns are symbols

Specified by:

getPWM in interface PWMSupplier

Returns:

the PWM