kwneuro

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.

Why kwneuro?

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.

Installation

pip install kwneuro             # Core (DTI, CSD, registration, templates)
pip install kwneuro[all]        # Everything including optional extras

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)

Requires Python 3.10+.

Quick start

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")

What’s included

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]

Example notebooks

The notebooks/ directory contains Jupytext notebooks you can run end-to-end:

Contributing

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 ruff check .

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.

Acknowledgements

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.

Indices and tables