oncoprep 0.2.3

A toolbox for analysing neuro-oncology MRI

oncoprep

A toolbox for preprocessing and analyzing neuro-oncology MRI using standardized, reproducible pipelines. The toolbox is centered on Nipype workflows, with fMRIprep-style preprocessing, automated tumor segmentation, and radiomics, plus utilities for DICOM→BIDS conversion, BIDS Apps execution, and report generation.

Scope

In-scope

• DICOM→BIDS conversion (heuristic + mapping workflows) with correct sidecars/headers
• BIDS App runner for preprocessing and tumor segmentation (BIDS Derivatives outputs)
• fMRIPrep-style HTML reports
• Multi-site robustness features (sequence missingness, vendor variability, optional defacing)

Out-of-scope (initially)

• Regulatory/clinical certification (THIS IS NOT A CLINICAL TOOL!)
• PACS/REST integration (can be a later adapter)
• Non-MRI modalities unless explicitly added later (PET, perfusion, etc.)

Architecture

OncoPrep is structured as a three-layer Nipype workflow system following nipreps conventions (fMRIPrep, sMRIPrep):

┌─────────────────────────────────────────────────────────────────────┐
│                          CLI / BIDS App                             │
│           oncoprep <bids_dir> <out_dir> participant|group           │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
          ┌────────────────────┴───────────────────┐
          │                                        │
          ▼                                        ▼
┌─────────────────────────────────────┐  ┌─────────────────────────┐
│      Participant-Level Stage        │  │   Group-Level Stage     │
│    init_oncoprep_wf()  (base.py)    │  │  run_group_analysis()   │
│  per-subject/session processing     │  │    (group.py)           │
└──┬────────┬──────────┬──────────┬───┘  │                         │
   │        │          │          │      │ •Collect radiomics      │
   ▼        ▼          ▼          ▼      │  JSONs across cohort    │
┌──────┐┌──────┐┌──────────┐┌────────┐   │ •ComBat harmonization   │
│Anat. ││Segm. ││ Fusion   ││Radiom. │   │  (neuroCombat)          │
│ WF   ││ WF   ││   WF     ││  WF    │   │ •Longitudinal auto-     │
│      ││      ││          ││        │   │  detect & handling      │
│•reg  ││•Dock.││•MAV      ││•Hist   │   │ •Age/sex covariates     │
│•skull││ mod. ││•SIMPLE   ││ norm   │   │ •HTML report            │
│ strip││•nnIn.││•BraTS    ││•SUSAN  │   └────────────┬────────────┘
│•def. ││ act. ││ fusion   ││•PyRad  │                │
│•temp.││ ens. ││          ││ feat.  │                │
└──┬───┘└──┬───┘└────┬─────┘└───┬────┘                │
   │       │         │          │                     │
   └───────┴─────────┴──────────┘                     │
                      │                               │
┌─────────────────────▼───────────────────────────────▼───────────────┐
│                        Outputs Layer                                │
│              DerivativesDataSink → BIDS Derivatives                 │
│   sub-XXX/anat/  •NIfTI  •JSON  •TSV  •HTML reports  •ComBat JSON   │
└─────────────────────────────────────────────────────────────────────┘

Data flow

Participant stage (per-subject):
  BIDS input ─► Anatomical WF ─► registered T1w/T1ce/T2w/FLAIR (native space)
                   │
                   ├──► Segmentation WF ─► tumor labels (native space)
                   │         │
                   │         ├──► Fusion WF ─► consensus segmentation
                   │         │
                   │         └──► Radiomics WF ─► features JSON + report
                   │                  (native-space mask, histogram norm + SUSAN)
                   │
                   ├──► Deferred Template Registration
                   │         (ANTs SyN with dilated tumor mask as -x exclusion)
                   │         │
                   │         └──► Resample tumor seg to template space
                   │                  │
                   │                  └──► VASARI WF ─► features + radiology report
                   │
                   └──► DerivativesDataSink ─► BIDS-compliant derivatives/

Group stage (cohort-wide, after all participants):
  BIDS sidecars ─► generate batch CSV (scanner metadata + age/sex)
       │
       └──► Collect all radiomics JSONs ─► ComBat harmonization ─► harmonized JSONs
                                              │
                                              └──► group_combat_report.html

Features

Feature	Description
BIDS-native	Full BIDS and BIDS Derivatives compliance for inputs, outputs, and file naming (via PyBIDS + niworkflows DerivativesDataSink).
Nipype workflows	Composable Nipype workflow graphs — parallel execution, HPC plugin support (SGE, PBS, SLURM), provenance tracking, and crash recovery.
Container-based segmentation	14 BraTS-challenge Docker models in isolated containers; supports Docker and Singularity/Apptainer runtimes with GPU passthrough.
nnInteractive segmentation	Zero-shot 3D promptable segmentation (Isensee et al., 2025) — no Docker needed, CPU or GPU, ~400 MB model weights from HuggingFace.
Ensemble fusion	Three fusion algorithms (majority vote, SIMPLE, BraTS-specific) combine predictions from multiple models for robust consensus labels.
IBSI-compliant radiomics	Intensity normalization (z-score, Nyul, WhiteStripe), SUSAN denoising, and PyRadiomics feature extraction; reproducible across scanners and sites.
ComBat harmonization	Group-level ComBat batch-effect correction (neuroCombat) removes scanner/site effects from radiomics features while preserving biological covariates (age, sex). Auto-generates batch labels from BIDS sidecars. Supports longitudinal multi-session data with automatic detection.
Multi-modal support	Joint processing of T1w, T1ce, T2w, and FLAIR with automatic handling of missing modalities.
fMRIPrep-style reports	Per-subject HTML reports with registration overlays, tumor ROI contour plots, radiomics summary tables, and methods boilerplate.
HPC-ready	Singularity/Apptainer support with pre-downloadable model caches; PBS/SLURM job script patterns included.
Portable & reproducible	Docker image with all neuroimaging dependencies (ANTs, FSL, FreeSurfer, dcm2niix) pinned; deterministic workflow hashing for cache reuse.

Installation

pip install oncoprep

Optional extras:

pip install "oncoprep[radiomics]"   # PyRadiomics feature extraction
pip install "oncoprep[dev]"         # development (pytest, ruff)

Docker:

docker pull nko11/oncoprep:latest

Quick start

Convert DICOMs to BIDS:

oncoprep-convert /path/to/dicoms /path/to/bids --subject 001

Run preprocessing:

oncoprep /path/to/bids /path/to/derivatives participant \
  --participant-label 001

Run with segmentation (nnInteractive, no Docker needed):

oncoprep /path/to/bids /path/to/derivatives participant \
  --participant-label 001 --run-segmentation --default-seg

Run with radiomics:

oncoprep /path/to/bids /path/to/derivatives participant \
  --participant-label 001 --run-radiomics --default-seg

Run group-level ComBat harmonization (after participant-level radiomics):

oncoprep /path/to/bids /path/to/derivatives group \
  --generate-combat-batch

Generate reports from existing outputs:

oncoprep /path/to/bids /path/to/derivatives participant \
  --participant-label 001 --reports-only

Documentation

Full documentation — including tutorials, CLI reference, Docker/HPC usage, segmentation details, radiomics configuration, and Python API — is available at:

https://oncoprep.readthedocs.io/en/latest

Development

git clone https://github.com/nikitas-k/oncoprep.git
cd oncoprep
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest