ProST-SoftNet

Reproducible cascade-CNN software for prostate MRI zonal segmentation (whole gland / central gland / peripheral zone)

Zenodo DOI is not minted yet — see Status below before citing this work.

Install the classification package with pip install prost-softnet.

ProST-SoftNet segments the prostate into whole gland (WG), central gland (CG), and peripheral zone (PZ) from multi-parametric MRI, using a cascade 3-D CNN pipeline built around Prostate158 — the public benchmark of 158 prostate MRI exams with expert zonal and lesion annotations (Zenodo archive, DOI 10.5281/zenodo.6481141).

On the held-out 19-case test split, the pipeline reaches a peripheral-zone Dice of 0.7513 — above the 0.7473 human inter-reader agreement measured on the same data. The peripheral zone is the hardest of the three to segment and the region where most clinically significant prostate cancers arise, so it is reported separately rather than averaged away. Full results are in Zone-Segmentation Results.

Every trained checkpoint, per-iteration ablation log, and per-case metric CSV is committed to this repository rather than described from the outside, so the numbers here can be recomputed and checked directly rather than taken on faith. An interactive dashboard (demo/) lets you browse the results or upload a new patient's MRI and run the pipeline yourself.

The repository also ships prostsoftnet, a pip-installable hybrid CNN-ViT classifier for benign/malignant prediction with Grad-CAM/Attention-Rollout explainability and ONNX export. It is complete and unit-tested, but has not been trained to completion on Prostate158 and carries no benchmark results — it is included as reusable, extensible architecture, not as a validated classifier. See Status.

What's in this repo

Status

Being upfront about what's real right now, rather than what the badges of a finished project usually imply:

• Working and benchmarked: the zone-segmentation pipeline — its checkpoints and reported metrics (recomputed from the committed per-case CSVs, not hand-typed), the dashboard, and the 106-test suite covering both the segmentation pipeline and the classification package.
• Complete but not benchmarked: the prostsoftnet classification package. Its training, evaluation, and explainability code is finished and unit-tested, but it has never been run to completion on the full Prostate158 dataset, so no trained checkpoint and no accuracy numbers exist. It is shipped as reusable architecture, and this README does not report classification results because there are none to report.
• Not yet done: no Zenodo DOI has been minted for this repository; the interactive HuggingFace Spaces demo (live per-patient inference) is built and passes an end-to-end smoke test locally, but is not yet deployed live — HuggingFace's free tier stopped hosting Gradio/Docker Spaces on CPU compute, which now requires a PRO subscription. A static landing page (results table + links, no live inference) is deployed at huggingface.co/spaces/MuhammadTausif/prost-softnet-v2-demo in the meantime. The package is published to PyPI (pip install prost-softnet) as of v1.2.1.
• Repository visibility: this repository is currently private to the ProST-SoftNet organization while the above items are finished. It will be made public before submission, per the venue's requirement that the code be openly accessible.

Zone-Segmentation Results

Held-out test split of Prostate158 (19 cases). The pipeline runs in two stages: a frozen Stage-A localizer finds the gland bounding box, then a Stage-B 3-D U-Net segments WG and CG at native crop resolution; PZ is derived as WG AND NOT CG.

The single-model, PZ-derived cascade is the checkpoint the dashboard's live "Zonal Analysis" tab runs. The peripheral zone is the hardest of the three by a wide margin — it's small, has a less distinct boundary on T2W, and is exactly where most clinically significant cancers arise, so tracking it separately from whole-gland Dice matters more than a single averaged number would suggest. Full iteration-by-iteration history, what changed between each one, and why some approaches didn't help are documented in checkpoints/prost_fusenet_optimal/README.md.

A note on the classification package

The prostsoftnet classifier is deliberately not benchmarked here. Its training, evaluation, and explainability code is complete and unit-tested, but it has never been run to completion on the full Prostate158 dataset — so no trained checkpoint exists and there are no accuracy numbers to report. Rather than publish a hastily-trained figure, this repository reports only what it can substantiate: the zone-segmentation results above.

The package remains fully usable for anyone who wants to train it themselves — see docs/classification-package.md — and prost-evaluate will produce the standard clinical metrics (AUROC, sensitivity, specificity, PPV, NPV with bootstrap confidence intervals) once a checkpoint exists.

Try the dashboard

No GPU needed to browse the pre-generated results; the live "Zonal Analysis" tab needs the trained checkpoints already present in checkpoints/prost_fusenet_optimal/.

cd demo
pip install -r requirements.txt
python server.py
# open http://localhost:8000

The dashboard opens on the zone-segmentation model comparison and statistics tabs. A third tab accepts a new patient's T2W/DWI/ADC MRI — NIfTI or a DICOM series as a ZIP — runs the cascade pipeline on it, and returns WG/CG/PZ volumes, overlay figures, and a plain-language, explicitly non-diagnostic description grounded in a small retrieval-augmented knowledge base (PI-RADS anatomy references, not a diagnosis).

Zone-Segmentation Models

Side-by-side test-set metrics for each trained checkpoint, per-zone ASD/HD95 distance metrics, and pre-generated ground-truth-vs-prediction overlays for individual test cases.

Zone Statistics

Whole-gland segmentation compared against ground truth on real T2W and DWI slices (red = ground truth, yellow = prediction, green = overlap), per-model Dice/IoU/precision/recall, voxel-level ROC and precision-recall curves computed from raw per-voxel probabilities across all 19 test cases, and training history.

