Table of Contents

Class ConfusionMatrix<T>

Namespace
AiDotNet.LinearAlgebra
Assembly
AiDotNet.dll

Represents a confusion matrix for evaluating the performance of a classification model.

public class ConfusionMatrix<T> : MatrixBase<T>

Type Parameters

T

The numeric data type used for calculations (e.g., float, double).

Inheritance
MatrixBase<T>
ConfusionMatrix<T>
Inherited Members
MatrixBase<T>._memory
MatrixBase<T>._rows
MatrixBase<T>._cols
MatrixBase<T>._numOps
MatrixBase<T>.MarkDirty()
MatrixBase<T>.Empty()
MatrixBase<T>.Diagonal()
MatrixBase<T>.ElementWiseMultiplyAndSum(MatrixBase<T>)
MatrixBase<T>.Add(MatrixBase<T>)
MatrixBase<T>.AddInPlace(MatrixBase<T>)
MatrixBase<T>.Subtract(MatrixBase<T>)
MatrixBase<T>.SubtractInPlace(MatrixBase<T>)
MatrixBase<T>.Multiply(MatrixBase<T>)
MatrixBase<T>.Multiply(Vector<T>)
MatrixBase<T>.Multiply(T)
MatrixBase<T>.MultiplyInPlace(T)
MatrixBase<T>.Transpose()
MatrixBase<T>.TransposeInPlace()
MatrixBase<T>.Clone()
MatrixBase<T>.AsSpan()
MatrixBase<T>.AsMemory()
MatrixBase<T>.ToString()
MatrixBase<T>.Engine
MatrixBase<T>.Rows
MatrixBase<T>.Columns
MatrixBase<T>.IsEmpty

Remarks

A confusion matrix is a table that summarizes the prediction results of a classification model. It supports both binary classification (2x2 matrix) and multi-class classification (NxN matrix).

For Beginners: A confusion matrix helps you understand how well your AI model is performing when classifying data into categories.

Binary Classification: For 2-class problems, it shows four important numbers:

  • True PositivesWhen your model correctly predicted "Yes" (e.g., correctly identified a cat as a cat)
  • True NegativesWhen your model correctly predicted "No" (e.g., correctly identified a non-cat as not a cat)
  • False PositivesWhen your model incorrectly predicted "Yes" (e.g., identified a dog as a cat) - also called a "Type I error"
  • False NegativesWhen your model incorrectly predicted "No" (e.g., identified a cat as not a cat) - also called a "Type II error"

Multi-Class Classification: For 3+ class problems, the matrix is NxN where N is the number of classes. Rows represent predicted classes, columns represent actual classes. Cell [i,j] contains the count of samples predicted as class i but actually belonging to class j.

Constructors

ConfusionMatrix(int)

Initializes a new instance of the ConfusionMatrix<T> class with the specified dimension.

public ConfusionMatrix(int dimension)

Parameters

dimension int

The number of classes (creates a dimension x dimension matrix).

Remarks

Creates a zero-initialized NxN confusion matrix for multi-class classification. Use the Increment(int, int) method to populate the matrix as predictions are made.

For Beginners: This constructor creates an empty confusion matrix for problems with multiple classes. For example, if you're classifying images into 10 categories (0-9 digits), you would use dimension=10. The matrix starts with all zeros, and you increment cells as your model makes predictions.

Exceptions

ArgumentException

Thrown when dimension is less than 2.

ConfusionMatrix(T, T, T, T)

Initializes a new instance of the ConfusionMatrix<T> class with the specified values.

public ConfusionMatrix(T truePositives, T trueNegatives, T falsePositives, T falseNegatives)

Parameters

truePositives T

The number of true positive predictions.

trueNegatives T

The number of true negative predictions.

falsePositives T

The number of false positive predictions.

falseNegatives T

The number of false negative predictions.

Remarks

For Beginners: This constructor creates a new confusion matrix with the four basic counts that describe how well your model performed. The matrix is always 2x2 in size, representing the four possible outcomes of a binary classification.

Properties

Accuracy

Gets the accuracy of the classification model.

public T Accuracy { get; }

Property Value

T

Remarks

Accuracy is calculated as (True Positives + True Negatives) / (Total Predictions).

