stream.learner.evaluation

Class ConfusionMatrix<T extends Serializable>

java.lang.Object

stream.learner.evaluation.ConfusionMatrix<T>

public final class ConfusionMatrix<T extends Serializable>
extends Object

This is a data structure for dealing with label-pair-relations. For statistical information on a per-label-base there are methods which return instance(s) of TableOfConfusion. That class has methods to calculate values like Precision, Recall, [...].

Look at http://en.wikipedia.org/wiki/Confusion_matrix for detailed descriptions.

Although there is a method for adding a label or a list of labels to the existing labels, it is highly recommended to use it as rare as possible, as it requires that (internally) the array storing the label-combination-counts has to be copied to a new array which then replaces the old array. Instead, use the constructor with a list of labels as argument, where that list should contain as much labels as possible so that the need for adding labels is at a minimum frequency. However, if the labels are not known in advance, using addLabels(java.util.List) is preferable to #addLabel(java.lang.Object) as there are fewer array copy operations needed with the first mentioned method.

Author:

Benedikt Kulmann, Lukas Kalabis, Christian Bockermann <christian.bockermann@udo.edu>

See Also:

TableOfConfusion

Field Summary

Fields

Modifier and Type	Field and Description
private long[][]	confusionMatrix Array which stores the counts of classification instances (pairs of true and predicted labels)
private List<T>	labels The list of all labels.

Constructor Summary

Constructors

Constructor and Description
ConfusionMatrix() Creates a new ConfusionMatrix instance with an empty list of labels.
ConfusionMatrix(List<T> labels) Creates a new ConfusionMatrix instance.

Method Summary

Modifier and Type	Method and Description
void	add(T truth, T prediction) Adds a classification instance (true and predicted label) to this ConfusionMatrix.
void	addLabel(T additionalLabel) Adds the provided label to the list of labels.
void	addLabels(List<T> additionalLabels) Adds the provided list of labels to the internal list of labels.
double	calculateAccuracy() Calculates and returns the overall accuracy for this confusion matrix in range [0,1].
private long	getFalseNegativeCount(T label) Returns the number of "false negative" instances for the provided label.
private long	getFalsePositiveCount(T label) Returns the number of "false positive" instances for the provided label.
List<T>	getLabels() Returns the list of labels this ConfusionMatrix maintains counters for.
TableOfConfusion	getTableOfConfusion(T label) Constructs and returns the TableOfConfusion for the provided label.
Map<T,TableOfConfusion>	getTablesOfConfusion() Returns a map which contains a TableOfConfusion per label.
private long	getTrueNegativeCount(T label) Returns the number of "true negative" instances for the provided label.
private long	getTruePositiveCount(T label) Returns the number of "true positive" instances for the provided label.
long	getWeightForLabel(T label) Returns the class size as a weight for per-class-calculations.
String	toHtml()
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

labels

private List<T extends Serializable> labels

The list of all labels. Indices refer to the confusionMatrix.

confusionMatrix

private long[][] confusionMatrix

Array which stores the counts of classification instances (pairs of true and predicted labels)

The first dimension represents the true labels while the second dimension represents the predicted labels.

Constructor Detail

ConfusionMatrix

public ConfusionMatrix()

Creates a new ConfusionMatrix instance with an empty list of labels. Don't use this constructor if it is possible to construct a list of possible labels in advance.

ConfusionMatrix

public ConfusionMatrix(List<T> labels)

Creates a new ConfusionMatrix instance.

Parameters:

labels - Labels to maintain a label-pair-combination-counter for.

Method Detail

addLabel

public void addLabel(T additionalLabel)

Adds the provided label to the list of labels. Afterwards it is necessary to create a new array for the internal counters so the usage of this method is expensive. Try to add as much labels as possible at a time by using addLabels(java.util.List) or, which is even better, at object creation time.

Duplicates are ignored.

Parameters:

additionalLabel - The label to add to the internal list of labels

addLabels

public void addLabels(List<T> additionalLabels)

Adds the provided list of labels to the internal list of labels. Afterwards it is necessary to create a new array for the internal counters so the usage of this method is expensive. Try to add as much labels as possible at object creation time.

Duplicates are ignored.

Parameters:

additionalLabels - The labels to add to the internal list of labels

getLabels

public List<T> getLabels()

Returns the list of labels this ConfusionMatrix maintains counters for.

Returns:

The list of labels this ConfusionMatrix maintains counters for.

add

public void add(T truth,
                T prediction)

Adds a classification instance (true and predicted label) to this ConfusionMatrix.

Each label which didn't exist previously will be added within this method automatically (which is expensive and to be avoided).

Parameters:

truth - The true label

prediction - The predicted label

getTablesOfConfusion

public Map<T,TableOfConfusion> getTablesOfConfusion()

Returns a map which contains a TableOfConfusion per label.

Returns:

a map of TableOfConfusion instances

See Also:

#getTableOfConfusion(java.lang.Object)

getTableOfConfusion

public TableOfConfusion getTableOfConfusion(T label)

Constructs and returns the TableOfConfusion for the provided label.

Parameters:

label - The label to construct a TableOfConfusion for

Returns:

A TableOfConfusion instance for the provided label

See Also:

TableOfConfusion

calculateAccuracy

public double calculateAccuracy()

Calculates and returns the overall accuracy for this confusion matrix in range [0,1].

Returns:

the overall accuracy for this confusion matrix in range [0,1]

getWeightForLabel

public long getWeightForLabel(T label)

Returns the class size as a weight for per-class-calculations.

Parameters:

label - The label to get the weight for

Returns:

the class size as a weight for per-class-calculations.

getTruePositiveCount

private long getTruePositiveCount(T label)

Returns the number of "true positive" instances for the provided label.

Parameters:

label - The label to return the counted number of "true positive" instances for

Returns:

The number of "true positive" instances for the provided label

getTrueNegativeCount

private long getTrueNegativeCount(T label)

Returns the number of "true negative" instances for the provided label.

Parameters:

label - The label to return the counted number of "true negative" instances for

Returns:

The number of "true negative" instances for the provided label

getFalsePositiveCount

private long getFalsePositiveCount(T label)

Returns the number of "false positive" instances for the provided label.

Parameters:

label - The label to return the counted number of "false positive" instances for

Returns:

The number of "false positive" instances for the provided label

getFalseNegativeCount

private long getFalseNegativeCount(T label)

Returns the number of "false negative" instances for the provided label.

Parameters:

label - The label to return the counted number of "false negative" instances for

Returns:

The number of "false negative" instances for the provided label

toString

public String toString()

Overrides:

toString in class Object

toHtml

public String toHtml()