HTFA 0.1.0

HTFA 0.1.0

HTFA fits spatial factors and their sample weights to spatial data, including brain images. Topographic factor analysis (TFA) models one participant; hierarchical TFA shares a template across participants, with optional nested group templates. The package is a standalone Python implementation with NumPy and torch backends and no BrainIAK or MPI runtime requirement.

Install

pip install htfa

Python 3.10 or newer. Optional extras include plot (matplotlib and Nilearn), brain3d (3D networks and animations), images, gpu, and tutorials. For example:

pip install "htfa[plot,brain3d]"

Optional dependencies install on first use; HTFA_AUTO_INSTALL=0 disables that behavior. Torch is a core dependency on Apple Silicon Macs. See installation for platform requirements.

Highlights

• Spatial factors. Gaussian, Laplace, and signed Mexican-hat kernels, with one or more components per factor. Each mixture shares one time course across its spatial components.
• Fitting. htfa.fit loads NIfTI files, folders, NumPy arrays, and 2D images; the TFA and HTFA estimators fit arrays directly. Fast and exact solver modes optimize the same objective with different step models. CPU, CUDA, and Apple Metal backends support different workloads; multiple CUDA GPUs can fit subjects concurrently.
• Nested groups. Group templates connect subjects to a global template, with names and nesting inferred from subfolders by default. Permutation comparisons use a label-independent factor reference and report per-factor results with optional family-wise correction.
• Connectivity and visualization. Static, dynamic, and inter-subject factor connectivity; BrainNet Viewer-style plots and animations; Nilearn glass-brain views. Mixture components appear as separate lobes with the factor connection value repeated between component pairs. Sphere/centroid summaries are also available.
• Reconstruction statistics. R², nominal parameter counts, and conditional Gaussian AIC, AICc, and BIC. Reconstruction figures share color scales so the data and fitted values can be compared directly.
• Worked examples. Synthetic recovery, real fMRI kernel comparisons, word decoding, dynamic ISFC, group inference, and plotting tutorials, with checksum-verified cached assets.

Documentation

• Archived release (Zenodo DOI)

• Quick start

• User guide

• Tutorials

• API reference

• Validation

• Source and issue tracker

Tutorial data (not a release of htfa)

This pre-release only holds data used by the documentation tutorials. It is not a release of the htfa package.

htfa_mitchell2008_K100.npz

This file is the HTFA fit used by tutorial 09 (docs/tutorials/09_word_decoding_mitchell2008.ipynb), fitted to the nine participants of the Mitchell et al. (2008) dataset. The tutorial downloads it by default; setting REFIT = True in the notebook fits it again from scratch.

• SHA-256: 635d821194ee1d4a37932a1f4a1ed03592f18838a6453200b1bda0570fa895c4
• Size: 2,518,508 bytes. It is a NumPy .npz archive with no pickled objects; it loads with np.load(..., allow_pickle=False).
• Contents:
  • weights (9, 100, 360), centers (9, 100, 3) and widths (9, 100): per participant.
  • global_centers (100, 3) and global_widths (100,): the template.
  • n_iter (10) and converged (False).
  • n_voxels: per participant.
  • settings, htfa_commit, htfa_version and fit_seconds.
• How it was produced:
  • Call: htfa.fit(Xs, coords=Rs, K=100, max_voxels=10000, init="ncorr", backend="numpy", n_jobs=3, random_state=0).
  • Code: htfa 0.1.0 at commit 9653702.
  • Inputs: the 360 trial images of each data-science-P1.mat to data-science-P9.mat file from the dataset page, with voxel coordinates in MNI mm from the dataset's get_mni_coordinates.m. The tutorial does this loading.
  • Machine: a 12-CPU Apple M2 Max, 1008 s.
  • The fit stopped at 10 global iterations without converging. It is identical to the fit that the tutorial previously computed and cached locally.

htfa_development_fmri_12adults_K50.npz

The HTFA fit used by tutorial 10 (docs/tutorials/10_dynamic_isfc_animation.ipynb). The tutorial downloads it by default; REFIT = True in the notebook fits it again from scratch.

• SHA-256: 647dc7c2da0eec69b16df12f7c3fcc68a2f33637056dc21532b77da9b3c0cc13
• Size: 796,190 bytes. NumPy .npz archive without pickled objects (np.load(..., allow_pickle=False)).
• Contents: weights (12, 50, 168), centers (12, 50, 3), widths (12, 50), global_centers (50, 3), global_widths (50,), n_iter (10), converged (False), subject_ids, n_voxels, settings, data, warnings, htfa_commit, htfa_version, fit_seconds, machine.
• Data: htfa.datasets.fetch_development_fmri(n_subjects=12), the adults sub-pixar123 to sub-pixar134 of nilearn's development_fmri dataset, masked and cleaned by that function.
• Produced with htfa.HTFA(K=50, max_voxels=3000, max_global_iter=10, init="ncorr", random_state=0, n_jobs=12).fit(ds.data, ds.coords), htfa 0.1.0 at commit f6691a8, in 103 s on a 12-CPU Apple M2 Max. It stopped at 10 global iterations without converging (one ConvergenceWarning).

