Claude Skill

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

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download kewang0622-mri-research-skill-skills_diffusion-mri-adaaf21.zip · 6 KB
Part of kewang0622/mri-research-skill — 7 skills

Install

skills CLI npx skills add https://github.com/KeWang0622/mri-research-skill/tree/main/skills/diffusion-mri
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kewang0622-mri-research-skill@llmmart
Git 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

  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

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.

No comments yet.

Reviews (0)

No reviews yet.

Related