Skip to content

About

MRI quantification modules for 3D Slicer: ADC histogram analysis and three T2 mapping variants (1TE, 2TE, AutoRef). Python scripted extensions.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

MR Quant Tools

MRI quantification modules for 3D Slicer — ADC histogram analysis and three T2 relaxometry variants, packaged as one installable bundle.

The four module panels in 3D Slicer: ADC Histogram, T2 Mapping (1 TE), T2 Mapping (2 TE) and T2 Mapping AutoRef

All four modules are Python scripted extensions. They add a 1 - MF MR Quant Tools category to Slicer, work on the volumes and segmentations already in the scene, and write their results back as new volume nodes plus a statistics table — no external binaries, no network access, no extra Python environment.

Research and educational software — not a medical device. The maps are apparent relaxometry values, not validated clinical measurements. See Limitations.


Modules

Module Input Output Reference
ADC Histogram ADC volume + segmentation Histogram with Gaussian fit, Q-Q plot, statistics table, CSV export —
T2 Mapping (2 TE) Two T2-weighted volumes + TE₁/TE₂ T2 map + ROI histogram and statistics Mono-exponential decay
T2 Mapping (1 TE) One T2-weighted volume + TE + anchor tissue T2 map + ROI histogram and statistics Anchor-tissue calibration
T2 Mapping AutoRef One T2-weighted volume + muscle/fat segments Pseudo-T2 map + ROI statistics Sørland et al. 2022; Zhu et al. 2023

Every module works on a segmentation ROI, so measurements are restricted to the tissue you delineated.


Requirements

  • 3D Slicer 5.6 – 5.12 (verified on 5.12.3, Linux)
  • No additional Python packages: the modules use only what Slicer bundles (numpy, scipy, SimpleITK, VTK, Qt)
  • For the unit tests outside Slicer: Python ≥ 3.10 with numpy, scipy, pytest

Installation

git clone https://github.com/lippisch2/MR_Quant_tools.git
cd MR_Quant_tools
python install.py

install.py locates your Slicer installation, copies the four modules into lib/Slicer-X.Y/qt-scripted-modules, and clears stale bytecode. Restart Slicer afterwards and look for the 1 - MF MR Quant Tools category.

python install.py --list          # show detected Slicer installations
python install.py --slicer PATH   # explicit installation directory
python install.py --dry-run       # show what would be copied
python install.py --uninstall     # remove the modules again

Manual copy, "additional module paths", drag-and-drop, and the reason the Extensions Manager's Install from file does not work on 5.12.3 are covered in INSTALL.md.


ADC Histogram

Whole-lesion apparent diffusion coefficient distribution analysis.

Inputs — an ADC volume, a segmentation node, and one segment.

