docs: add model card

README.md

@@ -0,0 +1,205 @@
+---
+license: mit
+language: en
+library_name: tensorflow
+tags:
+  - medical-imaging
+  - chest-xray
+  - pneumonia-detection
+  - pediatric
+  - computer-vision
+  - cross-validation
+datasets:
+  - paultimothymooney/chest-xray-pneumonia
+  - iamtanmayshukla/pneumonia-radiography-dataset
+metrics:
+  - accuracy
+  - sensitivity
+  - specificity
+model-index:
+- name: PneumoDetectAI
+  results:
+  - task:
+      type: image-classification
+      name: Pediatric Pneumonia Detection
+    dataset:
+      name: Cross-Operator Validation Dataset
+      type: medical-imaging
+    metrics:
+      - type: accuracy
+        name: Cross-Operator Accuracy
+        value: 0.86
+      - type: sensitivity
+        name: Sensitivity
+        value: 0.964
+      - type: specificity
+        name: Specificity
+        value: 0.748
+---
+
+# PneumoDetectAI
+
+Binary classification model for pneumonia detection in pediatric chest X-rays (ages 1-5). Built with TensorFlow and MobileNetV2, validated on independent operator cohort with 86% accuracy and 96.4% sensitivity.
+
+**Author**: Ayushi Rathour  
+**Contact**: [email protected]  
+**Framework**: TensorFlow 2.19  
+**Model Size**: ~14 MB  
+
+## Model Overview
+
+PneumoDetectAI is a deep learning model designed to detect pneumonia in chest X-rays of pediatric patients aged 1 to 5 years. The model uses transfer learning from MobileNetV2 for efficient inference while maintaining clinically relevant performance.
+
+### Key Specifications
+
+| Property | Value |
+|----------|-------|
+| **Architecture** | MobileNetV2 (ImageNet pretrained) + custom head |
+| **Input Shape** | 224 × 224 × 3 (RGB) |
+| **Output** | Binary classification (NORMAL/PNEUMONIA) |
+| **File Format** | TensorFlow SavedModel (.h5) |
+| **Model Size** | ~14 MB |
+| **Inference Time** | 0.46 seconds on CPU |
+| **Target Population** | Pediatric patients (1-5 years) |
+
+### Intended Users
+- ML researchers working on medical imaging
+- Healthcare AI developers building screening tools
+- Students learning medical AI validation approaches
+- Radiologists interested in AI-assisted screening
+
+## Performance Metrics
+
+| Validation Type | Dataset | Samples | Accuracy | Sensitivity | Specificity |
+|-----------------|---------|---------|----------|-------------|-------------|
+| **Internal** | Mooney 2018 | 269 | 94.8% | 89.6% | 100% |
+| **Cross-Operator** | Radiography 2024 | 485 | **86.0%** | **96.4%** | 74.8% |
+
+### Clinical Interpretation
+- **High Sensitivity (96.4%)**: Catches 96 out of 100 pneumonia cases, suitable for screening
+- **Moderate Specificity (74.8%)**: 25% false positive rate acceptable for screening tool
+- **Generalization**: 8.8% accuracy drop on independent cohort indicates reasonable robustness
+
+## Quick Start Usage
+
+```python
+from huggingface_hub import hf_hub_download
+import tensorflow as tf
+import numpy as np
+from PIL import Image
+
+# Download and load model
+model_path = hf_hub_download(
+    repo_id="ayushirathour/chest-xray-pneumonia-detection",
+    filename="best_chest_xray_model.h5"
+)
+model = tf.keras.models.load_model(model_path)
+
+# Preprocess image
+def preprocess_xray(image_path):
+    img = Image.open(image_path).convert("RGB").resize((224, 224))
+    img_array = np.array(img) / 255.0
+    return np.expand_dims(img_array, axis=0)
+
+# Make prediction
+image_array = preprocess_xray("chest_xray.jpg")
+probability = model.predict(image_array)[0][0]
+diagnosis = "PNEUMONIA" if probability >= 0.5 else "NORMAL"
+confidence = probability * 100 if probability >= 0.5 else (1 - probability) * 100
+
+print(f"Diagnosis: {diagnosis}")
+print(f"Confidence: {confidence:.1f}%")
+```
+
+## Training Details
+
+### Datasets
+- **Training Data**: Chest X-Ray Images (Pneumonia) by Paul Timothy Mooney
+  - Source: Guangzhou Women and Children's Medical Center
+  - Size: ~5,863 images (pediatric patients aged 1-5)
+  - Split: Pre-divided train/validation/test
+
+- **External Validation**: Pneumonia Radiography Dataset by Tanmay Shukla
+  - Source: Same hospital, different operators and time period
+  - Size: 485 independent samples
+  - Purpose: Cross-operator generalization testing
+
+### Architecture Details
+- **Base Model**: MobileNetV2 (ImageNet weights frozen initially)
+- **Custom Head**: Global Average Pooling → Dropout (0.5) → Dense (128) → Dense (1, sigmoid)
+- **Optimization**: Adam optimizer (lr=0.0001)
+- **Loss Function**: Binary crossentropy
+- **Training**: 20 epochs with early stopping
+
+## Limitations & Risks
+
+### Technical Limitations
+- **Single Institution**: Both datasets from same medical center
+- **Age Restriction**: Validated only on pediatric patients (1-5 years)
+- **Binary Output**: Cannot distinguish pneumonia subtypes (viral vs bacterial)
+- **Image Quality**: Performance degrades with poor quality or non-standard views
+
+### Clinical Limitations
+- **False Positive Rate**: 25.2% may increase radiologist workload
+- **Screening Only**: Not suitable for definitive diagnosis
+- **Population Bias**: Trained on Asian pediatric cohort only
+- **No Clinical Context**: Cannot incorporate patient history or symptoms
+
+### Deployment Risks
+- **Overconfidence**: High sensitivity may create false sense of security
+- **Misuse**: Risk of use without proper medical oversight
+- **Generalization**: Performance may vary on different imaging equipment
+
+## Responsible AI & Ethics
+
+### Bias Considerations
+- **Population Bias**: Model trained exclusively on Asian pediatric population
+- **Institutional Bias**: Single medical center may not represent global imaging practices
+- **Age Bias**: Performance on other age groups unknown
+
+### Required Safeguards
+- **Human Oversight**: All predictions must be reviewed by qualified radiologists
+- **Screening Context**: Should only be used as preliminary screening tool
+- **Informed Consent**: Patients must be informed of AI involvement in screening
+- **Quality Assurance**: Regular monitoring of real-world performance required
+
+### Regulatory Status
+- **Not FDA Approved**: Research prototype only
+- **Not CE Marked**: Not approved for clinical use in EU
+- **Research Use**: Intended for academic and development purposes only
+
+## Citation
+
+```bibtex
+@misc{rathour2025pneumodetectai,
+    title={PneumoDetectAI: Pediatric Chest X-Ray Pneumonia Detection with Cross-Operator Validation},
+    author={Rathour, Ayushi},
+    year={2025},
+    note={Cross-operator validation on 485 independent samples},
+    url={https://huggingface.co/ayushirathour/chest-xray-pneumonia-detection}
+}
+```
+
+## Acknowledgements
+
+### Datasets
+- **Training Dataset**: Chest X-Ray Images (Pneumonia) - Paul Timothy Mooney (Kaggle)
+- **Validation Dataset**: Pneumonia Radiography Dataset - Tanmay Shukla (Kaggle)
+- **Original Research**: Kermany et al., "Identifying Medical Diagnoses and Treatable Diseases by Image-Based Deep Learning", Cell 2018
+
+### Technical Stack
+- **Framework**: TensorFlow 2.19
+- **Architecture**: MobileNetV2 (Google)
+- **Deployment**: Streamlit, FastAPI
+- **Hosting**: Hugging Face Hub
+
+## Additional Resources
+
+- 🌐 **Live Demo**: [PneumoDetectAI Web App](https://pneumodetectai.streamlit.app/)
+- 📂 **Source Code**: [GitHub Repository](https://github.com/ayushirathour/chest-xray-pneumonia-detection)
+- 📖 **API Documentation**: Available when running locally
+- 💬 **Issues & Support**: GitHub Issues or email contact
+
+---
+
+**Disclaimer**: This model is for research and educational purposes only. It is not a medical device and should not be used for clinical diagnosis without appropriate medical supervision.