Skip to main content

Python 3.9 - 3.12 License: Apache 2.0 Release

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:

Command Role
T1Prep main CLI — batch + parallel processing (--multi)
t1prep-ui browser-based web UI
t1prep-run single-subject Python entry
CAT_SurfView surface viewer
CAT_VolView volume viewer (3 orthogonal slices)
t1prep-make-apps macOS: build .app bundles for the viewers
t1prep-download-models fetch model weights

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

Parameter Type Description
files str or list[str] Input NIfTI file(s)
out_dir str Output directory (default: same as input)
atlas list[str] Atlas names for ROI extraction
surf bool Run cortical surface estimation (default: True)
multi int Parallel workers; -1 = auto (default: 1)
bids bool Use BIDS derivatives naming
gz bool Save compressed NIfTI (.nii.gz)
wp bool Save warped (MNI space) segmentations
p bool Save native space segmentations
csf bool Save CSF segmentation
lesions bool Save WMH/lesion map
amap bool Use AMAP segmentation (CAT12-style)
skullstrip_only bool Only run skull stripping then exit
skip_skullstrip bool Skip skull stripping (pre-stripped input)

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

Document Covers
Installation pip, source checkout, WSL, manual install, Docker
Usage Options, output structure, naming, examples
Viewers CAT_SurfView and CAT_VolView, interactive and batch
Tools Web UI and the surface post-processing GUIs

License

Distributed under the Apache License 2.0.

Metadata

Release files for T1Prep 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for T1Prep 0.6.0
File Size Uploaded Provenance Actions
t1prep-0.6.0.tar.gz 34.9 MB With provenance Details for t1prep-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for T1Prep 0.6.0
File Interpreter ABI Platform Actions
t1prep-0.6.0-py3-none-any.whl Python 3 none any Details for t1prep-0.6.0-py3-none-any.whl

Total release size: 69.7 MB

Release files / t1prep-0.6.0.tar.gz

Download URL t1prep-0.6.0.tar.gz
Size 34.9 MB
Tags Source
SHA-256 checksum
How to use checksums
cd662813ba249f524311e7bdb0bea21d3831eb4384567a092709c13653a88078
BLAKE2b-256 checksum
How to use checksums
628bbabbc259e16035fb90b7ef6b518077a031e9cd5078b4c8a3e277dda7509e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 16, 2026.

Transparency log

Release files / t1prep-0.6.0-py3-none-any.whl

Download URL t1prep-0.6.0-py3-none-any.whl
Size 34.8 MB
Tags Python 3
SHA-256 checksum
How to use checksums
850d22655b23f9da5cadc3483362eac96e72e7837c86d52a1f8c76b61a3ea659
BLAKE2b-256 checksum
How to use checksums
0238536983bdb17a4ee8802fbb3169d5efd37d49df623057fb392498171400ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 16, 2026.

Transparency log

Security for T1Prep 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for t1prep-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page