What it computes

  1. Extracts finite, positive ADC voxels inside the segment.

  2. Bins them at a fixed width (range / bins, default 50 bins, adjustable 5–200).

  3. Fits a Gaussian to the raw voxel values (not to the bar heights, which would bias σ), with μ and σ (ddof = 1).

  4. Scales the fitted density back to expected counts:

    fitted_counts(x) = N · bin_width · pdf(x)
    

    so the curve is comparable to the histogram bars in any ADC unit.

  5. Reports mean, median, standard deviation, ADC10, ADC25, skewness, excess kurtosis and a Shapiro–Wilk normality test (subsampled above 5000 voxels, which is scipy's limit).

  6. Optional Q-Q plot with Blom's normal scores, reference lines for mean/median/ADC10/ADC25, a results table, and CSV export (voxel values, histogram + fit, statistics).

Useful for characterising lesion heterogeneity: a low ADC mean with a wide, right-skewed distribution behaves differently from a narrow one, and the histogram makes that visible before you commit to a number.

Unit tests: 20 (modules/ADC_histogram/tests).


T2 Mapping (2 TE)

The most direct of the three T2 modules: two co-registered echoes, no reference tissue needed.

S(TE₁) = S₀ · exp(−TE₁/T2)
S(TE₂) = S₀ · exp(−TE₂/T2)

T2 = (TE₂ − TE₁) / ln( S(TE₁) / S(TE₂) )

S₀ cancels in the ratio, so no flip-angle or proton-density normalisation is required. The implementation rejects, with an explicit warning, voxels where

  • either signal is non-positive or non-finite;
  • S(TE₂) ≥ S(TE₁) — physically impossible for T2 decay (wrong echo order, or noise dominating);
  • T2 exceeds the ceiling (default 2000 ms, i.e. noise).

Options: ROI segmentation, output volume name, optional ROI histogram with mean / median / SD / min / max / P10 / P90, and a literature reference table of T2 values for ten organs. Output geometry (origin, spacing, direction) is copied from the TE₁ volume.

Requirement: the two volumes must be co-registered and share the same geometry — the module does not register them.

Unit tests: 19 (modules/T2_mapping_2TE/tests).


T2 Mapping (1 TE)

Single-echo T2 from an internal reference anchor, for protocols where only one echo was acquired.

S      = S₀ · exp(−TE/T2)
S_ref  = S₀ · exp(−TE/T2_ref)

T2 = TE / ( (TE/T2_ref) − ln(S/S_ref) )

The anchor is a tissue whose T2 is known: CSF (T2_ref = 2000 ms) or fat (T2_ref = 70 ms). S_ref is either detected automatically (CSF peak / fat peak after CSF stripping) or measured inside a segment you draw — tick Measure S_ref from anchor segment and pick the segmentation, segment and statistic (mean, median, P10 or P90).

Instead of a single global S_ref, the module can build a spatial reference map to compensate for B1 and coil-sensitivity variation:

Method poly_degree / map_sigma
Global scalar map_sigma = 0
Nearest-neighbour map_sigma > 0, poly_degree = 0
Polynomial surface fit poly_degree = 1..3

Additional processing: Rician noise-floor correction, optional noise masking, T2 smoothing, clamp range, and an ROI histogram. Physics check: a voxel whose signal equals S_ref maps to exactly T2_ref.

Failure mode to know about: automatic anchor detection can fail on unusual contrast or pathology. If the map looks wrong, measure S_ref from a segment instead — that path is deterministic.

Unit tests: 6 (modules/T2_mapping_1TE/tests).


T2 Mapping AutoRef

A pseudo-T2 map from a single echo by linear two-anchor rescaling, per Sørland et al. 2022 — used for regional muscle and pelvic tissue.

pseudo-T2 = T2_low + (I − I_low) · (T2_high − T2_low) / (I_high − I_low)

You provide one segmentation with a muscle segment (low T2) and a fat segment (high T2). I_low and I_high are robust ROI statistics — by default the 10th percentile of muscle and the 90th percentile of fat, which tolerate imprecise ROI delineation. Mean, median and P90/P10 are also selectable.

Four anchor sets are available, and picking one updates the anchor labels and priors:

Method Low anchor High anchor T2 high (ms)
AutoRef_F Obturator internus muscle (37.4 ± 0.9) Ischioanal fossa fat 129.7 ± 1.9
AutoRef_FH Obturator internus muscle Yellow marrow, femoral heads 137.0 ± 2.7
AutoRef_PB Obturator internus muscle Pelvic bone marrow 98.7 ± 7.6
AutoRef_Zhu2023 Gluteus maximus muscle (51.0 ± 4.4) Subcutaneous fat 134.8 ± 3.9

AutoRef_Zhu2023 uses the 1.5 T values of Zhu et al. 2023 and is intended for pelvic/uterine imaging, where gluteus maximus and subcutaneous fat share the field of view. Both papers' reference tables are reproduced in the module panel as an aide-mémoire.

Pre-processing (all off by default): N4 bias-field correction via SimpleITK, P99 rescaling, and ROI cleanup (largest connected component + morphological opening). Output is optionally clipped to the anchor range; unclipped, voxels outside it are extrapolated as in the paper, which also amplifies noise.

Unit tests: 23 (modules/T2_mapping_AutoRef/tests).


Testing

The computation layer of every module is deliberately Slicer-free, so it can be tested with plain numpy/scipy:

python -m pip install -r requirements-dev.txt
python -m pytest -q          # 74 passed

Coverage is concentrated where errors are silent: the relaxometry equations (known-T2 phantoms), the validity rules, ROI masking, histogram binning, Gaussian-fit scaling, anchor statistics, clipping behaviour, and the literature tables. The Qt widget code is not unit-tested — it is exercised by loading the modules in Slicer.

Run the suite locally with python -m pytest -q (74 tests). The same configuration can be added as a GitHub Actions workflow (.github/workflows/tests.yml) once a push token with workflow scope is available.


Repository layout

MR_Quant_tools/
├── modules/
│   ├── ADC_histogram/
│   │   ├── ADC_histogram.py              # module registration
│   │   ├── ADC_histogramLib/
│   │   │   ├── adc_computation.py        # pure math, no Slicer
│   │   │   ├── ADC_histogramLogic.py     # Slicer I/O, VTK plots, CSV
│   │   │   └── ADC_histogramWidget.py    # Qt panel
│   │   ├── tests/
│   │   └── AGENTS.md                     # architecture + API notes
│   ├── T2_mapping_1TE/                   # same structure
│   ├── T2_mapping_2TE/
│   └── T2_mapping_AutoRef/
├── docs/slicer-modules.png
├── install.py                            # copy into a Slicer installation
├── INSTALL.md
├── pyproject.toml                        # version, pytest and ruff config
└── requirements-dev.txt

Each module keeps its own AGENTS.md: file map, formulas, Slicer 5.12 widget API gotchas, verified behaviours and known limitations. Read it before changing a module.


Limitations

  • Apparent values only. No B₀/B₁ correction, no T2* or multi-component fitting, no motion correction, no registration between echoes.
  • The 2-TE module requires co-registered inputs with identical geometry.
  • The 1-TE and AutoRef maps depend on their anchors. Wrong contrast, mis-placed ROIs, or pathology in the reference tissue bias the whole map. Anchor segmentation is the more reproducible path for the 1-TE module.
  • ADC histogram binning is bin-count driven in the GUI (bin width = range/bins); it changes the visual shape, not the statistics.
  • Not validated clinically. No phantom study, no reader study, no comparison against a commercial relaxometry package.
  • Windows and macOS are untested. The API calls used are identical, and install.py supports both, but only Linux 5.12.3 has been verified.

References


License

MIT — see LICENSE.

The software is provided for research and education. It is not a medical device, has not been cleared or approved by any regulatory body, and must not be used to make patient-care decisions.

About

MRI quantification modules for 3D Slicer: ADC histogram analysis and three T2 mapping variants (1TE, 2TE, AutoRef). Python scripted extensions.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages