MHub / GC - Add the GC Tiger challenge winner LB2 model

models/gc_tiger_lb2/__init__.py

@@ -0,0 +1 @@
+from .utils import *

models/gc_tiger_lb2/config/default.yml

@@ -0,0 +1,32 @@
+general:
+  data_base_dir: /app/data
+  version: 1.0
+  description: Tiger challenge winner LB2 (dicom:sm to json with TIL score)
+
+execute:
+- DicomImporter
+- TiffConverter
+- TigerLB2Runner
+- ReportExporter
+- DataOrganizer
+
+modules:
+  DicomImporter:
+    source_dir: input_data
+    import_dir: sorted_data
+    sort_data: True
+    meta: 
+      mod: "%Modality"
+
+  ReportExporter:
+    includes:
+    - data: til_score
+      label: TIL score
+      value: value
+
+  DataOrganizer:
+    target_dir: output_data
+    require_data_confirmation: true
+    targets:
+      - json-->[i:sid]/gc_tiger_lb2_til_score.json
+      - mha:mod=seg-->[i:sid]/gc_tiger_lb2_segmentation.mha

models/gc_tiger_lb2/config/tiff_pipeline.yml

@@ -0,0 +1,21 @@
+general:
+  data_base_dir: /app/data
+  version: 1.0
+  description: Tiger challenge winner LB2 (tiff:sm to json with TIL score)
+
+execute:
+- FileStructureImporter
+- TigerLB2Runner
+- DataOrganizer
+
+modules:
+  FileStructureImporter:
+    input_dir: input_data
+    structures:
+      - $instanceID@instance/wsi.tif@tiff:mod=sm
+
+  DataOrganizer:
+    target_dir: output_data
+    require_data_confirmation: true
+    targets:
+      - json-->[i:instanceID]/gc_tiger_lb2_til_score.json

models/gc_tiger_lb2/dockerfiles/Dockerfile

@@ -0,0 +1,55 @@
+FROM mhubai/base:latest
+
+# Specify/override authors label
+LABEL authors="[email protected]"
+
+# Install pipenv (for a custom Python/Pip environment for ASAP-2.1 and the other algorithm requirements)
+RUN pip3 install --no-cache-dir pipenv
+
+# Set environment variables for pipenv (installs into /app/.venv)
+ENV PIPENV_VENV_IN_PROJECT=1
+
+# Install ASAP 2.1
+RUN apt-get update && \
+    apt-get -y install curl libpython3.8-dev && \
+    curl --remote-name --location "https://github.com/computationalpathologygroup/ASAP/releases/download/ASAP-2.1/ASAP-2.1-py38-Ubuntu2004.deb" && \
+    dpkg --install ASAP-2.1-py38-Ubuntu2004.deb || true && \
+    apt-get -f install --fix-missing --fix-broken --assume-yes && \
+    ldconfig -v && \
+    apt-get clean && \
+    rm ASAP-2.1-py38-Ubuntu2004.deb
+
+# Install tiger LB2 algorithm
+#   - Clone tiger LB2 codebase (master branch, fixed to version 0.1.0)
+#   - Subsequently we remove the .git directory to procuce a compacter docker layer
+RUN git clone --depth 1 --branch 0.1.0 https://github.com/DIAGNijmegen/tiger_vuno_algorithm /vuno && \
+    rm -rf /vuno/.git
+
+# Setup and install algorithm pipenv environment
+#   1. Ensure we configure a new empty pipenv for Python 3.8
+#   2. Link ASAP libraries into our environment
+#   3. Install required torch and torchvision dependencies
+#   4. Install tiger LB2 dependencies from requirements.txt
+#   5. Upgrade version of numpy and numba to function correctly with ASAP
+RUN pipenv install --python 3.8 && \
+    echo "/opt/ASAP/bin" > /app/.venv/lib/python3.8/site-packages/asap.pth && \
+    pipenv run pip install --no-cache-dir torch==2.0.1+cu118 torchvision==0.15.2+cu118 -f https://download.pytorch.org/whl/torch_stable.html && \
+    pipenv run pip install --no-cache-dir -r /vuno/requirements.txt && \
+    pipenv run pip install --no-cache-dir --upgrade numpy==1.24.4 numba==0.58.1
+
+# Download and install model weights file from zenodo
+RUN rm -rf /vuno/pretrained_weights && \
+    wget https://zenodo.org/record/8112176/files/pretrained_weights.zip -O /vuno/pretrained_weights.zip && \
+    unzip /vuno/pretrained_weights.zip -d /vuno && \
+    rm /vuno/pretrained_weights.zip
+
+# Import the MHub model definiton
+ARG MHUB_MODELS_REPO
+RUN buildutils/import_mhub_model.sh gc_tiger_lb2 ${MHUB_MODELS_REPO}
+
+# Add model and algorithm code bases to python path
+ENV PYTHONPATH="/vuno:/app"
+
+# Set default entrypoint
+ENTRYPOINT ["python3", "-m", "mhubio.run"]
+CMD ["--config", "/app/models/gc_tiger_lb2/config/default.yml"]

