NerveTract

Standalone library and 3D Slicer module for nerve tractogram analysis: QuickBundles clustering, branch-split detection, path geometry, and optional along-fiber DTI metrics (FA, MD, AD, RD).

This repository is self-contained. Clone it, install the Python package, and run the CLI or load the Slicer module. You do not need any sibling lab packages.

Requirements

• Python 3.9+
• For the GUI: 3D Slicer 5.x with DIPY available in Slicer’s Python (see below)
• Optional, for DWI → FA/MD/AD/RD maps: MRtrix3, FSL, ANTs on PATH

Python dependencies are declared in pyproject.toml (numpy, scipy, dipy, vtk, matplotlib, pydicom, joblib, nibabel, pynrrd). Excel export also needs xlsxwriter (pip install -e ".[export]").

Install (CLI / library)

git clone <this-repo>
cd NerveTract
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Geometry clustering does not need MRtrix. Put MRtrix/FSL/ANTs on PATH (or set FSLDIR / ANTSPATH) only if you will compute diffusion maps from DWI.

Quick start (CLI)

Pass a VTK tractogram (this repository does not ship imaging data):

python -m nervetract.lib.cli.run_clustering path/to/your_bundle.vtk

That prints geodesic length, tortuosity, hull volume, and density, and writes colored VTK files under output/<basename>/ (gitignored).

Library API:

from nervetract.lib.clustering import read_streamlines, analyze_streamlines

streamlines = read_streamlines("path/to/your_bundle.vtk")
clusters_merged, resampled, split_info, metrics = analyze_streamlines(streamlines)
print(metrics["geodesic_length_mm"], metrics["tortuosity"])

3D Slicer module

1. Clone this repository (do not rely on pip install alone — Slicer loads the scripted module from disk).

2. In Slicer: Edit → Application Settings → Modules → Additional module paths → add:

   …/NerveTract/nervetract/3DSlicer

3. Restart Slicer. The module appears under IMAG2 → NerveTract.

4. Workflow: Bundles → Analyze → optional Diffusion → Results.

Slicer’s Python must be able to import nervetract and DIPY. Easiest path: in Slicer’s Python console,

slicer.util.pip_install("dipy nibabel pynrrd pydicom joblib")

and keep the repository root on sys.path (the module already prepends it via _slicer_paths.py). If DIPY is only in your conda env, launch Slicer from that environment.

Geometry metrics run from VTK tractograms alone. Diffusion metrics need 4D DWI (DICOM or a DWI volume in the scene) or a folder of precomputed *_fa.nii.gz, *_md.nii.gz, *_ad.nii.gz, *_rd.nii.gz, *_b0.nii.gz.

Repository layout

NerveTract/
  nervetract/                 Python package
    lib/                      clustering, geometry, diffusion, CLI
    3DSlicer/                 Slicer scripted module
    resources/                bundled GE 25-dir b=600 gradient tables
    METHOD.md                 scientific method (clustering, geometry, diffusion)
    SLICER_APP_GUIDE.md       3D Slicer module guide
  examples/                   optional local files (imaging not in git)
  docs/                       published FA/MD literature ranges
  data/                       optional local volumes (not in git)

Documentation

File	Read it for
nervetract/METHOD.md	Full method: clustering, branch split, geometry, DTI sampling
nervetract/SLICER_APP_GUIDE.md	Slicer tabs, Compute, and how the module is wired
docs/DIFFUSION_METRICS_LITERATURE.md	Published FA/MD ranges for lumbosacral roots

Tests

pip install -e ".[dev]"
python -m pytest

Acknowledgements

Streamline clustering uses QuickBundles, developed by Eleftherios Garyfallidis, Matthew Brett, Marta M. Correia, Guy B. Williams, and Ian Nimmo-Smith, as implemented in DIPY. If you use this software in a publication, please cite their work:

Garyfallidis E, Brett M, Correia MM, Williams GB, Nimmo-Smith I.
QuickBundles, a Method for Tractography Simplification.
Frontiers in Neuroscience. 2012;6:175.
doi:10.3389/fnins.2012.00175

The DIPY implementation should also be cited:

Garyfallidis E, Brett M, Amirbekian B, Rokem A, van der Walt S, Descoteaux M, Nimmo-Smith I, and DIPY contributors.
Dipy, a library for the analysis of diffusion MRI data.
Frontiers in Neuroinformatics. 2014;8:8.
doi:10.3389/fninf.2014.00008

License

MIT — see LICENSE. Developed at IMAG2 Lab.