fastdrs 0.1.0__py3-none-any.whl

fastdrs/__init__.py

@@ -0,0 +1,2 @@
+# Package marker for fastdrs
+

fastdrs/data.py

@@ -0,0 +1,113 @@
+"""
+Data loading and dataset handling for Diabetic Retinopathy screening.
+
+Supports Hugging Face datasets (e.g. `ctmedtech/EYEPACS`) as well as standard PyTorch datasets,
+with reproducible train/validation/test splitting and DataLoader construction.
+"""
+
+from typing import Tuple, Dict, Any, Optional
+import torch
+from torch.utils.data import Dataset, DataLoader, Subset
+from sklearn.model_selection import train_test_split
+from datasets import load_dataset
+from PIL import Image
+import numpy as np
+
+from fastdrs.preprocessing import get_transforms
+
+
+class EyepacsDataset(Dataset):
+    """
+    PyTorch Wrapper for Hugging Face EYEPACS dataset or image list.
+    """
+    def __init__(self, hf_dataset, transform=None):
+        self.dataset = hf_dataset
+        self.transform = transform
+
+    def __len__(self) -> int:
+        return len(self.dataset)
+
+    def __getitem__(self, idx: int) -> Tuple[torch.Tensor, int]:
+        item = self.dataset[int(idx)]
+        image = item["image"]
+        
+        # Ensure image is PIL Image in RGB mode
+        if not isinstance(image, Image.Image):
+            image = Image.fromarray(np.uint8(image))
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+            
+        label = item.get("label", item.get("dr_level", item.get("level", 0)))
+        
+        if self.transform is not None:
+            image = self.transform(image)
+            
+        return image, int(label)
+
+
+def create_dataloaders(
+    dataset_name: str = "sngsfydy/aptos",
+    batch_size: int = 32,
+    img_size: int = 224,
+    val_split: float = 0.15,
+    test_split: float = 0.15,
+    seed: int = 42,
+    num_workers: int = 2,
+    use_ben_graham: bool = False
+) -> Tuple[DataLoader, DataLoader, DataLoader, Dict[str, Any]]:
+    """
+    Loads dataset, splits into train/val/test, applies transforms, and returns PyTorch DataLoaders.
+    
+    Returns:
+        train_loader, val_loader, test_loader, dataset_info metadata dict
+    """
+    # Load raw dataset from Hugging Face
+    raw_dataset = load_dataset(dataset_name, split="train")
+    total_size = len(raw_dataset)
+    indices = np.arange(total_size)
+    
+    # Get labels if available for stratified splitting
+    try:
+        labels = [raw_dataset[i].get("label", raw_dataset[i].get("dr_level", 0)) for i in range(min(total_size, 1000))]
+        stratify = None # Avoid full scan if dataset is large, or use stratified split on subset
+    except Exception:
+        labels = None
+    
+    # Train / Val / Test Split
+    train_val_idx, test_idx = train_test_split(
+        indices, test_size=test_split, random_state=seed, shuffle=True
+    )
+    relative_val_size = val_split / (1.0 - test_split)
+    train_idx, val_idx = train_test_split(
+        train_val_idx, test_size=relative_val_size, random_state=seed, shuffle=True
+    )
+    
+    train_idx = [int(i) for i in train_idx]
+    val_idx = [int(i) for i in val_idx]
+    test_idx = [int(i) for i in test_idx]
+    
+    train_transform = get_transforms(img_size=img_size, is_train=True, use_ben_graham=use_ben_graham)
+    eval_transform = get_transforms(img_size=img_size, is_train=False, use_ben_graham=use_ben_graham)
+    
+    full_train_ds = EyepacsDataset(raw_dataset, transform=train_transform)
+    full_eval_ds = EyepacsDataset(raw_dataset, transform=eval_transform)
+    
+    train_ds = Subset(full_train_ds, train_idx)
+    val_ds = Subset(full_eval_ds, val_idx)
+    test_ds = Subset(full_eval_ds, test_idx)
+    
+    train_loader = DataLoader(train_ds, batch_size=batch_size, shuffle=True, num_workers=num_workers, pin_memory=True)
+    val_loader = DataLoader(val_ds, batch_size=batch_size, shuffle=False, num_workers=num_workers, pin_memory=True)
+    test_loader = DataLoader(test_ds, batch_size=batch_size, shuffle=False, num_workers=num_workers, pin_memory=True)
+    
+    info = {
+        "dataset_name": dataset_name,
+        "total_samples": total_size,
+        "train_samples": len(train_ds),
+        "val_samples": len(val_ds),
+        "test_samples": len(test_ds),
+        "batch_size": batch_size,
+        "img_size": img_size
+    }
+    
+    return train_loader, val_loader, test_loader, info

fastdrs/deployment/litert.py

@@ -0,0 +1 @@
+.py

fastdrs/evaluation.py

