de.jstacs.sequenceScores
Interface SequenceScore

All Superinterfaces:

Cloneable, Storable

All Known Subinterfaces:

DifferentiableSequenceScore, DifferentiableStatisticalModel, SamplingDifferentiableStatisticalModel, StatisticalModel, TrainableStatisticalModel, VariableLengthDiffSM

All Known Implementing Classes:

AbstractDifferentiableSequenceScore, AbstractDifferentiableStatisticalModel, AbstractHMM, AbstractMixtureDiffSM, AbstractMixtureTrainSM, AbstractTrainableStatisticalModel, AbstractVariableLengthDiffSM, BayesianNetworkDiffSM, BayesianNetworkTrainSM, CompositeTrainSM, CyclicMarkovModelDiffSM, DAGTrainSM, DifferentiableHigherOrderHMM, DifferentiableStatisticalModelWrapperTrainSM, DiscreteGraphicalTrainSM, DurationDiffSM, ExtendedZOOPSDiffSM, FSDAGModelForGibbsSampling, FSDAGTrainSM, HiddenMotifMixture, HigherOrderHMM, HomogeneousDiffSM, HomogeneousMM, HomogeneousMM0DiffSM, HomogeneousMMDiffSM, HomogeneousTrainSM, IndependentProductDiffSM, IndependentProductDiffSS, InhomogeneousDGTrainSM, LogisticDiffSS, MappingDiffSM, MarkovModelDiffSM, MarkovRandomFieldDiffSM, MixtureDiffSM, MixtureDurationDiffSM, MixtureTrainSM, MultiDimensionalSequenceWrapperDiffSM, NormalizedDiffSM, PositionDiffSM, SamplingHigherOrderHMM, SamplingPhyloHMM, SharedStructureMixture, SkewNormalLikeDurationDiffSM, StrandDiffSM, StrandTrainSM, UniformDiffSM, UniformDiffSS, UniformDurationDiffSM, UniformHomogeneousDiffSM, UniformTrainSM, VariableLengthMixtureDiffSM, VariableLengthWrapperTrainSM, ZOOPSTrainSM

public interface SequenceScore
extends Cloneable, Storable

This interface defines a scoring function that assigns a score to each input sequence. Such score can, for instance, be used in a AbstractScoreBasedClassifier to classify Sequences by chosing the class with the SequenceScore yielding the maximum score for the input Sequence. The most important sub-interfaces are the StatisticalModel for SequenceScores that define a proper, i.e., normalized, likelihood over the input Sequences, and DifferentiableSequenceScore that can compute the derivation with respect to their parameters.

Author:

Jan Grau, Jens Keilwagen

Method Summary

SequenceScore	clone() Creates a clone (deep copy) of the current SequenceScore instance.
AlphabetContainer	getAlphabetContainer() Returns the container of alphabets that were used when constructing the instance.
ResultSet	getCharacteristics() Returns some information characterizing or describing the current instance.
String	getInstanceName() Should return a short instance name such as iMM(0), BN(2), ...
int	getLength() Returns the length of sequences this instance can score.
double[]	getLogScoreFor(DataSet data) This method computes the logarithm of the scores of all sequences in the given sample.
void	getLogScoreFor(DataSet data, double[] res) This method computes and stores the logarithm of the scores for any sequence in the sample in the given double-array.
double	getLogScoreFor(Sequence seq) Returns the logarithmic score for the Sequence seq.
double	getLogScoreFor(Sequence seq, int start) Returns the logarithmic score for the Sequence seq beginning at position start in the Sequence.
double	getLogScoreFor(Sequence seq, int start, int end) Returns the logarithmic score for the Sequence seq beginning at position start in the Sequence.
NumericalResultSet	getNumericalCharacteristics() Returns the subset of numerical values that are also returned by getCharacteristics().
boolean	isInitialized() This method can be used to determine whether the instance is initialized.

Methods inherited from interface de.jstacs.Storable

toXML

Method Detail

clone

SequenceScore clone()
                    throws CloneNotSupportedException

Creates a clone (deep copy) of the current SequenceScore instance.

Returns:

the cloned instance

Throws:

CloneNotSupportedException - if something went wrong while cloning

getAlphabetContainer

AlphabetContainer getAlphabetContainer()

Returns the container of alphabets that were used when constructing the instance.

Returns:

the container of alphabets that were used when constructing the instance

getInstanceName

String getInstanceName()

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

Returns:

a short instance name

getLength

int getLength()

Returns the length of sequences this instance can score. Instances that can only score sequences of defined length are e.g. PWM or inhomogeneous Markov models. If the instance can score sequences of arbitrary length, e.g. homogeneous Markov models, this method returns 0 (zero).

Returns:

the length of sequences the instance can score

getCharacteristics

ResultSet getCharacteristics()
                             throws Exception

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

Returns:

the characteristics of the current instance

Throws:

Exception - if some of the characteristics could not be defined

See Also:

StorableResult

getNumericalCharacteristics

NumericalResultSet getNumericalCharacteristics()
                                               throws Exception

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

Returns:

the numerical characteristics of the current instance

Throws:

Exception - if some of the characteristics could not be defined

getLogScoreFor

double getLogScoreFor(Sequence seq)

Returns the logarithmic score for the Sequence seq.

Parameters:

seq - the sequence

Returns:

the logarithmic score for the sequence

getLogScoreFor

double getLogScoreFor(Sequence seq,
                      int start)

Returns the logarithmic score for the Sequence seq beginning at position start in the Sequence.

Parameters:

seq - the Sequence

start - the start position in the Sequence

Returns:

the logarithmic score for the Sequence

getLogScoreFor

double getLogScoreFor(Sequence seq,
                      int start,
                      int end)
                      throws Exception

Returns the logarithmic score for the Sequence seq beginning at position start in the Sequence.

Parameters:

seq - the Sequence

start - the start position in the Sequence

end - the end position (inclusive) in the Sequence

Returns:

the logarithmic score for the Sequence

Throws:

Exception - if, for instance, the subsequence length can not be handled

getLogScoreFor

double[] getLogScoreFor(DataSet data)
                        throws Exception

This method computes the logarithm of the scores 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 score 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 getLogScoreFor(Sequence).

Parameters:

data - the sample of sequences

Returns:

an array containing the logarithm of the score of all sequences of the sample

Throws:

Exception - if something went wrong

See Also:

getLogScoreFor(Sequence)

getLogScoreFor

void getLogScoreFor(DataSet data,
                    double[] res)
                    throws Exception

This method computes and stores the logarithm of the scores for any sequence in the sample in the given double-array.

The score 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 getLogScoreFor(Sequence).

Parameters:

data - the sample of sequences

res - the array for the results, has to have length data.getNumberOfElements() (which returns the number of sequences in the sample)

Throws:

Exception - if something went wrong

See Also:

getLogScoreFor(Sequence), getLogScoreFor(DataSet)

isInitialized

boolean isInitialized()

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

Returns:

true if the instance is initialized, false otherwise