cnn-classifier-toolkit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. cnn_classifier/__init__.py +5 -0
  2. cnn_classifier/_version.py +1 -0
  3. cnn_classifier/cli.py +1085 -0
  4. cnn_classifier/config/__init__.py +17 -0
  5. cnn_classifier/config/loader.py +102 -0
  6. cnn_classifier/config/presets/default.yaml +47 -0
  7. cnn_classifier/config/resolve.py +108 -0
  8. cnn_classifier/config/schema.py +251 -0
  9. cnn_classifier/core/__init__.py +19 -0
  10. cnn_classifier/core/device.py +50 -0
  11. cnn_classifier/core/errors.py +21 -0
  12. cnn_classifier/core/hashing.py +18 -0
  13. cnn_classifier/core/registry.py +46 -0
  14. cnn_classifier/core/seeding.py +37 -0
  15. cnn_classifier/core/types.py +97 -0
  16. cnn_classifier/data/__init__.py +22 -0
  17. cnn_classifier/data/adapters/__init__.py +19 -0
  18. cnn_classifier/data/adapters/_common.py +241 -0
  19. cnn_classifier/data/adapters/image_folder.py +65 -0
  20. cnn_classifier/data/adapters/manifest.py +62 -0
  21. cnn_classifier/data/adapters/numpy.py +96 -0
  22. cnn_classifier/data/adapters/registry.py +29 -0
  23. cnn_classifier/data/adapters/synthetic.py +114 -0
  24. cnn_classifier/data/adapters/torchvision.py +192 -0
  25. cnn_classifier/data/base.py +17 -0
  26. cnn_classifier/data/contract.py +28 -0
  27. cnn_classifier/data/image_io.py +116 -0
  28. cnn_classifier/data/inspection.py +111 -0
  29. cnn_classifier/data/loaders.py +79 -0
  30. cnn_classifier/data/manifest.py +98 -0
  31. cnn_classifier/data/splits.py +136 -0
  32. cnn_classifier/data/stats.py +106 -0
  33. cnn_classifier/data/transforms.py +192 -0
  34. cnn_classifier/diagnostics/__init__.py +22 -0
  35. cnn_classifier/diagnostics/activations.py +56 -0
  36. cnn_classifier/diagnostics/architecture.py +172 -0
  37. cnn_classifier/diagnostics/determinism.py +25 -0
  38. cnn_classifier/diagnostics/gradients.py +32 -0
  39. cnn_classifier/diagnostics/sanity.py +49 -0
  40. cnn_classifier/diagnostics/tracing.py +56 -0
  41. cnn_classifier/evaluation/__init__.py +53 -0
  42. cnn_classifier/evaluation/bootstrap.py +96 -0
  43. cnn_classifier/evaluation/calibration.py +74 -0
  44. cnn_classifier/evaluation/compare.py +111 -0
  45. cnn_classifier/evaluation/error_analysis.py +61 -0
  46. cnn_classifier/evaluation/evaluator.py +143 -0
  47. cnn_classifier/evaluation/latency.py +58 -0
  48. cnn_classifier/evaluation/metrics.py +94 -0
  49. cnn_classifier/evaluation/predict.py +64 -0
  50. cnn_classifier/models/__init__.py +50 -0
  51. cnn_classifier/models/base.py +62 -0
  52. cnn_classifier/models/residual_cnn.py +138 -0
  53. cnn_classifier/models/simple_cnn.py +55 -0
  54. cnn_classifier/models/summary.py +39 -0
  55. cnn_classifier/models/torchvision.py +46 -0
  56. cnn_classifier/models/transfer.py +193 -0
  57. cnn_classifier/runs/__init__.py +6 -0
  58. cnn_classifier/runs/artifacts.py +50 -0
  59. cnn_classifier/runs/context.py +130 -0
  60. cnn_classifier/tracking/__init__.py +34 -0
  61. cnn_classifier/tracking/base.py +16 -0
  62. cnn_classifier/tracking/composite.py +20 -0
  63. cnn_classifier/tracking/console.py +14 -0
  64. cnn_classifier/tracking/csv.py +19 -0
  65. cnn_classifier/tracking/tensorboard.py +22 -0
  66. cnn_classifier/training/__init__.py +37 -0
  67. cnn_classifier/training/amp.py +51 -0
  68. cnn_classifier/training/callbacks.py +229 -0
  69. cnn_classifier/training/checkpoint.py +151 -0
  70. cnn_classifier/training/losses.py +67 -0
  71. cnn_classifier/training/optim.py +40 -0
  72. cnn_classifier/training/schedulers.py +53 -0
  73. cnn_classifier/training/state.py +35 -0
  74. cnn_classifier/training/trainer.py +357 -0
  75. cnn_classifier/viz/__init__.py +42 -0
  76. cnn_classifier/viz/architecture.py +276 -0
  77. cnn_classifier/viz/compare.py +36 -0
  78. cnn_classifier/viz/data.py +56 -0
  79. cnn_classifier/viz/evaluation.py +134 -0
  80. cnn_classifier/viz/features.py +122 -0
  81. cnn_classifier/viz/report.py +821 -0
  82. cnn_classifier/viz/style.py +69 -0
  83. cnn_classifier/viz/templates/report.html.j2 +355 -0
  84. cnn_classifier/viz/training.py +83 -0
  85. cnn_classifier_toolkit-0.1.0.dist-info/METADATA +249 -0
  86. cnn_classifier_toolkit-0.1.0.dist-info/RECORD +89 -0
  87. cnn_classifier_toolkit-0.1.0.dist-info/WHEEL +4 -0
  88. cnn_classifier_toolkit-0.1.0.dist-info/entry_points.txt +2 -0
  89. cnn_classifier_toolkit-0.1.0.dist-info/licenses/LICENSE +202 -0