For Beginners: Accuracy tells you what percentage of all predictions your model got right. It's calculated by adding up all the correct predictions (both true positives and true negatives) and dividing by the total number of predictions made. A higher accuracy means your model is performing better. However, accuracy alone can be misleading if your data is imbalanced (e.g., if most of your data belongs to one class).

ClassCount

Gets the number of classes represented in the confusion matrix.

public int ClassCount { get; }

Property Value

int

Remarks

For multi-class classification, this property returns the dimension N of the NxN confusion matrix, where each class is represented by a row and a column.

For Beginners: This tells you how many categories your model is trying to predict. For example, if you are classifying images of digits (0-9), ClassCount will be 10.

F1Score

Gets the F1 score of the classification model.

public T F1Score { get; }

Property Value

T

Remarks

F1 score is calculated as 2 * (Precision * Recall) / (Precision + Recall).

For Beginners: The F1 score is a balance between precision and recall. It's useful when you need to find a middle ground between these two metrics. A high F1 score means that your model has both good precision and good recall. This is particularly useful when your data is imbalanced (when one class has many more examples than another). The F1 score ranges from 0 (worst) to 1 (best).

FalseNegatives

Gets the number of false negative predictions (incorrectly predicted negative cases).

public T FalseNegatives { get; }

Property Value

T

Remarks

For Beginners: False negatives are when your model incorrectly identified something as negative when it was actually positive. This is also called a "Type II error". For example, if your model is detecting spam emails, a false negative is when it incorrectly lets a spam email into your inbox.

FalsePositives

Gets the number of false positive predictions (incorrectly predicted positive cases).

public T FalsePositives { get; }

Property Value

T

Remarks

For Beginners: False positives are when your model incorrectly identified something as positive when it was actually negative. This is also called a "Type I error". For example, if your model is detecting spam emails, a false positive is when it incorrectly marks a legitimate email as spam.

Precision

Gets the precision of the classification model.

public T Precision { get; }

Property Value

T

Remarks

Precision is calculated as True Positives / (True Positives + False Positives).

For Beginners: Precision answers the question: "Of all the items my model predicted as positive, what percentage was actually positive?" It's a measure of how trustworthy the positive predictions are. High precision means that when your model says something is positive, it's usually correct. This is important in cases where false positives are costly (e.g., in medical diagnoses where a false positive might lead to unnecessary treatment).

Recall

Gets the recall (sensitivity) of the classification model.

public T Recall { get; }

Property Value

T

Remarks

Recall is calculated as True Positives / (True Positives + False Negatives).

For Beginners: Recall (also called sensitivity) answers the question: "Of all the items that were actually positive, what percentage did my model correctly identify as positive?" It measures how good your model is at finding all the positive cases. High recall means your model rarely misses positive cases. This is important in situations where missing a positive case is costly (e.g., in cancer detection where missing a cancer diagnosis could be life-threatening).

Specificity

Gets the specificity of the classification model.

public T Specificity { get; }

Property Value

T

Remarks

Specificity is calculated as True Negatives / (True Negatives + False Positives).

For Beginners: Specificity answers the question: "Of all the items that were actually negative, what percentage did my model correctly identify as negative?" It measures how good your model is at avoiding false alarms. High specificity means your model rarely misclassifies negative cases as positive. This is important in situations where false positives are costly (e.g., in spam detection where marking legitimate emails as spam would be problematic).

TrueNegatives

Gets the number of true negative predictions (correctly predicted negative cases).

public T TrueNegatives { get; }

Property Value

T

Remarks

For Beginners: True negatives are when your model correctly identified something as negative. For example, if your model is detecting spam emails, a true negative is when it correctly identifies a legitimate email as not spam.

TruePositives

Gets the number of true positive predictions (correctly predicted positive cases).

public T TruePositives { get; }

Property Value

T

Remarks

For Beginners: True positives are when your model correctly identified something as positive. For example, if your model is detecting spam emails, a true positive is when it correctly identifies a spam email as spam.

Methods

CreateInstance(int, int)

Creates a new instance of a matrix with the specified dimensions.

protected override MatrixBase<T> CreateInstance(int rows, int cols)

Parameters

rows int

The number of rows in the new matrix.

cols int

The number of columns in the new matrix.

Returns

MatrixBase<T>

A new matrix instance with the specified dimensions.

Remarks

This is an internal method used for matrix operations that require creating new matrices.

