Struct ConfusionMatrix

pub struct ConfusionMatrix { /* private fields */ }

A confusion matrix is used to record pairs of (actual class, predicted class) as typically produced by a classification algorithm.

It is designed to be called incrementally, as results are obtained from the classifier model. Class labels currently must be strings.

At any point, statistics may be obtained by calling the relevant methods.

A two-class example is:

    Predicted       Predicted     | 
    Positive        Negative      | Actual
    ------------------------------+------------
        a               b         | Positive
        c               d         | Negative

Here:

• a is the number of true positives (those labelled positive and classified positive)
• b is the number of false negatives (those labelled positive but classified negative)
• c is the number of false positives (those labelled negative but classified positive)
• d is the number of true negatives (those labelled negative and classified negative)

From this table, we can calculate statistics like:

• true_positive_rate = a/(a+b)
• positive recall = a/(a+c)

The implementation supports confusion matrices with more than two classes, and hence most statistics are calculated with reference to a named class. When more than two classes are in use, the statistics are calculated as if the named class were positive and all the other classes are grouped as if negative.

For example, in a three-class example:

Predicted       Predicted     Predicted     | 
   Red            Blue          Green       | Actual
--------------------------------------------+------------
    a               b             c         | Red
    d               e             f         | Blue
    g               h             i         | Green

We can calculate:

• true_red_rate = a/(a+b+c)
• red recall = a/(a+d+g)

Example

The following example creates a simple two-class confusion matrix, prints a few statistics and displays the table.

use confusion_matrix;
 
fn main() {
    let mut cm = confusion_matrix::new();
 
    cm[("pos", "pos")] = 10;
    cm[("pos", "neg")] = 3;
    cm[("neg", "neg")] = 20;
    cm[("neg", "pos")] = 5;
     
    println!("Precision: {}", cm.precision("pos"));
    println!("Recall: {}", cm.recall("pos"));
    println!("MCC: {}", cm.matthews_correlation("pos"));
    println!("");
    println!("{}", cm);
}

Output:

Precision: 0.7692307692307693
Recall: 0.6666666666666666
MCC: 0.5524850114241865
 
Predicted |
neg pos   | Actual
----------+-------
 20   3   | neg
  5  10   | pos

Implementations

impl ConfusionMatrix

pub fn add_for(&mut self, actual: &str, prediction: &str)

Adds one result to the matrix.

• actual - the actual class of the instance, which we are hoping the classifier will predict.
• prediction - the predicted class for the instance, as output from the classifier.

Example

The following table can be made as:

    Predicted       Predicted     | 
    Positive        Negative      | Actual
    ------------------------------+------------
        2               5         | Positive
        1               3         | Negative

let mut cm = confusion_matrix::new();
for _ in 0..2 { cm.add_for("positive", "positive"); }
for _ in 0..5 { cm.add_for("positive", "negative"); }
for _ in 0..1 { cm.add_for("negative", "positive"); }
for _ in 0..3 { cm.add_for("negative", "negative"); }

pub fn count_for(&self, actual: &str, prediction: &str) -> usize

Returns the count for an (actual, prediction) pair, or 0 if the pair is not known.

• actual - the actual class of the instance, which we are hoping the classifier will predict.
• prediction - the predicted class for the instance, as output from the classifier.

Example

(using cm from Self::add_for())

assert_eq!(2, cm.count_for("positive", "positive"));
assert_eq!(0, cm.count_for("positive", "not_known"));

pub fn false_negative(&self, label: &str) -> usize

Returns the number of instances of the given class label which are incorrectly classified.

• label - the class label to treat as “positive”.

Example

(using cm from Self::add_for())

assert_eq!(5, cm.false_negative("positive"));
assert_eq!(1, cm.false_negative("negative"));

pub fn false_positive(&self, label: &str) -> usize

Returns the number of incorrectly classified instances with the given class label.

• label - the class label to treat as “positive”.

Example

(using cm from Self::add_for())

assert_eq!(1, cm.false_positive("positive"));
assert_eq!(5, cm.false_positive("negative"));

pub fn false_rate(&self, label: &str) -> f64

Returns the proportion of instances of the given class label which are incorrectly classified out of all those instances not originally of that label.

• label - the class label to treat as “positive”.

Example

(using cm from Self::add_for())

assert!((cm.false_rate("positive") - 1.0/4.0).abs() < 0.001); // true_rate("positive") = 1/(1+3)
assert!((cm.false_rate("negative") - 5.0/7.0).abs() < 0.001); // true_rate("negative") = 5/(5+2)

pub fn f_measure(&self, label: &str) -> f64

Returns the F-measure for a given class label, which is the harmonic mean of the precision and recall for that label.

• label - the class label to treat as “positive”.

pub fn geometric_mean(&self) -> f64

Returns the geometric mean of the true rates for each class label.

pub fn kappa(&self, label: &str) -> f64