@@ -0,0 +1,36 @@
1
+ """Multi-run comparison figures."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Sequence
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ import matplotlib.pyplot as plt
10
+
11
+ from cnn_classifier.viz.style import PALETTE, save_figure
12
+
13
+
14
+ def plot_model_comparison(rows: Sequence[dict[str, Any]], path: Path) -> Path:
15
+ valid = [row for row in rows if row.get("accuracy") is not None]
16
+ fig, axes = plt.subplots(1, 2, figsize=(12, 4.5))
17
+ for index, row in enumerate(valid):
18
+ color = PALETTE[index % len(PALETTE)]
19
+ params = row.get("params")
20
+ latency = row.get("latency_ms")
21
+ if params is not None:
22
+ axes[0].scatter(params, row["accuracy"], color=color)
23
+ axes[0].annotate(str(row.get("run", "")), (params, row["accuracy"]), fontsize=8)
24
+ if latency is not None:
25
+ axes[1].scatter(latency, row["accuracy"], color=color)
26
+ axes[1].annotate(str(row.get("run", "")), (latency, row["accuracy"]), fontsize=8)
27
+ axes[0].set_xlabel("Parameters")
28
+ axes[0].set_ylabel("Accuracy")
29
+ axes[0].set_title("Accuracy vs parameters")
30
+ axes[1].set_xlabel("Latency (ms)")
31
+ axes[1].set_ylabel("Accuracy")
32
+ axes[1].set_title("Accuracy vs latency")
33
+ fig.tight_layout()
34
+ result = save_figure(fig, path)
35
+ plt.close(fig)
36
+ return result
@@ -0,0 +1,56 @@
1
+ """Dataset-oriented figures."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping, Sequence
6
+ from pathlib import Path
7
+ from typing import cast
8
+
9
+ import matplotlib.pyplot as plt
10
+ import numpy as np
11
+ import torch
12
+
13
+ from cnn_classifier.viz.style import PALETTE, save_figure
14
+
15
+
16
+ def _as_image(tensor: torch.Tensor) -> np.ndarray:
17
+ array: np.ndarray = np.asarray(tensor.detach().cpu().numpy())
18
+ if array.ndim == 3 and array.shape[0] in (1, 3):
19
+ if array.shape[0] == 1:
20
+ return cast(np.ndarray, array[0])
21
+ return np.transpose(array, (1, 2, 0))
22
+ return array
23
+
24
+
25
+ def plot_dataset_overview(
26
+ counts: Mapping[str, int], path: Path, title: str = "Class counts"
27
+ ) -> Path:
28
+ names = list(counts)
29
+ values = [counts[name] for name in names]
30
+ fig, axis = plt.subplots(figsize=(8, 4))
31
+ axis.bar(names, values, color=PALETTE[0])
32
+ axis.set_ylabel("Samples")
33
+ axis.set_title(title)
34
+ axis.tick_params(axis="x", rotation=45)
35
+ fig.tight_layout()
36
+ result = save_figure(fig, path)
37
+ plt.close(fig)
38
+ return result
39
+
40
+
41
+ def plot_augmentation_gallery(images: Sequence[torch.Tensor], path: Path) -> Path:
42
+ count = len(images)
43
+ columns = min(4, count) or 1
44
+ rows = max(1, (count + columns - 1) // columns)
45
+ fig, axes = plt.subplots(rows, columns, figsize=(3 * columns, 3 * rows))
46
+ flat = np.asarray(axes).reshape(-1)
47
+ for index, image in enumerate(images[: len(flat)]):
48
+ flat[index].imshow(_as_image(image))
49
+ flat[index].axis("off")
50
+ for axis in flat[count:]:
51
+ axis.axis("off")
52
+ fig.suptitle("Augmentation samples")
53
+ fig.tight_layout()
54
+ result = save_figure(fig, path)
55
+ plt.close(fig)
56
+ return result
@@ -0,0 +1,134 @@
1
+ """Evaluation figures."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping, Sequence
6
+ from pathlib import Path
7
+ from typing import Any, cast
8
+
9
+ import matplotlib.pyplot as plt
10
+ import numpy as np
11
+ import torch
12
+
13
+ from cnn_classifier.viz.style import PALETTE, save_figure
14
+
15
+
16
+ def plot_confusion_matrix(
17
+ matrix: Sequence[Sequence[int]] | np.ndarray,
18
+ class_names: Sequence[str],
19
+ path: Path,
20
+ title: str = "Confusion matrix",
21
+ ) -> Path:
22
+ counts = np.asarray(matrix, dtype=np.float64)
23
+ row_sums = counts.sum(axis=1, keepdims=True)
24
+ normalized = np.divide(counts, row_sums, out=np.zeros_like(counts), where=row_sums != 0)
25
+ fig, axes = plt.subplots(1, 2, figsize=(12, 5))
26
+ for axis, data, panel_title in (
27
+ (axes[0], counts, "Counts"),
28
+ (axes[1], normalized, "Row-normalized"),
29
+ ):
30
+ image = axis.imshow(data, cmap="Blues")
31
+ axis.set_title(panel_title)
32
+ axis.set_xticks(range(len(class_names)))
33
+ axis.set_yticks(range(len(class_names)))
34
+ axis.set_xticklabels(class_names, rotation=45, ha="right")
35
+ axis.set_yticklabels(class_names)
36
+ axis.set_xlabel("Predicted")
37
+ axis.set_ylabel("True")
38
+ fig.colorbar(image, ax=axis, fraction=0.046, pad=0.04)
39
+ for row in range(data.shape[0]):
40
+ for column in range(data.shape[1]):
41
+ value = (
42
+ f"{data[row, column]:.2f}"
43
+ if data is normalized
44
+ else f"{int(data[row, column])}"
45
+ )
46
+ axis.text(column, row, value, ha="center", va="center", fontsize=8)
47
+ fig.suptitle(title)
48
+ fig.tight_layout()
49
+ result = save_figure(fig, path)
50
+ plt.close(fig)
51
+ return result
52
+
53
+
54
+ def _f1(value: Any) -> float:
55
+ if hasattr(value, "f1"):
56
+ return float(value.f1)
57
+ if isinstance(value, Mapping):
58
+ return float(value.get("f1", 0.0))
59
+ return float(value)
60
+
61
+
62
+ def plot_per_class_metrics(
63
+ per_class: Mapping[str, Any],
64
+ path: Path,
65
+ title: str = "Per-class F1",
66
+ ) -> Path:
67
+ names = list(per_class)
68
+ values = [_f1(per_class[name]) for name in names]
69
+ fig, axis = plt.subplots(figsize=(8, max(3, 0.35 * len(names) + 1)))
70
+ axis.barh(names[::-1], values[::-1], color=PALETTE[0])
71
+ axis.set_xlim(0.0, 1.0)
72
+ axis.set_xlabel("F1")
73
+ axis.set_title(title)
74
+ for index, value in enumerate(values[::-1]):
75
+ axis.text(value + 0.01, index, f"{value:.2f}", va="center", fontsize=8)
76
+ fig.tight_layout()
77
+ result = save_figure(fig, path)
78
+ plt.close(fig)
79
+ return result
80
+
81
+
82
+ def plot_calibration(report: Any, path: Path, title: str = "Calibration") -> Path:
83
+ bins = [item for item in report.bins if item.count > 0]
84
+ confidence = [item.confidence for item in bins]
85
+ accuracy = [item.accuracy for item in bins]
86
+ counts = [item.count for item in bins]
87
+ fig, axis = plt.subplots(figsize=(7, 5))
88
+ axis.plot([0, 1], [0, 1], linestyle="--", color="#888888", label="Perfect")
89
+ axis.plot(confidence, accuracy, marker="o", color=PALETTE[0], label="Model")
90
+ axis.set_xlabel("Confidence")
91
+ axis.set_ylabel("Accuracy")
92
+ axis.set_title(f"{title} (ECE={report.ece:.3f}, Brier={report.brier:.3f})")
93
+ axis.legend()
94
+ if counts:
95
+ twin = axis.twinx()
96
+ twin.bar(confidence, counts, width=0.05, alpha=0.15, color=PALETTE[1])
97
+ twin.set_ylabel("Count")
98
+ fig.tight_layout()
99
+ result = save_figure(fig, path)
100
+ plt.close(fig)
101
+ return result
102
+
103
+
104
+ def _to_image(image: torch.Tensor) -> np.ndarray:
105
+ array: np.ndarray = np.asarray(image.detach().cpu().numpy())
106
+ if array.shape[0] == 1:
107
+ return cast(np.ndarray, array[0])
108
+ return np.transpose(array, (1, 2, 0))
109
+
110
+
111
+ def plot_error_gallery(
112
+ images: torch.Tensor,
113
+ y_true: Sequence[Any],
114
+ y_pred: Sequence[Any],
115
+ path: Path,
116
+ title: str = "Misclassifications",
117
+ ) -> Path:
118
+ count = min(len(images), len(y_true), len(y_pred))
119
+ columns = min(4, count) or 1
120
+ rows = max(1, (count + columns - 1) // columns)
121
+ fig, axes = plt.subplots(rows, columns, figsize=(3.2 * columns, 3.2 * rows))
122
+ flat = np.asarray(axes).reshape(-1)
123
+ for index in range(count):
124
+ axis = flat[index]
125
+ axis.imshow(_to_image(images[index]))
126
+ axis.set_title(f"True: {y_true[index]}\nPred: {y_pred[index]}", fontsize=8)
127
+ axis.axis("off")
128
+ for axis in flat[count:]:
129
+ axis.axis("off")
130
+ fig.suptitle(title)
131
+ fig.tight_layout()
132
+ result = save_figure(fig, path)
133
+ plt.close(fig)
134
+ return result
@@ -0,0 +1,122 @@
1
+ """Filters, feature maps, and Grad-CAM."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+
7
+ import matplotlib.pyplot as plt
8
+ import numpy as np
9
+ import torch
10
+ import torch.nn.functional as functional
11
+ from torch import nn
12
+
13
+ from cnn_classifier.viz.style import save_figure
14
+
15
+
16
+ def plot_filters(filters: torch.Tensor, path: Path, max_filters: int = 32) -> Path:
17
+ array = filters.detach().cpu()
18
+ if array.ndim != 4:
19
+ raise ValueError("filters must be [N,C,H,W]")
20
+ count = min(len(array), max_filters)
21
+ columns = min(8, count)
22
+ rows = max(1, (count + columns - 1) // columns)
23
+ fig, axes = plt.subplots(rows, columns, figsize=(1.6 * columns, 1.6 * rows))
24
+ flat = np.asarray(axes).reshape(-1)
25
+ for index in range(count):
26
+ kernel = array[index].numpy()
27
+ kernel = (kernel - kernel.min()) / (kernel.max() - kernel.min() + 1e-8)
28
+ if kernel.shape[0] == 3:
29
+ flat[index].imshow(np.transpose(kernel, (1, 2, 0)))
30
+ else:
31
+ flat[index].imshow(kernel[0], cmap="gray")
32
+ flat[index].axis("off")
33
+ flat[index].set_title(f"F{index}", fontsize=7)
34
+ for axis in flat[count:]:
35
+ axis.axis("off")
36
+ fig.suptitle("First-layer filters")
37
+ fig.tight_layout()
38
+ result = save_figure(fig, path)
39
+ plt.close(fig)
40
+ return result
41
+
42
+
43
+ def plot_feature_maps(feature_maps: torch.Tensor, path: Path, max_maps: int = 16) -> Path:
44
+ array = feature_maps.detach().cpu()
45
+ if array.ndim == 4:
46
+ array = array[0]
47
+ if array.ndim != 3:
48
+ raise ValueError("feature maps must be [C,H,W] or [1,C,H,W]")
49
+ count = min(len(array), max_maps)
50
+ columns = min(8, count)
51
+ rows = max(1, (count + columns - 1) // columns)
52
+ fig, axes = plt.subplots(rows, columns, figsize=(1.6 * columns, 1.6 * rows))
53
+ flat = np.asarray(axes).reshape(-1)
54
+ for index in range(count):
55
+ flat[index].imshow(array[index].numpy(), cmap="viridis")
56
+ flat[index].axis("off")
57
+ flat[index].set_title(f"Ch {index}", fontsize=7)
58
+ for axis in flat[count:]:
59
+ axis.axis("off")
60
+ fig.suptitle("Feature maps")
61
+ fig.tight_layout()
62
+ result = save_figure(fig, path)
63
+ plt.close(fig)
64
+ return result
65
+
66
+
67
+ def compute_gradcam(model: nn.Module, image: torch.Tensor, target_class: int) -> torch.Tensor:
68
+ """Return a normalized Grad-CAM heatmap for one image."""
69
+ if image.ndim != 3:
70
+ raise ValueError("image must be [C,H,W]")
71
+ parameter = next(model.parameters(), None)
72
+ device = parameter.device if parameter is not None else torch.device("cpu")
73
+ model.eval()
74
+ target_layer = next(
75
+ (module for module in reversed(list(model.modules())) if isinstance(module, nn.Conv2d)),
76
+ None,
77
+ )
78
+ if target_layer is None:
79
+ raise ValueError("Grad-CAM requires at least one Conv2d layer")
80
+ activations: list[torch.Tensor] = []
81
+
82
+ def hook(_module: nn.Module, _inputs: tuple[torch.Tensor, ...], output: torch.Tensor) -> None:
83
+ output.retain_grad()
84
+ activations.append(output)
85
+
86
+ handle = target_layer.register_forward_hook(hook)
87
+ try:
88
+ output = model(image.unsqueeze(0).to(device))
89
+ output[0, target_class].backward()
90
+ activation = activations[0]
91
+ gradients = activation.grad
92
+ if gradients is None:
93
+ raise RuntimeError("Grad-CAM target activation has no gradient")
94
+ weights = gradients.mean(dim=(2, 3), keepdim=True)
95
+ cam = torch.relu((weights * activation).sum(dim=1, keepdim=True))
96
+ cam = functional.interpolate(
97
+ cam, size=image.shape[-2:], mode="bilinear", align_corners=False
98
+ )
99
+ cam = cam[0, 0]
100
+ cam = (cam - cam.min()) / (cam.max() - cam.min() + 1e-8)
101
+ return cam.detach().cpu()
102
+ finally:
103
+ handle.remove()
104
+
105
+
106
+ def plot_gradcam(image: torch.Tensor, cam: torch.Tensor, path: Path) -> Path:
107
+ array = image.detach().cpu().numpy()
108
+ if array.shape[0] == 1:
109
+ display = array[0]
110
+ cmap = "gray"
111
+ else:
112
+ display = np.transpose(array, (1, 2, 0))
113
+ cmap = None
114
+ fig, axis = plt.subplots(figsize=(5, 5))
115
+ axis.imshow(display, cmap=cmap)
116
+ axis.imshow(cam.detach().cpu().numpy(), cmap="viridis", alpha=0.5)
117
+ axis.axis("off")
118
+ axis.set_title("Grad-CAM")
119
+ fig.tight_layout()
120
+ result = save_figure(fig, path)
121
+ plt.close(fig)
122
+ return result