Docker one-command WSI TIL inference + smoke test

[YoniSchirris]

Summary

• Adds a one-command, Dockerised pipeline to run end-to-end ECTIL TIL inference on whole-slide images: tissue mask (FESI) → DLUP tiling → RetCCL feature extraction → MeanMIL + GatedAttention → TIL score. Supports a single slide or a directory of slides, writes a timestamped run dir with per-slide artifacts (tils_score.json, tile_predictions.csv, features.h5, thumbnail/mask/heatmap PNGs) and an aggregate tils_scores.csv.
• Fixes the Docker build: pins setuptools/wheel/packaging as a matched set with pip==23.3.2 (the editable install otherwise died on canonicalize_version(strip_trailing_zero=)), and relaxes python_requires from ==3.10.9 to >=3.10,<3.11 so conda-resolved 3.10.x patches install.
• Adds --overwrite-mpp so slides without an embedded spacing (many TCGA SVS) can be opened/tiled instead of raising dlup's UnsupportedSlideError. Off by default (None); when set, it supplies the slide's native base spacing so dlup can resample to the model's target --mpp 0.5 (the value used in the extraction experiments — see configs/datamodule/encoder/retccl.yaml). For TCGA 40x diagnostic slides that native spacing is 0.25.
• Adds tools/infer/run_demo.sh: a standalone smoke test (plain bash, no external tooling) that downloads the RetCCL + ECTIL weights and 5 TCGA-BRCA slides, builds the image, runs both single-slide and directory modes on CPU, and asserts the outputs before printing SMOKE TEST PASSED/FAILED.

Verification

Smoke test passed end-to-end on CPU (both modes, all assertions green). Real TIL scores on 5 TCGA-BRCA slides:

Slide	TIL score	Tiles
TCGA-AC-A23G	5.3%	179
TCGA-OL-A5RW	10.3%	102
TCGA-OL-A5RX	7.9%	205
TCGA-OL-A5RZ	24.0%	266
TCGA-OL-A5S0	12.7%	147

Test plan

This is a single command. It downloads everything, builds the container, runs both inference modes, and validates the output. No weights, no slides, and no Python deps need to be set up by hand.

1. Clone and enter the repo

git clone https://github.com/NKI-AI/ectil
cd ectil

You need Docker running, plus curl and python3 on the host (the latter only to bootstrap gdown and parse the result JSON — all the heavy C deps live inside the image). The script refuses to start and tells you exactly what's missing if not.

2. Run the one command

./tools/infer/run_demo.sh

That's it. Everything below happens automatically, and it's idempotent — re-running skips anything already downloaded.

3. What you should see scroll past

The script narrates 7 stages. Roughly:

==> [1/7] Pre-flight checks ...
    docker, curl present; daemon running.
==> [2/7] RetCCL encoder weights ...        # ~94 MB from Google Drive
    -> model_zoo/retccl/retccl_best_ckpt.pth
==> [3/7] ECTIL classifier weights ...      # ~4.7 MB
    -> model_zoo/ectil/tcga/fold_0/epoch_065_step_858_weights_only.ckpt
==> [4/7] TCGA-BRCA slides (5 total) ...    # downloaded to data/wsi/demo/*.svs
    have 5 slides in data/wsi/demo.
==> [5/7] Building Docker image 'ectil-inference' (cached after first build) ...
==> [6/7] Running SINGLE-SLIDE mode (...) ...   # --wsi <one .svs>  -> 1 result
==> [6/7] Running DIRECTORY mode (all 5 slides ...) ...   # --wsi data/wsi/demo -> 5 results
==> [7/7] Validating outputs ...
    [ok]   tils_scores.csv has 1 data row(s)
    [ok]   5 per-slide subdir(s)
    [ok]   score sane for TCGA-...: 0.xx
    ...

The two [6/7] runs are the point of the test: single-slide (--wsi <one .svs>, expect 1 row) and directory (--wsi data/wsi/demo, expect 5 rows) modes.

4. What "pass" looks like

It ends with a per-slide score table and:

============================================================
SMOKE TEST PASSED
TIL score (single-slide TCGA-...): 0.xxxx   |   run dir: data/inference_output/demo_single

and exits 0. On any problem it prints SMOKE TEST FAILED with the offending [FAIL] lines and exits 1.

5. Inspect the artifacts (optional)

ls data/inference_output/demo_dir/          # config.json, tils_scores.csv, 5 per-slide subdirs
cat data/inference_output/demo_dir/tils_scores.csv

Each per-slide subdir holds: tils_score.json, tile_predictions.csv, features.h5, and thumbnail.png / mask.png / mask_overlay.png / attention_heatmap.png / til_heatmap.png. Spot-check a til_heatmap.png against the slide to sanity-check the spatial predictions.

Everything downloaded (data/wsi, model_zoo/**) and written (data/inference_output) is gitignored.

---

Requesting @NUltee as reviewer (recent commits on main).

🤖 Generated with Claude Code