gov.sandia.cognition.learning.performance.categorization
Class DefaultBinaryConfusionMatrix

java.lang.Object
  extended by gov.sandia.cognition.util.AbstractCloneableSerializable
      extended by gov.sandia.cognition.learning.performance.categorization.AbstractConfusionMatrix<Boolean>
          extended by gov.sandia.cognition.learning.performance.categorization.AbstractBinaryConfusionMatrix
              extended by gov.sandia.cognition.learning.performance.categorization.DefaultBinaryConfusionMatrix
All Implemented Interfaces:
BinaryConfusionMatrix, ConfusionMatrix<Boolean>, CloneableSerializable, Serializable, Cloneable

public class DefaultBinaryConfusionMatrix
extends AbstractBinaryConfusionMatrix

A default implementation of the BinaryConfusionMatrix. It stores the four entries in the confusion matrix: true positives, false positives, true negatives, and false negatives.

Since:
3.1
Author:
Justin Basilico, Kevin R. Dixon
See Also:
Serialized Form

Nested Class Summary
static class DefaultBinaryConfusionMatrix.ActualPredictedPairSummarizer
          A confusion matrix summarizer that summarizes actual-predicted pairs.
static class DefaultBinaryConfusionMatrix.CombineSummarizer
          A confusion matrix summarizer that adds together confusion matrices.
static class DefaultBinaryConfusionMatrix.PerformanceEvaluator<InputType>
          An implementation of the SupervisedPerformanceEvaluator interface for creating a DefaultBinaryConfusionMatrix.
 
Field Summary
protected  double falseNegativesCount
          Number of false negatives.
protected  double falsePositivesCount
          Number of false positives.
protected  double trueNegativesCount
          Number of true negatives.
protected  double truePositivesCount
          Number of true positives.
 
Constructor Summary
DefaultBinaryConfusionMatrix()
          Creates a new, empty DefaultBinaryConfusionMatrix.
 
Method Summary
 void add(Boolean target, Boolean estimate, double value)
          Adds a given value to the matrix entry for the (actual, predicted) pair.
static
<CategoryType>
DefaultBinaryConfusionMatrix
binarizeOnTrueCategory(ConfusionMatrix<CategoryType> matrix, CategoryType trueCategory)
          Takes a general confusion matrix and creates a binary form of it using true category.
static
<CategoryType>
DefaultBinaryConfusionMatrix
binarizeOnTrueSet(ConfusionMatrix<CategoryType> matrix, Set<? super CategoryType> trueSet)
          Takes a general confusion matrix and creates a binary form of it using the given set of true categories.
 void clear()
          Empties out all the data in this confusion matrix.
 DefaultBinaryConfusionMatrix clone()
          This makes public the clone method on the Object class and removes the exception that it throws.
static DefaultBinaryConfusionMatrix create(Iterable<? extends TargetEstimatePair<? extends Boolean,? extends Boolean>> input)
          Creates a new DefaultBinaryConfusionMatrix from the given target-estimate pairs.
static DefaultBinaryConfusionMatrix create(Iterable<? extends TargetEstimatePair<? extends Boolean,? extends Boolean>> input, boolean weightIfAvailable)
          Creates a new DefaultBinaryConfusionMatrix from the given target-estimate pairs.
static DefaultBinaryConfusionMatrix createFromActualPredictedPairs(Collection<? extends Pair<? extends Boolean,? extends Boolean>> pairs)
          Creates a new DefaultConfusionMatrix from the given actual-predicted pairs.
 double getFalseNegativesCount()
          Gets the number of false negatives.
 double getFalseNegativesRate()
          Gets the rate of true targets incorrectly classified as false.
 double getFalsePositivesCount()
          Gets the number of false positives.
 double getFalsePositivesRate()
          Gets the rate of false targets incorrectly classified as true.
 double getTrueNegativesCount()
          Gets the number of true negatives.
 double getTrueNegativesRate()
          Gets the rate of negative targets correctly classified.
 double getTruePositivesCount()
          Gets the number of true positives.
 double getTruePositivesRate()
          Gets the rate of target trues that were correctly classified as true.
 void setFalseNegativesCount(double falseNegativesCount)
          Sets the number of false negatives in the matrix.
 void setFalsePositivesCount(double falsePositivesCount)
          Sets the number of false positives in the matrix.
 void setTrueNegativesCount(double trueNegativesCount)
          Sets the number of true negatives in the matrix.
 void setTruePositivesCount(double truePositivesCount)
          Sets the number of true positives in the matrix.
 String toString()
           
 
