de.jstacs.scoringFunctions
Interface ScoringFunction

All Superinterfaces:
Cloneable, Storable
All Known Subinterfaces:
NormalizableScoringFunction, SamplingScoringFunction, VariableLengthScoringFunction
All Known Implementing Classes:
AbstractMixtureScoringFunction, AbstractNormalizableScoringFunction, AbstractVariableLengthScoringFunction, BayesianNetworkScoringFunction, CMMScoringFunction, DifferentiableHigherOrderHMM, DurationScoringFunction, HiddenMotifsMixture, HMM0ScoringFunction, HMMScoringFunction, HomogeneousScoringFunction, IndependentProductScoringFunction, MappingScoringFunction, MixtureDuration, MixtureScoringFunction, MRFScoringFunction, MutableMarkovModelScoringFunction, NormalizedScoringFunction, PositionScoringFunction, SkewNormalLikeScoringFunction, StrandScoringFunction, UniformDurationScoringFunction, UniformHomogeneousScoringFunction, UniformScoringFunction, VariableLengthMixtureScoringFunction

public interface ScoringFunction
extends Storable, Cloneable

This interface is the main part of any ScoreClassifier.

Author:
Jens Keilwagen, Jan Grau

Field Summary
static int UNKNOWN
          Indicates that the number of parameters of this ScoringFunction is not known (yet).
 
Method Summary
 ScoringFunction clone()
          Creates a clone (deep copy) of the current ScoringFunction instance.
 AlphabetContainer getAlphabetContainer()
          Returns the AlphabetContainer for this ScoringFunction.
 double[] getCurrentParameterValues()
          Returns a double array of dimension getNumberOfParameters() containing the current parameter values.
 double getInitialClassParam(double classProb)
          Returns the initial class parameter for the class this ScoringFunction is responsible for, based on the class probability classProb.
 String getInstanceName()
          Returns a short instance name.
 int getLength()
          Returns the length of this ScoringFunction, i.e. the length of the Sequences this ScoringFunction can handle.
 double getLogScore(Sequence seq)
          Returns the logarithmic score for the Sequence seq.
 double getLogScore(Sequence seq, int start)
          Returns the logarithmic score for the Sequence seq beginning at position start in the Sequence.
 double getLogScoreAndPartialDerivation(Sequence seq, int start, IntList indices, DoubleList partialDer)
          Returns the logarithmic score for a Sequence beginning at position start in the Sequence and fills lists with the indices and the partial derivations.
 double getLogScoreAndPartialDerivation(Sequence seq, IntList indices, DoubleList partialDer)
          Returns the logarithmic score for a Sequence seq and fills lists with the indices and the partial derivations.
 int getNumberOfParameters()
          Returns the number of parameters in this ScoringFunction.
 int getNumberOfRecommendedStarts()
          This method returns the number of recommended optimization starts.
 void initializeFunction(int index, boolean freeParams, Sample[] data, double[][] weights)
          This method creates the underlying structure of the ScoringFunction.
 void initializeFunctionRandomly(boolean freeParams)
          This method initializes the ScoringFunction randomly.
 boolean isInitialized()
          This method can be used to determine whether the model is initialized.
 void setParameters(double[] params, int start)
          This method sets the internal parameters to the values of params between start and start + getNumberOfParameters() - 1
 
Methods inherited from interface de.jstacs.Storable
toXML
 

Field Detail

UNKNOWN

static final int UNKNOWN
Indicates that the number of parameters of this ScoringFunction is not known (yet).

See Also:
Constant Field Values
Method Detail

clone

ScoringFunction clone()
                      throws CloneNotSupportedException
Creates a clone (deep copy) of the current ScoringFunction instance.

Returns:
the cloned instance of the current ScoringFunction
Throws:
CloneNotSupportedException - if something went wrong while cloning the ScoringFunction

initializeFunction

void initializeFunction(int index,
                        boolean freeParams,
                        Sample[] data,
                        double[][] weights)
                        throws Exception
This method creates the underlying structure of the ScoringFunction.

Parameters:
index - the index of the class the ScoringFunction models
freeParams - indicates whether the (reduced) parameterization is used
data - the samples
weights - the weights of the sequences in the samples
Throws:
Exception - if something went wrong

