Update README.md

README.md

@@ -1,3 +1,295 @@
----
-license: apache-2.0
----
+---
+---
+license: mit
+tags:
+- medical-imaging
+- pcos-detection
+- explainable-ai
+- grad-cam
+- ultrasound
+- tensorflow
+language: en
+metrics:
+- accuracy
+library_name: tensorflow
+---
+
+# 🏥 PCOS Detection with Explainable AI
+
+A deep learning model for **Polycystic Ovary Syndrome (PCOS)** detection from ultrasound images with **Grad-CAM** visualization for clinical interpretability.
+
+## 🎯 Model Overview
+
+- **Architecture**: Dual-path CNN with multi-head attention
+- **Input**: 224×224 RGB ultrasound images  
+- **Output**: Binary classification (PCOS-positive / Healthy)
+- **Accuracy**: ~95%+ on test set
+- **XAI**: Grad-CAM heatmaps for interpretability
+
+## 🚀 Quick Start
+
+```bash
+pip install tensorflow opencv-python matplotlib numpy requests huggingface-hub
+```
+
+### Complete Working Example
+
+```python
+# ============================================================
+# 🔍 PCOS Prediction + Grad-CAM (HF VERSION)
+# ============================================================
+
+import numpy as np
+import cv2
+import tensorflow as tf
+import matplotlib.pyplot as plt
+from tensorflow.keras import Model, Input
+from tensorflow.keras.layers import (
+    Conv2D, MaxPooling2D, Flatten, Dense,
+    Lambda, Reshape, Concatenate,
+    MultiHeadAttention, GlobalAveragePooling1D
+)
+import requests
+from huggingface_hub import hf_hub_download
+
+# ============================================================
+# Config
+# ============================================================
+IMG_SIZE = (224, 224)
+HF_MODEL_REPO = "Dehsahk-AI/Pcos-Detect"
+MODEL_FILENAME = "best_pcos_model.h5"
+IMAGE_URL = "https://example.com/ultrasound.jpg"  # Your image URL
+CLASS_NAMES = ["infected", "noninfected"]
+
+# ============================================================
+# Download model from HF
+# ============================================================
+MODEL_PATH = hf_hub_download(repo_id=HF_MODEL_REPO, filename=MODEL_FILENAME)
+print(f"✅ Model downloaded to: {MODEL_PATH}")
+
+# ============================================================
+# Custom Lambda Functions
+# ============================================================
+def split_image(image):
+    upper = image[:, :IMG_SIZE[0]//2, :, :]
+    lower = image[:, IMG_SIZE[0]//2:, :, :]
+    return upper, lower
+
+def flip_lower(lower_half):
+    return tf.image.flip_left_right(lower_half)
+
+# ============================================================
+# Rebuild Model Architecture
+# ============================================================
+input_layer = Input(shape=(224,224,3))
+
+upper_half, lower_half = Lambda(split_image)(input_layer)
+lower_half = Lambda(flip_lower)(lower_half)
+
+# Upper CNN
+u = Conv2D(32, 3, activation="relu", padding="same")(upper_half)
+u = MaxPooling2D(2)(u)
+u = Conv2D(64, 3, activation="relu", padding="same")(u)
+u = MaxPooling2D(2)(u)
+u = Conv2D(128, 3, activation="relu", padding="same", name="upper_last_conv")(u)
+u = MaxPooling2D(2)(u)
+u = Flatten()(u)
+
+# Lower CNN
+l = Conv2D(32, 3, activation="relu", padding="same")(lower_half)
+l = MaxPooling2D(2)(l)
+l = Conv2D(64, 3, activation="relu", padding="same")(l)
+l = MaxPooling2D(2)(l)
+l = Conv2D(128, 3, activation="relu", padding="same", name="lower_last_conv")(l)
+l = MaxPooling2D(2)(l)
+l = Flatten()(l)
+
+u_dense = Dense(512, activation="relu")(u)
+l_dense = Dense(512, activation="relu")(l)
+
+u_r = Reshape((1,512))(u_dense)
+l_r = Reshape((1,512))(l_dense)
+
+concat = Concatenate(axis=1)([u_r, l_r])
+
+att = MultiHeadAttention(num_heads=4, key_dim=64)(concat, concat)
+att = GlobalAveragePooling1D()(att)
+
+fc = Dense(256, activation="relu")(att)
+fc = Dense(128, activation="relu")(fc)
+
+# Logits for Grad-CAM
+logits = Dense(2, name="logits")(fc)
+output = tf.keras.layers.Activation('softmax', name='softmax')(logits)
+
+model = Model(input_layer, output)
+model.load_weights(MODEL_PATH)
+print("✅ Weights loaded successfully")
+
+# ============================================================
+# Load & Preprocess Image
+# ============================================================
+response = requests.get(IMAGE_URL)
+img_array_raw = np.asarray(bytearray(response.content), dtype=np.uint8)
+img = cv2.imdecode(img_array_raw, cv2.IMREAD_COLOR)
+img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+img = cv2.resize(img, IMG_SIZE)
+img = img.astype(np.float32) / 255.0
+img_array = np.expand_dims(img, axis=0)
+
+# ============================================================
+# Prediction
+# ============================================================
+pred = model.predict(img_array, verbose=0)[0]
+pred_class = np.argmax(pred)
+confidence = pred[pred_class]
+
+print(f"\n🔍 Prediction: {CLASS_NAMES[pred_class]}")
+print(f"📊 Confidence: {confidence:.2%}")
+
+# ============================================================
+# Grad-CAM
+# ============================================================
+def gradcam(img_array, model, layer_name, pred_index):
+    logits_layer = model.get_layer('logits')
+    grad_model = Model(
+        model.input,
+        [model.get_layer(layer_name).output, logits_layer.output]
+    )
+
+    with tf.GradientTape() as tape:
+        conv_out, logits = grad_model(img_array)
+        loss = logits[:, pred_index]
+
+    grads = tape.gradient(loss, conv_out)
+    pooled = tf.reduce_mean(grads, axis=(0,1,2))
+    conv_out = conv_out[0]
+
+    heatmap = conv_out @ pooled[..., tf.newaxis]
+    heatmap = tf.squeeze(heatmap)
+    heatmap = tf.maximum(heatmap, 0)
+
+    if tf.reduce_max(heatmap) > 0:
+        heatmap /= tf.reduce_max(heatmap)
+
+    return heatmap.numpy()
+
+upper = gradcam(img_array, model, "upper_last_conv", pred_class)
+lower = gradcam(img_array, model, "lower_last_conv", pred_class)
+
+h = IMG_SIZE[0] // 2
+upper = cv2.resize(upper, (IMG_SIZE[1], h))
+lower = cv2.resize(lower, (IMG_SIZE[1], h))
+lower = cv2.flip(lower, 1)
+
+heatmap = np.vstack([upper, lower])
+
+heatmap_color = cv2.applyColorMap(np.uint8(255*heatmap), cv2.COLORMAP_JET)
+heatmap_color = cv2.cvtColor(heatmap_color, cv2.COLOR_BGR2RGB) / 255.0
+
+overlay = 0.5 * heatmap_color + 0.5 * img
+
+# ============================================================
+# Visualization
+# ============================================================
+plt.figure(figsize=(15,5))
+
+plt.subplot(1,3,1)
+plt.imshow(img)
+plt.title("Original")
+plt.axis("off")
+
+plt.subplot(1,3,2)
+plt.imshow(heatmap, cmap="jet")
+plt.title("Grad-CAM")
+plt.axis("off")
+
+plt.subplot(1,3,3)
+plt.imshow(overlay)
+plt.title(f"{CLASS_NAMES[pred_class]} ({confidence:.2%})")
+plt.axis("off")
+
+plt.tight_layout()
+plt.show()
+```
+
+### Load from Local File
+
+```python
+# Replace URL loading with:
+img = cv2.imread('path/to/ultrasound.jpg')
+img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+img = cv2.resize(img, IMG_SIZE)
+img = img.astype(np.float32) / 255.0
+img_array = np.expand_dims(img, axis=0)
+```
+
+## 🔬 Understanding Grad-CAM Output
+
+- **Red/Hot regions**: High importance for prediction (follicles, cysts)
+- **Blue/Cool regions**: Low influence on decision
+- **Dual visualization**: Separate heatmaps for upper and lower ovarian regions
+
+## 📊 Model Architecture
+
+```
+Input (224×224×3)
+├── Split horizontally (upper/lower)
+├── Upper Path: Conv32 → Conv64 → Conv128 → Dense512
+├── Lower Path: Conv32 → Conv64 → Conv128 → Dense512
+├── Multi-Head Attention (4 heads, dim=64)
+└── Classification: Dense256 → Dense128 → Dense2
+```
+
+**Key Features:**
+- Dual-path CNN for separate ovarian region analysis
+- Lower region flipped for symmetry normalization  
+- Multi-head attention for feature fusion
+- Logits-based Grad-CAM (fixes saturated softmax gradients)
+
+## 📈 Dataset
+
+- **Total**: 11,784 ultrasound images
+- **PCOS-positive**: 6,784 images (57.5%)
+- **Healthy**: 5,000 images (42.5%)
+- **Source**: 3 clinics (2018-2022), expert-annotated
+- **Dataset**: [PCOS XAI Ultrasound](https://www.kaggle.com/datasets/...)
+
+## ⚠️ Important Notes
+
+**Clinical Use:**
+- ⚠️ Research purposes only - NOT FDA approved
+- ⚠️ Not a diagnostic tool - requires professional validation
+- ⚠️ Must be validated on local datasets before clinical deployment
+
+**Technical:**
+- Fixed 224×224 input size required
+- RGB images only
+- Model performance may vary across different ultrasound machines
+
+## 📝 Citation
+
+```bibtex
+@misc{pcos_xai_2024,
+  title={PCOS Detection with Explainable AI},
+  author={Dehsahk-AI},
+  year={2024},
+  url={https://huggingface.co/Dehsahk-AI/Pcos-Detect}
+}
+```
+
+## 📜 License
+
+MIT License - See LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+- Grad-CAM: Selvaraju et al. (ICCV 2017)
+- Multi-head Attention: Vaswani et al. (NeurIPS 2017)
+- Dataset from clinical retrospective studies with ethical compliance
+
+---
+
+**Model Version**: 1.0 | **Last Updated**: December 2024
+license: apache-2.0
+---