de.jstacs.scoringFunctions
Interface ScoringFunction

All Superinterfaces:
Cloneable, Storable
All Known Subinterfaces:
NormalizableScoringFunction
All Known Implementing Classes:
AbstractMixtureScoringFunction, AbstractNormalizableScoringFunction, BayesianNetworkScoringFunction, HMM0ScoringFunction, HMMScoringFunction, HomogeneousScoringFunction, IndependentProductScoringFunction, MixtureScoringFunction, MRFScoringFunction, UniformHomogeneousScoringFunction, UniformScoringFunction, VariableLengthScoringFunction

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 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 log score for the sequence
 double getLogScore(Sequence seq, int start)
          Returns the log score for the sequence
 double getLogScoreAndPartialDerivation(Sequence seq, int start, IntList indices, DoubleList partialDer)
          Returns the log score for the sequence and fills the list with the indices and the partial derivations.
 double getLogScoreAndPartialDerivation(Sequence seq, IntList indices, DoubleList partialDer)
          Returns the log score for the sequence and fills the list with the indices and the partial derivations.
 int getNumberOfParameters()
          The number of parameters in this scoring function.
 int getNumberOfRecommendedStarts()
          This method return the number of recommended optimization starts.
 void initializeFunction(int index, boolean freeParams, Sample[] data, double[][] weights)
          This method creates the underlying structure of the scoring function.
 void initializeFunctionRandomly(boolean freeParams)
          This method initializes the scoring function 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 + this.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
Throws:
CloneNotSupportedException

initializeFunction

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

Parameters:
index - the index of the class the scoring function models
freeParams - if true, the (reduced) parameterization is used
data - the samples
weights - the weights of the sequences in the samples
Throws:
Exception

initializeFunctionRandomly

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

Parameters:
freeParams - if true, the (reduced) parameterization is used
Throws:
Exception

getAlphabetContainer

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

Returns:
the alphabet

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 ScoringFunction, i.e. ScoringFunctions that support Sequences of different lengths, should return 0.

Returns:
the length

getLogScore

double getLogScore(Sequence seq)
Returns the log score for the sequence

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

getLogScore

double getLogScore(Sequence seq,
                   int start)
Returns the log score for the sequence

Parameters:
seq - the sequence
start - the startposition in the sequence
Returns:
the log score for the sequence

getLogScoreAndPartialDerivation

double getLogScoreAndPartialDerivation(Sequence seq,
                                       IntList indices,
                                       DoubleList partialDer)
Returns the log score for the sequence and fills the list with the indices and the partial derivations.

Parameters:
seq - the sequence
indices - after method invocation the list should contain the indices i where \frac{\partial \log score(seq)}{\partial \lambda_i} is not zero
partialDer - after method invocation the list should contain the corresponding \frac{\partial \log score(seq)}{\partial \lambda_i}
Returns:
the log score

getLogScoreAndPartialDerivation

double getLogScoreAndPartialDerivation(Sequence seq,
                                       int start,
                                       IntList indices,
                                       DoubleList partialDer)
Returns the log score for the sequence and fills the list with the indices and the partial derivations.

Parameters:
seq - the sequence
start - the startposition in the sequence
indices - after method invocation the list should contain the indices i where \frac{\partial \log score(seq)}{\partial \lambda_i} is not zero
partialDer - after method invocation the list should contain the corresponding \frac{\partial \log score(seq)}{\partial \lambda_i}
Returns:
the log score

getNumberOfParameters

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

Returns:
the number of parameters in this scoring function
See Also:
UNKNOWN

getNumberOfRecommendedStarts

int getNumberOfRecommendedStarts()
This method return 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 on e 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 - is thrown 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 + this.getNumberOfParameters() - 1

Parameters:
params - the parameters
start - the start index

isInitialized

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

Returns:
true if the model is initialized

getInitialClassParam

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

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