Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## de.jstacs.classifier
Class AbstractClassifier

    java.lang.Object
      de.jstacs.classifier.AbstractClassifier

All Implemented Interfaces:
  Storable, Cloneable

Direct Known Subclasses:
  AbstractScoreBasedClassifier

    public abstract class AbstractClassifier

extends Object
implements Storable, Cloneable

The super class for any classifier.
The order of the classes is never changed inside the classifier. The samples you put in the methods like `train, test` and `evaluate` should always have the same order that you have used while instantiation of the object.
For two classes it is highly recommended to set the foreground as first class and the second class as background.

Author:
  Jens Keilwagen, Jan Grau

Constructor Summary
`AbstractClassifier(AlphabetContainer abc)` The constructor for a homogeneous classifier.
`AbstractClassifier(AlphabetContainer abc, int length)` The constructor for an inhomogeneous classifier.
`AbstractClassifier(StringBuffer xml)` The constructor for the Storable interface.

Method Summary
`byte[]` | `classify(Sample s)` This method classifies all sequences of a sample and returns the index `i`, with `0 < i < getNumberOfClasses()`, of the class to which the sequence is assigned.
`abstract byte` | `classify(Sequence seq)` This method classifies a sequence and returns the index `i`, with `0 < i < getNumberOfClasses()`, of the class to which the sequence is assigned.
`AbstractClassifier` | `clone()`
`NumericalResultSet` | `evaluate(MeasureParameters params, boolean exceptionIfNotComputeable, Sample... s)` This method evaluates the classifier and computes all numerical results as for instance the sensitivity for a given specificity, the area under ROC curve and so on.
`ResultSet` | `evaluateAll(MeasureParameters params, boolean exceptionIfNotComputeable, Sample... s)` This method evaluates the classifier and computes all results.
`protected abstract void` | `extractFurtherClassifierInfosFromXML(StringBuffer xml)` Extracts further information of a classifier from an xml-representation.
`AlphabetContainer` | `getAlphabetContainer()` This method return the container of alphabets that is used in the classifier.
`ResultSet` | `getCharacteristics()` Returns some information characterizing or describing the current instance of the model.
`protected NumericalResult` | `getClassificationRate(Sample[] s)` This method computes the classification rate for a given array of samples.
`abstract CategoricalResult[]` | `getClassifierAnnotation()` Returns an array of Results of dimension `getNumberOfClasses` that contains information the classifier and for each class.
`protected abstract StringBuffer` | `getFurtherClassifierInfos()` This method returns further information of a classifier as a StringBuffer.
`abstract String` | `getInstanceName()` Returns a short description of the classifier.
`int` | `getLength()` Returns the length of the sequences this classifier can handle or `0` for sequences of arbitrary length.
`static MeasureParameters` | `getMeasuresForEvaluate()` Returns an object of the parameters for the evaluate-method.
`static MeasureParameters` | `getMeasuresForEvaluateAll()` Returns an object of the parameters for the evaluateAll-method.
`abstract int` | `getNumberOfClasses()` Returns the number of classes that can be distinguished.
`abstract NumericalResultSet` | `getNumericalCharacteristics()` Returns the subset of numerical values that are also returned by `getCharacteristsics`.
`protected LinkedList<? extends Result>` | `getResults(Sample[] s, MeasureParameters params, boolean exceptionIfNotComputeable, boolean all)` This method computes the results for any evaluation of the classifier.
`protected abstract String` | `getXMLTag()` Returns the String that is used as tag for the xml-representation.
`abstract boolean` | `isTrained()` This method the state of the classifier.
`boolean` | `setNewAlphabetContainerInstance(AlphabetContainer abc)` This method tries to set a new instance of an AlphabetConatiner for the current model.
`ConfusionMatrix` | `test(Sample... testData)` This method computes the confusion matrix for a given array of test data
`StringBuffer` | `toXML()` This method returns an XML-representation of an instance of the implementing class.
`void` | `train(Sample... s)` Trains the AbstractClassifier object given the data as `Sample`s.
`abstract void` | `train(Sample[] s, double[][] weights)` This method trains a classifier over an array of weighted `Sample`s.

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### AbstractClassifier

    public AbstractClassifier(AlphabetContainer abc)

  The constructor for a homogeneous classifier. Such a classifier can handle sequences of arbitrary length.

  Parameters:
    `abc` -

### AbstractClassifier

    public AbstractClassifier(AlphabetContainer abc,
                              int length)
                       throws IllegalArgumentException

  The constructor for an inhomogeneous classifier. Such a classifier can handle sequences of arbitrary length.

  Parameters:
    `abc` - the alphabets that are used for
    `length` - the length of the sequences that can be classified
  Throws:
    `IllegalArgumentException` - if the length and the possible length of the AlphabetContainer does not match

### AbstractClassifier

    public AbstractClassifier(StringBuffer xml)
                       throws NonParsableException

  The constructor for the Storable interface.

  Parameters:
    `xml` - the xml-representation
  Throws:
    `NonParsableException` - if the xml-format is not parsable

