README.md

metadata

title: Thyroid Pipeline
emoji: 🔬
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.15.2
python_version: '3.10'
app_file: app.py
pinned: false

Thyroid Nodule Analysis Pipeline

An automated pipeline for thyroid nodule analysis in ultrasound images, covering detection, segmentation, malignancy classification, and ACR TI-RADS risk scoring, all in a single inference flow through a web interface.

---

What it does

Given one or more thyroid ultrasound images, the system runs four sequential steps:

1. Detection - localises nodules with bounding boxes (YOLOv8s)
2. Segmentation - produces a pixel-level mask of each nodule (UNet++ with SCSE attention)
3. Malignancy classification - estimates benign/malignant probability with a Grad-CAM visual explanation (ResNet50)
4. TI-RADS scoring - assigns an ACR TI-RADS category (TR1–TR5) from 25 radiomic descriptors (Random Forest)

When multiple images of the same patient are uploaded, the results are automatically aggregated at patient level.

Note: Results are intended as decision support for a specialist and do not replace clinical judgement.

---

Project structure

thyroid-pipeline/
├── models/                              # Trained model weights
│   ├── yolo_finetuned_thyroidxl.pt
│   ├── best_unet_finetuned.pth
│   ├── resnet50_finetuned_thyroidxl.pth
│   ├── best_model_expB_RandomForest.pkl
│   └── train_features_patient_level_unetmask.csv
│
├── pipeline/
│   ├── detector.py          # YOLOv8s nodule detection
│   ├── segmentor.py         # UNet++ pixel-level segmentation
│   ├── classifier.py        # ResNet50 malignancy classification + Grad-CAM
│   ├── feature_extractor.py # 25 radiomic descriptors
│   ├── tirads_scorer.py     # Random Forest TI-RADS scoring (TR1–TR5)
│   └── aggregator.py        # Patient-level aggregation
│
├── utils/
│   └── visualization.py     # Detection and segmentation overlays
│
├── app.py                   # Gradio web interface
├── config.py                # Paths, thresholds, TI-RADS lookup tables
├── thyroid_pipeline.py      # Main pipeline orchestrator
└── requirements.txt

---

Installation

Requirements: Python 3.10+, and a CUDA-capable GPU (recommended) or CPU.

# Clone the repository
git clone <repo-url>
cd thyroid-pipeline

# Create and activate a virtual environment
python -m venv venv
# Windows:
venv\Scripts\activate
# Linux / macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Download the model weights and place them in the models/ folder.

---

Running the app

python app.py

The interface will be available at http://localhost:7860.

The app is also deployed on Hugging Face Spaces: https://huggingface.co/spaces/Ale22M/thyroid-pipeline and can be used without any local setup.

---

Usage

Single image mode - upload one .png / .jpg / .jpeg ultrasound image and click Analyze. The interface returns:

• Detection overlay (bounding box)
• Segmentation overlay (nodule mask)
• Nodule crop fed to the classifier
• Grad-CAM heatmap
• Malignancy probability and label
• Top radiomic features

Patient mode - upload multiple images of the same patient. In addition to per-image results, the system aggregates everything at patient level and returns a final malignancy classification and an ACR TI-RADS category with the corresponding biopsy recommendation.

---

Dependencies

ultralytics -> YOLOv8 detection segmentation-models-pytorch -> UNet++ with pretrained encoders grad-cam -> Grad-CAM explanations scikit-learn -> Random Forest TI-RADS classifier scikit-image, scipy, opencv-python -> radiomic feature extraction gradio -> web interface

Full pinned versions are in requirements.txt.