Skip to main content

Python 3.9 - 3.14 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 (CAT12's geodesic shooting)
  • 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
pip install "T1Prep[tinygrad]"   # optional (Python 3.11+): tinygrad backend, T1Prep --nn-backend tinygrad

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.14; 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)
PyCAT symlink to T1Prep; identical, only the banner differs
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
t1prep-bbreg BOLD reference, head-motion correction and boundary-based BOLD-to-T1w registration for fMRIPrep to reuse
CAT_PlotHistogram histograms of volumes, surfaces or text data

Download model weights

Model weights are not bundled in the wheel (about 250 MB once downloaded). Download them after installation:

t1prep-download-models

Models are stored in your user cache (~/Library/Caches/t1prep/models on macOS, ~/.cache/t1prep/models on Linux; T1PREP_MODEL_DIR overrides it) 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.
  • ~250 MB 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"],
    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)
)

run_t1prep processes the files one after another; for parallel batches use T1Prep --multi N or call it from several processes.

Key parameters

Parameter Type Description
inputs str or list[str] Input NIfTI file(s) (first argument)
out_dir str Output directory (default: same as input)
atlas list[str] Atlas names for ROI extraction
no_surf bool Skip cortical surface estimation (default: False)
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)
track bool Report a crash of the segmentation (default: True)

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/.


Telemetry

Unless you opt out, T1Prep tells its developers how many files a run processed and how many failed, and where in the code a segmentation crashed. File names, paths, images and host names are never sent. --no-track, run_t1prep(..., track=False), or T1PREP_NO_TRACK=1 / DO_NOT_TRACK=1 in the environment switch it off; details in docs/usage.md.


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.9.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.9.0
File Size Uploaded Provenance Actions
t1prep-0.9.0.tar.gz 60.8 MB With provenance Details for t1prep-0.9.0.tar.gz

Built distribution (wheel)

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

Total release size: 121.3 MB

Release files / t1prep-0.9.0.tar.gz

Download URL t1prep-0.9.0.tar.gz
Size 60.8 MB
Tags Source
SHA-256 checksum
How to use checksums
3b87072c5726bfc587c47154b6fa66a0de472e67059f6f4bc8571c7fda447f29
BLAKE2b-256 checksum
How to use checksums
fc24adf6970a6f29ac0b153bd752183d0bb14ed497bf4ac63cff502896f42f80
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 2, 2026.

Transparency log

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

Download URL t1prep-0.9.0-py3-none-any.whl
Size 60.5 MB
Tags Python 3
SHA-256 checksum
How to use checksums
495fa54f8b3c844bbc25e4f0b1dcfe26cd8f9b2b5987c9dbd3556fbe6533a66d
BLAKE2b-256 checksum
How to use checksums
38866f41f4efb16683a6f7979e83a5f9b9a64b1235820f2111593781d00af72a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 2, 2026.

Transparency log

Security for T1Prep 0.9.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.9.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 Nov 2, 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.9.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