kwneuro 0.3.0

Processing pipelines to extract brain microstructure from diffusion MRI

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 -- no system-level dependencies to configure.
• 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

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 extract a brain mask
dwi = dwi.denoise()
mask = dwi.extract_brain()

# Fit DTI and get FA / MD maps
dti = dwi.estimate_dti(mask=mask)
fa, md = dti.get_fa_md()

# Fit NODDI (needs multi-shell data)
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
Denoising	Patch2Self self-supervised denoising	DIPY
Brain extraction	Deep-learning brain masking from mean b=0	HD-BET
DTI	Tensor fitting, FA, MD, eigenvalue decomposition	DIPY
NODDI	Neurite density, orientation dispersion, free water fraction	AMICO
CSD	Fiber orientation distributions and peak extraction	DIPY
Tract segmentation	72 white-matter bundles from CSD peaks	TractSeg
Registration	Pairwise registration (rigid, affine, SyN)	ANTs
Template building	Iterative unbiased population templates (single- or multi-metric)	ANTs

Example notebooks

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.

Contributing

Contributions are welcome! To set up a dev environment:

pip install -e ".[dev]"
pre-commit install

Run the tests and linter:

pytest
ruff check .

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.