Usage

This toolbox presents a Python implementation to use the TFNBS for fMRI and EEG functional connectivity data with the flexibility to use structured data (i.e. block diagonal matrices) corresponding to frequency range and connectivity matrix. While other network-oriented toolkits are composed of higher computational complexity, TFNBS is based on the construction of a null distribution which is permuted across many thresholds to identify statistical significance therefore optimizing performance. Our implementation of TFNBS follows efficient algorithms and allows usage of parallel computing cores, therefore massively reducing required computing resources over conventional approaches.

Permutation-Based Inference

The main API for permutation-based p-values is tfnbs.pairwise_stats.compute_p_val().

Inputs

  • group1 / group2: arrays of shape (n_subjects, N, N), symmetric, with zero diagonal.

  • Recommended preprocessing: Fisher r-to-z transform (tfnbs.utils.fisher_r_to_z) before inference.

Methods

compute_p_val(..., method=...) supports:

  • "tstat": raw t-statistics (max-stat correction)

  • "tfnbs": threshold-free NBS / TFCE-style enhancement

  • "nbs": classical NBS with fixed threshold (nbs_stat="extent" or "intensity")

  • "cnbs": constrained NBS (requires net_labels)

  • "ni_tfnbs": network-informed TFNBS (requires net_labels)

  • "fbc_tfnbs": functional-block clustering TFNBS (requires net_labels)

Minimal example (two-sample)

from tfnbs.pairwise_stats import compute_p_val
from tfnbs.utils import fisher_r_to_z

# group1, group2: (n_subjects, N, N), symmetric, diagonal=0
group1_z = fisher_r_to_z(group1)
group2_z = fisher_r_to_z(group2)

p_vals = compute_p_val(
    group1_z,
    group2_z,
    n_permutations=1000,
    test_type="two-sample",
    method="tfnbs",
    use_mp=True,
)

Notes

  • Constrained methods (cnbs, ni_tfnbs, fbc_tfnbs) require net_labels: ndarray[int] of shape (N,).

  • NBS uses threshold and nbs_stat.

  • TFNBS-family uses e, h, n and start_thres (plus min_cluster_size for fbc_tfnbs).

Synthetic Method-Comparison Example

The repository includes a runnable comparison script that uses compute_p_val for all methods and saves heatmaps (ground truth, t-stat, and 1-p maps) to examples/output/:

python examples/sim_method_comparisons.py --all-scenarios --effect-size 0.25 --time-points 50 --n-permutations 50