pytfce

Fast probabilistic Threshold-Free Cluster Enhancement in Python.

Overview

pytfce is a pure-Python package for probabilistic TFCE (pTFCE) that provides analytical inference on neuroimaging statistical maps without permutation testing. It implements a baseline pTFCE faithful to the original R package (Spisák et al. 2019) and a novel hybrid eTFCE–GRF that combines union-find cluster retrieval with analytical GRF p-values. On real brain data (~2M voxels), pytfce is 73× faster than the R pTFCE package and produces concordant results.

Installation

pip install pytfce

# development install
git clone https://github.com/Don-Yin/pytfce.git
cd pytfce
pip install -e .

Dependencies: NumPy, SciPy, connected-components-3d (installed automatically).

Quick start

import nibabel as nib
from pytfce import ptfce_baseline, ptfce_exact

img = nib.load("zstat1.nii.gz")
Z = img.get_fdata()
mask = Z != 0  # or load a proper brain mask

# --- baseline pTFCE (fast, matches R pTFCE) ---
result = ptfce_baseline(Z, mask)

# --- hybrid eTFCE–GRF (exact cluster retrieval) ---
result = ptfce_exact(Z, mask)

# result keys:
#   result["p"]           — enhanced p-values (3-D array)
#   result["logp"]        — −log10(p) for visualization
#   result["Z_enhanced"]  — enhanced Z-scores
#   result["smoothness"]  — estimated smoothness dict

Variants

Both variants use identical GRF p-values and aggregation. The baseline sweeps a threshold grid with connected-component labelling at each level; the hybrid uses a single union-find sweep, which eliminates discretisation error at higher constant computational cost.

Validation

Spatial detection. Phantom study (64³ volume, 80 subjects, 3 embedded blobs). All pTFCE variants achieve Dice = 1.0:

Runtime. Log-scale comparison across five methods (emulated phantom). Py pTFCE runs in 0.34 s vs 21.7 s for R pTFCE (64× speedup):

API reference

Citation

If you use pytfce in your research, please cite:

@article{pytfce2026,
  author  = {Yin, Don and Chen, Hao},
  title   = {pytfce: {Fast} probabilistic {Threshold-Free Cluster Enhancement}
             in {Python}},
  journal = {Journal of Open Source Software},
  year    = {2026},
  doi     = {10.21105/joss.XXXXX}
}

License

MIT