Error analysis
Inspect which classes a classifier confuses and distinguish correct predictions from false positives and false negatives.
Scikit-Learn · Function
confusion_matrix
Compute a classification confusion matrix from true and predicted labels. The result counts or normalizes observations by true and predicted class.
How it works
The function compares ground-truth labels with classifier predictions and counts each true/predicted class pairing in a square matrix. Rows represent actual classes and columns represent predicted classes; optional labels fix the class order, sample weights alter contributions, and normalize converts counts into row-wise, column-wise, or overall proportions.
Syntax
sklearn.metrics.confusion_matrix(y_true, y_pred, *, labels=None, sample_weight=None, normalize=None)Parameters
| Name | Type | Description |
|---|---|---|
y_true | array-like of shape (n_samples,) | Ground-truth target values. |
y_pred | array-like of shape (n_samples,) | Estimated targets returned by a classifier. |
labels | array-like of shape (n_classes,), default=None | Labels used to index the matrix; if omitted, labels are inferred from the observed values. |
sample_weight | array-like of shape (n_samples,), default=None | Per-sample weights used when accumulating matrix entries. |
normalize | {'true', 'pred', 'all'}, default=None | Normalization mode: true for rows, pred for columns, all for the full population, or None for counts. |
Returns
C, ndarray of shape (n_classes, n_classes): confusion matrix indexed by true class rows and predicted class columns.
Key points
- Use the function to summarize classification predictions and inspect where errors occur.
- Rows index known classes and columns index predicted classes, so each cell describes one true/predicted pairing.
- For binary labels ordered 0 and 1, the four cells map directly to true negatives, false negatives, true positives, and false positives.
- Normalization can produce per-true-class, per-predicted-class, or whole-dataset proportions.
- The result is a square NumPy array, with one row and column for each indexed class.
Common mistakes
- The default returns counts; choose a normalization mode explicitly when proportions are required.
- Pass labels when you need a specific class order or need classes represented consistently across evaluations.
Example: Compute a confusion matrix
from sklearn.metrics import confusion_matrix
y_true = ["cat", "dog", "cat", "cat"]
y_pred = ["cat", "cat", "dog", "cat"]
cm = confusion_matrix(y_true, y_pred, labels=["cat", "dog"])
print(cm.tolist())
# [[2, 1], [1, 0]]This computes a matrix whose rows follow the supplied label order for true classes and whose columns represent predicted classes.
When to use it
Per-class evaluation
Compare class-wise performance when classes have different numbers of observations.
Consistent reporting
Create stable matrices across runs by explicitly controlling class order with labels.
Interview questions
QWhat does each cell of the returned matrix represent?
It returns an array with shape (n_classes, n_classes). Entry (i, j) counts samples whose true label is class i and predicted label is class j.
Follow-up: How are binary outcomes located? The diagonal contains correct predictions; with labels ordered as 0 then 1, true negatives are (0, 0) and true positives (1, 1), while the off-diagonal cells are false negatives and false positives.
QHow does the normalize argument work?
normalize="true" normalizes over rows, normalize="pred" over columns, and normalize="all" over the entire population. With None, the function leaves the matrix as counts.
Follow-up: Which mode is useful for comparing recall across classes? normalize="true", because each true-class row is scaled relative to that class's samples.
QWhat inputs does the function require?
y_true contains the correct target values and y_pred contains the classifier's estimated targets. Both describe the same samples, so corresponding positions are compared.
Follow-up: How can weighted observations be included? Supply sample_weight; each sample contributes according to its associated weight rather than uniformly.
Related
ConfusionMatrixDisplayconfusion_matrix_at_thresholds