GetAccuracy()

Gets the overall accuracy across all classes.

public T GetAccuracy()

Returns

T

The accuracy as a value between 0 and 1.

Remarks

Accuracy is calculated as the sum of diagonal elements (correct predictions) divided by the sum of all elements (total predictions).

For Beginners: This tells you what percentage of all predictions your model got right, across all classes. An accuracy of 0.85 means your model was correct 85% of the time.

GetCohenKappa()

Gets the Cohen's Kappa coefficient, measuring inter-rater agreement.

public T GetCohenKappa()

Returns

T

The Kappa value between -1 and 1.

Remarks

Cohen's Kappa is calculated as: (observed agreement - expected agreement) / (1 - expected agreement)

For Beginners: Cohen's Kappa measures how much better your model is compared to random chance. It accounts for the possibility of agreement occurring by accident.

The Kappa value ranges from -1 to +1:

  • 1.0: Perfect agreement
  • 0.81-1.0: Almost perfect agreement
  • 0.61-0.80: Substantial agreement
  • 0.41-0.60: Moderate agreement
  • 0.21-0.40: Fair agreement
  • 0.0-0.20: Slight agreement
  • Less than 0: Less than chance agreement

Kappa is especially useful when you have imbalanced classes, as it adjusts for the expected agreement that would occur by chance.

GetF1Score(int)

Gets the F1 score for a specific class.

public T GetF1Score(int classIndex)

Parameters

classIndex int

The class index (0-based).

Returns

T

The F1 score for the specified class.

Remarks

F1 score for class i is the harmonic mean of precision and recall: 2 * (Precision * Recall) / (Precision + Recall).

For Beginners: This is a balanced measure that considers both precision and recall for this class. It's useful when you want a single metric that captures both how accurate and how complete your predictions are.

Exceptions

ArgumentOutOfRangeException

Thrown when class index is out of range.

GetFalseNegatives(int)

Gets the false negatives for a specific class.

public T GetFalseNegatives(int classIndex)

Parameters

classIndex int

The class index (0-based).

Returns

T

The number of false negatives for the specified class.

Remarks

False negatives for class i are the sum of column i excluding the diagonal element [i,i]. These are cases that were actually class i but were incorrectly predicted as other classes.

For Beginners: This tells you how many times your model missed this class by predicting something else. For example, GetFalseNegatives(5) tells you how many times the digit was actually 5, but your model predicted it as some other digit.

Exceptions

ArgumentOutOfRangeException

Thrown when class index is out of range.

GetFalsePositives(int)

Gets the false positives for a specific class.

public T GetFalsePositives(int classIndex)

Parameters

classIndex int

The class index (0-based).

Returns

T

The number of false positives for the specified class.

Remarks

False positives for class i are the sum of row i excluding the diagonal element [i,i]. These are cases incorrectly predicted as class i when they were actually other classes.

For Beginners: This tells you how many times your model incorrectly identified something as this class when it was actually a different class. For example, GetFalsePositives(5) tells you how many times your model predicted digit 5 when it was actually a different digit.

Exceptions

ArgumentOutOfRangeException

Thrown when class index is out of range.

GetHammingLoss()

Gets the Hamming Loss, measuring the fraction of incorrect predictions.

public T GetHammingLoss()

Returns

T

The Hamming Loss value between 0 and 1.

Remarks

Hamming Loss is calculated as: (number of incorrect predictions) / (total predictions)

For Beginners: Hamming Loss is simply 1 minus accuracy. It measures the fraction of labels that are incorrectly predicted. While this seems redundant with accuracy, it's the standard metric in multi-label classification where each sample can have multiple labels.

The Hamming Loss ranges from 0 to 1:

  • 0: Perfect prediction (no errors)
  • 1: Complete failure (all predictions wrong)

Lower values are better. A Hamming Loss of 0.1 means 10% of your predictions are wrong.

GetJaccardScore()

Gets the Jaccard Score (Jaccard Index) for classification.

public T GetJaccardScore()

Returns

T

The macro-averaged Jaccard Score between 0 and 1.

Remarks

Jaccard Score for each class is calculated as: TP / (TP + FP + FN) This returns the macro-averaged Jaccard Score across all classes.

For Beginners: The Jaccard Score (also known as Jaccard Index or Intersection over Union) measures the similarity between predicted and actual labels. It's the size of the intersection divided by the size of the union of the predicted and actual label sets.