Method Detail

### getMeasuresForEvaluate

    public static final MeasureParameters getMeasuresForEvaluate()
                                                          throws ParameterException

  Returns an object of the parameters for the evaluate-method. The parameters can be set and the measures can be switch on or off.

  Returns:
    an object of the parameters for the evaluate-method
  Throws:
    `ParameterException`
  See Also:
    `evaluate(MeasureParameters, boolean, Sample...)`

### getMeasuresForEvaluateAll

    public static final MeasureParameters getMeasuresForEvaluateAll()
                                                             throws ParameterException

  Returns an object of the parameters for the evaluateAll-method. The parameters can be set and the measures can be switch on or off.

  Returns:
    an object of the parameters for the evaluateAll-method
  Throws:
    `ParameterException`
  See Also:
    `evaluateAll(MeasureParameters, boolean, Sample...)`

### classify

    public abstract byte classify(Sequence seq)
                           throws Exception

  This method classifies a sequence and returns the index `i`, with `0 < i < getNumberOfClasses()`, of the class to which the sequence is assigned.
  This method should check that the sequence is defined over the underlying alphabet and length.

  Parameters:
    `seq` - the sequence to be classified
  Returns:
    the index of the class to which the sequence is assigned
  Throws:
    `Exception` - if the classifier is not trained or something is wrong with the sequence

### classify

    public byte[] classify(Sample s)
                    throws Exception

  This method classifies all sequences of a sample and returns the index `i`, with `0 < i < getNumberOfClasses()`, of the class to which the sequence is assigned.

  Parameters:
    `s` - the sample to be classified
  Returns:
    an array of class assignments
  Throws:
    `Exception` - if something went wrong while classification

### clone

    public AbstractClassifier clone()
                             throws CloneNotSupportedException

  Overrides:
    `clone` in class `Object`
  Throws:
    `CloneNotSupportedException`

### evaluate

    public final NumericalResultSet evaluate(MeasureParameters params,
                                             boolean exceptionIfNotComputeable,
                                             Sample... s)
                                      throws Exception

  This method evaluates the classifier and computes all numerical results as for instance the sensitivity for a given specificity, the area under ROC curve and so on. This method should be used in any kind of classifier assessment as for instance crossvalidation, hold out sampling, ... .
  For two classes it is highly recommended to set the foreground as first class and the second class as background, i.e. the first sample should be the foreground sample and the second should be background sample. See also this comment.

  Parameters:
    `params` - the current parameters
    `exceptionIfNotComputeable` - if `true` the method
    `s` - the array of Samples
  Returns:
    a set of numerical results
  Throws:
    `Exception` - if something went wrong
  See Also:
    `ClassifierAssessment.assess(MeasureParameters, ClassifierAssessmentAssessParameterSet, ProgressUpdater, Sample[])`, `ClassifierAssessment.assess(MeasureParameters, ClassifierAssessmentAssessParameterSet, Sample[])`, `ClassifierAssessment.assess(MeasureParameters, ClassifierAssessmentAssessParameterSet, ProgressUpdater, Sample[][][])`

### evaluateAll

    public final ResultSet evaluateAll(MeasureParameters params,
                                       boolean exceptionIfNotComputeable,
                                       Sample... s)
                                throws Exception

  This method evaluates the classifier and computes all results.

  Parameters:
    `params` - the current parameters
    `exceptionIfNotComputeable` - if `true` the method throws an exception if a measure could not be computed, otherwise it is ignored
    `s` - the array of Samples
  Returns:
    a set of results
  Throws:
    `Exception` - if something went wrong

### getResults

    protected LinkedList<? extends Result> getResults(Sample[] s,
                                                      MeasureParameters params,
                                                      boolean exceptionIfNotComputeable,
                                                      boolean all)
                                               throws Exception

  This method computes the results for any evaluation of the classifier.

  Parameters:
    `s` - the array of Samples
    `params` - the current parameters
    `exceptionIfNotComputeable` - if `true` the method throws an exception if a measure could not be computed, otherwise it is ignored
    `all` - if `true` the method computes all results, if `false` it computes only the numerical results
  Returns:
    a list of results
  Throws:
    `Exception` - if something went wrong
  See Also:
    `evaluate(MeasureParameters, boolean, Sample...)`, `evaluateAll(MeasureParameters, boolean, Sample...)`

### getClassificationRate

    protected final NumericalResult getClassificationRate(Sample[] s)
                                                   throws Exception

  This method computes the classification rate for a given array of samples.

  Parameters:
    `s` - the array of samples; sample 0 contains only elements of class 0; sample 1 ...
  Returns:
    the classification rate
  Throws:
    `Exception` - if something went wrong while classification

### getAlphabetContainer

    public final AlphabetContainer getAlphabetContainer()

  This method return the container of alphabets that is used in the classifier.

  Returns:
    the used alphabet

