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
MRFoundry: Diffusion MRI
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).
Route
| 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 |
| 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 |
| Preprocessing (denoise, Gibbs, topup/eddy), CSD, NODDI, tractography, QSIPrep | MRtrix3, FSL, DIPY, AMICO | preprocessing and models |
| Group comparisons, repeatability, cutoffs | mri-research-workflow/scripts/study_stats.py |
mri-research-workflow |
Checks that prevent silent errors
- Frames as a rule, then an independent test. FSL bvecs are array-axis components with x negated when
det(affine[:3, :3]) > 0; MRtrix3
-gradtables 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 withsimulate_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. - Shells for ADC/DTI come from the study or task, not from a habit. If the task states a single-tensor
(Gaussian) signal model, fit every diffusion-weighted volume. For in vivo data with shells above about
1500 s/mm², a conventional ADC/DTI may keep the lower shells (
adc_fit(..., bmax=1000)); DKI fits all shells. Never hard-code a b cutoff in an entrypoint that is rerun on other schemes: it can leave fewer than six directions or no volumes at all. - 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 --rangein the units the task asks for. - 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. - 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. - Noise floor at high b: estimate sigma from background (
background_sigma) and correct (floor_correct) or fit a Rician-aware model. - 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.
Before you finish
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
Setup and scope
- Use the workspace interpreter (
.venv/bin/pythonif present); numpy and scipy cover the helpers. Install DIPY, MRtrix3 or FSL only for steps that need them; see the tool setup guide if an install fails. - Citations: reading list. Project notes (only with
.mrfoundry/INDEX.md): project memory. - Raw k-space:
mri-reconstruction. Acquisition design:pulse-sequence-design. Non-diffusion image analysis:mri-research.
Files (mri-research-skill)
-
references
-
dwi-dti.md 5.4 KB
Loading… -
preprocessing-and-models.md 1.8 KB
Loading… -
reading-list.md 2 KB
Loading…
-
-
scripts
-
gradient_frames.py 5 KB
Loading… -
spectrum_fit.py 10.6 KB
Loading… -
test_gradient_frames.py 2.3 KB
Loading… -
test_spectrum_fit.py 4.4 KB
Loading…
-
-
SKILL.md 5.1 KB
--- name: diffusion-mri description: >- Read before fitting, converting or reporting diffusion-weighted MRI: ADC, DTI/DKI, IVIM, NODDI, compartment or spectrum fractions, tractography and diffusion biomarker studies. Prevents silent errors in b-vector frames and vendor vector files, the b-range for ADC/DTI, units, noise floor and uncalibrated or unstable fraction models. Ships tested numpy helpers (frame conversion, tensor fit, noise floor, calibration, stratified recovery and retest tests). Starts from reconstructed DWI. metadata: author: Ke Wang version: "0.14.0" --- # MRFoundry: Diffusion MRI 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). ## Route | 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` | ## Checks that prevent silent errors 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. **Shells for ADC/DTI come from the study or task, not from a habit.** If the task states a single-tensor (Gaussian) signal model, fit every diffusion-weighted volume. For in vivo data with shells above about 1500 s/mm², a conventional ADC/DTI may keep the lower shells (`adc_fit(..., bmax=1000)`); DKI fits all shells. Never hard-code a b cutoff in an entrypoint that is rerun on other schemes: it can leave fewer than six directions or no volumes at all. 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. ## Before you finish 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 ## Setup and scope - 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`.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.