The Jaccard Score ranges from 0 to 1:

  • 1: Perfect overlap (prediction exactly matches actual)
  • 0: No overlap at all

Unlike F1 Score, Jaccard Score doesn't double-count true positives, making it a more conservative measure. It's commonly used in image segmentation and multi-label classification.

GetJaccardScore(int)

Gets the Jaccard Score for a specific class.

public T GetJaccardScore(int classIndex)

Parameters

classIndex int

The class index (0-based).

Returns

T

The Jaccard Score for the specified class.

Remarks

Jaccard Score for class i is calculated as: TP / (TP + FP + FN)

For Beginners: This calculates the Jaccard Score for a single class. It measures how well your model predicts this specific class by comparing the overlap between predicted and actual instances of this class.

Exceptions

ArgumentOutOfRangeException

Thrown when class index is out of range.

GetMacroF1Score()

Gets the macro-averaged F1 score across all classes.

public T GetMacroF1Score()

Returns

T

The macro-averaged F1 score.

Remarks

Macro-average treats all classes equally by computing the metric independently for each class and then taking the average. This gives equal weight to each class regardless of support.

For Beginners: This is the average F1 score across all classes, treating each class equally. It provides a balanced view of model performance across all classes.

GetMacroPrecision()

Gets the macro-averaged precision across all classes.

public T GetMacroPrecision()

Returns

T

The macro-averaged precision.

Remarks

Macro-average treats all classes equally by computing the metric independently for each class and then taking the average. This gives equal weight to each class regardless of support.

For Beginners: This is the average precision across all classes, treating each class equally. It's useful when you care about performance on all classes equally, even rare ones.

GetMacroRecall()

Gets the macro-averaged recall across all classes.

public T GetMacroRecall()

Returns

T

The macro-averaged recall.

Remarks

Macro-average treats all classes equally by computing the metric independently for each class and then taking the average. This gives equal weight to each class regardless of support.

For Beginners: This is the average recall across all classes, treating each class equally. It tells you how good your model is at finding instances across all classes on average.

GetMatthewsCorrelationCoefficient()

Gets the Matthews Correlation Coefficient (MCC) for classification.

public T GetMatthewsCorrelationCoefficient()

Returns

T

The MCC value between -1 and 1.

Remarks

For binary classification: MCC = (TP * TN - FP * FN) / sqrt((TP+FP)(TP+FN)(TN+FP)(TN+FN))

For multi-class classification, this uses the generalized formula that operates directly on the confusion matrix: MCC = (c * s - sum(pk * tk)) / sqrt((s^2 - sum(pk^2)) * (s^2 - sum(tk^2))) where c is the trace, s is total sum, pk is row sum, and tk is column sum.

For Beginners: The Matthews Correlation Coefficient is considered one of the best metrics for classification, especially when classes are imbalanced. Unlike accuracy, it takes into account all values in the confusion matrix.

The MCC ranges from -1 to +1:

  • +1: Perfect prediction (your model is always correct)
  • 0: No better than random prediction
  • -1: Total disagreement (your model is always wrong)

MCC is particularly useful because it only produces a high score if your model performs well on all classes.

GetMicroF1Score()

Gets the micro-averaged F1 score across all classes.

public T GetMicroF1Score()

Returns

T

The micro-averaged F1 score.

Remarks

Micro-average aggregates the contributions of all classes to compute the average metric. For F1 score, this equals accuracy in multi-class classification.

For Beginners: This calculates F1 score by considering all predictions together, giving more weight to classes with more samples. For multi-class problems, this equals overall accuracy.

GetMicroPrecision()

Gets the micro-averaged precision across all classes.

public T GetMicroPrecision()

Returns

T

The micro-averaged precision.

Remarks

Micro-average aggregates the contributions of all classes to compute the average metric. For precision, this equals accuracy in multi-class classification.

For Beginners: This calculates precision by considering all predictions together, giving more weight to classes with more samples. For multi-class problems, this equals overall accuracy.

GetMicroRecall()

Gets the micro-averaged recall across all classes.

public T GetMicroRecall()

Returns

T

The micro-averaged recall.

Remarks

Micro-average aggregates the contributions of all classes to compute the average metric. For recall, this equals accuracy in multi-class classification.

