Upload 5 files

README.md

@@ -5,49 +5,193 @@ tags:
   - ophthalmology
   - image-classification
   - explainable-ai
-  - core-ml
   - grad-cam
+  - core-ml
+  - resnet
+  - pytorch
 language:
   - zh
   - en
 metrics:
   - roc_auc
+  - f1
+pipeline_tag: image-classification
 ---
 
 # ELIAS — Eyelid Lesion Intelligent Analysis System
 
-**AUC 0.93 · iPhone 即時推論 < 1s · 2026 智慧創新大賞參賽作品**
+**眼瞼疾病智慧分析系統**
+
+> 🏆 2026 年經濟部智慧創新大賞（學生組）參賽作品
+
+---
 
 ## Model Description
-Clinician-guided deep learning classifier for epiblepharon detection
-from external eye photographs. Uses a frozen ImageNet-pretrained
-ResNet-18 backbone with a task-specific classification head.
 
-- **Architecture**: ResNet-18 (frozen) + Linear head
-- **Training**: 5-fold cross-validation, BCEWithLogitsLoss
-- **Explainability**: Native PyTorch Grad-CAM (layer4)
-- **Deployment**: Apple Core ML, on-device iOS inference < 1s
+ELIAS is a **clinician-guided deep learning classifier** for automated detection of **epiblepharon** (睫毛倒插) from external eye photographs.
 
-## Performance (5-Fold Cross-Validation)
-| Metric | Value |
+The model uses a **frozen ImageNet-pretrained ResNet-18 backbone** with a task-specific classification head. The key innovation is the explicit integration of clinician-defined anatomical **Regions of Interest (ROI)** — specifically the lower eyelid margin and eyelash–cornea interface — as a prior constraint, enabling robust classification in a **small-data regime (~80–150 cases per class)**.
+
+### Architecture
+
+```
+Input (224×224 RGB)
+    │
+    ▼
+ResNet-18 backbone (frozen, ImageNet pretrained)
+    │  layer1 → layer2 → layer3 → layer4
+    │  Global Average Pooling → (512,)
+    ▼
+Dropout(0.3) → Linear(512 → 2)
+    │
+    ▼
+Softmax → [P(control), P(epiblepharon)]
+```
+
+| Component | Detail |
+|---|---|
+| Backbone | ResNet-18 (ImageNet pretrained, **fully frozen**) |
+| Classification head | `Dropout(0.3)` + `Linear(512 → 2)` |
+| Loss function | `CrossEntropyLoss` |
+| Optimizer | `Adam(lr=1e-3)`, head parameters only |
+| Input size | 224 × 224 px, RGB (Grayscale → 3ch conversion applied) |
+| Normalization | ImageNet mean/std `[0.485, 0.456, 0.406]` / `[0.229, 0.224, 0.225]` |
+
+---
+
+## Performance
+
+Evaluated by **stratified 5-fold cross-validation** (`random_state=42`, 20 epochs/fold).
+
+| Metric | Mean (5-fold) |
 |---|---|
-| AUC | **0.93** |
+| **AUC** | **0.93** |
+| Accuracy | High |
 | Sensitivity | High |
 | Specificity | Moderate |
 | F1 Score | High |
 
-## Intended Use
-Research prototype for clinical decision support in
-epiblepharon screening. **Not a validated medical device.**
+- ✅ No fold collapse observed across all 5 folds
+- ✅ Label-shuffling negative control confirmed genuine feature learning
+- ✅ ROI ablation experiments validated lower eyelid margin as primary diagnostic signal
+
+### ROI Ablation Summary
+
+| Condition | Performance vs Baseline |
+|---|---|
+| Full image (baseline) | ✅ Optimal |
+| ROI ablated (lower eyelid blurred) | ❌ Significant drop |
+| Non-ROI ablated (ROI preserved) | ✅ Near-baseline |
+
+> Diagnostic features are **spatially localized** to the clinically defined lower eyelid margin — consistent with clinical examination principles for epiblepharon.
+
+---
+
+## Grad-CAM Explainability
+
+Grad-CAM heatmaps were generated using native PyTorch hooks on `layer4` (no Captum dependency):
+
+- **Epiblepharon cases**: Activation consistently focused on **lower eyelid margin and eyelash–cornea interface**
+- **Control cases**: Diffuse, anatomically unfocused activation patterns
+
+Heatmap overlay: α = 0.45, JET colormap, bilinear upsampling to 224×224.
+
+---
+
+## iOS On-Device Inference
 
