Brain Tumor Virtual Biopsy
Code

Additional Pipelines banner

This directory contains supplementary Brain Tumor Virtual Biopsy pipelines that are packaged separately from the primary IDH/1p19q clinical pipeline. The current user-facing entry points include dual-stage workflows that run a 1p/19q model and an IDH model, plus a standalone MGMT workflow. t2_pipeline uses the T2-focused 1p/19q model; mc_pipeline uses the multi-contrast 1p/19q model; mgmt_pipeline uses the multi-contrast MGMT model.

These pipelines are intended for research, evaluation, and workflow development. They share preprocessing components with the clinical pipeline but use their own model bundle and result-writing code.

Pipeline Overview

The main commands are:

python additional_pipelines/bin/py/t2_pipeline.py INDIR OUTDIR
python additional_pipelines/bin/py/mc_pipeline.py INDIR OUTDIR
python additional_pipelines/bin/py/mgmt_pipeline.py INDIR OUTDIR
python additional_pipelines/bin/py/t2_pipeline_csv.py SUBJECTS.csv OUTDIR
python additional_pipelines/bin/py/mc_pipeline_csv.py SUBJECTS.csv OUTDIR
python additional_pipelines/bin/py/mgmt_pipeline_csv.py SUBJECTS.csv OUTDIR

The pipeline performs four major steps:

  1. Select or convert MRI inputs.
  2. Preprocess the subject with ANTs by default, or FeTS when requested.
  3. Run the selected model workflow.
  4. Write per-model CSV outputs and a subject_predictions.json report.

The DICOM or NIfTI study should include T1, T1 post-contrast, T2, and T2 FLAIR images. For NIfTI input, JSON sidecars are optional but useful for sequence selection.

The CSV wrappers assume DICOM to NIfTI conversion has already been completed and that the input CSV has SubjectID, T1, T1GD, T2, and T2FLAIR columns. Each row is processed into OUTDIR/SubjectID, and the batch summary is written to OUTDIR/results.csv.

Docker Build

Build the additional-pipelines image from this directory:

cd /path/to/btvb/additional_pipelines
docker build -t git.biohpc.swmed.edu:5050/ansir/btvb/additional_pipelines:cpu .

The Dockerfile packages ANTs, dcm2niix, nnUNet v2, ANSIR utilities, the additional pipeline source, templates, nnUNet patches, and the bundled model folders under /opt/additional_pipelines.

Docker Usage

For a DICOM input directory:

docker run --rm -it \
  -v /path/to/subject_dicom:/input:ro \
  -v /path/to/output:/output \
  git.biohpc.swmed.edu:5050/ansir/btvb/additional_pipelines:cpu \
  python /opt/additional_pipelines/bin/py/t2_pipeline.py /input /output

Use mc_pipeline.py instead of t2_pipeline.py to run the multi-contrast 1p/19q first stage. Use mgmt_pipeline.py to run the standalone MGMT workflow.

For batch CSV input with existing NIfTI paths:

docker run --rm -it \
  -v /path/to/data:/data \
  -v /path/to/output:/output \
  git.biohpc.swmed.edu:5050/ansir/btvb/additional_pipelines:cpu \
  python /opt/additional_pipelines/bin/py/t2_pipeline_csv.py \
    /data/subjects.csv /output

For previously converted NIfTI input:

docker run --rm -it \
  -v /path/to/subject_nifti:/input:ro \
  -v /path/to/output:/output \
  git.biohpc.swmed.edu:5050/ansir/btvb/additional_pipelines:cpu \
  python /opt/additional_pipelines/bin/py/t2_pipeline.py \
    /input /output \
    --skip_dicom_conversion

To request a specific torch device, pass --device:

python /opt/additional_pipelines/bin/py/t2_pipeline.py /input /output --device cpu

or:

python /opt/additional_pipelines/bin/py/t2_pipeline.py /input /output --device cuda:0

For Docker GPU runs, add --gpus all to the docker run command and use --device cuda:0.

Local Usage

When running from a checkout rather than a container, initialize the additional-pipelines environment variables first:

cd /path/to/btvb
source additional_pipelines/bin/env.bash
python additional_pipelines/bin/py/t2_pipeline.py /path/to/input /path/to/output
python additional_pipelines/bin/py/t2_pipeline_csv.py /path/to/subjects.csv /path/to/output

Local execution requires the same runtime dependencies as the container: ANTs, dcm2niix, PyTorch, nnUNet v2, ANSIR utilities, and the bundled model folders.

Output Files

The main combined report is:

OUTDIR/subject/subject_predictions.json

For FeTS preprocessing runs, the report is written under:

OUTDIR/DataForFeTS/subject/subject_predictions.json

The JSON report follows the clinical pipeline schema:

{
    "subject_id": "subject",
    "IDH_status": "IDH Mutated",
    "mutated_voxel_percentage": 94.54,
    "wildtype_voxel_percentage": 5.46,
    "1p19q_status": "1p19q non-codeleted",
    "codel_voxel_percentage": 30.05,
    "non-codel_voxel_percentage": 69.95
}

For IDH wild-type predictions, the pipeline reports:

"1p19q_status": "1p19q non-codeleted (assumed from IDH WT)"

The 1p/19q voxel percentages still come from the 1p/19q model output.

For mgmt_pipeline, the JSON report contains:

{
    "subject_id": "subject",
    "MGMT_status": "MGMT methylated",
    "methylated_voxel_percentage": 62.14,
    "unmethylated_voxel_percentage": 37.86
}

Additional model-specific files are written to:

The 1p/19q CSV uses Co-deleted_voxel_percentage and Non_co-deleted_voxel_percentage. The IDH CSV uses Mutated_voxel_percentage and WildType_voxel_percentage. The MGMT CSV uses Methylated_voxel_percentage and Unmethylated_voxel_percentage.

CSV wrapper batch summaries are written to OUTDIR/results.csv. The T2 and multi-contrast 1p/19q wrappers include IDH and 1p/19q columns. The MGMT wrapper includes MGMT status and methylated/unmethylated voxel percentage columns.

Command-Line Options

Key options exposed by t2_pipeline.py, mc_pipeline.py, and mgmt_pipeline.py include:

The hidden --fets option switches preprocessing from the default ANTs path to the FeTS preprocessing path.

The CSV wrappers expose the same preprocessing/model/template/device options except --skip_dicom_conversion, which is always enabled because the CSV gives the NIfTI paths directly.

Models

The packaged workflows use:

Model folders are expected under additional_pipelines/models locally or /opt/additional_pipelines/models inside the container.

Citation

If you use mgmt_pipeline, please cite:

@article{Yogananda2021MGMT,
  title={{MRI}-Based Deep-Learning Method for Determining Glioma {MGMT} Promoter Methylation Status},
  author={Yogananda, C. G. B. and Shah, B. R. and Nalawade, S. S. and Murugesan, G. K. and Yu, F. F. and Pinho, M. C. and Wagner, B. C. and Mickey, B. and Patel, T. R. and Fei, B. and Madhuranthakam, A. J. and Maldjian, J. A.},
  journal={American Journal of Neuroradiology},
  volume={42},
  number={5},
  pages={845--852},
  year={2021},
  doi={10.3174/ajnr.A7029},
  url={https://www.ajnr.org/content/42/5/845}
}

The article page includes an editorial expression of concern and a subsequent erratum; review those notices when interpreting reported performance.

Repository Layout

Notes And Caveats

This pipeline is not the same entry point as the primary clinical pipeline. It is useful for testing and extending the additional 1p/19q and IDH model workflows.

Model outputs are research outputs and should be interpreted in the context of the underlying model training data, preprocessing assumptions, and validation history.

Funding

Funding provided by NIH/NCI grant R01CA260705.