README.md

---
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.

```bash
# 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

```bash
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.