kwneuro is a Python package for building MRI analysis workflows around diffusion microstructure and structural MRI data.

It works with ordinary NIfTI images and FSL-style .bval/.bvec files, then gives you composable Python objects for common steps: denoising, DTI, NODDI, CSD, brain masks, T1 bias correction, tissue segmentation, parcellation, registration, template building, harmonization, and cached reruns of expensive work.

kwneuro is designed for workflows that:

• fit diffusion microstructure models and write scalar maps such as FA, MD, NDI, ODI, and free-water fraction;
• combine DWI and structural MRI data through masking, registration, segmentation, and region-level analysis;
• build study-specific templates or harmonize scalar maps across sites;
• write Python pipeline code without managing each backend tool's file formats and coordinate conventions yourself.

kwneuro is not intended to be a replacement for the full power of FSL or MRtrix3. It is a lightweight layer for researchers who want standard structural or dMRI analyses with minimal friction.

pip install kwneuro              # Core DWI, structural, registration, templates
pip install "kwneuro[all]"       # All optional backends

Individual optional extras can also be installed separately:

pip install "kwneuro[hdbet]"      # Brain extraction (HD-BET)
pip install "kwneuro[noddi]"      # NODDI estimation (AMICO)
pip install "kwneuro[tractseg]"   # Tract segmentation (TractSeg)
pip install "kwneuro[combat]"     # ComBat harmonization (neuroCombat)
pip install "kwneuro[antspynet]"  # Deep structural segmentation/parcellation

Some optional extras install PyTorch- or TensorFlow-backed tools. If the selected wheel does not match your GPU or driver, install the CPU-only or CUDA-specific backend appropriate for that machine before installing the extra.

Requires Python 3.10-3.13.

from kwneuro import read_dwi_fsl, write_volume

# .bval and .bvec are inferred from the DWI NIfTI path when they
# use the same BIDS-style stem.
dwi = read_dwi_fsl("sub-01_dwi.nii.gz").load()

dwi_denoised = dwi.denoise()
dti = dwi_denoised.estimate_dti()
fa, md = dti.get_fa_md()

write_volume(dti.volume, "output/dti.nii.gz")
write_volume(fa, "output/fa.nii.gz")
write_volume(md, "output/md.nii.gz")

Pass explicit bval= or bvec= paths to read_dwi_fsl() when those files do not share the DWI NIfTI stem.

from kwneuro import read_structural, write_structural, write_volume

t1 = read_structural("sub-01_T1w.nii.gz").load()

t1_corrected = t1.correct_bias()
tissue_labels = t1_corrected.segment_tissues()

write_structural(t1_corrected, "output/sub-01_T1w_n4.nii.gz")
write_volume(tissue_labels, "output/sub-01_tissues.nii.gz")

The file helpers are convenience adapters for file-first scripts and notebooks. The resource model remains the core API for reusable pipelines.

Wrap pipeline code in a Cache context to persist outputs and reuse them when the same inputs and parameters are seen again:

from kwneuro import Cache, read_dwi_fsl

dwi = read_dwi_fsl("sub-01_dwi.nii.gz")

with Cache("cache/sub-01"):
    dwi_denoised = dwi.denoise()
    dti = dwi_denoised.estimate_dti()

Outside a Cache context, the same functions run normally.

Common one-step workflows are also exposed through the kwneuro command:

kwneuro --help

kwneuro dwi dti \
  --dwi sub-01_dwi.nii.gz \
  --out-dti output/dti.nii.gz \
  --out-fa output/fa.nii.gz \
  --out-md output/md.nii.gz

kwneuro structural segment-tissues \
  --image sub-01_T1w.nii.gz \
  --out output/tissues.nii.gz

kwneuro registration dwi-to-structural \
  --dwi sub-01_dwi.nii.gz \
  --structural sub-01_T1w.nii.gz \
  --out-transform output/dwi_to_t1_transform

Start with the tutorial that matches the job:

• Run a single-subject DWI microstructure pipeline
• Combine T1 and DWI data for region-level analysis
• Build a population template
• Harmonize multi-site scalar maps
• Use one kwneuro step in an existing non-kwneuroworkflow
• Add a custom non-kwneuro step to a kwneuro pipeline

Contributions are welcome! Set up a dev environment with uv:

uv sync --extra dev
uv run pre-commit install

Run the tests and linter:

uv run pytest
uv run pre-commit run -a

See the Developer Guide for the full guide, including a non-uv setup option.

See the GitHub Discussions for questions and ideas, or open an issue for bugs and feature requests.

This work is supported by the National Institutes of Health under Award Number 1R21MH132982. The content is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.