-## Source Code
-GitHub: https://github.com/YOUR_USERNAME/ELIAS
+The trained model has been converted to **Apple Core ML** format (`.mlpackage`):
+
+| Metric | Value |
+|---|---|
+| Model size | < 50 MB |
+| Inference latency | **< 1 second / image** |
+| Device | iPhone 12+ (A14+ Neural Engine) |
+| Network required | ❌ None — fully on-device |
+
+Privacy: facial images never leave the device, consistent with PDPA / HIPAA principles.
+
+---
+
+## Training Data
+
+- **Task**: Binary classification — epiblepharon vs. control
+- **Image type**: External eye photographs
+- **Dataset size**: ~80–150 cases per class (single-center, retrospective)
+- **Preprocessing**: Resize 224×224, Grayscale→3ch, ColorJitter, RandomHorizontalFlip, ImageNet normalization
+
+> ⚠️ Clinical images are **not distributed** in this repository due to patient privacy regulations (Personal Data Protection Act, IRB). For academic collaboration, please contact the corresponding author.
+
+---
+
+## Usage
+
+```python
+import torch
+from torchvision import models, transforms
+from PIL import Image
+
+# Load model
+model = models.resnet18(weights=None)
+for param in model.parameters():
+    param.requires_grad = False
+model.fc = torch.nn.Linear(model.fc.in_features, 2)
+model.load_state_dict(torch.load("pytorch_model.pt", map_location="cpu"))
+model.eval()
+
+# Preprocess
+transform = transforms.Compose([
+    transforms.Resize((224, 224)),
+    transforms.Grayscale(num_output_channels=3),
+    transforms.ToTensor(),
+    transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
+])
+
+img = Image.open("eye_photo.jpg").convert("RGB")
+x = transform(img).unsqueeze(0)  # (1, 3, 224, 224)
+
+with torch.no_grad():
+    logits = model(x)
+    prob = torch.softmax(logits, dim=1)[0, 1].item()
+    print(f"Epiblepharon probability: {prob:.3f}")
 ```
 
 ---
 
-### Step 5 — 取得佐證連結
+## Files in This Repository
+
+| File | Description |
+|---|---|
+| `README.md` | This model card |
+| `model.py` | Model architecture definition |
+| `train.py` | 5-fold cross-validation training script |
+| `config.json` | Model configuration |
+| `requirements.txt` | Python dependencies |
+| `pytorch_model.pt` | *(Checkpoint — upload separately after training)* |
+
+---
+
+## Intended Use & Limitations
+
+- **Intended use**: Research prototype for clinical decision support in epiblepharon screening
+- **NOT** a validated medical device — prospective evaluation and regulatory assessment required before clinical deployment
+- Single-center retrospective data — generalizability across imaging conditions and demographics requires multi-center validation
 
-上傳完成後，你的 Hugging Face 頁面會是：
+---
+
+## Citation
+
+```bibtex
+@misc{elias2026,
+  title     = {ELIAS: Eyelid Lesion Intelligent Analysis System},
+  year      = {2026},
+  note      = {2026 MOEA Smart Innovation Award submission},
+  url       = {https://huggingface.co/YOUR_HF_USERNAME/ELIAS-epiblepharon}
+}
 ```
-https://huggingface.co/YOUR_HF_USERNAME/ELIAS-epiblepharon
+
+---
+
+## License
+
+[MIT License](LICENSE) — Source code only. Clinical data excluded.

config.json

@@ -0,0 +1,46 @@
+{
+  "model_name": "ELIAS-epiblepharon",
+  "model_type": "resnet18",
+  "architecture": "ResNet-18 (frozen ImageNet backbone + task-specific head)",
+  "task": "binary-image-classification",
+  "disease": "epiblepharon",
+  "num_classes": 2,
+  "id2label": {
+    "0": "control",
+    "1": "epiblepharon"
+  },
+  "label2id": {
+    "control": 0,
+    "epiblepharon": 1
+  },
+  "image_size": 224,
+  "input_channels": 3,
+  "preprocessing": {
+    "resize": [224, 224],
+    "grayscale_to_3ch": true,
+    "normalize_mean": [0.485, 0.456, 0.406],
+    "normalize_std": [0.229, 0.224, 0.225]
+  },
+  "training": {
+    "backbone_frozen": true,
+    "optimizer": "Adam",
+    "learning_rate": 0.001,
+    "epochs": 20,
+    "batch_size": 32,
+    "loss": "CrossEntropyLoss",
+    "validation": "StratifiedKFold(n_splits=5, random_state=42)"
+  },
+  "performance": {
+    "auc": 0.93,
+    "validation_strategy": "5-fold cross-validation",
+    "note": "No fold collapse observed"
+  },
+  "deployment": {
+    "ios_coreml": true,
+    "inference_latency_ms": "<1000",
+    "device": "iPhone 12+ (A14+ Neural Engine)",
+    "model_size_mb": "<50"
+  },
+  "framework": "pytorch",
+  "torch_version": ">=2.0.0"
+}

model.py

@@ -0,0 +1,65 @@
+"""
+ELIAS — Eyelid Lesion Intelligent Analysis System
+model.py
+
+Frozen ResNet-18 classifier for epiblepharon detection.
+Compatible with Hugging Face model loading.
+"""
+
+import torch
+import torch.nn as nn
+from torchvision import models
+
+
+def build_elias_model(num_classes: int = 2, freeze_backbone: bool = True) -> nn.Module:
+    """
+    Build ELIAS classifier.
+
+    Args:
+        num_classes:      2 for binary (CrossEntropyLoss)
+        freeze_backbone:  Freeze all layers except the final FC head.
+
+    Returns:
+        ResNet-18 model with task-specific classification head.
+    """
+    model = models.resnet18(weights=models.ResNet18_Weights.IMAGENET1K_V1)
+
+    if freeze_backbone:
+        for param in model.parameters():
+            param.requires_grad = False
+
+    # Replace final FC with task-specific head
+    in_features = model.fc.in_features  # 512
+    model.fc = nn.Sequential(
+        nn.Dropout(p=0.3),
+        nn.Linear(in_features, num_classes),
+    )
+
+    return model
+
+
+def load_elias_model(checkpoint_path: str, device: str = "cpu") -> nn.Module:
+    """
+    Load a trained ELIAS model from checkpoint.
+
+    Usage:
+        model = load_elias_model("pytorch_model.pt")
+    """
+    model = build_elias_model()
+    state_dict = torch.load(checkpoint_path, map_location=device)
+    model.load_state_dict(state_dict)
+    model.eval()
+    return model
+
+
+if __name__ == "__main__":
+    model = build_elias_model()
+    trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
+    total = sum(p.numel() for p in model.parameters())
+    print(f"Trainable parameters: {trainable:,} / {total:,}")
+
+    # Sanity check
+    x = torch.randn(2, 3, 224, 224)
+    with torch.no_grad():
+        out = model(x)
+    print(f"Output shape: {out.shape}")  # (2, 2)

requirements.txt

@@ -0,0 +1,9 @@
+torch>=2.0.0
+torchvision>=0.15.0
+numpy>=1.24.0
+scikit-learn>=1.3.0
+matplotlib>=3.7.0
+seaborn>=0.12.0
+pandas>=2.0.0
+openpyxl>=3.1.0
+Pillow>=9.5.0

train.py

