RCLM

Languages: English | 日本語 (Japanese)

RCLM: Region / ROI Change-conditioned Longitudinal Morphing
Subject-specific simulation of future brain MRI from a baseline T1 scan.

RCLM is an inference-only package. Given a skull-stripped baseline T1 and clinical conditions (sex, age, elapsed years, and optionally ROI volume change ratios), it predicts a future brain MRI via a latent deformation field.

Typical workflow:

1. Skull-strip the T1 (recommended: OpenMAP-T1)
2. Register to MNI (template/MNI_FULL.nii.gz) with src/register.py or --register if needed
3. Place weights under model/ (rclm.pth, args.json)
4. Run src/inference.py with --sex, --age, --years (and optional --vcr-*)
5. Find the simulated future MRI under the output folder

RCLM expects skull-stripped T1-weighted MRI. We recommend running OpenMAP-T1 for skull stripping (and related preprocessing) before RCLM.

Images must also be aligned to the MNI template (template/MNI_FULL.nii.gz). Registration is required for native-space inputs; this repository provides ANTsPy TRSAA registration via src/register.py and the --register flag.

• Python 3.11+
• PyTorch 2.2+ (installed by uv sync; install separately when using pip)
• nibabel, numpy, scipy, tqdm
• Optional: ANTsPy (antspyx) for MNI registration

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

cd RCLM
uv sync

For MNI registration (ANTsPy):

uv sync --extra register

python -m venv .venv
source .venv/bin/activate
# https://pytorch.org/
pip install -r requirements.txt
pip install torch
pip install "antspyx>=0.6.3"   # optional, for registration

model/
  rclm.pth         # pretrained weights
  args.json        # inference hyperparameters

template/
  MNI_FULL.nii.gz  # MNI template (required for registration)

--sex, --age, and --years are required. If no --vcr-* options are set, RCLM runs without VCR conditioning (rates = 0, flag = 0). To enable VCR, set all four --vcr-* options.

uv run python src/inference.py -i input -o output -m model \
  --sex F --age 70 --years 5

Volume change ratio (VCR):

$$ r = \frac{v_{\mathrm{target}} - v_{\mathrm{source}}}{\max(|v_{\mathrm{source}}|, \varepsilon)} $$

where $v$ is ICV-normalized relative volume. Per-ROI --vcr-* values are total change over --years (not annual rates). All four --vcr-* options must be set to enable VCR conditioning; omitting all of them runs without VCR.

Set all ROIs (required for VCR-on):

uv run python src/inference.py -i input -o output -m model \
  --sex F --age 70 --years 5 \
  --vcr-lateral-ventricle 0.2 \
  --vcr-amyg -0.05 \
  --vcr-hippo -0.04 \
  --vcr-sylvian 0.15

Disable VCR (omit all --vcr-*, or use --no-roi-change):

uv run python src/inference.py -i input -o output -m model \
  --sex F --age 70 --years 5 --no-roi-change

trsaa corresponds to ANTsPy type_of_transform="TRSAA" (Translation → Rigid → Similarity → Affine → Affine).

uv sync --extra register

# Registration only
uv run python src/register.py -i input_native -o output

# Register, then run RCLM
uv run python src/inference.py -i input_native -o output -m model \
  --sex F --age 70 --years 5 --register

Optional registration flags: -t / --mni, --reg-iterations, --save-transforms, --verbose.