Methods inherited from class gov.sandia.cognition.learning.performance.categorization.AbstractBinaryConfusionMatrix
getActualCategories, getActualCount, getCategories, getCount, getFalseNegativesFraction, getFalsePositivesFraction, getFScore, getFScore, getPrecision, getPredictedCategories, getPredictedCategories, getRecall, getSensitivity, getSpecificity, getTrueNegativesFraction, getTruePositivesFraction
 
Methods inherited from class gov.sandia.cognition.learning.performance.categorization.AbstractConfusionMatrix
add, addAll, getAccuracy, getAverageCategoryAccuracy, getAverageCategoryErrorRate, getCategoryAccuracy, getCategoryErrorRate, getErrorRate, getPredictedCount, getTotalCorrectCount, getTotalCount, getTotalIncorrectCount, isEmpty
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface gov.sandia.cognition.learning.performance.categorization.ConfusionMatrix
add, addAll, getAccuracy, getAverageCategoryAccuracy, getAverageCategoryErrorRate, getCategoryAccuracy, getCategoryErrorRate, getErrorRate, getPredictedCount, getTotalCorrectCount, getTotalCount, getTotalIncorrectCount, isEmpty
 

Field Detail

trueNegativesCount

protected double trueNegativesCount
Number of true negatives. The (false, false) entry.


falsePositivesCount

protected double falsePositivesCount
Number of false positives. The (false, true) entry.


falseNegativesCount

protected double falseNegativesCount
Number of false negatives. The (true, false) entry.


truePositivesCount

protected double truePositivesCount
Number of true positives. The (true, true) entry.

Constructor Detail

DefaultBinaryConfusionMatrix

public DefaultBinaryConfusionMatrix()
Creates a new, empty DefaultBinaryConfusionMatrix.

Method Detail

clone