@@ -0,0 +1,302 @@
+"""
+ELIAS — Eyelid Lesion Intelligent Analysis System
+train.py
+
+Stratified 5-fold cross-validation training pipeline.
+Extracted and refactored from gemini_crossval_masked.ipynb.
+
+Usage:
+    python train.py --data_dir ./data/data --output_dir ./outputs
+
+Data directory structure:
+    data/data/
+    ├── epiblepharon/   (positive class)
+    └── control/        (negative class)
+"""
+
+import argparse
+import os
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from sklearn.metrics import auc, confusion_matrix, f1_score, roc_curve
+from sklearn.model_selection import StratifiedKFold
+from torch.utils.data import DataLoader, Subset
+from torchvision import datasets, models, transforms
+
+from model import build_elias_model
+
+
+# ── Hyperparameters ────────────────────────────────────────────────────────────
+BATCH_SIZE   = 32
+EPOCHS       = 20
+LR           = 1e-3
+N_FOLDS      = 5
+RANDOM_STATE = 42
+IMAGE_SIZE   = 224
+
+
+# ── Dataset Utilities ──────────────────────────────────────────────────────────
+
+class ApplyTransform(torch.utils.data.Dataset):
+    """Wrapper to apply different transforms to train/val subsets."""
+    def __init__(self, subset, transform=None):
+        self.subset    = subset
+        self.transform = transform
+
+    def __getitem__(self, index):
+        x, y = self.subset[index]
+        if self.transform:
+            x = self.transform(x)
+        return x, y
+
+    def __len__(self):
+        return len(self.subset)
+
+
+def get_transforms():
+    """
+    Returns train and validation transform pipelines.
+
+    Note: Grayscale(num_output_channels=3) is applied to normalize
+    illumination variation across clinical photographs while maintaining
+    3-channel input compatibility with ImageNet-pretrained ResNet-18.
+    """
+    train_tf = transforms.Compose([
+        transforms.Resize((IMAGE_SIZE, IMAGE_SIZE)),
+        transforms.Grayscale(num_output_channels=3),
+        transforms.ColorJitter(brightness=0.5, contrast=0.5, saturation=0.5),
+        transforms.RandomHorizontalFlip(),
+        transforms.ToTensor(),
+        transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
+    ])
+    val_tf = transforms.Compose([
+        transforms.Resize((IMAGE_SIZE, IMAGE_SIZE)),
+        transforms.Grayscale(num_output_channels=3),
+        transforms.ToTensor(),
+        transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
+    ])
+    return train_tf, val_tf
+
+
+# ── Training & Evaluation ──────────────────────────────────────────────────────
+
+def train_one_epoch(model, loader, criterion, optimizer, device):
+    model.train()
+    running_loss = 0.0
+    for inputs, labels in loader:
+        inputs, labels = inputs.to(device), labels.to(device)
+        optimizer.zero_grad()
+        outputs = model(inputs)
+        loss = criterion(outputs, labels)
+        loss.backward()
+        optimizer.step()
+        running_loss += loss.item() * inputs.size(0)
+    return running_loss / len(loader.dataset)
+
+
+@torch.no_grad()
+def evaluate(model, loader, device):
+    model.eval()
+    y_true, y_probs, y_pred = [], [], []
+    correct = 0
+    for inputs, labels in loader:
+        inputs, labels = inputs.to(device), labels.to(device)
+        outputs = model(inputs)
+        probs   = torch.softmax(outputs, dim=1)[:, 1]
+        preds   = torch.argmax(outputs, dim=1)
+        correct += (preds == labels).sum().item()
+        y_true.extend(labels.cpu().numpy())
+        y_probs.extend(probs.cpu().numpy())
+        y_pred.extend(preds.cpu().numpy())
+    acc = correct / len(loader.dataset)
+    return acc, np.array(y_true), np.array(y_probs), np.array(y_pred)
+
+
+def compute_fold_metrics(y_true, y_probs, y_pred, class_names):
+    """Compute sensitivity, specificity, F1, AUC from fold predictions."""
+    cm = confusion_matrix(y_true, y_pred)
+    tn, fp, fn, tp = cm.ravel()
+    sensitivity = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+    specificity  = tn / (tn + fp) if (tn + fp) > 0 else 0.0
+    f1           = f1_score(y_true, y_pred)
+    fpr, tpr, _  = roc_curve(y_true, y_probs)
+    fold_auc     = auc(fpr, tpr)
+    return {
+        "sensitivity": sensitivity,
+        "specificity":  specificity,
+        "f1":           f1,
+        "auc":          fold_auc,
+        "fpr":          fpr,
+        "tpr":          tpr,
+        "cm":           cm,
+    }
+
+
+# ── Plotting ───────────────────────────────────────────────────────────────────
+
+def save_confusion_matrix(cm, class_names, fold_idx, output_dir):
+    plt.figure(figsize=(6, 5))
+    sns.heatmap(
+        cm, annot=True, fmt="d", cmap="Blues",
+        xticklabels=class_names, yticklabels=class_names,
+    )
+    plt.title(f"Confusion Matrix — Fold {fold_idx + 1}")
+    plt.ylabel("Actual"); plt.xlabel("Predicted")
+    path = os.path.join(output_dir, f"confusion_matrix_fold_{fold_idx + 1}.png")
+    plt.savefig(path, dpi=120, bbox_inches="tight")
+    plt.close()
+
+
+def save_roc_curves(roc_data, output_dir):
+    plt.figure(figsize=(8, 6))
+    for fold_idx, (fpr, tpr, fold_auc) in enumerate(roc_data):
+        plt.plot(fpr, tpr, label=f"Fold {fold_idx + 1} (AUC = {fold_auc:.3f})")
+    plt.plot([0, 1], [0, 1], "k--", linewidth=1)
+    plt.xlabel("False Positive Rate"); plt.ylabel("True Positive Rate")
+    plt.title("ROC Curves — 5-Fold Cross-Validation")
+    plt.legend(loc="lower right")
+    path = os.path.join(output_dir, "roc_curves.png")
+    plt.savefig(path, dpi=120, bbox_inches="tight")
+    plt.close()
+    print(f"[ELIAS] ROC curve saved → {path}")
+
+
+def save_learning_curves(all_train_loss, all_val_acc, output_dir):
+    fig, axes = plt.subplots(1, 2, figsize=(12, 4))
+    axes[0].plot(np.mean(all_train_loss, axis=0), linewidth=2)
+    axes[0].fill_between(
+        range(EPOCHS),
+        np.mean(all_train_loss, axis=0) - np.std(all_train_loss, axis=0),
+        np.mean(all_train_loss, axis=0) + np.std(all_train_loss, axis=0),
+        alpha=0.2,
+    )
+    axes[0].set_title("Mean Training Loss (±SD)"); axes[0].set_xlabel("Epoch")
+
+    axes[1].plot(np.mean(all_val_acc, axis=0), linewidth=2, color="tab:orange")
+    axes[1].fill_between(
+        range(EPOCHS),
+        np.mean(all_val_acc, axis=0) - np.std(all_val_acc, axis=0),
+        np.mean(all_val_acc, axis=0) + np.std(all_val_acc, axis=0),
+        alpha=0.2, color="tab:orange",
+    )
+    axes[1].set_title("Mean Validation Accuracy (±SD)"); axes[1].set_xlabel("Epoch")
+
+    plt.tight_layout()
+    path = os.path.join(output_dir, "learning_curves.png")
+    plt.savefig(path, dpi=120, bbox_inches="tight")
+    plt.close()
+    print(f"[ELIAS] Learning curves saved → {path}")
+
+
+# ── Main ───────────────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(description="ELIAS 5-Fold Cross-Validation")
+    parser.add_argument("--data_dir",   type=str, default="./data/data")
+    parser.add_argument("--output_dir", type=str, default="./outputs")
+    args = parser.parse_args()
+
+    os.makedirs(args.output_dir, exist_ok=True)
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"[ELIAS] Device: {device}")
+
+    # ── Load dataset ─────────────────────────────────────────────────────
+    full_dataset = datasets.ImageFolder(args.data_dir)
+    labels       = np.array(full_dataset.targets)
+    class_names  = full_dataset.classes
+    print(f"[ELIAS] Classes: {class_names}")
+    print(f"[ELIAS] Total samples: {len(full_dataset)}")
+
+    train_tf, val_tf = get_transforms()
+
+    # ── Cross-validation setup ────────────────────────────────────────────
+    skf = StratifiedKFold(n_splits=N_FOLDS, shuffle=True, random_state=RANDOM_STATE)
+
+    all_train_loss = np.zeros((N_FOLDS, EPOCHS))
+    all_val_acc    = np.zeros((N_FOLDS, EPOCHS))
+    fold_results   = []
+    roc_data       = []
+
+    # ── Fold loop ─────────────────────────────────────────────────────────
+    for fold, (train_ids, val_ids) in enumerate(skf.split(np.zeros(len(labels)), labels)):
+        print(f"\n{'='*20} FOLD {fold + 1}/{N_FOLDS} {'='*20}")
+        print(f"  Train: {len(train_ids)} | Val: {len(val_ids)}")
+
+        train_data   = ApplyTransform(Subset(full_dataset, train_ids), transform=train_tf)
+        val_data     = ApplyTransform(Subset(full_dataset, val_ids),   transform=val_tf)
+        train_loader = DataLoader(train_data, batch_size=BATCH_SIZE, shuffle=True,  num_workers=2)
+        val_loader   = DataLoader(val_data,   batch_size=BATCH_SIZE, shuffle=False, num_workers=2)
+
+        model     = build_elias_model(num_classes=2, freeze_backbone=True).to(device)
+        criterion = nn.CrossEntropyLoss()
+        optimizer = optim.Adam(model.fc.parameters(), lr=LR)
+
+        # Epoch loop
+        for epoch in range(EPOCHS):
+            train_loss = train_one_epoch(model, train_loader, criterion, optimizer, device)
+            val_acc, _, _, _ = evaluate(model, val_loader, device)
+            all_train_loss[fold, epoch] = train_loss
+            all_val_acc[fold, epoch]    = val_acc
+            print(
+                f"  Epoch {epoch + 1:02d}/{EPOCHS}  "
+                f"loss={train_loss:.4f}  val_acc={val_acc:.4f}"
+            )
+
+        # Final fold evaluation
+        val_acc, y_true, y_probs, y_pred = evaluate(model, val_loader, device)
+        metrics = compute_fold_metrics(y_true, y_probs, y_pred, class_names)
+
+        print(
+            f"\n  ✅ Fold {fold + 1} | "
+            f"AUC={metrics['auc']:.4f}  "
+            f"Sen={metrics['sensitivity']:.3f}  "
+            f"Spe={metrics['specificity']:.3f}  "
+            f"F1={metrics['f1']:.3f}"
+        )
+
+        fold_results.append({
+            "Fold":        fold + 1,
+            "Accuracy":    val_acc,
+            "Sensitivity": metrics["sensitivity"],
+            "Specificity": metrics["specificity"],
+            "F1 Score":    metrics["f1"],
+            "AUC":         metrics["auc"],
+        })
+        roc_data.append((metrics["fpr"], metrics["tpr"], metrics["auc"]))
+
+        # Save confusion matrix per fold
+        save_confusion_matrix(metrics["cm"], class_names, fold, args.output_dir)
+
+        # Save best model checkpoint (fold-specific)
+        ckpt_path = os.path.join(args.output_dir, f"pytorch_model_fold{fold + 1}.pt")
+        torch.save(model.state_dict(), ckpt_path)
+
+    # ── Aggregate results ─────────────────────────────────────────────────
+    results_df = pd.DataFrame(fold_results)
+    avg_row    = results_df.mean(numeric_only=True).to_dict()
+    avg_row["Fold"] = "Average"
+    results_df = pd.concat([results_df, pd.DataFrame([avg_row])], ignore_index=True)
+
+    excel_path = os.path.join(args.output_dir, "model_performance_results.xlsx")
+    results_df.to_excel(excel_path, index=False)
+
+    print(f"\n{'='*60}")
+    print("  CROSS-VALIDATION SUMMARY")
+    print(f"{'='*60}")
+    print(results_df.to_string(index=False))
+
+    # ── Save plots ────────────────────────────────────────────────────────
+    save_roc_curves(roc_data, args.output_dir)
+    save_learning_curves(all_train_loss, all_val_acc, args.output_dir)
+
+    print(f"\n[ELIAS] All outputs saved to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()