htfa_development_fmri_6adults_K30.npz

The HTFA fit used by tutorial 11 (docs/tutorials/11_plotting_and_appearance.ipynb). The tutorial downloads it by default; REFIT = True in the notebook fits it again from scratch.

• SHA-256: 48d0cdda811a515fad809b2b667f29d470cf5c2c19c53a9c7bc29495ee4ba829
• Size: 242,010 bytes. NumPy .npz archive without pickled objects (np.load(..., allow_pickle=False)).
• Contents: weights (6, 30, 168), centers (6, 30, 3), widths (6, 30), global_centers (30, 3), global_widths (30,), n_iter (6), converged (False), subject_ids, n_voxels, settings, data, warnings, htfa_commit, htfa_version, fit_seconds, machine.
• Data: htfa.datasets.fetch_development_fmri(n_subjects=6), the adults sub-pixar123 to sub-pixar128.
• Produced with htfa.fit(ds.data, coords=ds.coords, K=30, max_global_iter=6, max_local_iter=5, max_voxels=5000, max_trs=168, init="ncorr", random_state=0, n_jobs=12), htfa 0.1.0 at commit f6691a8, in 43 s on a 12-CPU Apple M2 Max. It stopped at 6 global iterations without converging (one ConvergenceWarning).

The fits for tutorials 10 and 11 may be regenerated when htfa's fitting code changes; each file records the commit that made it.

htfa_mitchell2008_embeddings_Qwen3-Embedding-0.6B.npz

These are the word embeddings of the 60 nouns used by tutorial 09. The tutorial loads them by default; with RECOMPUTE_EMBEDDINGS = True it computes them again.

• SHA-256: 0f61b70541d0e5c3cb428fb9b81f1cb98df2a835bb76cbd7c76d9f13ce6b2e96
• Size: 117,751 bytes. It is a NumPy .npz archive with no pickled objects (np.load(..., allow_pickle=False)).
• Contents:
  • E (60, 1024) float32 and vocab (60,), in the tutorial's vocabulary order.
  • embedding_model, embedding_revision, method and machine.
• How they were computed: hypertools.tools.format_data(list(vocab), vectorizer="Qwen/Qwen3-Embedding-0.6B", semantic=None, corpus=None, ppca=False)[0], with the model at revision 97b0c614be4d77ee51c0cef4e5f07c00f9eb65b3 (the revision the local Hugging Face cache resolved). This ran on an Apple M2 Max (macOS arm64) on 2026-10-25, through the tutorial's own embedding cache.

htfa_mitchell2008_null_20.npz and htfa_mitchell2008_null_100.npz

These are tutorial 09's permutation nulls for 20 and 100 permutations. The tutorial loads the one matching N_PERMUTATIONS by default; with RECOMPUTE_NULL = True it computes the null again.

• SHA-256:
  • htfa_mitchell2008_null_20.npz: 69a937cefa24806ac16b842564285434e43869485ce5cf5d0f24e4d90f8e7b05 (4,605 bytes)
  • htfa_mitchell2008_null_100.npz: c756356412a1f4b85eaa6d4c93b00901e41dc0b5b415f5fefd95c4d2c526f337 (7,807 bytes)
• Format: NumPy .npz archives with no pickled objects.
• Contents:
  • null (N, 7): the 9-participant means of the 7 statistics for each permutation.
  • statistics: the names of the 7 statistics.
  • n_permutations and seeds (1000 to 1000 + N - 1).
  • seconds and observed (the unpermuted statistics).
  • fit and fit_sha256: htfa_mitchell2008_K100.npz above.
  • embeddings and embeddings_sha256_of_E: the SHA-256 of the bytes of E in the embeddings file above.
  • embedding_model, embedding_revision, htfa_commit, htfa_version and machine.
• How they were computed: by the tutorial notebook at htfa commit c0a17d8, on a 12-CPU Apple M2 Max. Inputs were the saved fit and the saved embeddings above. It took 1003 s for 20 permutations and 2706 s for 100.
• Checks: each null is identical to the corresponding null computed earlier with the same inputs. The first 20 rows of the 100-permutation null equal the 20-permutation null.