Installation

The prostsoftnet classification package is on PyPI:

pip install prost-softnet

See docs/installation.md and docs/quickstart.md (also bundled inside the installed package) for what this does and doesn't include.

To work with the full repository — the zone-segmentation checkpoints, dashboard, tests, and notebooks — install from source instead:

git clone https://github.com/ProST-SoftNet/ProST-SoftNet-v2.git
cd ProST-SoftNet-v2
pip install -e ".[dev,train,notebook]"

Requirements: Python 3.10 or newer, PyTorch 2.2+, CUDA 11.8+ recommended for training (CPU works for inference and for browsing the dashboard).

The prostsoftnet classification package

Alongside the segmentation pipeline, this repository ships a pip-installable hybrid CNN-ViT classifier (EfficientNetV2-S + 6-layer ViT + cross-attention fusion) for benign/malignant prediction, with Grad-CAM and Attention-Rollout explainability, ONNX export, and a CLI (prost-train, prost-evaluate, prost-predict, prost-export).

As noted in Status, it has not been trained to completion and carries no benchmark results — it is included as reusable, extensible architecture rather than as a validated classifier.

Full architecture description, quick start, training/evaluation/inference commands, and explainability API: docs/classification-package.md.

Tests and illustrative examples

pytest tests/

106 tests pass in a clean environment, covering each part of the software in turn:

CI runs the suite on Python 3.10 and 3.11 on every push, and lints the whole repository with ruff check ..

The tests that need the trained checkpoints skip cleanly rather than fail when those Git LFS files aren't present, so a fresh clone without git lfs pull still passes.

Two more test files sit outside the table above because they check something different from the software itself: test_release_workflow_config.py is a static check that the release pipeline's GitHub Actions permissions haven't regressed, and test_pypi_package.py verifies the actual published PyPI wheel — not just an editable install from source — gated behind an explicit environment variable since it needs a real pip install prost-softnet first. See docs/testing.md for the full testing strategy, how to run each kind, and the latest test report.

The three notebooks in notebooks/ are executed end to end by a separate CI job (nbconvert --execute) rather than just sitting in the repo unverified — each one falls back to a tiny synthetic dataset (scripts/make_synthetic_prostate158.py) and one or two training epochs under a PROST_SMOKE_TEST environment variable, so they run in seconds on a CPU-only runner without needing the real ~2 GB dataset:

1. 01_data_preparation.ipynb — loading, preprocessing, and augmenting Prostate158
2. 02_training_and_evaluation.ipynb — training the classifier and computing clinical metrics with bootstrap confidence intervals
3. 03_inference_and_explainability.ipynb — running inference and generating Grad-CAM / Attention Rollout visualizations

Project structure

ProST-SoftNet-v2/
├── checkpoints/prost_fusenet_optimal/  # zone-segmentation checkpoints + per-case metrics, Git LFS
├── demo/                               # zone-segmentation dashboard (FastAPI + static frontend)
│   ├── server.py
│   ├── wgcgpz_inference.py             # live WG/CG/PZ cascade inference
│   ├── zone_pipeline/                  # segmentation model definitions (self-contained)
│   ├── rag_report.py                   # retrieval-augmented report generation
│   └── static/index.html
├── hf_spaces/                          # Gradio demo of the segmentation pipeline (not yet deployed)
├── prostsoftnet/                       # classification package (pip installable, not benchmarked)
│   ├── data/                           # Prostate158 dataset, DICOM/NIfTI loading, augmentation
│   ├── models/                         # hybrid CNN-ViT architecture, losses
│   ├── training/                       # training loop, evaluation, ONNX export
│   ├── utils/                          # Grad-CAM, Attention Rollout, metrics, visualization
│   └── cli.py                          # prost-train / prost-evaluate / prost-predict / prost-export
├── web-app/                            # React frontend for the classification web app
├── php-api/                            # PHP REST API (auth, predict proxy, history, admin)
├── ml-api/                             # FastAPI ONNX inference server for the web app
├── notebooks/                          # 3 illustrative notebooks, executed in CI
├── tests/                              # pytest suite (106 tests)
├── docs/                               # architecture, classification package, API reference,
│                                       #   setup, deployment, user/admin manuals
├── .github/workflows/                  # CI and release automation
├── CITATION.cff, codemeta.json         # machine-readable citation and software metadata
└── pyproject.toml                      # package configuration

Code metadata

Citation

No DOI has been minted for this software yet — a Zenodo release is planned, at which point this section and CITATION.cff will be updated with the real DOI. Until then, cite the repository directly, or prost-softnet on PyPI if referring specifically to the classification package:

@software{iqbal_prostsoftnet,
  title  = {ProST-SoftNet: Reproducible Cascade-CNN Software for Prostate MRI Zonal Segmentation},
  author = {Iqbal, Saqib and Saddiqui, Ghzanfar Farooq and Tausif, Muhammad and Iqbal, Muhammad Zafar},
  url    = {https://github.com/ProST-SoftNet/ProST-SoftNet-v2},
  note   = {Classification package also available via PyPI: pip install prost-softnet}
}

If you use the Prostate158 dataset itself, please also cite the original dataset paper and repository.

Authors

• Saqib Iqbal — Quaid-i-Azam University — model design, zone-segmentation methodology, training and evaluation
• Muhammad Tausif — software architecture and implementation: the classification package, the dashboard, the full-stack web application, and CI/testing infrastructure

License

MIT — see LICENSE.