models/gc_tiger_lb2/meta.json

@@ -0,0 +1,146 @@
+{
+  "id": "c5397909-0397-489f-8744-6bf3952e9a1c",
+  "name": "gc_tiger_lb2",
+  "title": "TIGER challenge winner: Team VUNO",
+  "summary": {
+    "description": "This algorithm predicts the percentage of stromal area covered by tumour infiltrating lymphocytes (TIL) on H&E-stained whole-slide images of breast cancer histopathology. This algorithm first segments invasive tumor and tumor-associated stroma and subsequently detects lymphocytes and plasma cells, which are finally combined to estimate the relevant regions for TIL estimation. This model algorithm was the challenge winner of the TIGER challenge hosted on Grand Challenge.",
+    "inputs": [
+      {
+        "label": "Whole-slide image",
+        "description": "H&E-stained whole-slide image of breast cancer histopathology",
+        "format": "DICOM",
+        "modality": "SM",
+        "bodypartexamined": "Breast",
+        "slicethickness": "",
+        "non-contrast": false,
+        "contrast": false
+      }
+    ],
+    "outputs": [
+      {
+        "type": "Prediction",
+        "valueType": "Probability",
+        "label": "TIL score",
+        "description": "Percentage of stromal area covered by tumour infiltrating lymphocytes. Values between 0 (percent) to 100 (percent).",
+        "classes": []
+      },
+      {
+        "type": "Prediction",
+        "valueType": "Segmentation mask",
+        "label": "WSI Tumor and stroma segmentation mask",
+        "description": "WSI tumor and stroma segmentation mask (MHA) used as first step in the pipeline. This segmentation mask was not validated, use it at your own risk! The labels are: 1-tumor, 2-stroma, 3-rest.",
+        "classes": []
+      }
+    ],
+    "model": {
+      "architecture": "Combination of multiple U-Nets with EfficientNet B2/B0 encoders, and YOLOv5 networks for detection.",
+      "training": "supervised",
+      "cmpapproach": "2D"
+    },
+    "data": {
+      "training": {
+        "vol_samples": 277
+      },
+      "evaluation": {
+        "vol_samples": 707
+      },
+      "public": false,
+      "external": false
+    }
+  },
+  "details": {
+    "name": "LB2",
+    "version": "0.1.0",
+    "devteam": "VUNO",
+    "type": "Segmentation/Prediction hybrid",
+    "date": {
+      "weights": "2023-07-06",
+      "code": "2023-07-06",
+      "pub": "2022-08-26"
+    },
+    "cite": "",
+    "license": {
+      "code": "Apache 2.0",
+      "weights": "CC BY-NC 4.0"
+    },
+    "publications": [
+      {
+        "uri": "https://github.com/vuno/tiger_challenge/blob/720f8dfca4624792c8e57915c4222efec5a0c2d4/figure/method_description.pdf",
+        "title": "TIGER Challenge - Description of the Developed Algorithm - Team VUNO"
+      }
+    ],
+    "github": "https://github.com/vuno/tiger_challenge",
+    "zenodo": "https://doi.org/10.5281/zenodo.8112147",
+    "colab": "",
+    "slicer": false
+  },
+  "info": {
+    "use": {
+      "title": "Intended use",
+      "text": "This algorithm is a classification method using a variety of deep-learning techniques to predict the percentage of stromal area covered by tumour infiltrating lymphocytes on H&E-stained whole-slide image of breast cancer histopathology. The algorithm can also be found on Grand Challenge [1] (access upon request), where it participated and won the TIGER challenge.",
+      "references": [
+        {
+          "label": "TIGER challenge winner algorithm on Grand Challenge (access upon request)",
+          "uri": "https://grand-challenge.org/algorithms/tiger-algorithm-lb2"
+        }
+      ],
+      "tables": []
+    },
+    "analyses": {
+      "title": "Evaluation",
+      "text": "Patient-level diagnosis performance is evaluated using the \"TIL score\". The diagnostic performance of the algorithms were estimated using a multivariate Cox regression model trained with predefined clinical variables and the produced TIL scores. Based on this regression model the concordance index (Uno’s C-index) was computed to rank this algorithm.",
+      "references": [
+        {
+          "label": "TIGER challenge details",
+          "uri": "https://tiger.grand-challenge.org"
+        },
+        {
+          "label": "TIGER team VUNO algorithm final evaluation results on Grand Challenge.",
+          "uri": "https://tiger.grand-challenge.org/evaluation/survival-final-evaluation/leaderboard/"
+        }
+      ],
+      "tables": [
+        {
+          "label": "Evaluation results on the TIGER testing cohort of 707 WSI cases.",
+          "entries": {
+              "Uno's Concordance-index": "0.6388"
+          }
+        }
+      ]
+    },
+    "evaluation": {
+      "title": "Evaluation data",
+      "text": "The test set consists of a separate hidden dataset of n=707 H&E-stained whole-slide breast cancer histopathology images.",
+      "references": [
+        {
+          "label": "TIGER data section",
+          "uri": "https://tiger.grand-challenge.org/Data/"
+        }
+      ],
+      "tables": []
+    },
+    "training": {
+      "title": "Training data",
+      "text": "This algorithm was trained using two public training datasets: 1. WSIROIS: Whole-slide images with manual annotations in regions of interest. 2. WSITILS: Whole-slide images with visual estimation of the TILs at slide level.",
+      "references": [
+        {
+          "label": "WSIROIS, WSITILS on AWS Open Data",
+          "uri": "https://registry.opendata.aws/tiger/"
+        }
+      ],
+      "tables": []
+    },
+    "ethics": {
+      "title": "",
+      "text": "",
+      "references": [],
+      "tables": []
+    },
+    "limitations": {
+      "title": "Limitations",
+      "text": "This algorithm was developed for research purposes only.",
+      "references": [],
+      "tables": []
+    }
+  }
+}

