Deep T1 Hypointensity

Developed by Elior Drori, Mezer Lab, The Hebrew University of Jerusalem.

If you use this software, please reference https://github.com/eliord/deep-t1-hypo where appropriate.

Python tools for constructing a deep-gray-matter region of interest (ROI) from a FreeSurfer aseg/aparc+aseg or SynthSeg segmentation and for generating experimental T1-weighted hypointensity candidates inside that ROI.

This package produces research candidates, not diagnoses. T1-weighted MRI alone cannot reliably distinguish enlarged perivascular spaces, lacunes, segmentation errors, partial-volume voxels, and other causes of low signal.

ROI definition

The ROI covers the general corpus of the basal ganglia, including the striatum, globus pallidus, internal capsule, and nearby white matter.

ROI and candidate outputs are labeled 1=left hemisphere and 2=right hemisphere.

Installation

python -m pip install -e '.[test]'

Command-line pipeline

deep-t1-hypo \
  --t1 subject_T1w.nii.gz \
  --segmentation subject_synthseg.nii.gz \
  --output-dir deep_t1_hypo_output

This single command writes:

• deep_t1_hypo/deep_roi.nii.gz
• deep_t1_hypo/deep_t1_hypo_seg.nii.gz
• deep_t1_hypo/deep_t1_hypo_metadata.json

The anatomical and detection parameters are configurable:

deep-t1-hypo --t1 T1w.nii.gz --segmentation aseg.nii.gz \
  --output-dir output --exclusion-dilation-iterations 1 \
  --opening-iterations 2 --mad-multiplier 3.5 \
  --minimum-component-voxels 2

Candidate detection uses a robust lower-tail threshold inside the ROI:

threshold = median(ROI) - mad_multiplier * 1.4826 * MAD(ROI)

It then retains 26-connected components containing at least two voxels. This is an explicit baseline, not a validated lesion classifier. Bias-field correction and consistent T1 preprocessing are strongly recommended. Parameters and the derived threshold can be written to JSON with --metadata.

Python API

from deep_t1_hypo import create_roi_nifti, detect_hypointensities_nifti

create_roi_nifti("aseg.nii.gz", "deep_roi.nii.gz")
detect_hypointensities_nifti(
    "T1w.nii.gz",
    "aseg.nii.gz",
    "deep_t1_hypo_seg.nii.gz",
    minimum_component_voxels=2,
)

Development

pytest