A Python-native toolkit for diffusion MRI analysis -- pip install and go from
raw dMRI data to microstructure maps, fiber orientations, and tract
segmentations without wrestling with multi-tool installations.
Early phase, under active development. The API may change between releases.
Diffusion MRI analysis typically requires stitching together several packages (FSL, MRtrix3, DIPY, AMICO, ANTs, ...), each with its own installation story, file conventions, and coordinate quirks. kwneuro wraps the best of these tools behind a single, pip-installable Python interface so you can:
- Get started fast -- core analysis (DTI, CSD, registration, template building) works out of the box. Additional tools (brain extraction, NODDI, tract segmentation, harmonization) are available as optional extras.
- Swap models easily -- go from DTI to NODDI to CSD without rewriting your script.
- Work lazily or eagerly -- data stays on disk until you call
.load(), so you control memory usage.
kwneuro is not (yet) a replacement for the full power of FSL or MRtrix3. It is a lightweight layer for researchers who want standard dMRI analyses with minimal friction.
pip install kwneuro # Core (DTI, CSD, registration, templates)
pip install kwneuro[all] # Everything including optional extrasIndividual 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)Requires Python 3.10+.
from kwneuro.dwi import Dwi
from kwneuro.io import FslBvalResource, FslBvecResource, NiftiVolumeResource
# Load DWI data into memory
dwi = Dwi(
NiftiVolumeResource("sub-01_dwi.nii.gz"),
FslBvalResource("sub-01_dwi.bval"),
FslBvecResource("sub-01_dwi.bvec"),
).load()
# Denoise and fit DTI (core -- no extras needed)
dwi = dwi.denoise()
dti = dwi.estimate_dti()
fa, md = dti.get_fa_md()
# Brain extraction and NODDI require optional extras:
# pip install kwneuro[hdbet,noddi]
mask = dwi.extract_brain()
noddi = dwi.estimate_noddi(mask=mask)
# Save everything to disk
dti.save("output/dti.nii.gz")
NiftiVolumeResource.save(fa, "output/fa.nii.gz")
noddi.save("output/noddi.nii.gz")| Capability | What it does | Powered by | Extra |
|---|---|---|---|
| Denoising | Patch2Self self-supervised denoising | DIPY | |
| Brain extraction | Deep-learning brain masking from mean b=0 | HD-BET | [hdbet] |
| DTI | Tensor fitting, FA, MD, eigenvalue decomposition | DIPY | |
| NODDI | Neurite density, orientation dispersion, free water fraction | AMICO | [noddi] |
| CSD | Fiber orientation distributions and peak extraction | DIPY | |
| Tract segmentation | 72 white-matter bundles from CSD peaks | TractSeg | [tractseg] |
| Registration | Pairwise registration (rigid, affine, SyN) | ANTs | |
| Template building | Iterative unbiased population templates (single- or multi-metric) | ANTs | |
| Harmonization | ComBat site-effect removal for multi-site scalar maps | neuroCombat | [combat] |
The
notebooks/
directory contains Jupytext notebooks you can run end-to-end:
- example-pipeline.py -- Single-subject walkthrough: loading, denoising, brain extraction, DTI, NODDI, CSD, and TractSeg.
- example-group-template.py -- Multi-subject FA/MD template construction using iterative registration.
- example-harmonization.py -- ComBat harmonization of multi-site scalar maps.
Contributions are welcome! Set up a dev environment with uv:
uv sync --extra dev
uv run pre-commit installRun the tests and linter:
uv run pytest
uv run ruff check .See CONTRIBUTING.md 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.