@@ -0,0 +1,111 @@
+"""
+Evaluation and benchmarking module for Diabetic Retinopathy screening models.
+
+Calculates clinical metrics:
+- Accuracy, Precision, Sensitivity/Recall, Specificity, F1 Score
+- Per-class classification report and Confusion Matrix
+- Inference latency and deployment feasibility metrics
+"""
+
+from typing import Dict, Any, List, Tuple, Optional
+import time
+import torch
+import torch.nn as nn
+import numpy as np
+from sklearn.metrics import accuracy_score, precision_recall_fscore_support, confusion_matrix
+
+from fastdrs.models import get_model_info
+
+
+def compute_specificity(cm: np.ndarray) -> np.ndarray:
+    """
+    Computes per-class specificity from confusion matrix.
+    Specificity = TN / (TN + FP)
+    """
+    num_classes = cm.shape[0]
+    specificities = []
+    total = np.sum(cm)
+    for i in range(num_classes):
+        tp = cm[i, i]
+        fp = np.sum(cm[:, i]) - tp
+        fn = np.sum(cm[i, :]) - tp
+        tn = total - (tp + fp + fn)
+        spec = tn / (tn + fp) if (tn + fp) > 0 else 0.0
+        specificities.append(spec)
+    return np.array(specificities)
+
+
+def evaluate_model(
+    model: nn.Module,
+    dataloader: torch.utils.data.DataLoader,
+    device: torch.device,
+    class_names: Optional[List[str]] = None
+) -> Dict[str, Any]:
+    """
+    Evaluates a model on a dataloader, measuring clinical performance and inference latency.
+    """
+    if class_names is None:
+        class_names = ["0 - No DR", "1 - Mild", "2 - Moderate", "3 - Severe", "4 - Proliferative"]
+
+    model.to(device)
+    model.eval()
+
+    all_preds = []
+    all_targets = []
+    inference_times = []
+
+    with torch.no_grad():
+        for inputs, targets in dataloader:
+            inputs = inputs.to(device)
+            
+            start_time = time.perf_counter()
+            outputs = model(inputs)
+            if device.type == "cuda":
+                torch.cuda.synchronize()
+            end_time = time.perf_counter()
+            
+            batch_latency = (end_time - start_time) / inputs.size(0)
+            inference_times.append(batch_latency)
+            
+            preds = torch.argmax(outputs, dim=1).cpu().numpy()
+            all_preds.extend(preds)
+            all_targets.extend(targets.numpy())
+
+    all_preds = np.array(all_preds)
+    all_targets = np.array(all_targets)
+
+    acc = accuracy_score(all_targets, all_preds)
+    precision, recall, f1, _ = precision_recall_fscore_support(all_targets, all_preds, average='macro', zero_division=0)
+    _, _, f1_weighted, _ = precision_recall_fscore_support(all_targets, all_preds, average='weighted', zero_division=0)
+    
+    cm = confusion_matrix(all_targets, all_preds, labels=list(range(len(class_names))))
+    per_class_spec = compute_specificity(cm)
+    per_class_prec, per_class_rec, per_class_f1, _ = precision_recall_fscore_support(
+        all_targets, all_preds, average=None, labels=list(range(len(class_names))), zero_division=0
+    )
+
+    avg_latency_ms = float(np.mean(inference_times) * 1000.0)
+    model_info = get_model_info(model)
+
+    results = {
+        "accuracy": round(float(acc), 4),
+        "precision_macro": round(float(precision), 4),
+        "sensitivity_macro": round(float(recall), 4),
+        "specificity_macro": round(float(np.mean(per_class_spec)), 4),
+        "f1_macro": round(float(f1), 4),
+        "f1_weighted": round(float(f1_weighted), 4),
+        "inference_latency_ms": round(avg_latency_ms, 2),
+        "model_size_mb": model_info["model_size_mb"],
+        "total_parameters": model_info["total_parameters"],
+        "confusion_matrix": cm.tolist(),
+        "per_class": {
+            class_names[i]: {
+                "precision": round(float(per_class_prec[i]), 4),
+                "sensitivity_recall": round(float(per_class_rec[i]), 4),
+                "specificity": round(float(per_class_spec[i]), 4),
+                "f1": round(float(per_class_f1[i]), 4),
+            } for i in range(len(class_names))
+        }
+    }
+
+    return results

fastdrs/models.py

