README.md

metadata

title: ConvNeXt CheXpert Classifier with GradCAM
emoji: 🫁
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: apache-2.0

🫁 ConvNeXt CheXpert Classifier with GradCAM

A web-based chest X-ray analysis tool using ConvNeXt-Base with CBAM attention mechanism. This app provides multi-label classification of 14 thoracic pathologies with GradCAM visualization showing where the model focuses its attention.

✨ Features

• 🔍 Multi-label Classification: Detects 14 different chest conditions
• 📊 Confidence Filtering: Only shows predictions above configurable thresholds
• 🎯 GradCAM Visualization: See exactly where the model is looking
• 📋 Metadata Fusion: Combines X-ray features with patient metadata for better accuracy
• 🖼️ Interactive Interface: Easy-to-use web interface via Gradio
• 🏥 Research Ready: Optimized for medical imaging research

🔒 Security Features

This application includes multiple security enhancements:

• Secure Model Loading: Validates state dictionaries and prevents malicious model injection
• Input Validation: Comprehensive validation of image inputs and parameters
• Error Sanitization: Prevents sensitive information disclosure in error messages
• Environment Variables: Uses secure environment variables for API tokens
• File Validation: Validates downloaded model files and extensions

📋 Supported Conditions

#	Pathology	#	Pathology
1	No Finding	8	Pneumonia
2	Enlarged Cardiomediastinum	9	Atelectasis
3	Cardiomegaly	10	Pneumothorax
4	Lung Opacity	11	Pleural Effusion
5	Lung Lesion	12	Pleural Other
6	Edema	13	Fracture
7	Consolidation	14	Support Devices

🚀 Quick Start

1. Upload: Click "Upload Chest X-ray" and select a chest X-ray image
2. Analyze: The model will process the image and show confident predictions
3. Review: View GradCAM visualizations showing model attention regions

📊 How It Works

Model Architecture

• Backbone: ConvNeXt-Base (modern efficient architecture)
• Attention: CBAM (Convolutional Block Attention Module)
• Input: 384×384 chest X-rays (automatically resized)
• Output: 14 pathology probabilities with sigmoid activation

GradCAM Visualization

• Heatmap: Shows attention intensity (red = high attention)
• Overlay: Superimposes attention map on original X-ray
• Confidence: Only displays findings above 55% confidence threshold

🏗️ Technical Details

Model Performance

• Validation AUC: 0.81 (multi-label)
• Parameters: ~88M + CBAM attention
• Training Data: CheXpert dataset (224K+ chest X-rays)
• Framework: PyTorch + timm library

Installation

pip install -r requirements.txt

Note: The app automatically downloads the ensemble models from HuggingFace Hub (calender/Ensemble_C) on first run.

Authentication for Private Repository

Set the HF_TOKEN environment variable:

export HF_TOKEN="your_huggingface_token_here"

For HuggingFace Spaces, add HF_TOKEN to your Space secrets.

Get your token from: https://huggingface.co/settings/tokens

📈 Performance Results

Ensemble Model (3 ConvNeXt-Base Models)

• Overall Validation AUC: 0.817 (better than single model 0.811)
• Training approach: Multi-iteration ensemble refinement with CBAM attention
• Dataset: CheXpert (Stanford ML Group, 224K+ images)

Model outputs: Sigmoid-activated probabilities for each pathology (0-1 range)

🖼️ Example GradCAM Visualizations

Model predictions with attention maps showing pathology localization:

Example 1: Edema Detection

• Prediction: Edema 63.7%
• Visualization: GradCAM highlights fluid accumulation regions

Example 2: Fracture Detection

• Prediction: Fracture 67.2%
• Visualization: GradCAM highlights rib/bone fracture area

Example 3: Pleural Other

• Prediction: Pleural Other 65.7%
• Visualization: GradCAM shows pleural involvement

Example 4: Atelectasis Detection

• Prediction: Atelectasis 63.1%
• Visualization: GradCAM localizes collapsed lung regions

🏗️ Model Architecture

Ensemble of 3 ConvNeXt-Base Models:

• Each model: Modern efficient architecture (Liu et al., 2022)
• ImageNet-22k pretrained weights
• Inverted bottleneck design
• LayerNorm + GELU activations

CBAM Attention Module:

• Channel attention: Refines feature importance
• Spatial attention: Highlights important regions
• Lightweight addition to base architecture
• Improves pathology localization

Ensemble Method: Average predictions from 3 iterations for better accuracy Result: Better accuracy + interpretability with GradCAM (AUC: 0.817)

📚 Dataset Information

• Source: CheXpert Dataset (Stanford ML Group)
• Size: 224,316 chest X-rays from 65,240 patients
• Period: October 2002 - July 2017 (Stanford Hospital)
• Labels: 14 pathologies auto-extracted from radiology reports
• Uncertainty: Labels include uncertainty handling (-1 for uncertain)

⚠️ Important Medical Disclaimer

🚨 FOR RESEARCH & EDUCATION ONLY 🚨

❌ DO NOT USE FOR:

• Clinical diagnosis or treatment decisions
• Emergency medical situations
• Replacing professional radiologist review
• Patient care without expert validation

⚠️ Limitations:

• Not clinically validated or FDA-approved
• Trained on historical Stanford data (2002-2017)
• Performance may vary on different populations/equipment
• Requires qualified radiologist review for any clinical use

✅ Appropriate Uses:

• Academic research and benchmarking
• Algorithm development and comparison
• Educational demonstrations
• Proof-of-concept prototypes

Always consult qualified healthcare professionals for medical decisions.

📝 Citation & Attribution

You MUST cite this work if used in publications:

@software{convnext_chexpert_attention_2025,
  author = {Time},
  title = {ConvNeXt-Base CheXpert Classifier with CBAM Attention},
  year = {2025},
  publisher = {HuggingFace},
  url = {https://huggingface.co/spaces/calender/convnext-chexpert-gradcam}
}

@article{irvin2019chexpert,
  title={CheXpert: A large chest radiograph dataset with uncertainty labels and expert comparison},
  author={Irvin, Jeremy and Rajpurkar, Pranav and Ko, Michael and Yu, Yifan and others},
  journal={AAAI Conference on Artificial Intelligence},
  volume={33},
  pages={590--597},
  year={2019}
}

Claiming you trained this model when you didn't is scientific misconduct.

🔗 Links

• Original Repository: GitHub
• CheXpert Dataset: Stanford ML Group
• Paper: CheXpert: A large chest radiograph dataset

📄 License

Apache License 2.0 - See LICENSE for details.

---

Created by Time | October 2025