SegResNet weights, TorchScript export and model card

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,104 @@
+---
+license: apache-2.0
+library_name: monai
+pipeline_tag: image-segmentation
+tags:
+  - medical-imaging
+  - mri
+  - brain-tumour
+  - segmentation
+  - segresnet
+  - monai
+  - brats
+  - 3d
+---
+
+# MEDTRACE brain tumour segmentation (SegResNet)
+
+3D tumour compartment segmentation from four co-registered MRI sequences. Trained on BraTS 2023 GLI and used by the [MEDTRACE](https://huggingface.co/spaces/AIOmarRehan/medtrace) longitudinal workstation.
+
+> [!WARNING]
+> **Research prototype. Not a medical device.** Not for diagnosis, treatment planning, or any clinical decision. Not clinically validated. It has been measured against one annotation protocol on one dataset, which is agreement, not clinical accuracy.
+
+## Results on the held-out test split
+
+186 cases from 169 subjects, split by subject so no subject appears in two splits.
+
+| Region | Dice mean | Dice median | HD95 median | Sensitivity | Precision |
+|---|---|---|---|---|---|
+| Tumour core | 0.908 | 0.956 | 2.00 | 0.917 | 0.917 |
+| Whole tumour | 0.922 | 0.949 | 2.45 | 0.925 | 0.924 |
+| Enhancing tumour | 0.852 | 0.898 | 1.41 | 0.883 | 0.849 |
+
+Empty regions follow the BraTS convention: with empty ground truth, Dice is 1 if the prediction is also empty and 0 otherwise, rather than being averaged away as NaN.
+
+**Use the test figures, not the validation ones.** Epoch selection and post-processing thresholds were both tuned on the validation split, so validation numbers are optimistic by construction.
+
+## Files
+
+| File | Size | Contents |
+|---|---|---|
+| `medtrace_seg_best.pt` | 72 MB | Selected weights, epoch 32 |
+| `medtrace_seg.torchscript.pt` | 72 MB | TorchScript export, no MONAI needed to run |
+| `model_card.json` | 6 KB | Full machine-readable card: architecture, contracts, metrics, environment |
+
+## Input contract
+
+**Channel order is not recoverable from the weights. The wrong order gives wrong output and no error.**
+
+```
+channels:       [t1c, t1n, t2f, t2w]
+normalisation:  per case, per channel, zero mean unit variance over NON-ZERO voxels only
+spacing:        1.0 x 1.0 x 1.0 mm
+preprocessing:  skull-stripped and co-registered, as BraTS 2023 distributes it
+cropping:       non-zero bounding box of the summed channels, 4 voxel margin
+patch size:     128 x 128 x 128
+inference:      sliding window, overlap 0.5, gaussian blend
+```
+
+## Output contract
+
+Three **overlapping** channels with independent sigmoid activation, not a softmax over classes.
+
+| Channel | Meaning |
+|---|---|
+| `TC` | Tumour core: necrotic core + enhancing |
+| `WT` | Whole tumour: necrotic core + oedema + enhancing |
+| `ET` | Enhancing tumour |
+
+Thresholded at 0.5, with enhancing tumour suppressed below 200 voxels. To convert to BraTS integer labels, write `WT` as 2, then `TC` as 1, then `ET` as 3, **in that order**: the regions overlap, so the write order is what produces the correct nesting.
+
+## Architecture and training
+
+`monai.networks.nets.SegResNet`, 18.8M parameters, 4 input channels, 3 output channels, `init_filters=32`, `blocks_down=[1,2,2,4]`, `blocks_up=[1,1,1]`, `dropout_prob=0.2`.
+
+DiceFocalLoss with AdamW at lr 2e-4, cosine annealing, AMP float16, on a Tesla T4. 37 epochs completed of 60 planned; epoch 32 selected on mean validation Dice. Patch sampling was 80% centred on whole tumour, 20% uniform. Augmentation was random axis flips and intensity scale and shift within 10%. Seed 20260813.
+
+MONAI 1.6.0, PyTorch 2.10.0+cu128.
+
+## Limitations
+
+- Trained on **pre-operative adult glioma only**. Post-treatment appearances, including resection cavities and radiation change, are not represented.
+- Requires **all four sequences**. Behaviour with one missing is untested.
+- Assumes BraTS preprocessing: skull-stripped, co-registered, 1 mm isotropic.
+- Agreement with one annotation protocol on one dataset is not a measure of clinical accuracy.
+
+## A note on how MEDTRACE uses this
+
+The hosted MEDTRACE demo does **not** run this model. Its measurements come from expert-corrected segmentations shipped with RHUH-GBM, because that dataset is post-operative and post-treatment, which is exactly the regime this model was not trained for. Publishing the model and measuring with it are separate decisions, and only one of them is justified by the numbers above.
+
+## Training data and required citations
+
+Trained on the **BraTS 2023 GLI** challenge training split, the only labelled split. The BraTS data use agreement grants use and requires citation; it does **not** grant redistribution, so no BraTS imaging appears in this repository or in any MEDTRACE artefact.
+
+> Menze, B. H., et al. (2015). The Multimodal Brain Tumor Image Segmentation Benchmark (BRATS). IEEE Transactions on Medical Imaging, 34(10), 1993-2024. https://doi.org/10.1109/TMI.2014.2377694
+
+> Bakas, S., et al. (2017). Advancing The Cancer Genome Atlas glioma MRI collections with expert segmentation labels and radiomic features. Scientific Data, 4, 170117. https://doi.org/10.1038/sdata.2017.117
+
+> Baid, U., et al. (2021). The RSNA-ASNR-MICCAI BraTS 2021 Benchmark on Brain Tumor Segmentation and Radiogenomic Classification. arXiv:2107.02314. https://doi.org/10.48550/arXiv.2107.02314
+
+## Related
+
+- Space: [AIOmarRehan/medtrace](https://huggingface.co/spaces/AIOmarRehan/medtrace)
+- Dataset: [AIOmarRehan/medtrace-rhuh-gbm-derived](https://huggingface.co/datasets/AIOmarRehan/medtrace-rhuh-gbm-derived)
+- Code: [github.com/AIOmarRehan/medtrace](https://github.com/AIOmarRehan/medtrace)

medtrace_seg.torchscript.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1a3ae7875399bef7fe905e0b336c3a5f75f428c5952b67299220cafcf15d7992
+size 75452080

medtrace_seg_best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:885b7acf5332a86b94afa6c3fdb0fb03532526c7f81e3bfd7636cf818817ac89
+size 75228900

model_card.json

@@ -0,0 +1,172 @@
+{
+  "name": "medtrace-brats-seg",
+  "version": "1.0.0",
+  "task": "3D brain tumour segmentation from four MRI sequences",
+  "intended_use": "Produce tumour compartment masks for MEDTRACE's longitudinal measurement pipeline. Research use. Not a diagnostic device and not for clinical decision-making.",
+  "architecture": {
+    "class": "monai.networks.nets.SegResNet",
+    "spatial_dims": 3,
+    "in_channels": 4,
+    "out_channels": 3,
+    "init_filters": 32,
+    "blocks_down": [
+      1,
+      2,
+      2,
+      4
+    ],
+    "blocks_up": [
+      1,
+      1,
+      1
+    ],
+    "dropout_prob": 0.2,
+    "parameters": 18798627
+  },
+  "input_contract": {
+    "channel_order": [
+      "t1c",
+      "t1n",
+      "t2f",
+      "t2w"
+    ],
+    "note": "Channel order is not recoverable from the weights. Wrong order, wrong output, no error.",
+    "normalisation": "per case, per channel, zero mean unit variance over NON-ZERO voxels only",
+    "spacing_mm": [
+      1.0,
+      1.0,
+      1.0
+    ],
+    "orientation": "as distributed by BraTS 2023 (already co-registered and skull-stripped)",
+    "cropping": "crop to the non-zero bounding box of the summed channels, 4 voxel margin",
+    "patch_size": [
+      128,
+      128,
+      128
+    ],
+    "inference": {
+      "method": "sliding window",
+      "overlap": 0.5,
+      "blend": "gaussian"
+    }
+  },
+  "output_contract": {
+    "activation": "sigmoid, independent per channel",
+    "channels": [
+      "TC",
+      "WT",
+      "ET"
+    ],
+    "channel_meaning": {
+      "TC": "tumour core = necrotic core + enhancing",
+      "WT": "whole tumour = necrotic core + oedema + enhancing",
+      "ET": "enhancing tumour"
+    },
+    "overlapping": true,
+    "postprocessing": {
+      "threshold": 0.5,
+      "min_component_voxels": 0,
+      "et_min_voxels": 200
+    },
+    "to_integer_labels": {
+      "convention": "BRATS",
+      "mapping": {
+        "1": "necrotic_core",
+        "2": "oedema",
+        "3": "enhancing"
+      },
+      "procedure": "write WT as 2, then TC as 1, then ET as 3, in that order"
+    }
+  },
+  "training_data": {
+    "dataset": "BraTS 2023 GLI, challenge training split (the only labelled split)",
+    "split_unit": "subject",
+    "split_seed": 20260813,
+    "cases": {
+      "train": 874,
+      "val": 191,
+      "test": 186
+    },
+    "subjects": {
+      "train": 792,
+      "val": 172,
+      "test": 169
+    },
+    "label_mapping_verified": true,
+    "excluded_cases": []
+  },
+  "training": {
+    "epochs_completed": 37,
+    "epochs_planned": 60,
+    "selected_epoch": 32,
+    "selection_metric": "mean Dice over TC, WT, ET on the validation split",
+    "loss": "DiceFocalLoss(sigmoid=True, squared_pred=True, batch=True)",
+    "optimizer": "AdamW lr=0.0002 wd=1e-05",
+    "scheduler": "CosineAnnealingLR",
+    "precision": "AMP float16",
+    "augmentation": [
+      "random axis flips",
+      "intensity scale +-10%",
+      "intensity shift +-10%"
+    ],
+    "patch_sampling": "80% centred on whole tumour, 20% uniform",
+    "seed": 20260813
+  },
+  "metrics": {
+    "validation": {
+      "TC": {
+        "dice_mean": 0.9015418441673284,
+        "dice_median": 0.947789848286196,
+        "hd95_median": 2.0
+      },
+      "WT": {
+        "dice_mean": 0.9177529638232264,
+        "dice_median": 0.939965202760836,
+        "hd95_median": 3.316624879837036
+      },
+      "ET": {
+        "dice_mean": 0.8503461605067909,
+        "dice_median": 0.9047415373334963,
+        "hd95_median": 1.4142135381698608
+      }
+    },
+    "test": {
+      "TC": {
+        "dice_mean": 0.9078361539305267,
+        "dice_median": 0.9563434942782733,
+        "hd95_median": 2.0,
+        "sensitivity_mean": 0.9165695598827129,
+        "precision_mean": 0.9170155149790782
+      },
+      "WT": {
+        "dice_mean": 0.921562897191002,
+        "dice_median": 0.9489419374016819,
+        "hd95_median": 2.4494898319244385,
+        "sensitivity_mean": 0.9247750225794058,
+        "precision_mean": 0.9235932925559869
+      },
+      "ET": {
+        "dice_mean": 0.852042452735223,
+        "dice_median": 0.8984435921432055,
+        "hd95_median": 1.4142135381698608,
+        "sensitivity_mean": 0.8833305802745401,
+        "precision_mean": 0.8486887298796273
+      }
+    },
+    "empty_region_rule": "BraTS convention: with empty ground truth, Dice is 1 if the prediction is also empty and 0 otherwise. Not averaged away as NaN."
+  },
+  "limitations": [
+    "Trained on pre-operative adult glioma only. LUMIERE's post-treatment appearances, including resection cavities and radiation change, are not represented.",
+    "Requires all four sequences. Behaviour with a missing sequence is untested.",
+    "Assumes BraTS preprocessing: skull-stripped, co-registered, 1 mm isotropic.",
+    "Agreement with one annotation protocol on one dataset. Not a measure of clinical accuracy.",
+    "Selection and post-processing tuning both used the validation split, so validation figures are optimistic. Use the test figures."
+  ],
+  "environment": {
+    "monai": "1.6.0",
+    "torch": "2.10.0+cu128",
+    "numpy": "2.0.2",
+    "device": "Tesla T4, 15.6 GB",
+    "amp": true
+  }
+}