diffusion-mri
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 corre
Install
npx skills add https://github.com/KeWang0622/mri-research-skill/tree/main/skills/diffusion-mri
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kewang0622-mri-research-skill@llmmart
git clone https://github.com/KeWang0622/mri-research-skill.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kewang0622/mri-research-skill collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 for primary papers, textbooks, publication details, direct source links and what each source supports. Use the repo-wide reference index 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
For project experiments, read .mri-research/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
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 when installing,
repairing, or choosing an execution environment. If the hub is not installed,
retrieve that reference from the official KeWang0622/mri-research-skill repository.
DWI, DTI and acquisition choices
Read DWI and DTI 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
- Convert & organize — DICOM→NIfTI with
dcm2niix(keeps.bval/.bvec); organize as BIDS. Sanity-check the gradient table. - 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). - Gibbs ringing removal — MRtrix3
mrdegibbs. - Distortion + eddy + motion — FSL
topup(reversed phase-encode pairs) theneddy(retain its rotated b-vectors): https://fsl.fmrib.ox.ac.uk/fsl/docs/#/diffusion/eddy . - Mask / bias field — brain mask; N4 bias correction (ANTs).
- Model fitting (below).
- 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
- 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).
Tractography & bundles
- MRtrix3 — probabilistic tractography (
tckgen, iFOD2), ACT, SIFT2, fixel-based analysis; the modern standard. - DIPY — deterministic/probabilistic tractography in Python.
- FSL FDT —
bedpostx/probtrackxprobabilistic tracking. - TractSeg (https://github.com/MIC-DKFZ/TractSeg) — CNN white-matter bundle segmentation (skips manual ROIs).
Vendor / acquisition notes
- Always keep the
.bval/.bvecwith the data; check b-vector orientation vs. image axes (a flipped bvec silently ruins tractography). - For
topupyou 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 totopup. - Multi-shell (multiple b-values) enables DKI/NODDI/multi-tissue CSD.
Hand-offs
- This skill starts from reconstructed DWI volumes. If the user has raw
k-space (twix/ISMRMRD/
.cfl) and no images yet,mri-reconstructiongets 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-researchhub. - Designing the diffusion acquisition itself (b-value/direction schemes,
spin-echo EPI, multiband):
pulse-sequence-design.
Deeper reference (analysis tooling, formats): https://github.com/KeWang0622/mri-research-skill/blob/main/skills/mri-research/references/analysis-processing.md
Files (mri-research-skill)
-
references
-
dwi-dti.md 4.8 KB
# DWI and DTI: acquisition to interpretable maps Read for diffusion-weighted data, tensor fitting, ADC/FA/MD maps or a diffusion study plan. Diffusion MRI measures water displacement statistics; it is not a generative diffusion model. DENSE measures coherent tissue displacement and belongs in the sequence-design reference, not the DTI pipeline. ## Choose the measurement before the model | Term | What it describes | Decision it changes | |---|---|---| | DWI | Images acquired with diffusion sensitization, indexed by b-value and direction | Preserve each volume's encoding and acquisition metadata. | | ADC | An apparent diffusivity estimated under a chosen signal model | Report b-values and fitting method; a bright DWI image alone is not proof of low diffusivity. | | DTI | A symmetric diffusion tensor fitted to directional DWI | Needs sufficient independent directions and an appropriate b-value range; cannot resolve multiple fiber populations within a voxel. | | HARDI / multi-shell | Angular sampling / sampling at multiple b-values | These describe acquisition, not a unique fitted model. | | DKI, CSD, NODDI | Different models for non-Gaussian diffusion, fiber orientations or microstructure | Check each model's acquisition requirements and assumptions before fitting. | For a single tensor, `S(b,g) = S0 exp(-b gᵀ D g)`, with unit direction `g`, `b` in s/mm² and diffusivity in mm²/s. Six independent tensor components plus `S0` must be estimated: six independent diffusion directions and a b≈0 reference are an algebraic minimum, not a robust acquisition recommendation. Select angular coverage, repeats, b-values and SNR for the question; do not fit a tensor blindly to all high-b shells. See the [DIPY tensor tutorial](https://docs.dipy.org/stable/examples_built/reconstruction/reconst_dti.html). ## Inspect the inputs - Match NIfTI volume count to `.bval` and `.bvec` entries; check finite values, b≈0 volumes, shells and direction norms. Preserve original files. - Inspect b-vector coordinates against image orientation. Conversion, rotation and resampling can change conventions; do not fix a suspected flip by trial and error until the anatomy merely looks plausible. - Retain BIDS `PhaseEncodingDirection`, `TotalReadoutTime`, voxel sizes and acquisition details. A filename saying AP/PA is not sufficient metadata. - Examine representative b≈0 and diffusion-weighted volumes for dropout, motion, distortion, ghosts, coverage and noise floor before deciding the pipeline. ## Preprocess, then fit Use official [FSL diffusion guidance](https://fsl.fmrib.ox.ac.uk/fsl/docs/diffusion/index.html) and established MRtrix3/DIPY workflows. Denoising and Gibbs correction generally precede interpolation; check denoiser assumptions and partial-Fourier caveats in [`mrdegibbs`](https://userdocs.mrtrix.org/en/latest/reference/commands/mrdegibbs.html). `topup` estimates susceptibility fields from suitable differing phase-encoding images, commonly reversed-PE b≈0 pairs. A conventional fieldmap is a different input route, not an interchangeable `topup` input. `eddy` addresses motion and eddy-current effects and can use a susceptibility estimate. Use its corrected images **with the rotated b-vectors** for downstream fitting; inspect outlier and motion reports. See the [eddy guide](https://fsl.fmrib.ox.ac.uk/fsl/docs/diffusion/eddy/users_guide/index.html). For BIDS datasets, [QSIPrep](https://qsiprep.readthedocs.io/) handles preprocessing; [QSIRecon](https://qsirecon.readthedocs.io/) handles downstream diffusion modeling and tractography. Here “reconstruction” means diffusion-model reconstruction, not reconstructing raw scanner k-space. Avoid repeating corrections on derivatives. Fit with DIPY, MRtrix3 or FSL using the selected shells, corrected gradients and an inspected mask. Keep the estimator and software version in the run record. ## Evaluate and report - MD is the mean tensor eigenvalue; AD is the largest eigenvalue and RD the mean of the other two. FA measures eigenvalue anisotropy, not “white-matter health.” - Inspect FA/MD, fit residuals, eigenvalue behavior, masks and principal-direction maps together. Report diffusivity units and display scales. - Crossing fibers, partial volume, motion, noise and protocol differences can change tensor metrics. A metric change alone does not identify a biological mechanism; design controls and report alternative explanations. - Tractography is model-dependent inference; streamline counts are not axon counts. Use suitable orientation models and validate downstream claims. Example request: “Compare FA between groups.” First inspect acquisition and preprocessing comparability, motion and registration; then choose fitting, statistics and confound handling. Deliver QC figures, maps, effect sizes and limitations, not only a significant p-value. -
reading-list.md 2.1 KB
# Papers and textbooks — diffusion-mri [Skill instructions](../SKILL.md) · [All skill reading lists](../../../REFERENCES.md) A starter reading list, organized by the decision it supports. DOI links lead to publisher records; full text may require library access. Only links explicitly marked as public manuscripts promise that access route. Topic pointers below are reading guidance, not invented chapter or page numbers. ## Diffusion encoding Stejskal EO, Tanner JE. **Spin Diffusion Measurements: Spin Echoes in the Presence of a Time-Dependent Field Gradient.** Journal of Chemical Physics, 1965;42:288–292. [DOI](https://doi.org/10.1063/1.1695690). **Use it for:** Pulsed-gradient diffusion sensitization and the assumptions behind diffusion attenuation. ## Tensor model Basser PJ, Mattiello J, LeBihan D. **MR diffusion tensor spectroscopy and imaging.** Biophysical Journal, 1994;66:259–267. [PubMed](https://pubmed.ncbi.nlm.nih.gov/8130344/) · [DOI](https://doi.org/10.1016/S0006-3495%2894%2980775-1). **Use it for:** The tensor formulation, directional diffusion and tissue orientation. ## Preprocessing Andersson JLR, Sotiropoulos SN. **An integrated approach to correction for off-resonance effects and subject movement in diffusion MR imaging.** NeuroImage, 2016;125:1063–1078. [DOI](https://doi.org/10.1016/j.neuroimage.2015.10.019). **Use it for:** Why susceptibility, eddy-current effects and motion must be handled before interpreting fitted maps. ## Practical references and software [DWI/DTI practical guide](dwi-dti.md) · [DIPY tensor tutorial](https://docs.dipy.org/stable/examples_built/reconstruction/reconst_dti.html) · [FSL eddy documentation](https://fsl.fmrib.ox.ac.uk/fsl/docs/diffusion/eddy/index.html) Software documentation explains installation and APIs; it does not replace the method paper. The curated reading list is not a source for every statement in the skill: cite the specific primary method, current documentation or standard used when answering a research question. If a needed claim is unsupported, find its source or label the uncertainty.
-
-
SKILL.md 6.2 KB
--- 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. metadata: author: Ke Wang version: "0.7.0" --- # 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](../../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 For project experiments, read `.mri-research/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](../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](../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/mri-research-skill` 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 - **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). ## Tractography & bundles - **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). ## Vendor / acquisition notes - 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. ## Hand-offs - 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`. Deeper reference (analysis tooling, formats): https://github.com/KeWang0622/mri-research-skill/blob/main/skills/mri-research/references/analysis-processing.md
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.