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

Skull-stripping and tissue segmentation run the trained networks of DeepMriPrep and of its brain extraction deepbet, which T1Prep builds on (Lukas Fisch et al., "deepmriprep: Voxel-based Morphometry (VBM) Preprocessing via Deep Neural Networks", https://doi.org/10.48550/arXiv.2408.10656). T1Prep runs them with its own code; neither package has to be installed.

Cortical surface reconstruction uses the cat-surf Python package (Python bindings to the CAT-Surface C library, shipped as pre-built wheels — no separate CAT-Surface binaries have to be installed).

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 T1Prep under a second name; identical, only the banner differs
t1prep-gui, T1Prep_gui desktop launcher: choose images, run, browse the results
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
CAT_PlotBoxplot box and violin plots of volumes, surfaces or text data
CAT_VolDiff, CAT_VolSmooth_ui, CAT_SurfResampleMulti_ui, CAT_SurfParameters_ui, CAT_Surf2ROIMulti_ui, CAT_GrepJson command-line helpers for post-processing and reports
process_longitudinal.sh, realign_longitudinal.sh, warp_longitudinal.sh, modulate_longitudinal.sh experimental longitudinal pipeline

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, in a folder named after the model release (~/Library/Caches/t1prep/models/<release> on macOS, ~/.cache/t1prep/models/<release> 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.14 (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 (implies gz)
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 Refine the network segmentation with CAT12's AMAP
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 input (the image lies in an anat/ folder): the results go to <out_dir or dataset root>/derivatives/T1Prep-v<version>/sub-XX[/ses-YY]/anat/.

bids=True names the files by the BIDS derivatives convention; for an image outside an anat/ folder they then go directly into the output directory, without the subfolders.


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 Launcher, plot tools and the post-processing helpers

License

Distributed under the Apache License 2.0.

Metadata

Release files for T1Prep 0.9.1

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.1
File Size Uploaded Provenance Actions
t1prep-0.9.1.tar.gz 76.4 MB With provenance Details for t1prep-0.9.1.tar.gz

Built distribution (wheel)

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

Total release size: 152.4 MB

Release files / t1prep-0.9.1.tar.gz

Download URL t1prep-0.9.1.tar.gz
Size 76.4 MB
Tags Source
SHA-256 checksum
How to use checksums
a60957df33ba2898d300c9de5e28088168846a2e66ac5d2c869b6c23170a8ec0
BLAKE2b-256 checksum
How to use checksums
821e34385632ecfb01e5c0ff85f989b4236480e7514c2b8ad5f2ab046bbefa51
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 19, 2026.

Transparency log

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

Download URL t1prep-0.9.1-py3-none-any.whl
Size 76.0 MB
Tags Python 3
SHA-256 checksum
How to use checksums
99612e254e0bd830c3738a603236fcda00687746a9942b0bbf3effcfc31f4c95
BLAKE2b-256 checksum
How to use checksums
d3848b2e70171931cd1f3309a9a5c849f45dd7b1656807219ffeba853078597c
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 19, 2026.

Transparency log

Security for T1Prep 0.9.1

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.1.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 19, 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.1 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