initializeFunctionRandomly

void initializeFunctionRandomly(boolean freeParams)
                                throws Exception
This method initializes the ScoringFunction randomly. It has to create the underlying structure of the ScoringFunction.

Parameters:
freeParams - indicates whether the (reduced) parameterization is used
Throws:
Exception - if something went wrong

getAlphabetContainer

AlphabetContainer getAlphabetContainer()
Returns the AlphabetContainer for this ScoringFunction. Only Sequences with a comparable AlphabetContainer can be modeled.

Returns:
the AlphabetContainer

getInstanceName

String getInstanceName()
Returns a short instance name.

Returns:
a short instance name

getLength

int getLength()
Returns the length of this ScoringFunction, i.e. the length of the Sequences this ScoringFunction can handle. For homogeneous ScoringFunctions, i.e. ScoringFunctions that support Sequences of different lengths, the method should return 0.

Returns:
the length of this ScoringFunction

getLogScore

double getLogScore(Sequence seq)
Returns the logarithmic score for the Sequence seq.

Parameters:
seq - the sequence
Returns:
the logarithmic score for the sequence

getLogScore

double getLogScore(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

getLogScoreAndPartialDerivation

double getLogScoreAndPartialDerivation(Sequence seq,
                                       IntList indices,
                                       DoubleList partialDer)
Returns the logarithmic score for a Sequence seq and fills lists with the indices and the partial derivations.

Parameters:
seq - the Sequence
indices - an IntList of indices, after method invocation the list should contain the indices i where $\frac{\partial \log score(seq)}{\partial \lambda_i}$ is not zero
partialDer - a DoubleList of partial derivations, after method invocation the list should contain the corresponding $\frac{\partial \log score(seq)}{\partial \lambda_i}$ that are not zero
Returns:
the logarithmic score for the Sequence

getLogScoreAndPartialDerivation

double getLogScoreAndPartialDerivation(Sequence seq,
                                       int start,
                                       IntList indices,
                                       DoubleList partialDer)
Returns the logarithmic score for a Sequence beginning at position start in the Sequence and fills lists with the indices and the partial derivations.

Parameters:
seq - the Sequence
start - the start position in the Sequence
indices - an IntList of indices, after method invocation the list should contain the indices i where $\frac{\partial \log score(seq)}{\partial \lambda_i}$ is not zero
partialDer - a DoubleList of partial derivations, after method invocation the list should contain the corresponding $\frac{\partial \log score(seq)}{\partial \lambda_i}$ that are not zero
Returns:
the logarithmic score for the Sequence

getNumberOfParameters

int getNumberOfParameters()
Returns the number of parameters in this ScoringFunction. If the number of parameters is not known yet, the method returns UNKNOWN.

Returns:
the number of parameters in this ScoringFunction
See Also:
UNKNOWN

getNumberOfRecommendedStarts

int getNumberOfRecommendedStarts()
This method returns the number of recommended optimization starts. The standard implementation returns 1.

Returns:
the number of recommended optimization starts

getCurrentParameterValues

double[] getCurrentParameterValues()
                                   throws Exception
Returns a double array of dimension getNumberOfParameters() containing the current parameter values. If one likes to use these parameters to start an optimization it is highly recommended to invoke initializeFunction(int, boolean, Sample[], double[][]) before. After an optimization this method can be used to get the current parameter values.

Returns:
the current parameter values
Throws:
Exception - if no parameters exist (yet)

setParameters

void setParameters(double[] params,
                   int start)
This method sets the internal parameters to the values of params between start and start + getNumberOfParameters() - 1

Parameters:
params - the new parameters
start - the start index in params

isInitialized

boolean isInitialized()
This method can be used to determine whether the model is initialized. If the model is not initialized you should invoke the method initializeFunction(int, boolean, Sample[], double[][]).

Returns:
true if the model is initialized, false otherwise

getInitialClassParam

double getInitialClassParam(double classProb)
Returns the initial class parameter for the class this ScoringFunction is responsible for, based on the class probability classProb.

Parameters:
classProb - the class probability
Returns:
the initial class parameter