Getting Started

Installation

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.

Quick starts

DWI microstructure

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.

Structural MRI

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.

Caching

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.

Command line

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

What’s included

Area	Capability	Powered by	Install
DWI	Patch2Self denoising, DTI, FA/MD, CSD response/peaks	DIPY	core
DWI	NODDI maps: NDI, ODI, free-water fraction	AMICO	[noddi]
DWI	White-matter tract segmentation from CSD peaks	TractSeg	[tractseg]
Structural	N4 bias correction and Atropos tissue segmentation	ANTsPy	core
Structural	Brain extraction	HD-BET	[hdbet]
Structural	Deep Atropos segmentation and DKT parcellation	ANTsPyNet	[antspynet]
Cross-modal	DWI/T1 registration, transforms, and template building	ANTsPy	core
Group data	ComBat harmonization of scalar maps	neuroCombat	[combat]
Pipelines	Lazy resources, file helpers, CLI commands, caching	kwneuro	core