This directory contains the user-facing documentation for the Dockerized clinical pipeline. For the shortest copy-paste commands, start with the repository quick start. For container build notes and local development details, see DEVELOPER_README.md.
Scientific Basis¶
This pipeline implements the MRI-based deep learning workflow described by Bangalore Yogananda et al. in Neuro-Oncology Advances (2025) for confidence-informed prediction of isocitrate dehydrogenase (IDH) mutation status in brain gliomas.
The workflow accepts DICOM or NIfTI MRI input and performs preprocessing steps including DICOM conversion when needed, coregistration, N4 bias correction, skull stripping, and tumor segmentation before model inference. The primary reported endpoint is IDH mutation status with voxel-level class percentages and an associated confidence estimate. The pipeline also reports 1p/19q codeletion status; for IDH-wildtype predictions, 1p/19q non-codeletion is assigned according to the molecular classification relationship represented in the implementation.
This repository provides a Docker-based implementation for reproducible execution of the published workflow. Model outputs are intended for research, evaluation, and downstream analysis and should be interpreted in the context of the cited publication.
Pipeline Usage¶
The command-line interface exposes the major stages of the workflow, allowing users to execute the complete pipeline or selectively skip preprocessing, model inference, DICOM conversion, or DICOM output generation.
$ docker run --rm -it git.biohpc.swmed.edu:5050/ansir/btvb/idh_pipeline:cpu --help
usage: utsw_clinical_tumor_idh_pipeline.py [-h]
[--skip_dicom_conversion] [--skip_preprocessing] [--skip_modeling] [--skip_dicom_generation] [--own_directory]
[--preparedataset_template PREPAREDATASET_TEMPLATE] [--preparedataset_brain_template PREPAREDATASET_BRAIN_TEMPLATE]
[--preparedataset_brain_mask PREPAREDATASET_BRAIN_MASK] [--models_dir MODELS_DIR] [-d]
indir [outdir]
Run UTSW IDH classification
positional arguments:
indir Input directory of DICOM files or NIfTI files with sidecars.
outdir Output directory. If not specified, output will be placed in the input directory.
options:
-h, --help show this help message and exit
--skip_dicom_conversion
Skip dicom conversion [STEP 1].
--skip_preprocessing Skip preprocessing (coregistration, n4, etc. previously done) [STEP 2].
--skip_modeling, --skip_modelling
Skip modeling [STEP 3].
--skip_dicom_generation
Skip dicom generation [STEP 4].
--own_directory Place DICOMs in directories named series_number_series_description instead of all together
--preparedataset_template PREPAREDATASET_TEMPLATE
Preprocessing template for coregistration. Also can set ANSIR_CLASS_TEMPLATE. (default: /opt/Templates/T1_FeTS.nii.gz).
--preparedataset_brain_template PREPAREDATASET_BRAIN_TEMPLATE
Preprocessing template for skull stripping. Also can set ANSIR_CLASS_BRAIN_TEMPLATE. (default: /opt/Templates/avgT1_Dartel_IXI550_MNI152.nii).
--preparedataset_brain_mask PREPAREDATASET_BRAIN_MASK
Preprocessing template for brain mask. Also can set ANSIR_CLASS_BRAIN_MASK. (default: /opt/Templates/brainmask.nii).
--models_dir MODELS_DIR
Directory of the IDH_Predictor toolset. (default: /opt/IDH_Predictor/Trained_Models/).
-d, --debug Debug this script. Add more -d to increase verbosity
Examples:
utsw_clinical_tumor_idh_pipeline dicom_directory
Runtime Characteristics¶
In local testbed runs using NIfTI inputs, average end-to-end runtime was approximately 26 minutes with the CPU-tagged Docker image and 17 minutes with the GPU-tagged Docker image. Runtime was dominated by ANTs-based preprocessing, which accounted for more than 15 minutes of the total execution time.
DICOM Input¶
For studies supplied as DICOM series, the pipeline performs image conversion and preprocessing before tumor segmentation and molecular prediction. The example below mounts a local test dataset into the container and writes pipeline outputs to a separate output directory.
docker run -v ../../testbed:/data --rm -it git.biohpc.swmed.edu:5050/ansir/btvb/idh_pipeline:cpu /data/subject0038 /data/clinical_pipeline_out_subject0038
To run the same workflow with GPU acceleration, use Docker's NVIDIA runtime support and the GPU image tag:
docker run --gpus all -v ../../testbed:/data --rm -it git.biohpc.swmed.edu:5050/ansir/btvb/idh_pipeline:gpu /data/subject0038 /data/clinical_pipeline_out_subject0038
NIfTI Input¶
For previously converted studies, NIfTI inputs may be supplied directly. JSON sidecars are optional but recommended because they preserve sequence metadata used during input selection. It is recommended to run without creating output DICOM images, as the routine can be fragile without a template input image.
docker run -e IDH_SKIP_DICOM_GENERATION=1 -v ~/testbed:/data --rm -it git.biohpc.swmed.edu:5050/ansir/btvb/idh_pipeline:cpu \
/data/subject0044 /data/clinical_pipeline_out_subject0044 \
--skip_dicom_conversion --skip_dicom_generation
Explicit Sequence Selection¶
The pipeline will attempt to identify T1, T1 Post, T2, and T2 FLAIR sequences automatically. To specify sequences explicitly, create a file called modality_preference.json in the NIfTI directory (the generated output/nifti directory for DICOM input, or the input directory for NIfTI input). Paths should reference how the data appears inside the container.
{
"t1_pre": "/data/subject0044/AX_T1.nii.gz",
"t1_post": "/data/subject0044/AX_3D_MPR.nii.gz",
"t2": "/data/subject0044/SAG_T2_SPACE.nii.gz",
"flair": "/data/subject0044/SPACE_FLAIR.nii.gz"
}
Example Model Outputs¶
The following examples illustrate the structure of the model-derived JSON outputs. Values are representative of the output schema and should not be interpreted as benchmark results.
IDH Wild-Type¶
Representative output for a case classified as IDH wild-type.
{
"subject_id": "subject",
"IDH_status": "IDH Wild-Type",
"mutated_voxel_percentage": 27.46,
"wildtype_voxel_percentage": 72.54,
"Confidence in IDH prediction": 95.54,
"1p19q_status": "1p19q non-codeleted (assumed from IDH WT)",
"codel_voxel_percentage": 0,
"non-codel_voxel_percentage": 72.54
}
IDH Mutated¶
Representative output for a case classified as IDH-mutated.
{
"subject_id": "subject",
"IDH_status": "IDH Mutated",
"mutated_voxel_percentage": 94.54,
"wildtype_voxel_percentage": 5.46,
"Confidence in IDH prediction": 89.39,
"1p19q_status": "1p19q non-codeleted",
"codel_voxel_percentage": 30.05,
"non-codel_voxel_percentage": 69.95
}
Citation¶
If you use this repository, please cite:
@article{BangaloreYogananda2025IDHConfidence,
title={Bridging the clinical gap: Confidence informed IDH prediction in brain gliomas using MRI and deep learning},
author={{Bangalore Yogananda}, Chandan Ganesh and Truong, Nghi C. D. and Wagner, Benjamin C. and Xi, Yin and Bowerman, Jason and Reddy, Divya D. and Holcomb, James M. and Saadat, Niloufar and Hatanpaa, Kimmo J. and Patel, Toral R. and Fei, Baowei and Lee, Matthew D. and Jain, Rajan and Bruce, Richard J. and Madhuranthakam, Ananth J. and Pinho, Marco C. and Maldjian, Joseph A.},
journal={Neuro-Oncology Advances},
volume={7},
number={1},
pages={vdaf142},
year={2025},
doi={10.1093/noajnl/vdaf142},
url={https://doi.org/10.1093/noajnl/vdaf142}
}
Funding¶
Funding provided by NIH/NCI grant R01CA260705.