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

cnn_classifier/data/manifest.py

@@ -0,0 +1,98 @@
+"""CSV manifest parsing and deterministic dataset fingerprints."""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from cnn_classifier.core.errors import DataError
+from cnn_classifier.core.hashing import stable_hash
+from cnn_classifier.core.types import SampleRecord
+
+SplitName = Literal["train", "val", "test"]
+_REQUIRED_COLUMNS = ("path", "label", "split")
+
+
+@dataclass(frozen=True)
+class Manifest:
+    records: tuple[SampleRecord, ...]
+
+    @property
+    def class_names(self) -> tuple[str, ...]:
+        return tuple(sorted({record.label for record in self.records}))
+
+    @classmethod
+    def from_csv(
+        cls,
+        path: Path,
+        image_root: Path,
+        columns: dict[str, str],
+    ) -> Manifest:
+        """Read a CSV manifest and validate every referenced image path."""
+        for logical in _REQUIRED_COLUMNS:
+            if logical not in columns:
+                raise DataError(f"manifest columns must include {logical!r}")
+        records: list[SampleRecord] = []
+        try:
+            handle = path.open("r", encoding="utf-8", newline="")
+        except OSError as exc:
+            raise DataError(f"cannot read manifest {path}: {exc}") from exc
+        with handle:
+            reader = csv.DictReader(handle)
+            for row_number, row in enumerate(reader, start=2):
+                raw_path = row.get(columns["path"], "").strip()
+                label = row.get(columns["label"], "").strip()
+                split = row.get(columns["split"], "").strip()
+                if not raw_path or not label:
+                    raise DataError(f"manifest row {row_number} is missing path or label")
+                if split not in {"train", "val", "test"}:
+                    raise DataError(f"manifest row {row_number} has invalid split {split!r}")
+                image_path = Path(raw_path)
+                if not image_path.is_absolute():
+                    image_path = image_root / image_path
+                if not image_path.is_file():
+                    raise DataError(
+                        f"manifest row {row_number} references missing file {image_path}"
+                    )
+                group = None
+                if "group" in columns:
+                    group = row.get(columns["group"], "").strip() or None
+                severity = None
+                if "severity" in columns:
+                    raw_severity = row.get(columns["severity"], "").strip()
+                    if raw_severity:
+                        try:
+                            severity = float(raw_severity)
+                        except ValueError as exc:
+                            raise DataError(
+                                f"manifest row {row_number} has invalid severity {raw_severity!r}"
+                            ) from exc
+                records.append(
+                    SampleRecord(
+                        path=image_path,
+                        label=label,
+                        split=split,  # type: ignore[arg-type]
+                        group=group,
+                        severity=severity,
+                    )
+                )
+        if not records:
+            raise DataError(f"manifest {path} contains no records")
+        return cls(records=tuple(records))
+
+
+def fingerprint_records(records: tuple[SampleRecord, ...]) -> str:
+    """Return a deterministic fingerprint independent of manifest row order."""
+    payload = [
+        {
+            "path": str(record.path),
+            "label": record.label,
+            "split": record.split,
+            "group": record.group,
+            "severity": record.severity,
+        }
+        for record in sorted(records, key=lambda item: str(item.path))
+    ]
+    return stable_hash(payload)

cnn_classifier/data/splits.py