@@ -0,0 +1,110 @@
+"""
+Model architecture factory for Diabetic Retinopathy classification.
+
+Supports building and benchmarking multiple vision architectures:
+- ResNet (e.g. resnet50, resnet18)
+- DenseNet (e.g. densenet121)
+- ConvNeXt (e.g. convnext_tiny)
+- Swin Transformer (e.g. swin_t)
+- MobileNetV2 (efficient baseline)
+"""
+
+from typing import Tuple, Dict, Any
+import torch
+import torch.nn as nn
+import torchvision.models as models
+
+
+def build_model(
+    architecture: str = "resnet50",
+    num_classes: int = 5,
+    pretrained: bool = True,
+    dropout_rate: float = 0.2
+) -> nn.Module:
+    """
+    Constructs a vision model with customized classification head.
+    
+    Args:
+        architecture: Choice of 'resnet50', 'resnet18', 'densenet121', 'convnext_tiny', 'swin_t', 'mobilenet_v2'.
+        num_classes: Number of output severity classes (default: 5).
+        pretrained: Whether to use ImageNet pre-trained weights.
+        dropout_rate: Dropout rate before classification layer.
+    """
+    arch = architecture.lower()
+    
+    if arch == "resnet50":
+        weights = models.ResNet50_Weights.DEFAULT if pretrained else None
+        model = models.resnet50(weights=weights)
+        in_features = model.fc.in_features
+        model.fc = nn.Sequential(
+            nn.Dropout(p=dropout_rate),
+            nn.Linear(in_features, num_classes)
+        )
+        
+    elif arch == "resnet18":
+        weights = models.ResNet18_Weights.DEFAULT if pretrained else None
+        model = models.resnet18(weights=weights)
+        in_features = model.fc.in_features
+        model.fc = nn.Sequential(
+            nn.Dropout(p=dropout_rate),
+            nn.Linear(in_features, num_classes)
+        )
+
+    elif arch == "densenet121":
+        weights = models.DenseNet121_Weights.DEFAULT if pretrained else None
+        model = models.densenet121(weights=weights)
+        in_features = model.classifier.in_features
+        model.classifier = nn.Sequential(
+            nn.Dropout(p=dropout_rate),
+            nn.Linear(in_features, num_classes)
+        )
+
+    elif arch in ("convnext_tiny", "convnext"):
+        weights = models.ConvNeXt_Tiny_Weights.DEFAULT if pretrained else None
+        model = models.convnext_tiny(weights=weights)
+        in_features = model.classifier[2].in_features
+        model.classifier[2] = nn.Sequential(
+            nn.Dropout(p=dropout_rate),
+            nn.Linear(in_features, num_classes)
+        )
+
+    elif arch in ("swin_t", "swin"):
+        weights = models.Swin_T_Weights.DEFAULT if pretrained else None
+        model = models.swin_t(weights=weights)
+        in_features = model.head.in_features
+        model.head = nn.Sequential(
+            nn.Dropout(p=dropout_rate),
+            nn.Linear(in_features, num_classes)
+        )
+
+    elif arch in ("mobilenet_v2", "mobilenet"):
+        weights = models.MobileNet_V2_Weights.DEFAULT if pretrained else None
+        model = models.mobilenet_v2(weights=weights)
+        in_features = model.classifier[1].in_features
+        model.classifier = nn.Sequential(
+            nn.Dropout(p=dropout_rate),
+            nn.Linear(in_features, num_classes)
+        )
+
+    else:
+        raise ValueError(f"Unsupported architecture '{architecture}'. "
+                         f"Supported: resnet50, resnet18, densenet121, convnext_tiny, swin_t, mobilenet_v2")
+
+    return model
+
+
+def get_model_info(model: nn.Module) -> Dict[str, Any]:
+    """
+    Calculates parameter count and estimated model memory size in MB.
+    """
+    total_params = sum(p.numel() for p in model.parameters())
+    trainable_params = sum(p.numel() for p in model.parameters() if p.requires_grad)
+    
+    # Estimate size assuming float32 (4 bytes per param)
+    param_size_mb = (total_params * 4) / (1024 * 1024)
+    
+    return {
+        "total_parameters": total_params,
+        "trainable_parameters": trainable_params,
+        "model_size_mb": round(param_size_mb, 2)
+    }

fastdrs/preprocessing.py

@@ -0,0 +1,88 @@
+"""
+Preprocessing module for Diabetic Retinopathy retinal fundus images.
+
+Provides standard image transformations, augmentations, and specialized
+preprocessing routines (e.g., circular cropping, Ben Graham color processing)
+tailored for fundus image classification.
+"""
+
+from typing import Tuple, Optional, Callable
+import torch
+import torchvision.transforms as T
+from PIL import Image
+import numpy as np
+import cv2
+
+
+def crop_image_from_gray(img: np.ndarray, tol: int = 7) -> np.ndarray:
+    """
+    Crops black boundaries from fundus images.
+    """
+    if img.ndim == 2:
+        mask = img > tol
+        return img[np.ix_(mask.any(1), mask.any(0))]
+    elif img.ndim == 3:
+        gray_img = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
+        mask = gray_img > tol
+        
+        check_start = img[:, :, 0][np.ix_(mask.any(1), mask.any(0))]
+        if check_start.size == 0:
+            return img
+        else:
+            img1 = img[:, :, 0][np.ix_(mask.any(1), mask.any(0))]
+            img2 = img[:, :, 1][np.ix_(mask.any(1), mask.any(0))]
+            img3 = img[:, :, 2][np.ix_(mask.any(1), mask.any(0))]
+            return np.stack([img1, img2, img3], axis=-1)
+    return img
+
+
+def ben_graham_preprocessing(img_pil: Image.Image, img_size: int = 224, sigma_x: int = 10) -> Image.Image:
+    """
+    Applies Ben Graham's method for enhancing retinal fundus features (subtract local average color).
+    """
+    img = np.array(img_pil)
+    img = crop_image_from_gray(img)
+    img = cv2.resize(img, (img_size, img_size))
+    img = cv2.addWeighted(img, 4, cv2.GaussianBlur(img, (0, 0), sigma_x), -4, 128)
+    return Image.fromarray(img)
+
+
+def get_transforms(
+    img_size: int = 224,
+    is_train: bool = True,
+    mean: Tuple[float, float, float] = (0.485, 0.456, 0.406),
+    std: Tuple[float, float, float] = (0.229, 0.224, 0.225),
+    use_ben_graham: bool = False
+) -> T.Compose:
+    """
+    Returns torchvision transforms for training or evaluation.
+    
+    Args:
+        img_size: Target image height and width.
+        is_train: Whether to include data augmentation transforms.
+        mean: Normalization channel means.
+        std: Normalization channel standard deviations.
+        use_ben_graham: Whether to apply Ben Graham preprocessing.
+    """
+    transforms_list = []
+    
+    if use_ben_graham:
+        transforms_list.append(T.Lambda(lambda img: ben_graham_preprocessing(img, img_size=img_size)))
+    else:
+        transforms_list.append(T.Resize((img_size, img_size)))
+    
+    if is_train:
+        transforms_list.extend([
+            T.RandomHorizontalFlip(p=0.5),
+            T.RandomVerticalFlip(p=0.5),
+            T.RandomRotation(degrees=30),
+            T.ColorJitter(brightness=0.2, contrast=0.2, saturation=0.2),
+            T.RandomAffine(degrees=0, translate=(0.05, 0.05), scale=(0.95, 1.05))
+        ])
+    
+    transforms_list.extend([
+        T.ToTensor(),
+        T.Normalize(mean=mean, std=std)
+    ])
+    
+    return T.Compose(transforms_list)

fastdrs/training.py

@@ -0,0 +1,169 @@
+"""
+Training script and loop for Diabetic Retinopathy classification models.
+
+Features:
+- PyTorch modular training loop with validation
+- Support for class-weighted loss (for imbalanced DR classes)
+- Learning rate schedulers (CosineAnnealing / ReduceLROnPlateau)
+- Best model checkpointing
+- Weights & Biases (wandb) logging integration
+"""
+
+from typing import Dict, Any, Optional, Tuple
+import os
+import time
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.optim.lr_scheduler import CosineAnnealingLR, ReduceLROnPlateau
+
+from fastdrs.data import create_dataloaders
+from fastdrs.models import build_model, get_model_info
+from fastdrs.evaluation import evaluate_model
+
+
+def train_epoch(
+    model: nn.Module,
+    dataloader: torch.utils.data.DataLoader,
+    criterion: nn.Module,
+    optimizer: optim.Optimizer,
+    device: torch.device
+) -> Tuple[float, float]:
+    model.train()
+    running_loss = 0.0
+    correct = 0
+    total = 0
+
+    for inputs, targets in dataloader:
+        inputs, targets = inputs.to(device), targets.to(device)
+        
+        optimizer.zero_grad()
+        outputs = model(inputs)
+        loss = criterion(outputs, targets)
+        loss.backward()
+        optimizer.step()
+
+        running_loss += loss.item() * inputs.size(0)
+        preds = torch.argmax(outputs, dim=1)
+        correct += (preds == targets).sum().item()
+        total += inputs.size(0)
+
+    epoch_loss = running_loss / total
+    epoch_acc = correct / total
+    return epoch_loss, epoch_acc
+
+
+def validate_epoch(
+    model: nn.Module,
+    dataloader: torch.utils.data.DataLoader,
+    criterion: nn.Module,
+    device: torch.device
+) -> Tuple[float, float]:
+    model.eval()
+    running_loss = 0.0
+    correct = 0
+    total = 0
+
+    with torch.no_grad():
+        for inputs, targets in dataloader:
+            inputs, targets = inputs.to(device), targets.to(device)
+            outputs = model(inputs)
+            loss = criterion(outputs, targets)
+
+            running_loss += loss.item() * inputs.size(0)
+            preds = torch.argmax(outputs, dim=1)
+            correct += (preds == targets).sum().item()
+            total += inputs.size(0)
+
+    epoch_loss = running_loss / total
+    epoch_acc = correct / total
+    return epoch_loss, epoch_acc
+
+
+def train_model(
+    architecture: str = "resnet50",
+    dataset_name: str = "sngsfydy/aptos",
+    epochs: int = 10,
+    batch_size: int = 32,
+    lr: float = 1e-4,
+    weight_decay: float = 1e-4,
+    img_size: int = 224,
+    save_dir: str = "models",
+    use_wandb: bool = False,
+    device: str = "cuda" if torch.cuda.is_available() else "cpu"
+) -> Dict[str, Any]:
+    """
+    Main entry point for training a DR classification model.
+    """
+    os.makedirs(save_dir, exist_ok=True)
+    device_obj = torch.device(device)
+    
+    print(f"--- Training {architecture} on {device} ---")
+    
+    # 1. DataLoaders
+    train_loader, val_loader, test_loader, ds_info = create_dataloaders(
+        dataset_name=dataset_name,
+        batch_size=batch_size,
+        img_size=img_size
+    )
+
+    # 2. Build Model
+    model = build_model(architecture=architecture, num_classes=5, pretrained=True)
+    model.to(device_obj)
+    
+    model_info = get_model_info(model)
+    print(f"Model parameters: {model_info['total_parameters']:,} ({model_info['model_size_mb']} MB)")
+
+    # 3. Optimization Setup
+    criterion = nn.CrossEntropyLoss()
+    optimizer = optim.AdamW(model.parameters(), lr=lr, weight_decay=weight_decay)
+    scheduler = CosineAnnealingLR(optimizer, T_max=epochs)
+
+    best_val_loss = float("inf")
+    best_checkpoint_path = os.path.join(save_dir, f"{architecture}_best.pth")
+
+    history = {"train_loss": [], "train_acc": [], "val_loss": [], "val_acc": []}
+
+    # 4. Training Loop
+    for epoch in range(1, epochs + 1):
+        t0 = time.time()
+        train_loss, train_acc = train_epoch(model, train_loader, criterion, optimizer, device_obj)
+        val_loss, val_acc = validate_epoch(model, val_loader, criterion, device_obj)
+        scheduler.step()
+        elapsed = time.time() - t0
+
+        history["train_loss"].append(train_loss)
+        history["train_acc"].append(train_acc)
+        history["val_loss"].append(val_loss)
+        history["val_acc"].append(val_acc)
+
+        print(f"Epoch {epoch:02d}/{epochs:02d} [{elapsed:.1f}s] | "
+              f"Train Loss: {train_loss:.4f}, Acc: {train_acc:.4f} | "
+              f"Val Loss: {val_loss:.4f}, Acc: {val_acc:.4f}")
+
+        if val_loss < best_val_loss:
+            best_val_loss = val_loss
+            torch.save(model.state_dict(), best_checkpoint_path)
+            print(f" Saved new best model to {best_checkpoint_path}")
+
+    # 5. Final Evaluation on Test Set using Best Weights
+    if os.path.exists(best_checkpoint_path):
+        model.load_state_dict(torch.load(best_checkpoint_path, map_location=device_obj))
+
+    print("\n--- Final Test Set Evaluation ---")
+    test_results = evaluate_model(model, test_loader, device_obj)
+    print(f"Test Accuracy: {test_results['accuracy']}")
+    print(f"Test Macro F1: {test_results['f1_macro']}")
+    print(f"Test Macro Sensitivity: {test_results['sensitivity_macro']}")
+    print(f"Test Latency: {test_results['inference_latency_ms']} ms/sample")
+
+    return {
+        "architecture": architecture,
+        "history": history,
+        "test_results": test_results,
+        "best_checkpoint": best_checkpoint_path
+    }
+
+
+if __name__ == "__main__":
+    train_model(architecture="resnet50", epochs=5)

