diffusion-mri · diff
v0.8.0 to v0.11.0
56 added, 108 removed. Audit A to A.
---
name: diffusion-mri
description: >-
- Diffusion MRI (dMRI) expert — acquisition, preprocessing, modeling, and
- tractography. Use for anything diffusion-weighted: DWI/DTI/DKI/NODDI/HARDI,
- b-values and b-vectors (bval/bvec), diffusion preprocessing (denoising, Gibbs
- removal, susceptibility distortion + eddy/motion correction), fiber-orientation
- estimation (CSD), tractography, white-matter bundle segmentation, and turnkey
- diffusion pipelines. Tools: MRtrix3, DIPY, FSL (eddy/topup/FDT), AMICO (NODDI),
- TractSeg, QSIPrep. Triggers: diffusion MRI, DTI, DKI, tractography, FA/MD,
- bvec/bval, dwidenoise, topup, eddy, CSD, fixel, NODDI, connectome. Starts from
- reconstructed DWI volumes — for k-space reconstruction hand off to
- mri-reconstruction, and for non-diffusion image analysis to the mri-research hub.
+ Read before fitting, converting or reporting any diffusion-weighted MRI
+ result: ADC, DTI/DKI (FA, MD, kurtosis, eigenvectors), IVIM, NODDI,
+ multi-compartment or spectrum signal fractions, CSD and tractography, and
+ diffusion biomarker or repeatability studies. Prevents silent errors:
+ b-vector frames (FSL, vendor, world) when reporting orientations, b-values
+ from vector norms, the b-range for conventional ADC/DTI, noise-floor bias, units,
+ and biased or unstable fractions from uncalibrated model settings. Ships tested
+ numpy helpers (frame conversion with forward-phantom checks, closed-form tensor
+ fit, noise floor, regularized and fixed-basis fits, calibration, stratified
+ recovery tests). Starts from reconstructed DWI.
metadata:
author: Ke Wang
- version: "0.8.0"
+ version: "0.11.0"
---
# MRFoundry: Diffusion MRI
- You are a diffusion-MRI scientist. Diffusion data is often EPI-based and artifact-prone,
- so preprocessing quality dominates results — respect the pipeline order.
-
-
- ## Papers and textbooks
-
- See the [annotated reading list](references/reading-list.md) for primary papers,
- textbooks, publication details, direct source links and what each source supports.
- Use the [repo-wide reference index](https://github.com/KeWang0622/MRFoundry/blob/main/REFERENCES.md) to navigate across skills.
- When using a method, cite its specific source; distinguish paper evidence from
- software instructions and current venue/safety requirements.
-
-
- ## Project research memory
-
- If only the legacy `.mri-research/` notebook exists, migrate it with the project
- memory initializer before creating new notes; preserve existing evidence.
- For project experiments, read `.mrfoundry/INDEX.md` when present and retrieve
- only relevant preferences, environment notes and evidence-linked lessons. After
- meaningful runs or corrections, record outcomes, failures, limitations and next
- steps; revise scoped lessons without erasing history. Keep user preferences
- separate from scientific findings. Use the [project memory workflow](https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/project-memory.md)
- to initialize the folder or connect project `CLAUDE.md` / `AGENTS.md`. If the hub
- is absent, retrieve the reference from the official skill repository.
-
- ## Tool setup before execution
-
- For any application this skill uses, check for a compatible installation and
- follow the official upstream's setup instructions. Within the authorized task,
- install missing dependencies yourself in an isolated environment, run a small
- upstream example, then execute the user's workflow. Do not leave routine setup
- to the user or replace a missing tool with a homemade numerical implementation.
- Use established simulators/solvers; write only necessary configuration and glue.
- If blocked, report the actual obstacle and an established alternative.
- Read the [tool setup guide](https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/tool-setup.md) when installing,
- repairing, or choosing an execution environment. If the hub is not installed,
- retrieve that reference from the official `KeWang0622/MRFoundry` repository.
-
- ## DWI, DTI and acquisition choices
-
- Read [DWI and DTI](references/dwi-dti.md) for the measurement/model distinction,
- gradient and BIDS metadata checks, tensor fitting, QC and interpretation limits.
- DWI is acquired data; DTI is one model of it. EPI is a readout, and DENSE is
- tissue-displacement imaging, not a diffusion-tensor technique.
-
- ## Typical pipeline
-
- 1. **Convert & organize** — DICOM→NIfTI with `dcm2niix` (keeps `.bval`/`.bvec`);
- organize as BIDS. Sanity-check the gradient table.
- 2. **Denoise** — MP-PCA via MRtrix3 `dwidenoise` (do this first, on raw data):
- https://github.com/MRtrix3/mrtrix3 (Veraart 2016, *NeuroImage*). DIPY offers
- Patch2Self (self-supervised).
- 3. **Gibbs ringing removal** — MRtrix3 `mrdegibbs`.
- 4. **Distortion + eddy + motion** — FSL **`topup`** (reversed phase-encode pairs)
- then **`eddy`** (retain its rotated b-vectors): https://fsl.fmrib.ox.ac.uk/fsl/docs/#/diffusion/eddy .
- 5. **Mask / bias field** — brain mask; N4 bias correction (ANTs).
- 6. **Model fitting** (below).
- 7. **Tractography / bundles** (below).
-
- Prefer a validated turnkey pipeline when possible: **QSIPrep**
- (https://github.com/PennLINC/qsiprep) — BIDS-native diffusion preprocessing +
- QC. Downstream diffusion modeling and tractography use **QSIRecon**
- (https://qsirecon.readthedocs.io/); this is distinct from raw k-space reconstruction.
-
- ## Models
+ Use the tested numpy helpers; a closed-form log-linear DTI fit needs no toolbox installation. Open only the
+ row you need; `python .agents/skills/diffusion-mri/scripts/spectrum_fit.py --api` (or `gradient_frames.py`) lists signatures (do not cat the source).
- - **DTI / DKI** — tensors → FA, MD, RD, AD (DTI); kurtosis (DKI). Fit with **DIPY**
- (https://github.com/dipy/dipy) or MRtrix3.
- - **CSD (constrained spherical deconvolution)** — fiber orientation distributions
- for crossing fibers; MRtrix3 `dwi2fod`.
- - **NODDI / microstructure** — neurite density & orientation dispersion; fit fast
- with **AMICO** (https://github.com/daducci/AMICO).
+ ## Route
- ## Tractography & bundles
+ | Task | Use (`scripts/`) | Read only if needed |
+ |---|---|---|
+ | Gradient tables, frames, DTI/DKI orientation, b-values | `gradient_frames.py`: `array_from_fsl`, `fsl_from_world`, `world_from_array`, `world_from_lps`, `bvals_bvecs_from_vectors`, `fit_tensor_lls`, `simulate_tensor_signal` | [DWI and DTI](references/dwi-dti.md) |
+ | ADC, signal fractions, diffusivity spectra, IVIM-type fits | `spectrum_fit.py`: `background_sigma`, `floor_correct`, `adc_fit`, `fit_weights`, `fit_fixed_basis`, `calibrate_basis`, `fraction_below`, `stratified_recovery_test` | [model calibration](../mri-research/references/model-calibration.md) |
+ | Preprocessing (denoise, Gibbs, topup/eddy), CSD, NODDI, tractography, QSIPrep | MRtrix3, FSL, DIPY, AMICO | [preprocessing and models](references/preprocessing-and-models.md) |
+ | Group comparisons, repeatability, cutoffs | `mri-research-workflow/scripts/study_stats.py` | `mri-research-workflow` |
- - **MRtrix3** — probabilistic tractography (`tckgen`, iFOD2), ACT, SIFT2,
- fixel-based analysis; the modern standard.
- - **DIPY** — deterministic/probabilistic tractography in Python.
- - **FSL FDT** — `bedpostx`/`probtrackx` probabilistic tracking.
- - **TractSeg** (https://github.com/MIC-DKFZ/TractSeg) — CNN white-matter bundle
- segmentation (skips manual ROIs).
+ ## Checks that prevent silent errors
- ## Vendor / acquisition notes
+ 1. **Frames as a rule, then an independent test.** FSL bvecs are array-axis components with x negated when
+ det(affine[:3, :3]) > 0; MRtrix3 `-grad` tables are world coordinates; vendor vector files state their own
+ frame (for example patient LPS) and b-value encoding (b may scale with the squared vector norm). Fit in one
+ declared frame and report orientations in world coordinates. Verify with `simulate_tensor_signal`: build
+ signals from a known world fibre direction, pass them through YOUR conversion and fit, and confirm the
+ reported direction. A check that reuses your conversion in both directions cannot detect a frame error.
+ 2. **Conventional ADC/DTI use b <= 1000 s/mm²** (`adc_fit(signals, bvals, bmax=1000)`) unless the study says
+ otherwise; DKI fits all shells including the higher ones.
+ 3. **Units**: MD and ADC in mm²/s (brain tissue about 0.6e-3 to 1.0e-3, free water about 3e-3 at body
+ temperature) or µm²/ms (x1000); b in s/mm². Check map medians with `finish_check.py --range` in the units
+ the task asks for.
+ 4. **Fractions and spectra are ill-conditioned**: default to a regularized spectrum with the weight chosen on
+ development data; calibrate any fixed basis on pooled development curves (`calibrate_basis`) and check
+ identifiability; never copy diffusivities from examples, other organs or protocols.
+ 5. **Stratified recovery tests** (`stratified_recovery_test`): truth for each compared group from development
+ fits, a generative model that differs from the fitting basis, the real b-values and noise. Choose settings
+ by the worst group or bin RMSE, then confirm the worst bias and voxelwise stability (`retest_tol=` reports
+ the fraction of voxels whose estimate changes between two noise realizations). A pooled bias near zero
+ proves nothing about any one tissue.
+ 6. **Noise floor** at high b: estimate sigma from background (`background_sigma`) and correct
+ (`floor_correct`) or fit a Rician-aware model.
+ 7. **Studies**: summarize per subject and session, declare the statistical unit for each endpoint, make every
+ choice on development subjects only, and recompute every reported number from the saved maps.
- - Always keep the **`.bval`/`.bvec`** with the data; check b-vector orientation
- vs. image axes (a flipped bvec silently ruins tractography).
- - For `topup` you need **reversed phase-encode** (blip-up/blip-down) acquisitions
- with suitable metadata. A conventional fieldmap requires a separate
- fieldmap-based route; it is not a replacement image passed directly to `topup`.
- - Multi-shell (multiple b-values) enables DKI/NODDI/multi-tissue CSD.
+ ## Before you finish
- ## Hand-offs
+ python .agents/skills/mri-research-workflow/scripts/finish_check.py --require <every deliverable name> \
+ --rerun "python <entrypoint> <documented arguments with {inputs} and {out}>" --inputs <input folder> \
+ --range <md map>:<low>:<high> # e.g. 0.0001:0.004 for MD in mm²/s
- - This skill starts from **reconstructed DWI volumes**. If the user has raw
- k-space (twix/ISMRMRD/`.cfl`) and no images yet, `mri-reconstruction` gets them
- there first — including the EPI-specific caveat that EPI is Cartesian and needs
- regridding when ramp-sampled plus Nyquist-ghost correction; a
- NUFFT alone does not address these effects.
- - **Non-diffusion image analysis** (fMRI/GLM, FreeSurfer, registration, BIDS
- plumbing) belongs to the `mri-research` hub.
- - **Designing the diffusion acquisition** itself (b-value/direction schemes,
- spin-echo EPI, multiband): `pulse-sequence-design`.
+ ## Setup and scope
- Deeper reference (analysis tooling, formats):
- https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/analysis-processing.md
+ - Use the workspace interpreter (`.venv/bin/python` if present); numpy and scipy cover the helpers. Install
+ DIPY, MRtrix3 or FSL only for steps that need them; see the [tool setup guide](../mri-research/references/tool-setup.md)
+ if an install fails.
+ - Citations: [reading list](references/reading-list.md). Project notes (only with `.mrfoundry/INDEX.md`):
+ [project memory](../mri-research/references/project-memory.md).
+ - Raw k-space: `mri-reconstruction`. Acquisition design: `pulse-sequence-design`. Non-diffusion image
+ analysis: `mri-research`.