@@ -0,0 +1,136 @@
+"""Deterministic split policies and group-leakage checks."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from cnn_classifier.core.errors import DataError
+from cnn_classifier.core.types import SplitInfo
+
+
+@dataclass(frozen=True)
+class SplitIndices:
+    train_indices: tuple[int, ...]
+    val_indices: tuple[int, ...]
+    test_indices: tuple[int, ...] | None = None
+
+
+def _validate_fraction(val_fraction: float) -> None:
+    if not 0.0 < val_fraction < 1.0:
+        raise DataError("val_fraction must be in (0, 1)")
+
+
+def random_split_indices(
+    labels: Sequence[Any],
+    val_fraction: float,
+    seed: int,
+) -> SplitIndices:
+    """Split indices with a seeded permutation, without stratification."""
+    _validate_fraction(val_fraction)
+    count = len(labels)
+    if count < 2:
+        return SplitIndices(tuple(range(count)), ())
+    rng = np.random.default_rng(seed)
+    order = rng.permutation(count).tolist()
+    val_count = min(count - 1, max(1, round(count * val_fraction)))
+    val = tuple(sorted(order[:val_count]))
+    train = tuple(sorted(order[val_count:]))
+    return SplitIndices(train_indices=train, val_indices=val)
+
+
+def stratified_split_indices(
+    labels: Sequence[Any],
+    val_fraction: float,
+    seed: int,
+) -> SplitIndices:
+    """Split each class proportionally, then combine the class splits."""
+    _validate_fraction(val_fraction)
+    by_class: dict[Any, list[int]] = defaultdict(list)
+    for index, label in enumerate(labels):
+        by_class[label].append(index)
+    rng = np.random.default_rng(seed)
+    train: list[int] = []
+    val: list[int] = []
+    for label in sorted(by_class):
+        indices = np.array(by_class[label])
+        order = rng.permutation(len(indices))
+        shuffled = indices[order].tolist()
+        val_count = min(len(shuffled) - 1, max(1, round(len(shuffled) * val_fraction)))
+        if len(shuffled) == 1:
+            val_count = 0
+        val.extend(shuffled[:val_count])
+        train.extend(shuffled[val_count:])
+    return SplitIndices(tuple(sorted(train)), tuple(sorted(val)))
+
+
+def group_split_indices(
+    groups: Sequence[str],
+    val_fraction: float,
+    seed: int,
+) -> SplitIndices:
+    """Assign whole groups to train or validation, never splitting a group."""
+    _validate_fraction(val_fraction)
+    group_to_indices: dict[str, list[int]] = defaultdict(list)
+    for index, group in enumerate(groups):
+        group_to_indices[group].append(index)
+    unique_groups = sorted(group_to_indices)
+    if len(unique_groups) < 2:
+        raise DataError("group split requires at least two groups")
+    rng = np.random.default_rng(seed)
+    order = rng.permutation(len(unique_groups)).tolist()
+    target = round(len(groups) * val_fraction)
+    val_groups: list[str] = []
+    val_count = 0
+    for position in order:
+        if val_count >= target and val_groups:
+            break
+        if len(val_groups) >= len(unique_groups) - 1:
+            break
+        group = unique_groups[position]
+        val_groups.append(group)
+        val_count += len(group_to_indices[group])
+    val_group_set = set(val_groups)
+    train_indices: list[int] = []
+    val_indices: list[int] = []
+    for group in unique_groups:
+        target_list = val_indices if group in val_group_set else train_indices
+        target_list.extend(group_to_indices[group])
+    return SplitIndices(tuple(sorted(train_indices)), tuple(sorted(val_indices)))
+
+
+def assert_no_group_overlap(split: SplitIndices, groups: Sequence[str]) -> None:
+    """Raise when a group appears in more than one split."""
+    members = {
+        "train": {groups[index] for index in split.train_indices},
+        "val": {groups[index] for index in split.val_indices},
+        "test": {groups[index] for index in (split.test_indices or ())},
+    }
+    for left, right in (("train", "val"), ("train", "test"), ("val", "test")):
+        overlap = members[left] & members[right]
+        if overlap:
+            raise DataError(f"groups leak across {left}/{right}: {sorted(overlap)}")
+
+
+def make_split_info(
+    split: SplitIndices,
+    *,
+    mode: str,
+    seed: int,
+    group_column: str | None,
+    fingerprint: str,
+) -> SplitInfo:
+    """Package a split for the dataset bundle."""
+    return SplitInfo(
+        mode=mode,  # type: ignore[arg-type]
+        train_indices=split.train_indices,
+        val_indices=split.val_indices,
+        test_indices=split.test_indices,
+        seed=seed,
+        group_column=group_column,
+        fingerprint=fingerprint,
+    )

cnn_classifier/data/stats.py

@@ -0,0 +1,106 @@
+"""Channel normalization statistics with caching helpers."""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import torch
+from torch.utils.data import DataLoader, Dataset
+
+from cnn_classifier.core.errors import DataError
+from cnn_classifier.core.hashing import stable_hash
+from cnn_classifier.core.types import NormalizationStats
+
+
+def _as_batch(images: torch.Tensor) -> torch.Tensor:
+    if images.ndim == 3:
+        return images.unsqueeze(0)
+    if images.ndim != 4:
+        raise DataError(f"normalization expects [C,H,W] or [B,C,H,W]; got {tuple(images.shape)}")
+    return images
+
+
+def compute_normalization(
+    dataset: Dataset[Any],
+    batch_size: int = 256,
+) -> NormalizationStats:
+    """Compute per-channel mean and standard deviation over a dataset.
+
+    Accumulation is in float64. A constant channel gets a standard deviation of
+    1.0 so downstream normalization never divides by zero.
+    """
+    if len(dataset) == 0:  # type: ignore[arg-type]
+        raise DataError("cannot compute normalization for an empty dataset")
+    loader = DataLoader(dataset, batch_size=batch_size, shuffle=False, num_workers=0)
+    sums: torch.Tensor | None = None
+    squares: torch.Tensor | None = None
+    count = 0
+    for item in loader:
+        images = item[0] if isinstance(item, (tuple, list)) else item
+        batch = _as_batch(images).to(torch.float64)
+        if sums is None:
+            sums = torch.zeros(batch.shape[1], dtype=torch.float64)
+            squares = torch.zeros(batch.shape[1], dtype=torch.float64)
+        assert sums is not None and squares is not None
+        sums += batch.sum(dim=(0, 2, 3))
+        squares += (batch * batch).sum(dim=(0, 2, 3))
+        count += batch.shape[0] * batch.shape[2] * batch.shape[3]
+    if sums is None or squares is None or count == 0:
+        raise DataError("dataset produced no samples for normalization")
+    mean = sums / count
+    variance = (squares / count) - (mean * mean)
+    std = torch.sqrt(torch.clamp(variance, min=0.0))
+    std = torch.where(std == 0, torch.ones_like(std), std)
+    return NormalizationStats(
+        mean=tuple(float(value) for value in mean.tolist()),
+        std=tuple(float(value) for value in std.tolist()),
+        source="computed",
+    )
+
+
+def save_normalization(stats: NormalizationStats, path: Path) -> None:
+    """Write normalization statistics as deterministic JSON."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"mean": list(stats.mean), "std": list(stats.std), "source": stats.source}
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def load_normalization(path: Path) -> NormalizationStats:
+    """Load normalization statistics written by :func:`save_normalization`."""
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        mean = tuple(float(value) for value in payload["mean"])
+        std = tuple(float(value) for value in payload["std"])
+        source = str(payload["source"])
+    except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+        raise DataError(f"cannot load normalization {path}: {exc}") from exc
+    if not all(math.isfinite(value) for value in (*mean, *std)):
+        raise DataError(f"normalization {path} contains non-finite values")
+    return NormalizationStats(mean=mean, std=std, source=source)  # type: ignore[arg-type]
+
+
+def normalization_cache_key(
+    dataset_fingerprint: str,
+    image_size: tuple[int, int],
+    channels: str,
+    value_range: Mapping[str, Any] | Any,
+) -> str:
+    """Return a stable cache key for a normalization computation."""
+    if hasattr(value_range, "model_dump"):
+        policy = value_range.model_dump()
+    elif isinstance(value_range, Mapping):
+        policy = dict(value_range)
+    else:
+        policy = str(value_range)
+    return stable_hash(
+        {
+            "fingerprint": dataset_fingerprint,
+            "image_size": list(image_size),
+            "channels": channels,
+            "value_range": policy,
+        }
+    )