models/gc_tiger_lb2/utils/TigerLB2Runner.py

@@ -0,0 +1,60 @@
+"""
+------------------------------------------------
+Mhub / DIAG - Run Module for Tiger LB2 Algorithm
+------------------------------------------------
+
+------------------------------------------------
+Author: Sil van de Leemput
+Email:  [email protected]
+------------------------------------------------
+"""
+from mhubio.core import Instance, InstanceData, IO, Module, ValueOutput, Meta, DataType, FileType
+
+from pathlib import Path
+import json
+
+
+@ValueOutput.Name('til_score')
+@ValueOutput.Meta(Meta(scale="percent", min=0, max=100))
+@ValueOutput.Label('TIL score')
+@ValueOutput.Type(int)
+@ValueOutput.Description('percentage of stromal area covered by tumour infiltrating lymphocytes. Values between 0 (percent) to 100 (percent).')
+class TilScoreOutput(ValueOutput):
+    pass
+
+
+class TigerLB2Runner(Module):
+
+    CLI_SCRIPT_PATH = Path(__file__).parent / "cli.py"
+
+    @IO.Instance()
+    @IO.Input('in_data', 'tiff:mod=sm', the='input whole slide image Tiff')
+    @IO.Output('out_data', 'gc_tiger_lb2_til_score.json', 'json:model=TigerLB2TIL', 'in_data', the='TIGER LB2 TIL score')
+    @IO.Output('out_segmentation', 'gc_tiger_lb2_segmentation.mha', 'mha:mod=seg:model=TigerLB2TIL', 'in_data', the='Raw initial TIGER LB2 segmentation map for the input WSI image. The labels are: 1-Tumor, 2-Stroma, 3-Rest.')
+    @IO.OutputData('til_score', TilScoreOutput, data='in_data', the='TIGER LB2 TIL score - percentage of stromal area covered by tumour infiltrating lymphocytes. Values between 0-100 (percent).')
+    def task(self, instance: Instance, in_data: InstanceData, out_data: InstanceData, out_segmentation: InstanceData, til_score: TilScoreOutput) -> None:
+        # Execute the Tiger LB2 Algorithm through a Python subprocess and associated pipenv environment
+        self.subprocess(
+            [
+                "pipenv",
+                "run",
+                "python",
+                str(self.CLI_SCRIPT_PATH),
+                in_data.abspath,
+                out_data.abspath,
+                out_segmentation.abspath,
+            ]
+        )
+
+        # Validate that the required output file(s) were generated by the subprocess
+        for expected_file_path in (out_data.abspath, out_segmentation.abspath):
+            if not Path(expected_file_path).is_file():
+                raise FileNotFoundError(
+                    f"Couldn't find expected output file: `{expected_file_path}`. "
+                    f"The subprocess `{self.CLI_SCRIPT_PATH}` did not generate the required output file."
+                )
+
+        # export output til score as data as well
+        with open(out_data.abspath, "r") as f:
+            til_score.value = json.load(f)
+        assert isinstance(til_score.value, int)