fastdrs-0.1.0.dist-info/METADATA

@@ -0,0 +1,776 @@
+Metadata-Version: 2.5
+Name: fastdrs
+Version: 0.1.0
+Summary: Diabetic retinopathy screening toolkit
+Author: Michael Mukiibi
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: pillow
+Provides-Extra: export
+Provides-Extra: training
+Requires-Dist: datasets; extra == 'training'
+Requires-Dist: opencv-python; extra == 'training'
+Requires-Dist: scikit-learn; extra == 'training'
+Requires-Dist: torch; extra == 'training'
+Requires-Dist: torchvision; extra == 'training'
+Description-Content-Type: text/markdown
+
+# AI-Assisted Diabetic Retinopathy Screening & Triage
+
+> **Marconi Research & Innovations Lab — Internship Capstone Project**
+
+An economically motivated computer-vision system for **AI-assisted diabetic retinopathy screening and clinical triage**, designed with resource-constrained healthcare environments in mind.
+
+The project investigates whether modern deep-learning vision architectures can classify diabetic retinopathy severity from retinal fundus photographs while balancing **clinical sensitivity, predictive performance, model size, and inference latency** for practical deployment.
+
+> **Important:** This project is a research and engineering prototype. It is **not a medical device and does not provide an autonomous clinical diagnosis**. Predictions are intended to demonstrate AI-assisted screening and referral prioritization.
+
+---
+
+## 1. Problem
+
+Diabetic retinopathy (DR) is a major complication of diabetes and an important cause of preventable vision loss. Early identification can enable timely clinical assessment and treatment.
+
+In resource-constrained healthcare environments, however, screening can be limited by:
+
+* Shortage of ophthalmologists and trained specialists
+* Geographic barriers to specialist care
+* Cost of specialist examinations
+* Increasing numbers of patients requiring screening
+* Limited access to regular retinal imaging assessment
+
+This creates an opportunity for **AI-assisted screening and triage**.
+
+Rather than replacing clinicians, an AI system can potentially help healthcare workers identify images that require **higher-priority specialist review**, allowing limited clinical resources to be allocated more efficiently.
+
+---
+
+## 2. Proposed Solution
+
+This project develops a computer-vision pipeline that analyzes retinal fundus photographs and estimates the severity of diabetic retinopathy.
+
+The system investigates multiple modern vision architectures and evaluates them not only by predictive performance, but also by their suitability for deployment.
+
+### Core workflow
+
+```text
+Retinal Fundus Image
+        │
+        ▼
+      EDA
+        │
+        ▼
+Preprocessing
+        │
+        ▼
+Model Fine-Tuning
+        │
+        ├── ResNet
+        ├── DenseNet
+        ├── ConvNeXt
+        └── Swin Transformer
+        │
+        ▼
+Model Evaluation
+        │
+        ├── Accuracy
+        ├── Precision
+        ├── Recall / Sensitivity
+        ├── Specificity
+        └── F1 Score
+        │
+        ▼
+Deployment Analysis
+        │
+        ├── Model Size
+        ├── Parameter Count
+        └── Inference Latency
+        │
+        ▼
+Final Model
+        │
+        ▼
+Android Application / API
+```
+
+---
+
+## 3. Capstone Research Question
+
+> **Can modern computer-vision architectures provide sufficiently sensitive diabetic-retinopathy screening while remaining computationally efficient enough for deployment in resource-constrained healthcare environments?**
+
+The project therefore treats model selection as a multi-objective engineering problem:
+
+```text
+Clinical Performance
+        +
+Computational Efficiency
+        +
+Deployment Feasibility
+        =
+Practical Model
+```
+
+---
+
+## 4. Objectives
+
+### Primary objective
+
+Develop and evaluate a deployable AI-assisted diabetic-retinopathy screening prototype using retinal fundus photographs.
+
+### Specific objectives
+
+1. Perform exploratory data analysis on the APTOS 2019 dataset.
+2. Develop a standardized image preprocessing and training pipeline.
+3. Fine-tune modern computer-vision architectures for diabetic-retinopathy classification.
+4. Compare ResNet, DenseNet, ConvNeXt, and Swin Transformer architectures.
+5. Evaluate models using clinically relevant classification metrics.
+6. Investigate the relationship between sensitivity, model size, and inference latency.
+7. Select a final model based on predictive performance and deployment feasibility.
+8. Integrate the trained model into an **Android application or inference API**.
+9. Demonstrate an end-to-end screening workflow.
+
+---
+
+## 5. Dataset
+
+### APTOS 2019 Blindness Detection
+
+The primary dataset is the **APTOS 2019 Blindness Detection** dataset.
+
+It contains approximately **3,662 labeled retinal fundus photographs** across five diabetic-retinopathy severity grades.
+
+### Classes
+
+| Label | Severity                           |
+| ----: | ---------------------------------- |
+|     0 | No diabetic retinopathy            |
+|     1 | Mild                               |
+|     2 | Moderate                           |
+|     3 | Severe                             |
+|     4 | Proliferative diabetic retinopathy |
+
+The dataset was originally released through the APTOS 2019 Blindness Detection Kaggle competition.
+
+Dataset source:
+
+[https://www.kaggle.com/competitions/aptos2019-blindness-detection](https://www.kaggle.com/competitions/aptos2019-blindness-detection)
+
+### Data considerations
+
+The project will investigate:
+
+* Class distribution
+* Image dimensions
+* Image quality
+* Color/channel characteristics
+* Class imbalance
+* Training/validation/test splitting
+* Appropriate augmentation
+* Image normalization
+
+Because the dataset is imbalanced, **accuracy will not be treated as the sole measure of model quality**.
+
+---
+
+## 6. Evaluation Strategy
+
+The project evaluates models using multiple metrics.
+
+### Accuracy
+
+Measures the proportion of correctly classified samples.
+
+### Precision
+
+Measures how many predicted positive cases are actually positive.
+
+### Recall / Sensitivity
+
+Measures the proportion of relevant positive cases detected by the model.
+
+For a screening application, sensitivity is particularly important because missed cases may require further clinical assessment.
+
+### Specificity
+
+Measures the proportion of negative cases correctly identified.
+
+### F1 Score
+
+Balances precision and recall.
+
+### Confusion Matrix
+
+Used to examine errors across the five diabetic-retinopathy severity classes.
+
+---
+
+## 7. Model Benchmarking
+
+The project will investigate four major vision architectures.
+
+### ResNet
+
+Uses residual/skip connections to facilitate the training of deep convolutional networks.
+
+### DenseNet
+
+Uses dense connectivity and feature reuse between layers.
+
+### ConvNeXt
+
+A modern convolutional architecture incorporating design principles developed alongside the rise of vision transformers.
+
+### Swin Transformer
+
+Uses hierarchical vision-transformer representations with shifted-window attention.
+
+The objective is not simply to identify the model with the highest accuracy.
+
+The benchmark will investigate:
+
+> **Predictive performance vs. computational cost vs. deployment feasibility.**
+
+---
+
+## 8. Experimental Tracking
+
+Experiments will be tracked using **Weights & Biases (W&B)**.
+
+Potentially tracked parameters include:
+
+* Model architecture
+* Learning rate
+* Batch size
+* Number of epochs
+* Training loss
+* Validation loss
+* Accuracy
+* Precision
+* Recall
+* Sensitivity
+* Specificity
+* F1 score
+* Training duration
+
+This enables systematic comparison between experiments instead of relying on isolated notebook outputs.
+
+---
+
+## 9. Training Framework & Quickstart
+
+The project builds on technologies explored during the Marconi internship:
+
+* Python
+* PyTorch
+* Hugging Face Datasets
+* scikit-learn
+* Weights & Biases (W&B)
+
+### Running the Training Pipeline (`train.py`)
+
+A unified, single-execution training script (`train.py`) is provided for local execution and experiment tracking.
+
+#### 1. Setup Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+#### 2. Single-Command Training Examples
+
+* **Default Run (ResNet-50 with W&B logging)**:
+  ```bash
+  python train.py
+  ```
+
+* **Architecture Benchmarking (DenseNet-121 with Ben Graham Preprocessing)**:
+  ```bash
+  python train.py --arch densenet121 --epochs 15 --batch-size 16 --ben-graham
+  ```
+
+* **Modern Vision Transformers (Swin Transformer / ConvNeXt)**:
+  ```bash
+  python train.py --arch swin_t --epochs 10 --batch-size 16
+  python train.py --arch convnext_tiny --epochs 10 --batch-size 16
+  ```
+
+* **Local Offline Run (without Weights & Biases)**:
+  ```bash
+  python train.py --arch mobilenet_v2 --epochs 5 --no-wandb
+  ```
+
+#### 3. Command-Line Options
+
+| Argument | Default | Description |
+| :--- | :--- | :--- |
+| `--arch`, `-a` | `resnet50` | Architecture (`resnet50`, `resnet18`, `densenet121`, `convnext_tiny`, `swin_t`, `mobilenet_v2`) |
+| `--dataset`, `-d` | `sngsfydy/aptos` | Hugging Face dataset identifier |
+| `--epochs`, `-e` | `10` | Number of training epochs |
+| `--batch-size`, `-b` | `16` | Batch size per step |
+| `--lr` | `1e-4` | Learning rate |
+| `--ben-graham` | `False` | Apply Ben Graham circular crop & local color subtraction |
+| `--device` | `auto` | Execution device (`auto`, `cuda`, `cpu`, `mps`) |
+| `--wandb-project` | `diabetic-retinopathy-screening` | W&B project name |
+| `--no-wandb` | `False` | Disable W&B online tracking |
+| `--save-dir` | `models` | Directory for model checkpoints |
+| `--results-dir` | `results` | Directory for benchmark metric CSV tables |
+
+---
+
+## 10. Deployment
+
+A trained model is not considered the final deliverable by itself.
+
+The selected model will be integrated into a usable inference system.
+
+Two deployment paths are being considered.
+
+### Option A — Android
+
+```text
+Android Application
+        │
+        ▼
+Fundus Image
+        │
+        ▼
+Preprocessing
+        │
+        ▼
+ML Model
+        │
+        ▼
+Prediction
+        │
+        ▼
+Severity / Referral Risk
+```
+
+Potential technologies:
+
+* Kotlin
+* Jetpack Compose
+* ONNX Runtime
+* TensorFlow Lite
+
+### Option B — API
+
+```text
+Client
+  │
+  ▼
+HTTP POST /predict
+  │
+  ▼
+FastAPI
+  │
+  ▼
+Preprocessing
+  │
+  ▼
+Trained Model
+  │
+  ▼
+Prediction
+  │
+  ▼
+JSON Response
+```
+
+Potential API stack:
+
+* Python
+* FastAPI
+* Uvicorn
+* PyTorch / Hugging Face
+
+The final deployment path will be selected after evaluating the trained model's framework, size, conversion requirements, and inference performance.
+
+---
+
+## 11. Deployment-Oriented Model Selection
+
+The final model will not necessarily be the model with the highest raw accuracy.
+
+A model-selection framework will consider:
+
+| Criterion                | Importance  |
+| ------------------------ | ----------- |
+| Sensitivity              | High        |
+| Specificity              | High        |
+| F1 score                 | High        |
+| Generalization           | High        |
+| Model size               | Medium–High |
+| Parameter count          | Medium      |
+| Inference latency        | Medium–High |
+| Deployment compatibility | High        |
+
+The goal is to identify a model that provides an appropriate balance between **screening performance and practical deployment requirements**.
+
+---
+
+## 12. Economic Rationale
+
+The project is motivated by an operational healthcare problem rather than model development for its own sake.
+
+A potential AI-assisted screening system could help:
+
+* Extend screening capacity
+* Prioritize patients for specialist review
+* Reduce unnecessary specialist referrals
+* Support healthcare workers without specialist expertise
+* Reduce geographic barriers to initial screening
+* Enable lower-cost preliminary assessment
+
+The economic hypothesis is:
+
+> **If AI can reliably identify higher-risk retinal images for specialist review, limited ophthalmology resources can potentially be allocated more efficiently.**
+
+This project does **not** attempt to quantify the real-world cost savings without clinical and operational validation. Economic impact remains a hypothesis requiring field evaluation.
+
+---
+
+## 13. System Architecture
+
+The target system is:
+
+```text
+                   ┌─────────────────┐
+                   │  Fundus Image   │
+                   └────────┬────────┘
+                            │
+                            ▼
+                   ┌─────────────────┐
+                   │  Preprocessing  │
+                   └────────┬────────┘
+                            │
+                            ▼
+                   ┌─────────────────┐
+                   │  Trained Model  │
+                   └────────┬────────┘
+                            │
+                            ▼
+                   ┌─────────────────┐
+                   │   Prediction    │
+                   └────────┬────────┘
+                            │
+              ┌─────────────┴─────────────┐
+              ▼                           ▼
+      Severity Estimate             Confidence
+              │
+              ▼
+      Screening / Triage
+      Recommendation
+```
+
+---
+
+## 14. Project Structure
+
+The final repository is expected to evolve toward:
+
+```text
+marconi-diabetic-retinopathy/
+│
+├── README.md
+├── requirements.txt
+├── train.py                  # Single-command training script (HF & W&B)
+│
+├── data/
+│   └── README.md
+│
+├── notebooks/
+│   ├── 01_eda.ipynb
+│   ├── 02_baseline.ipynb
+│   ├── 03_model_comparison.ipynb
+│   └── 04_final_model.ipynb
+│
+├── src/
+│   ├── __init__.py
+│   ├── data.py
+│   ├── preprocessing.py
+│   ├── models.py
+│   ├── train.py
+│   └── evaluate.py
+│
+├── models/
+│   └── README.md
+│
+├── results/
+│   ├── metrics.csv
+│   ├── model_comparison.csv
+│   └── figures/
+│
+├── deployment/
+│   ├── api/
+│   └── android/
+│
+└── presentation/
+    └── README.md
+```
+
+The exact structure will be adapted from the existing Marconi repositories rather than unnecessarily rebuilding working code.
+
+---
+
+## 15. Existing Marconi Work
+
+This project builds upon work completed during the internship.
+
+### Deep-learning foundations
+
+* Neural-network mechanics
+* Forward propagation
+* Backpropagation
+* Gradient descent
+* Keras
+* PyTorch
+* MNIST classification
+
+### Transfer learning
+
+* MobileNetV2
+* Custom PyTorch datasets
+* DataLoader pipelines
+* Image transforms
+
+### Architecture benchmarking
+
+Existing repositories:
+
+**ResNet vs DenseNet**
+
+[https://github.com/MichaelMukiibi/resnet-v-densenet.git](https://github.com/MichaelMukiibi/resnet-v-densenet.git)
+
+**ConvNeXt vs Swin**
+
+[https://github.com/MichaelMukiibi/convnext-v-swin.git](https://github.com/MichaelMukiibi/convnext-v-swin.git)
+
+### Hugging Face vision pipeline
+
+Existing repository:
+
+**Drone Landing Safety**
+
+[https://github.com/MichaelMukiibi/drone-landing-safety.git](https://github.com/MichaelMukiibi/drone-landing-safety.git)
+
+### Additional repositories
+
+**Omniglot**
+
+[https://github.com/MichaelMukiibi/omniglot.git](https://github.com/MichaelMukiibi/omniglot.git)
+
+**Electricity Consumption**
+
+[https://github.com/MichaelMukiibi/electricity-consumption.git](https://github.com/MichaelMukiibi/electricity-consumption.git)
+
+The first development task is to inspect these repositories and reuse the most mature training/evaluation infrastructure.
+
+---
+
+## 16. Immediate Execution Plan
+
+### Phase 1 — Repository inspection
+
+Inspect:
+
+1. `convnext-v-swin`
+2. `resnet-v-densenet`
+3. `drone-landing-safety`
+
+Identify:
+
+* Training scripts
+* Dataset loaders
+* Hugging Face integration
+* W&B integration
+* Evaluation functions
+* Existing checkpoints
+* Preprocessing functions
+* Existing plots
+
+### Phase 2 — APTOS integration
+
+Adapt the strongest existing pipeline to APTOS.
+
+Perform:
+
+* Dataset download
+* Data validation
+* EDA
+* Train/validation split
+* Preprocessing
+* Baseline training
+
+### Phase 3 — Model comparison
+
+Train feasible candidates:
+
+* ResNet
+* DenseNet
+* ConvNeXt
+* Swin
+
+Do not attempt unnecessarily large experiments given the closeout deadline.
+
+### Phase 4 — Evaluation
+
+Generate:
+
+* Confusion matrices
+* Accuracy
+* Precision
+* Recall
+* Sensitivity
+* Specificity
+* F1
+* Model size
+* Inference latency
+
+### Phase 5 — Final model
+
+Select a model using:
+
+```text
+Clinical relevance
++
+Predictive performance
++
+Computational efficiency
++
+Deployment feasibility
+```
+
+### Phase 6 — Deployment
+
+Implement either:
+
+* Android inference
+
+or
+
+* FastAPI inference service
+
+### Phase 7 — Closeout
+
+Prepare:
+
+* Working demo
+* Final repository
+* Results
+* Presentation
+* Technical Q&A preparation
+
+---
+
+## 17. Current Status
+
+### Completed
+
+* Deep-learning foundation training
+* PyTorch training
+* Transfer learning
+* Medical ML evaluation concepts
+* ResNet/DenseNet research
+* ConvNeXt/Swin research
+* W&B experiment tracking
+* Hugging Face vision workflows
+* EDA workflow development
+
+### In progress
+
+* Selecting the final economically meaningful capstone
+* Adapting existing vision pipelines to APTOS 2019
+* Model benchmarking
+* Final model selection
+* Deployment
+
+### Pending
+
+* Final trained APTOS model
+* Final evaluation results
+* Deployment implementation
+* End-to-end demo
+* Closeout presentation
+
+---
+
+## 18. Limitations
+
+This prototype has important limitations.
+
+* APTOS is a relatively small dataset compared with large-scale medical imaging datasets.
+* Dataset distribution may not represent the target population.
+* Dataset labels may contain uncertainty.
+* Image quality can vary substantially.
+* Model performance does not automatically translate to clinical effectiveness.
+* External validation is required.
+* Clinical workflow integration has not been established.
+* Regulatory approval would be required for clinical deployment.
+* Economic impact has not yet been empirically demonstrated.
+
+Therefore, the system should be presented as an **AI-assisted research prototype**, not as an autonomous diagnostic product.
+
+---
+
+## 19. Future Work
+
+Potential future development includes:
+
+* External validation on additional retinal datasets
+* Calibration of model confidence
+* Explainability methods such as Grad-CAM
+* Model quantization
+* ONNX/TensorFlow Lite conversion
+* On-device inference
+* Offline-first deployment
+* Prospective clinical validation
+* Integration with existing health-information systems
+* Human-in-the-loop referral workflows
+* Health-economic evaluation
+* Field testing in resource-constrained healthcare settings
+
+---
+
+## 20. Expected Capstone Outcome
+
+The final deliverable should demonstrate the complete ML lifecycle:
+
+```text
+REAL-WORLD PROBLEM
+       ↓
+DATA
+       ↓
+EDA
+       ↓
+MODEL DEVELOPMENT
+       ↓
+EXPERIMENT TRACKING
+       ↓
+ARCHITECTURE BENCHMARKING
+       ↓
+CLINICALLY RELEVANT EVALUATION
+       ↓
+MODEL SELECTION
+       ↓
+DEPLOYMENT
+       ↓
+WORKING DEMONSTRATION
+```
+
+The central objective is not merely to achieve a high classification score.
+
+The project aims to demonstrate that the intern can take a meaningful problem from **research question → machine-learning experimentation → engineering implementation → deployable prototype**.
+
+---
+
+## 21. Project Status
+
+**Status:** Active development
+**Intern:** MUKIIBI MICHAEL KIRINNYA
+**Capstone:** AI-Assisted Diabetic Retinopathy Screening & Triage
+**Dataset:** APTOS 2019 Blindness Detection
+**Primary ML Task:** Five-class diabetic-retinopathy severity classification
+**Deployment Requirement:** Android application **or** inference API

fastdrs-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+fastdrs/__init__.py,sha256=gmXsoS_boRaNYtP4QD08ygvVkSwdI_dDd-gTC8pGedo,30
+fastdrs/data.py,sha256=QmlE9o2if4kG1IRM99bihDvnnA5eSofE1pbKhPRY1Yk,4149
+fastdrs/evaluation.py,sha256=y3OvOJYvhjUV2MCWwzHtigXpNYKbLuntY9jycnBNeZo,3955
+fastdrs/models.py,sha256=n9o15ihvoTOjeUjPcok9APp6G8vFELGeZZl9aB7PIXA,3905
+fastdrs/preprocessing.py,sha256=gR3PDxUrbYeb7oyyifBK7xv15ZQuchdMsmeG7Z915Sw,2980
+fastdrs/training.py,sha256=zoNCjV896v6wzIRlSoLKWRhxhZ2UcBix1Iz1iBR1LEs,5487
+fastdrs/deployment/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastdrs/deployment/litert.py,sha256=inAsJXL5qgVXnWRcEhtFEEc1Lp8Q4-MW2JLZGPCRUEE,3
+fastdrs-0.1.0.dist-info/METADATA,sha256=8T1q4QjKUt7f6P4LJr-FzKsL2JtvJAF_IYZBHJzooK4,20054
+fastdrs-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+fastdrs-0.1.0.dist-info/RECORD,,

fastdrs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any