cnn_classifier/data/transforms.py

@@ -0,0 +1,192 @@
+"""Declarative torchvision v2 transform construction."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import numpy as np
+import torch
+from PIL import Image
+from torchvision.transforms import v2
+
+from cnn_classifier.config.schema import DataConfig, TransformConfig
+from cnn_classifier.core.errors import ConfigError
+from cnn_classifier.core.registry import Registry
+from cnn_classifier.core.types import NormalizationStats
+
+Transform = Callable[[Any], torch.Tensor]
+TransformFactory = Callable[[TransformConfig, NormalizationStats | None], Callable[[Any], Any]]
+TRANSFORMS: Registry[TransformFactory] = Registry("transform")
+
+
+class EnsureTensor:
+    """Convert PIL/NumPy input to a float32 tensor, leaving tensors untouched."""
+
+    def __call__(self, value: Any) -> torch.Tensor:
+        if torch.is_tensor(value):
+            return value.to(torch.float32)
+        if isinstance(value, (Image.Image, np.ndarray)):
+            image = v2.functional.to_image(value)
+            return v2.functional.to_dtype(image, dtype=torch.float32, scale=True)
+        raise ConfigError(f"unsupported image type: {type(value).__name__}")
+
+
+def _normalize_pair(
+    spec: TransformConfig,
+    normalization: NormalizationStats | None,
+) -> tuple[tuple[float, ...], tuple[float, ...]]:
+    params = spec.params()
+    mean = params.get("mean", "auto")
+    std = params.get("std", "auto")
+    if mean == "auto" or std == "auto":
+        if normalization is None:
+            raise ConfigError(
+                f"transform {spec.name!r} needs normalization statistics; "
+                "set data.normalization.mode=supplied or add a compute pipeline"
+            )
+        return normalization.mean, normalization.std
+    if not isinstance(mean, (list, tuple)) or not isinstance(std, (list, tuple)):
+        raise ConfigError("Normalize mean/std must be lists/tuples or 'auto'")
+    return tuple(float(value) for value in mean), tuple(float(value) for value in std)
+
+
+def _resize(spec: TransformConfig, _: NormalizationStats | None) -> Callable[[Any], Any]:
+    params = spec.params()
+    return v2.Resize(params.get("size"), antialias=True)
+
+
+def _random_crop(spec: TransformConfig, _: NormalizationStats | None) -> Callable[[Any], Any]:
+    params = spec.params()
+    return v2.RandomCrop(params.get("size"), padding=params.get("padding", 0))
+
+
+def _random_resized_crop(
+    spec: TransformConfig, _: NormalizationStats | None
+) -> Callable[[Any], Any]:
+    params = spec.params()
+    return v2.RandomResizedCrop(
+        params.get("size"),
+        scale=tuple(params.get("scale", (0.08, 1.0))),
+        ratio=tuple(params.get("ratio", (0.75, 1.3333333333333333))),
+        antialias=True,
+    )
+
+
+def _color_jitter(spec: TransformConfig, _: NormalizationStats | None) -> Callable[[Any], Any]:
+    params = spec.params()
+    return v2.ColorJitter(
+        brightness=params.get("brightness", 0.0),
+        contrast=params.get("contrast", 0.0),
+        saturation=params.get("saturation", 0.0),
+        hue=params.get("hue", 0.0),
+    )
+
+
+def _gaussian_blur(spec: TransformConfig, _: NormalizationStats | None) -> Callable[[Any], Any]:
+    params = spec.params()
+    return v2.GaussianBlur(
+        kernel_size=params.get("kernel_size", 3), sigma=params.get("sigma", (0.1, 2.0))
+    )
+
+
+def _rand_augment(spec: TransformConfig, _: NormalizationStats | None) -> Callable[[Any], Any]:
+    params = spec.params()
+    return v2.RandAugment(
+        num_ops=params.get("num_ops", 2),
+        magnitude=params.get("magnitude", 9),
+        num_magnitude_bins=params.get("num_magnitude_bins", 31),
+    )
+
+
+def _auto_augment(spec: TransformConfig, _: NormalizationStats | None) -> Callable[[Any], Any]:
+    params = spec.params()
+    policy_name = str(params.get("policy", "imagenet")).lower()
+    policies = {
+        "imagenet": v2.AutoAugmentPolicy.IMAGENET,
+        "cifar10": v2.AutoAugmentPolicy.CIFAR10,
+        "svhn": v2.AutoAugmentPolicy.SVHN,
+    }
+    if policy_name not in policies:
+        raise ConfigError(f"unknown AutoAugment policy {policy_name!r}")
+    return v2.AutoAugment(policy=policies[policy_name])
+
+
+def _random_erasing(spec: TransformConfig, _: NormalizationStats | None) -> Callable[[Any], Any]:
+    params = spec.params()
+    return v2.RandomErasing(
+        p=params.get("p", 0.5),
+        scale=tuple(params.get("scale", (0.02, 0.33))),
+        ratio=tuple(params.get("ratio", (0.3, 3.3))),
+    )
+
+
+def _normalize(
+    spec: TransformConfig, normalization: NormalizationStats | None
+) -> Callable[[Any], Any]:
+    mean, std = _normalize_pair(spec, normalization)
+    return v2.Normalize(mean=mean, std=std)
+
+
+_BUILTINS: dict[str, TransformFactory] = {
+    "resize": _resize,
+    "randomcrop": _random_crop,
+    "randomresizedcrop": _random_resized_crop,
+    "colorjitter": _color_jitter,
+    "gaussianblur": _gaussian_blur,
+    "randaugment": _rand_augment,
+    "autoaugment": _auto_augment,
+    "random erasing": _random_erasing,
+    "random_erasing": _random_erasing,
+    "randomerasing": _random_erasing,
+    "normalize": _normalize,
+}
+
+
+def register_transform(name: str) -> Callable[[TransformFactory], TransformFactory]:
+    """Register a custom transform factory."""
+    return TRANSFORMS.register(name)
+
+
+def _factory_for(name: str) -> TransformFactory:
+    lowered = name.lower()
+    if lowered == "totensor":
+        return lambda _spec, _norm: EnsureTensor()
+    if lowered == "randomhorizontalflip":
+        return lambda spec, _norm: v2.RandomHorizontalFlip(p=spec.params().get("p", 0.5))
+    if lowered == "randomverticalflip":
+        return lambda spec, _norm: v2.RandomVerticalFlip(p=spec.params().get("p", 0.5))
+    if lowered == "randomrotation":
+        return lambda spec, _norm: v2.RandomRotation(spec.params().get("degrees", 10))
+    if lowered == "centercrop":
+        return lambda spec, _norm: v2.CenterCrop(spec.params().get("size"))
+    if lowered == "grayscale":
+        return lambda spec, _norm: v2.Grayscale(
+            num_output_channels=spec.params().get("num_output_channels", 1)
+        )
+    if lowered in _BUILTINS:
+        return _BUILTINS[lowered]
+    try:
+        return TRANSFORMS.get(name)
+    except Exception as exc:
+        raise ConfigError(f"unknown transform {name!r}") from exc
+
+
+def build_transforms(
+    config: DataConfig,
+    normalization: NormalizationStats | None,
+    train: bool,
+) -> Transform:
+    """Build the train or evaluation transform pipeline."""
+    specs = config.transforms["train" if train else "eval"]
+    operations: list[Callable[[Any], Any]] = [EnsureTensor()]
+    for spec in specs:
+        if spec.name.lower() == "totensor":
+            continue
+        operations.append(_factory_for(spec.name)(spec, normalization))
+    return v2.Compose(operations)
+
+
+def transform_params(spec: TransformConfig) -> Mapping[str, Any]:
+    """Return transform parameters; useful for logging and tests."""
+    return spec.params()

cnn_classifier/diagnostics/__init__.py

@@ -0,0 +1,22 @@
+"""Diagnostics: overfit checks, shape tracing, gradients, activations, determinism."""
+
+from cnn_classifier.diagnostics.activations import ActivationStat, activation_report
+from cnn_classifier.diagnostics.architecture import ArchitectureStage, architecture_stages
+from cnn_classifier.diagnostics.determinism import determinism_check
+from cnn_classifier.diagnostics.gradients import GradientStat, gradient_report
+from cnn_classifier.diagnostics.sanity import OverfitResult, overfit_batch
+from cnn_classifier.diagnostics.tracing import LayerShape, trace_shapes
+
+__all__ = [
+    "ActivationStat",
+    "ArchitectureStage",
+    "GradientStat",
+    "LayerShape",
+    "OverfitResult",
+    "activation_report",
+    "architecture_stages",
+    "determinism_check",
+    "gradient_report",
+    "overfit_batch",
+    "trace_shapes",
+]

cnn_classifier/diagnostics/activations.py

@@ -0,0 +1,56 @@
+"""Activation statistics for ReLU layers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import torch
+from torch import nn
+
+
+@dataclass(frozen=True)
+class ActivationStat:
+    name: str
+    type: str
+    mean: float
+    std: float
+    zero_fraction: float
+
+
+def activation_report(model: nn.Module, batch: torch.Tensor) -> list[ActivationStat]:
+    """Record mean, std, and zero fraction for each ReLU activation."""
+    parameter = next(model.parameters(), None)
+    device = parameter.device if parameter is not None else torch.device("cpu")
+    was_training = model.training
+    records: list[ActivationStat] = []
+    handles = []
+
+    def hook(name: str, module: nn.Module) -> Callable[[nn.Module, Any, Any], None]:
+        def _record(_module: nn.Module, _inputs: Any, output: Any) -> None:
+            tensor = output.detach().float()
+            records.append(
+                ActivationStat(
+                    name=name,
+                    type=type(module).__name__,
+                    mean=float(tensor.mean().item()),
+                    std=float(tensor.std().item()) if tensor.numel() > 1 else 0.0,
+                    zero_fraction=float((tensor == 0).float().mean().item()),
+                )
+            )
+
+        return _record
+
+    for name, module in model.named_modules():
+        if isinstance(module, nn.ReLU):
+            handles.append(module.register_forward_hook(hook(name, module)))
+    try:
+        model.eval()
+        with torch.no_grad():
+            model(batch.to(device))
+    finally:
+        for handle in handles:
+            handle.remove()
+        model.train(was_training)
+    return records