For Beginners: This calculates recall by considering all predictions together, giving more weight to classes with more samples. For multi-class problems, this equals overall accuracy.

GetPrecision(int)

Gets the precision for a specific class.

public T GetPrecision(int classIndex)

Parameters

classIndex int

The class index (0-based).

Returns

T

The precision for the specified class.

Remarks

Precision for class i is calculated as TP / (TP + FP). It answers: "Of all predictions for this class, what percentage was correct?"

For Beginners: This tells you how trustworthy your model's predictions are for this specific class. High precision means when your model says something is class i, it's usually right.

Exceptions

ArgumentOutOfRangeException

Thrown when class index is out of range.

GetRecall(int)

Gets the recall for a specific class.

public T GetRecall(int classIndex)

Parameters

classIndex int

The class index (0-based).

Returns

T

The recall for the specified class.

Remarks

Recall for class i is calculated as TP / (TP + FN). It answers: "Of all actual cases of this class, what percentage did we correctly identify?"

For Beginners: This tells you how good your model is at finding all instances of this class. High recall means your model rarely misses cases of this class.

Exceptions

ArgumentOutOfRangeException

Thrown when class index is out of range.

GetTrueNegatives(int)

Gets the true negatives for a specific class.

public T GetTrueNegatives(int classIndex)

Parameters

classIndex int

The class index (0-based).

Returns

T

The number of true negatives for the specified class.

Remarks

True negatives for class i are all predictions where neither predicted nor actual was class i. This is the sum of all cells excluding row i and column i.

For Beginners: This tells you how many times your model correctly identified that something was NOT this class. For example, GetTrueNegatives(5) tells you how many times your model correctly determined that a digit was NOT 5 (it was some other digit, and the model predicted correctly).

Exceptions

ArgumentOutOfRangeException

Thrown when class index is out of range.

GetTruePositives(int)

Gets the true positives for a specific class.

public T GetTruePositives(int classIndex)

Parameters

classIndex int

The class index (0-based).

Returns

T

The number of true positives for the specified class.

Remarks

True positives for class i are the diagonal element [i,i] - cases correctly predicted as class i.

For Beginners: This tells you how many times your model correctly identified this specific class. For example, if you're classifying digits 0-9, GetTruePositives(5) tells you how many times your model correctly identified the digit 5 as 5.

Exceptions

ArgumentOutOfRangeException

Thrown when class index is out of range.

GetWeightedF1Score()

Gets the weighted-averaged F1 score across all classes.

public T GetWeightedF1Score()

Returns

T

The weighted-averaged F1 score.

Remarks

Weighted-average computes the metric for each class and averages them, weighted by the number of true instances for each class (support). This accounts for class imbalance.

For Beginners: This is like macro-average, but gives more importance to classes that appear more frequently in your data. It provides a balanced measure that accounts for class imbalance.

GetWeightedPrecision()

Gets the weighted-averaged precision across all classes.

public T GetWeightedPrecision()

Returns

T

The weighted-averaged precision.

Remarks

Weighted-average computes the metric for each class and averages them, weighted by the number of true instances for each class (support). This accounts for class imbalance.

For Beginners: This is like macro-average, but gives more importance to classes that appear more frequently in your data. It's useful when you have imbalanced classes but still want to see per-class performance weighted by how common each class is.

GetWeightedRecall()

Gets the weighted-averaged recall across all classes.

public T GetWeightedRecall()

Returns

T

The weighted-averaged recall.

Remarks

Weighted-average computes the metric for each class and averages them, weighted by the number of true instances for each class (support). This accounts for class imbalance.

For Beginners: This is like macro-average, but gives more importance to classes that appear more frequently in your data. For recall, this often equals overall accuracy.

Increment(int, int)

Increments the count for a specific prediction-actual class pair.

public void Increment(int predictedClass, int actualClass)

Parameters

predictedClass int

The predicted class index (0-based).

actualClass int

The actual class index (0-based).

Remarks

For Beginners: This method is used to build up your confusion matrix as you evaluate predictions. Each time your model makes a prediction, you call this method with what it predicted and what the true answer was. For example, if your model predicted class 2 but the actual class was 1, you call Increment(2, 1).

Exceptions

ArgumentOutOfRangeException

Thrown when class indices are out of range.

Edit this page