Note: This project is still in development and may contain bugs. Please report issues if you encounter problems.

T1Prep: T1 PREProcessing Pipeline (aka PyCAT)

T1Prep is a Python pipeline for preprocessing and segmenting T1-weighted MRI data. It supports:

• Bias-field correction and denoising
• Brain extraction (skull stripping)
• Tissue segmentation (GM, WM, CSF)
• Cortical surface reconstruction and thickness estimation
• Non-linear spatial registration to MNI152 space
• Atlas-based ROI extraction
• White matter hyperintensity (WMH/lesion) detection
• BIDS derivatives output naming

Cortical surface reconstruction uses the cat-surf Python package (pure Python bindings to the CAT-Surface C library — no compiled binaries required).

For full documentation, CLI usage, Docker instructions, and helper scripts see the GitHub repository.

Installation

pip install T1Prep

Multiple Python versions? Install with the exact interpreter you will run T1Prep with, e.g. python3.12 -m pip install T1Prep (requires Python 3.9–3.12; on macOS prefer 3.10+, since a 3.9 install is pinned to PyTorch 2.8 and runs slower). If the wrong interpreter is auto-detected, point T1Prep at the right one with T1Prep --python /path/to/python … or export T1PREP_PYTHON=/path/to/python. pipx install T1Prep or a dedicated venv avoids the ambiguity.

pip install places every entry point into the active environment's bin/ directory. With that directory on your PATH (e.g. an activated venv) the following commands are available:

Download model weights

Model weights are not bundled in the wheel (they are ~500 MB). Download them after installation:

t1prep-download-models

Models are stored alongside the deepmriprep package data and are downloaded automatically on first pipeline use if this step is skipped.

Requirements

• Python 3.9–3.12 (3.10+ recommended). PyTorch 2.9+ (Python 3.10+) adds MPS kernels that give a measurable speed-up on Apple Silicon (2:39 min vs 3:02 min per subject); a Python 3.9 install is pinned to PyTorch 2.8 and falls back to the CPU for those kernels. On Linux/CUDA/CPU both stacks perform the same.
• ~2 GB disk space for model weights (downloaded separately, see above)
• For GPU acceleration: CUDA-capable GPU or Apple Silicon (MPS)

Python API

from t1prep import run_t1prep

# Single file — results saved next to input
run_t1prep("/data/sub-01_T1w.nii.gz")

# Single file, BIDS-compatible output
run_t1prep("/data/sub-01/ses-1/anat/sub-01_ses-1_T1w.nii.gz", bids=True)

# Batch processing with options
run_t1prep(
    ["/data/T1/sub-01.nii.gz", "/data/T1/sub-02.nii.gz"],
    out_dir="/results",
    atlas=["neuromorphometrics", "suit"],
    multi=-1,          # auto-detect parallelism
    wp=True,           # save warped segmentations
    p=True,            # save native segmentations
    csf=True,          # save CSF segmentation
    lesions=True,      # save WMH lesion map
    gz=True,           # compress outputs (.nii.gz)
    stream_output=True,
    log_file="/results/T1Prep_run.log",
)

Key parameters

Output structure

Non-BIDS (default): subfolders mri/, surf/, report/, label/ in the output directory, with CAT12-compatible filenames (e.g., mwp1sub-01.nii, lh.thickness.sub-01).

BIDS (with bids=True): BIDS derivatives layout <out_dir>/derivatives/T1Prep-v<version>/sub-XX/ses-YY/anat/.

Documentation

License

Distributed under the Apache License 2.0.