models/gc_tiger_lb2/utils/__init__.py

@@ -0,0 +1 @@
+from .TigerLB2Runner import *

models/gc_tiger_lb2/utils/cli.py

@@ -0,0 +1,61 @@
+"""
+-----------------------------------------------------------
+GC / MHub - CLI Run script for the TIGER LB2 Algorithm
+  The model algorith was wrapped in a CLI to ensure
+  the mhub framework is able to properly capture the nnUNet
+  stdout/stderr outputs. Furthermore, it simplifies running
+  the algorithm in its own environment using pipenv.
+-----------------------------------------------------------
+
+-----------------------------------------------------------
+Author: Sil van de Leemput
+Email:  [email protected]
+-----------------------------------------------------------
+"""
+import argparse
+from pathlib import Path
+
+import torch
+import SimpleITK
+
+# The required pipeline methods are imported from the tiger_challenge repository
+# The algorithm.rw module is imported for IO operations
+import pipeline.tils_pipeline as tils_pipeline
+import algorithm.rw as rw
+
+
+def tiger_lb2_cli() -> None:
+    parser = argparse.ArgumentParser("Tiger LB2 Run CLI")
+    parser.add_argument("input_file", type=str, help="Input WSI TIFF file path")
+    parser.add_argument("output_file", type=str, help="Output JSON file path")
+    parser.add_argument("output_segmentation_file", type=str, help="Output segmentation MHA file path")
+    args = parser.parse_args()
+    run_tiger_lb2(
+        wsi_filepath=Path(args.input_file),
+        output_json_file=Path(args.output_file),
+        output_segmentation_file=Path(args.output_segmentation_file),
+    )
+
+
+def run_tiger_lb2(wsi_filepath: Path, output_json_file: Path, output_segmentation_file: Path) -> None:
+    if not torch.cuda.is_available():
+        raise RuntimeError("run_tiger_lb2 requires CUDA to be available!")
+
+    print(f"Input WSI: {wsi_filepath}")
+    wsi_mri = rw.open_multiresolutionimage_image(wsi_filepath)
+
+    print("Run pipeline")
+    tils_score, seg_mask_np = tils_pipeline.run_tils_pipeline(wsi_mri)
+
+    print(f"Writing segmentation map to {output_segmentation_file}")
+    seg_mask_sitk = SimpleITK.GetImageFromArray(seg_mask_np)
+    SimpleITK.WriteImage(seg_mask_sitk, str(output_segmentation_file), True)
+
+    print(f"Writing tils score to {output_json_file}")
+    tils_score_writer = rw.TilsScoreWriter(output_json_file)
+    tils_score_writer.set_tils_score(tils_score=tils_score)
+    tils_score_writer.save()
+
+
+if __name__ == "__main__":
+    tiger_lb2_cli()