spec: add confusion-matrix specification (#2277)

## New Specification: `confusion-matrix`

Related to #2272

---

### specification.md

# confusion-matrix: Confusion Matrix Heatmap

## Description

A specialized heatmap visualization for evaluating classification model
performance, displaying the counts or proportions of predicted vs actual
class labels. The confusion matrix reveals true positives, false
positives, true negatives, and false negatives at a glance, making it
essential for understanding model behavior, identifying class
imbalances, and diagnosing specific misclassification patterns.

## Applications

- Binary classification model evaluation showing sensitivity and
specificity
- Multi-class classifier performance analysis with per-class accuracy
breakdown
- Model comparison to identify which classes are most often confused
- Error analysis to understand systematic misclassification patterns

## Data

- `true_labels` (categorical) - ground truth class labels for each
sample
- `predicted_labels` (categorical) - model-predicted class labels for
each sample
- `class_names` (string) - display names for each class on the axes
- Size: 2-20 classes (larger matrices may have readability issues)
- Example: Classification results from a trained model on test data

## Notes

- Label axes clearly: "True Label" (y-axis) and "Predicted Label"
(x-axis)
- Annotate cells with counts or percentages for precise interpretation
- Support normalization options: none (raw counts), by row (recall), by
column (precision), or by total
- Use sequential colormap (e.g., Blues) for count data
- Include colorbar showing the value scale
- Consider highlighting diagonal (correct predictions) for visual
clarity

---

**Next:** Add `approved` label to the issue to merge this PR.

---
:robot: *[spec-create
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/20526498624)*

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/confusion-matrix/specification.md

@@ -0,0 +1,29 @@
+# confusion-matrix: Confusion Matrix Heatmap
+
+## Description
+
+A specialized heatmap visualization for evaluating classification model performance, displaying the counts or proportions of predicted vs actual class labels. The confusion matrix reveals true positives, false positives, true negatives, and false negatives at a glance, making it essential for understanding model behavior, identifying class imbalances, and diagnosing specific misclassification patterns.
+
+## Applications
+
+- Binary classification model evaluation showing sensitivity and specificity
+- Multi-class classifier performance analysis with per-class accuracy breakdown
+- Model comparison to identify which classes are most often confused
+- Error analysis to understand systematic misclassification patterns
+
+## Data
+
+- `true_labels` (categorical) - ground truth class labels for each sample
+- `predicted_labels` (categorical) - model-predicted class labels for each sample
+- `class_names` (string) - display names for each class on the axes
+- Size: 2-20 classes (larger matrices may have readability issues)
+- Example: Classification results from a trained model on test data
+
+## Notes
+
+- Label axes clearly: "True Label" (y-axis) and "Predicted Label" (x-axis)
+- Annotate cells with counts or percentages for precise interpretation
+- Support normalization options: none (raw counts), by row (recall), by column (precision), or by total
+- Use sequential colormap (e.g., Blues) for count data
+- Include colorbar showing the value scale
+- Consider highlighting diagonal (correct predictions) for visual clarity

plots/confusion-matrix/specification.yaml

@@ -0,0 +1,30 @@
+# Specification-level metadata for confusion-matrix
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: confusion-matrix
+title: Confusion Matrix Heatmap
+
+# Specification tracking
+created: 2025-12-26T17:27:45Z
+updated: null
+issue: 2272
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/concepts/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - heatmap
+    - matrix
+    - confusion-matrix
+  data_type:
+    - categorical
+    - classification
+  domain:
+    - machine-learning
+    - statistics
+    - data-science
+  features:
+    - annotated
+    - evaluation
+    - model-performance