Returns Cohen’s Kappa Statistic, which is a measure of the quality of binary classification.

• label - the class label to treat as “positive”.

pub fn labels(&self) -> Vec<String>

Returns a sorted vector of the class labels contained in the matrix.

Example

(using cm from Self::add_for())

assert_eq!(vec!["negative", "positive"], cm.labels());

pub fn matthews_correlation(&self, label: &str) -> f64

Returns the Matthews Correlation Coefficient, which is a measure of the quality of binary classification.

• label - the class label to treat as “positive”.

pub fn overall_accuracy(&self) -> f64

Returns the proportion of instances which are correctly labelled.

Example

(using cm from Self::add_for())

assert!((cm.overall_accuracy() - (2.0+3.0)/11.0) < 0.001); // overall_accuracy() = (2+3)/(2+5+1+3)

pub fn precision(&self, label: &str) -> f64

Returns the proportion of instances classified as the given class label which are correct.

• label - the class label to treat as “positive”.

Example

(using cm from Self::add_for())

assert!((cm.precision("positive") - 2.0/3.0) < 0.001); // precision("positive") = 2/(2+1)

pub fn prevalence(&self, label: &str) -> f64

Returns the proportion of instances of the given label, out of the total.

• label - the class label to treat as “positive”.

Example

(using cm from Self::add_for())

assert!((cm.prevalence("positive") - 7.0/11.0).abs() < 0.001); // prevalence = (2+5)/(2+5+1+3)

pub fn recall(&self, label: &str) -> f64

Recall is another name for the true positive rate for that label.

• label - the class label to treat as “positive”.

pub fn sensitivity(&self, label: &str) -> f64

Sensitivity is another name for the true positive rate (recall) for that label.

• label - the class label to treat as “positive”.

pub fn specificity(&self, label: &str) -> f64

Returns 1 - false_rate(label)

• label - the class label to treat as “positive”.

pub fn total(&self) -> usize

Returns the total number of instances referenced in the matrix.

Example

(using cm from Self::add_for())

assert_eq!(11, cm.total());

pub fn true_negative(&self, label: &str) -> usize

Returns the number of instances NOT of the given class label which are correctly classified.

• label - the class label to treat as “positive”.

Example

(using cm from Self::add_for())

assert_eq!(3, cm.true_negative("positive"));
assert_eq!(2, cm.true_negative("negative"));

pub fn true_positive(&self, label: &str) -> usize

Returns the number of instances of the given class label which are correctly classified.

• label - the class label to treat as “positive”.

Example

(using cm from Self::add_for())

assert_eq!(2, cm.true_positive("positive"));
assert_eq!(3, cm.true_positive("negative"));

pub fn true_rate(&self, label: &str) -> f64

Returns the proportion of instances of the given class label which are correctly classified.

• label - the class label to treat as “positive”.

Example

(using cm from Self::add_for())

assert!((cm.true_rate("positive") - 2.0/7.0) < 0.001); // true_rate("positive") = 2/(2+5)
assert!((cm.true_rate("negative") - 3.0/4.0) < 0.001); // true_rate("negative") = 3/(1+3)

Trait Implementations

impl Clone for ConfusionMatrix

fn clone(&self) -> ConfusionMatrix

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ConfusionMatrix

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ConfusionMatrix

fn default() -> ConfusionMatrix

Returns the “default value” for a type.

impl Display for ConfusionMatrix

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Index<(&str, &str)> for ConfusionMatrix

fn index(&self, (actual, prediction): (&str, &str)) -> &usize

Returns the count for an (actual, prediction) pair, or 0 if the pair is not known.

• actual - the actual class of the instance, which we are hoping the classifier will predict.
• prediction - the predicted class for the instance, as output from the classifier.

Example

(using cm from Self::add_for())

assert_eq!(2, cm[("positive", "positive")]);
assert_eq!(0, cm[("positive", "not_known")]);

type Output = usize

The returned type after indexing.

impl IndexMut<(&str, &str)> for ConfusionMatrix

fn index_mut(&mut self, (actual, prediction): (&str, &str)) -> &mut usize

Provides a mutable reference to the count for an (actual, prediction) pair.

• actual - the actual class of the instance, which we are hoping the classifier will predict.
• prediction - the predicted class for the instance, as output from the classifier.

Example

let mut cm = confusion_matrix::new();
for _ in 0..2 { cm[("positive", "positive")] += 1; }
cm[("positive", "negative")] = 5;
cm[("negative", "positive")] = 1;
for _ in 0..3 { cm[("negative", "negative")] += 1; }
assert_eq!(2, cm[("positive", "positive")]);
assert_eq!(5, cm[("positive", "negative")]);
assert_eq!(0, cm[("positive", "not_known")]);

impl PartialEq for ConfusionMatrix

fn eq(&self, other: &ConfusionMatrix) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for ConfusionMatrix

impl StructuralPartialEq for ConfusionMatrix