public DefaultBinaryConfusionMatrix clone()
Description copied from class: AbstractCloneableSerializable
This makes public the clone method on the Object class and removes the exception that it throws. Its default behavior is to automatically create a clone of the exact type of object that the clone is called on and to copy all primitives but to keep all references, which means it is a shallow copy. Extensions of this class may want to override this method (but call super.clone() to implement a "smart copy". That is, to target the most common use case for creating a copy of the object. Because of the default behavior being a shallow copy, extending classes only need to handle fields that need to have a deeper copy (or those that need to be reset). Some of the methods in ObjectUtil may be helpful in implementing a custom clone method. Note: The contract of this method is that you must use super.clone() as the basis for your implementation.

Specified by:
clone in interface CloneableSerializable
Overrides:
clone in class AbstractCloneableSerializable
Returns:
A clone of this object.

add

public void add(Boolean target,
                Boolean estimate,
                double value)
Description copied from interface: ConfusionMatrix
Adds a given value to the matrix entry for the (actual, predicted) pair.

Parameters:
target - The actual category.
estimate - The predicted category.
value - The value to add.

clear

public void clear()
Description copied from interface: ConfusionMatrix
Empties out all the data in this confusion matrix.


getTruePositivesCount

public double getTruePositivesCount()
Description copied from interface: BinaryConfusionMatrix
Gets the number of true positives. This is the (true, true) entry.

Returns:
The number of true positives.

setTruePositivesCount

public void setTruePositivesCount(double truePositivesCount)
Sets the number of true positives in the matrix.

Parameters:
truePositivesCount - The number of true positives. Cannot be negative.

getFalsePositivesCount

public double getFalsePositivesCount()
Description copied from interface: BinaryConfusionMatrix
Gets the number of false positives. This is the (false, true) entry.

Returns:
The number of false positives.

setFalsePositivesCount

public void setFalsePositivesCount(double falsePositivesCount)
Sets the number of false positives in the matrix.

Parameters:
falsePositivesCount - The number of false positives. Cannot be negative.

getTrueNegativesCount

public double getTrueNegativesCount()
Description copied from interface: BinaryConfusionMatrix
Gets the number of true negatives. This is the (false, false) entry.

Returns:
The number of true negatives.

setTrueNegativesCount

public void setTrueNegativesCount(double trueNegativesCount)
Sets the number of true negatives in the matrix.

Parameters:
trueNegativesCount - The number of true negatives. Cannot be negative.

getFalseNegativesCount

public double getFalseNegativesCount()
Description copied from interface: BinaryConfusionMatrix
Gets the number of false negatives. This is the (true, false) entry.

Returns:
The number of false negatives.

setFalseNegativesCount

public void setFalseNegativesCount(double falseNegativesCount)
Sets the number of false negatives in the matrix.

Parameters:
falseNegativesCount - The number of false negatives. Cannot be negative.

getTrueNegativesRate

public double getTrueNegativesRate()
Gets the rate of negative targets correctly classified. Computed as: TrueNegatives / TotalNegatives = TrueNegatives / (TrueNegatives + FalsePositives)

Returns:
True negative rate, which is in [0,1].

getTruePositivesRate

public double getTruePositivesRate()
Gets the rate of target trues that were correctly classified as true. Computed as: TruePositives / TotalPositives = TruePositives / (TruePositives + FalseNegatives)

Returns:
True positives rate, which is in [0,1].

getFalsePositivesRate

public double getFalsePositivesRate()
Gets the rate of false targets incorrectly classified as true. Computed as: FalsePositives / TotalNegatives = FalsePositives / (TrueNegatives + FalsePositives)

Returns:
Rate of false positives, which is in [0,1]. Equal to 1 - trueNegativeRate.

getFalseNegativesRate

public double getFalseNegativesRate()
Gets the rate of true targets incorrectly classified as false. Computed as: FalseNegatives / TotalPositives = FalseNegatives / (TruePositives + FalseNegatives)

Returns:
Rate of false negatives, which is in [0,1]. Equal to 1 - truePositiveRate

toString

public String toString()
Overrides:
toString in class Object

binarizeOnTrueCategory

public static <CategoryType> DefaultBinaryConfusionMatrix binarizeOnTrueCategory(ConfusionMatrix<CategoryType> matrix,
                                                                                 CategoryType trueCategory)
Takes a general confusion matrix and creates a binary form of it using true category. All other categories are considered false.

Type Parameters:
CategoryType - The true category type.
Parameters:
matrix - The general confusion matrix to binarize.
trueCategory - The value of the true category for the binary confusion matrix.
Returns:
A new binary confusion matrix.

binarizeOnTrueSet

public static <CategoryType> DefaultBinaryConfusionMatrix binarizeOnTrueSet(ConfusionMatrix<CategoryType> matrix,
                                                                            Set<? super CategoryType> trueSet)
Takes a general confusion matrix and creates a binary form of it using the given set of true categories. All other categories are considered false.

Type Parameters:
CategoryType - The true category type.
Parameters:
matrix - The general confusion matrix to binarize.
trueSet - The set of categories in the true set for the binary confusion matrix.
Returns:
A new binary confusion matrix.

createFromActualPredictedPairs

public static DefaultBinaryConfusionMatrix createFromActualPredictedPairs(Collection<? extends Pair<? extends Boolean,? extends Boolean>> pairs)
Creates a new DefaultConfusionMatrix from the given actual-predicted pairs.

Parameters:
pairs - The actual-category pairs.
Returns:
A new confusion matrix populated from the given actual-category pairs.

create

public static DefaultBinaryConfusionMatrix create(Iterable<? extends TargetEstimatePair<? extends Boolean,? extends Boolean>> input)
Creates a new DefaultBinaryConfusionMatrix from the given target-estimate pairs.

Parameters:
input - The target-estimate pairs.
Returns:
A new confusion matrix populated from the given target-estimate pairs.

create

public static DefaultBinaryConfusionMatrix create(Iterable<? extends TargetEstimatePair<? extends Boolean,? extends Boolean>> input,
                                                  boolean weightIfAvailable)
Creates a new DefaultBinaryConfusionMatrix from the given target-estimate pairs.

Parameters:
input - The target-estimate pairs.
weightIfAvailable - True uses the weight of each item (or 1.0 if there is none); false means 1.0 is used regardless of weight.
Returns:
A new confusion matrix populated from the given target-estimate pairs.