"""Training script for the Week 04 Kvasir-SEG U-Net assignment. Run example: python train.py --output-dir ./kvasir-unet --num-train-epochs 10 To publish after training, pass ``--push-to-hub``. """ from __future__ import annotations import argparse import os from pathlib import Path import numpy as np import torch from datasets import load_dataset from huggingface_hub import upload_folder from safetensors.torch import save_file from torch import nn from torchvision.transforms import Compose, Resize, ToTensor from torchvision.transforms import InterpolationMode from transformers import Trainer, TrainingArguments from model import UNet IMAGE_SIZE = 256 DEFAULT_HUB_MODEL_ID = "FolashadeO/week4" DEFAULT_DATASET_CACHE_DIR = Path("hf_cache") def dataset_cache_dir() -> str | None: """Use the workspace dataset cache when present, otherwise use HF defaults.""" configured_cache = os.environ.get("HF_DATASETS_CACHE") if configured_cache: return configured_cache if DEFAULT_DATASET_CACHE_DIR.exists(): return str(DEFAULT_DATASET_CACHE_DIR) return None def process_dataset_sample(example: dict) -> dict[str, torch.Tensor]: """Convert one Kvasir-SEG sample into tensors expected by the model.""" image_transform = Compose([Resize((IMAGE_SIZE, IMAGE_SIZE)), ToTensor()]) mask_transform = Compose( [Resize((IMAGE_SIZE, IMAGE_SIZE), interpolation=InterpolationMode.NEAREST), ToTensor()] ) image = image_transform(example["image"].convert("RGB")) mask = mask_transform(example["mask"].convert("L")) # The masks are binary segmentation targets. Thresholding removes any # interpolation values introduced by resizing. mask = (mask > 0.5).float() return {"pixel_values": image, "labels": mask} class SegmentationCollator: """Stack already-processed samples into a mini-batch.""" def __call__(self, features: list[dict[str, torch.Tensor]]) -> dict[str, torch.Tensor]: return { "pixel_values": torch.stack([feature["pixel_values"] for feature in features]), "labels": torch.stack([feature["labels"] for feature in features]), } class DiceBCELoss(nn.Module): """Binary cross entropy plus Dice loss for imbalanced segmentation masks.""" def __init__(self, smooth: float = 1.0) -> None: super().__init__() self.bce = nn.BCEWithLogitsLoss() self.smooth = smooth def forward(self, logits: torch.Tensor, labels: torch.Tensor) -> torch.Tensor: bce_loss = self.bce(logits, labels) probabilities = torch.sigmoid(logits) probabilities = probabilities.flatten(start_dim=1) labels = labels.flatten(start_dim=1) intersection = (probabilities * labels).sum(dim=1) denominator = probabilities.sum(dim=1) + labels.sum(dim=1) dice_loss = 1.0 - ((2.0 * intersection + self.smooth) / (denominator + self.smooth)) return bce_loss + dice_loss.mean() class UNetTrainer(Trainer): """Trainer subclass that applies segmentation loss to raw model logits.""" def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) self.loss_fn = DiceBCELoss() def compute_loss( self, model: nn.Module, inputs: dict[str, torch.Tensor], return_outputs: bool = False, **_: object, ): labels = inputs["labels"] logits = model(inputs["pixel_values"]) loss = self.loss_fn(logits, labels) outputs = {"logits": logits} return (loss, outputs) if return_outputs else loss def compute_metrics(eval_prediction) -> dict[str, float]: """Compute common binary segmentation metrics from Trainer predictions.""" logits, labels = eval_prediction if isinstance(logits, (tuple, list)): logits = logits[0] probabilities = 1.0 / (1.0 + np.exp(-logits)) predictions = probabilities > 0.5 labels = labels > 0.5 intersection = np.logical_and(predictions, labels).sum() union = np.logical_or(predictions, labels).sum() prediction_sum = predictions.sum() label_sum = labels.sum() dice = (2 * intersection + 1.0) / (prediction_sum + label_sum + 1.0) iou = (intersection + 1.0) / (union + 1.0) return {"dice": float(dice), "iou": float(iou)} def write_model_card(output_dir: str, model_name: str) -> None: """Write a lightweight model card for the trained U-Net.""" model_card = f"""--- language: en license: mit tags: - image-segmentation - medical-imaging - pytorch - unet datasets: - Angelou0516/kvasir-seg --- # {model_name} This model is a compact PyTorch U-Net for binary gastrointestinal polyp segmentation on the Kvasir-SEG dataset. ## Architecture The network uses a four-level U-Net with convolutional encoder blocks, a bottleneck, transposed-convolution decoder blocks, skip connections, and a final `1 x 1` convolution that produces one mask logit channel. ## Loss Training uses a combined Dice and binary cross-entropy loss. BCE handles per-pixel classification, while Dice loss directly optimizes mask overlap and helps with foreground/background class imbalance. """ Path(output_dir).mkdir(parents=True, exist_ok=True) Path(output_dir, "README.md").write_text(model_card, encoding="utf-8") def build_datasets(): """Load and preprocess the required Hugging Face Kvasir-SEG dataset.""" dataset = load_dataset("Angelou0516/kvasir-seg", cache_dir=dataset_cache_dir()) train_dataset = dataset["train"].map( process_dataset_sample, remove_columns=dataset["train"].column_names, ) validation_split = "validation" if "validation" in dataset else "test" eval_dataset = dataset[validation_split].map( process_dataset_sample, remove_columns=dataset[validation_split].column_names, ) train_dataset.set_format(type="torch", columns=["pixel_values", "labels"]) eval_dataset.set_format(type="torch", columns=["pixel_values", "labels"]) return train_dataset, eval_dataset def parse_args() -> argparse.Namespace: parser = argparse.ArgumentParser(description="Train a U-Net on Kvasir-SEG.") parser.add_argument("--output-dir", default="./kvasir-unet", help="Training output directory.") parser.add_argument("--hub-model-id", default=DEFAULT_HUB_MODEL_ID, help="Hugging Face Hub repo id.") parser.add_argument("--push-to-hub", action="store_true", help="Push weights and model card.") parser.add_argument("--num-train-epochs", type=float, default=10.0) parser.add_argument("--learning-rate", type=float, default=1e-4) parser.add_argument("--batch-size", type=int, default=4) parser.add_argument("--eval-batch-size", type=int, default=4) return parser.parse_args() def main() -> None: args = parse_args() train_dataset, eval_dataset = build_datasets() model = UNet() training_args = TrainingArguments( output_dir=args.output_dir, num_train_epochs=args.num_train_epochs, learning_rate=args.learning_rate, per_device_train_batch_size=args.batch_size, per_device_eval_batch_size=args.eval_batch_size, eval_strategy="epoch", save_strategy="epoch", logging_steps=25, load_best_model_at_end=True, metric_for_best_model="dice", greater_is_better=True, remove_unused_columns=False, push_to_hub=False, hub_model_id=args.hub_model_id, ) trainer = UNetTrainer( model=model, args=training_args, train_dataset=train_dataset, eval_dataset=eval_dataset, data_collator=SegmentationCollator(), compute_metrics=compute_metrics, ) trainer.train() trainer.evaluate() save_file(model.state_dict(), f"{args.output_dir}/model.safetensors") write_model_card(args.output_dir, args.hub_model_id) if args.push_to_hub: upload_folder( repo_id=args.hub_model_id, folder_path=args.output_dir, repo_type="model", ) if __name__ == "__main__": main()