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 standard constructor for the interface `Storable`.

Method Summary
`byte[]` | `classify(Sample s)` This method classifies all sequences of a sample and returns an array of indices of the classes to which the respective sequences are assigned with for each index `i` in the array `0 < i < getNumberOfClasses()`.
`abstract byte` | `classify(Sequence seq)` This method classifies a sequence and returns the index `i` of the class to which the sequence is assigned with `0 < i < getNumberOfClasses()`.
`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 the 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 returns the container of alphabets that is used in the classifier.
`ResultSet` | `getCharacteristics()` Returns some information characterizing or describing the current instance of the classifier.
`protected NumericalResult` | `getClassificationRate(Sample[] s)` This method computes the classification rate for a given array of samples.
`abstract CategoricalResult[]` | `getClassifierAnnotation()` Returns an array of `Result`s of dimension `getNumberOfClasses()` that contains information about 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 method `evaluate(MeasureParameters, boolean, Sample...)`.
`static MeasureParameters` | `getMeasuresForEvaluateAll()` Returns an object of the parameters for the method `evaluateAll(MeasureParameters, boolean, Sample...)`.
`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 `getCharacteristics()`.
`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 of the classifier.
`abstract boolean` | `isTrained()` This method gives information about the state of the classifier.
`boolean` | `setNewAlphabetContainerInstance(AlphabetContainer abc)` This method tries to set a new instance of an `AlphabetContainer` for the current classifier.
`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 as `StringBuffer` 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` - the alphabets that are used
  See Also:
    `AbstractClassifier(AlphabetContainer, int)`

### AbstractClassifier

    public AbstractClassifier(AlphabetContainer abc,
                              int length)
                       throws IllegalArgumentException

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

  Parameters:
    `abc` - the alphabets that are used
    `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 standard constructor for the interface `Storable`. Creates a new `AbstractClassifier` out of its XML representation.

  Parameters:
    `xml` - the XML representation as `StringBuffer`
  Throws:
    `NonParsableException` - if the `AbstractClassifier` could not be reconstructed out of the XML representation (the `StringBuffer` could not be parsed)
  See Also:
    `Storable`

Method Detail

### getMeasuresForEvaluate

    public static final MeasureParameters getMeasuresForEvaluate()
                                                          throws ParameterException

  Returns an object of the parameters for the method `evaluate(MeasureParameters, boolean, Sample...)`. The parameters can be set and the measures can be switched on or off.

  Returns:
    an object of the parameters for the method `evaluate(MeasureParameters, boolean, Sample...)`
  Throws:
    `ParameterException` - if something went wrong while constructing the parameter object
  See Also:
    `evaluate(MeasureParameters, boolean, Sample...)`, `MeasureParameters.MeasureParameters(boolean)`

### getMeasuresForEvaluateAll

    public static final MeasureParameters getMeasuresForEvaluateAll()
                                                             throws ParameterException

  Returns an object of the parameters for the method `evaluateAll(MeasureParameters, boolean, Sample...)`. The parameters can be set and the measures can be switched on or off.

  Returns:
    an object of the parameters for the method `evaluateAll(MeasureParameters, boolean, Sample...)`
  Throws:
    `ParameterException` - if something went wrong while constructing the parameter object
  See Also:
    `evaluateAll(MeasureParameters, boolean, Sample...)`, `MeasureParameters.MeasureParameters(boolean)`

### classify

    public abstract byte classify(Sequence seq)
                           throws Exception

  This method classifies a sequence and returns the index `i` of the class to which the sequence is assigned with `0 < i < getNumberOfClasses()`.
  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 an array of indices of the classes to which the respective sequences are assigned with for each index `i` in the array `0 < i < getNumberOfClasses()`.

  Parameters:
    `s` - the sample to be classified
  Returns:
    an array of class assignments
  Throws:
    `Exception` - if something went wrong during the 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 the 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` - indicates the method throws an `Exception` if a measure could not be computed
    `s` - the array of `Sample`s
  Returns:
    a set of numerical results
  Throws:
    `Exception` - if something went wrong
  See Also:
    `NumericalResultSet.NumericalResultSet(LinkedList)`, `getResults(Sample[], MeasureParameters, boolean, boolean)`, `ClassifierAssessment.assess(MeasureParameters, de.jstacs.classifier.assessment.ClassifierAssessmentAssessParameterSet, de.jstacs.utils.ProgressUpdater, Sample...)`, `ClassifierAssessment.assess(MeasureParameters, de.jstacs.classifier.assessment.ClassifierAssessmentAssessParameterSet, Sample...)`, `ClassifierAssessment.assess(MeasureParameters, de.jstacs.classifier.assessment.ClassifierAssessmentAssessParameterSet, de.jstacs.utils.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` - indicates the method throws an `Exception` if a measure could not be computed
    `s` - the array of `Sample`s
  Returns:
    a set of results
  Throws:
    `Exception` - if something went wrong
  See Also:
    `ResultSet.ResultSet(java.util.Collection)`, `getResults(Sample[], MeasureParameters, boolean, boolean)`

### 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 `Sample`s
    `params` - the current parameters
    `exceptionIfNotComputeable` - indicates the method throws an `Exception` if a measure could not be computed
    `all` - indicates the method computes all results or 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 `Sample`s; `Sample` 0 contains only elements of class 0; `Sample` 1 ...
  Returns:
    the classification rate for the samples
  Throws:
    `Exception` - if something went wrong during the classification

### getAlphabetContainer

    public final AlphabetContainer getAlphabetContainer()

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

  Returns:
    the used container of alphabets

### getCharacteristics

    public ResultSet getCharacteristics()
                                 throws Exception

  Returns some information characterizing or describing the current instance of the classifier. 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 `StorableResult`.

  Returns:
    the characteristics of the current instance of the classifier
  Throws:
    `Exception` - if some of the characteristics could not be defined
  See Also:
    `StorableResult`, `getNumericalCharacteristics()`, `ResultSet.ResultSet(de.jstacs.results.Result[][])`

### 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 `Result`s of dimension `getNumberOfClasses()` that contains information about 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 `Result`s that contains information about 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 of the sequences the classifier can handle

### getNumericalCharacteristics

    public abstract NumericalResultSet getNumericalCharacteristics()
                                                            throws Exception

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

  Returns:
    the numerical characteristics
  Throws:
    `Exception` - 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 distinguishing 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 gives information about the state of the classifier.

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

### setNewAlphabetContainerInstance

    public boolean setNewAlphabetContainerInstance(AlphabetContainer abc)

  This method tries to set a new instance of an `AlphabetContainer` for the current classifier.
  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 `AlphabetContainer` could be set, `false` otherwise
  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 given array of test data
  Returns:
    the confusion matrix
  Throws:
    `ClassDimensionException` - if the number of `Sample`s is incorrect
    `Exception` - if something else 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
    - an enumeration of `Sample`s: `train(s1,s2,s3)`
  Throws:
    `Exception` - if the training did not succeed
  See Also:
    `train(Sample[], double[][])`

### train

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

  This method trains a classifier over an array of weighted `Sample` s. That is 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 the `Sample`s
  Throws:
    `Exception` - if the weights are incorrect or the training did not succeed
  See Also:
    `train(Sample...)`

### getXMLTag

    protected abstract String getXMLTag()

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

  Returns:
    the `String` that is used as tag for the XML representation of the classifier

### 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 as `StringBuffer`
  Throws:
    `NonParsableException` - if the information could not be parsed out of the XML representation (the `StringBuffer` could not be parsed)
  See Also:
    `fromXML(StringBuffer)`

### toXML

    public final 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

### 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`
  See Also:
    `toXML()`

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