### getCharacteristics

    public ResultSet getCharacteristics()
                                 throws Exception

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

  Returns:
    the characteristics
  Throws:
    `Exception` - an `Exception` is thrown if some of the characteristics could not be defined
  See Also:
    `StorableResult`

### getInstanceName

    public abstract String getInstanceName()

  Returns a short description of the classifier.

  Returns:
    a short description of the classifier

### getClassifierAnnotation

    public abstract CategoricalResult[] getClassifierAnnotation()

  Returns an array of Results of dimension `getNumberOfClasses` that contains information the classifier and for each class. `res[0] = new CategoricalResult( "classifier", "the kind of classifier", getInstanceName() ); res[1] = new CategoricalResult( "class info 0", "some information about the class", "info0" ); res[2] = new CategoricalResult( "class info 1", "some information about the class", "info1" ); ...`

  Returns:
    an array of Results that contains information the classifier

### getLength

    public final int getLength()

  Returns the length of the sequences this classifier can handle or `0` for sequences of arbitrary length.

  Returns:
    the length

### getNumericalCharacteristics

    public abstract NumericalResultSet getNumericalCharacteristics()
                                                            throws Exception

  Returns the subset of numerical values that are also returned by `getCharacteristsics`.

  Returns:
    the numerical characteristics
  Throws:
    `Exception` - an `Exception` is thrown if some of the characteristics could not be defined

### getNumberOfClasses

    public abstract int getNumberOfClasses()

  Returns the number of classes that can be distinguished. For example if distinguish between foreground and background this method should return 2, even if you use a mixture model for either foreground or background.

  Returns:
    the number of classes that can be distinguished

### isTrained

    public abstract boolean isTrained()

  This method the state of the classifier.

  Returns:
    `true` if the classifier is able to classify sequences, otherwise `false`

### setNewAlphabetContainerInstance

    public boolean setNewAlphabetContainerInstance(AlphabetContainer abc)

  This method tries to set a new instance of an AlphabetConatiner for the current model. This instance has to be consistent with the underlying instance of an AlphabetContainer.
  This method can be very useful to save time.

  Parameters:
    `abc` - the alphabets
  Returns:
    `true` if the new container could be set
  See Also:
    `getAlphabetContainer()`, `AlphabetContainer.checkConsistency(AlphabetContainer)`

### test

    public ConfusionMatrix test(Sample... testData)
                         throws Exception,
                                ClassDimensionException

  This method computes the confusion matrix for a given array of test data

  Parameters:
    `testData` - the data
  Returns:
    the confusion matrix
  Throws:
    `ClassDimensionException` - if the number of samples in incorrect
    `Exception` - if something went wrong

### train

    public void train(Sample... s)
               throws Exception

  Trains the AbstractClassifier object given the data as `Sample`s.
  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`.
  This method should check that the `Sample`s are defined over the underlying alphabet and length.

  Parameters:
    `s` - the data
    - either an array of `Sample`s: `train( new Sample[]{s1,s2,s3})` or
    - a enumeration of `Sample`s: `train(s1,s2,s3)`
  Throws:
    `Exception` - an Exception should be thrown if the training did not succeed

### train

    public abstract void train(Sample[] s,
                               double[][] weights)
                        throws Exception

  This method trains a classifier over an array of weighted `Sample`s. That's why the following has to be fulfilled:
  - `s.length == weights.length`
  - and for all i: `weights[i] == null || s[i].getNumberOfElements() == weights[i].length`.
  This method should work non-incrementally as the method `train( Sample[] )`.
  This method should check that the `Sample`s are defined over the underlying alphabet and length.

  Parameters:
    `s` - an array of `Sample`s
    `weights` - the weights for `s`
  Throws:
    `Exception` - an Exception should be thrown if the weights are incorrect or the training did not succeed

### getXMLTag

    protected abstract String getXMLTag()

  Returns the String that is used as tag for the xml-representation. This method is used by the methods `fromXML( StringBuffer )` and `toXML()`.

  Returns:
    the String that is used as tag for the xml-representation

### extractFurtherClassifierInfosFromXML

    protected abstract void extractFurtherClassifierInfosFromXML(StringBuffer xml)
                                                          throws NonParsableException

  Extracts further information of a classifier from an xml-representation. This method is used by the method `fromXML( StringBuffer )` and should not be made public.

  Parameters:
    `xml` - the xml-representation
  Throws:
    `NonParsableException`

### toXML

    public final StringBuffer toXML()

  Description copied from interface: `Storable`
  This method returns an XML-representation of an instance of the implementing class.

  Specified by:
    `toXML` in interface `Storable`
  Returns:
    the XML-representation

### getFurtherClassifierInfos

    protected abstract StringBuffer getFurtherClassifierInfos()

  This method returns further information of a classifier as a StringBuffer. This method is used by the method `toXML()` and should not be made public.

  Returns:
    further information of a classifier as a StringBuffer

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD