tfce 0.1.0__tar.gz

tfce-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2020-2026, Christian Gaser
+Structural Brain Mapping Group, Jena University Hospital
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tfce-0.1.0/MANIFEST.in

@@ -0,0 +1,17 @@
+# The C core is vendored into src/tfce/_c/ by setup.py. It MUST go into the sdist:
+# without it there is nothing to compile, and `pip install tfce` from source fails.
+include src/tfce/_c/*.c
+include src/tfce/_c/*.h
+include src/tfce/*.pyx
+
+include README.md
+include LICENSE
+
+# the docs the PyPI page links to, so an sdist is self-documenting
+recursive-include docs *.md
+
+recursive-include tests *.py
+recursive-include tests/data *.npz
+
+exclude src/tfce/_maxtree.c
+global-exclude *.so *.pyd __pycache__/*

tfce-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: tfce
+Version: 0.1.0
+Summary: Exact threshold-free cluster enhancement (TFCE) with no step size, and the permutation inference around it
+Author-email: Christian Gaser <christian.gaser@uni-jena.de>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ChristianGaser/tfce
+Project-URL: Source, https://github.com/ChristianGaser/tfce
+Project-URL: Issues, https://github.com/ChristianGaser/tfce/issues
+Keywords: neuroimaging,TFCE,permutation,statistics,fMRI,VBM
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: io
+Requires-Dist: nibabel>=4.0; extra == "io"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: nibabel>=4.0; extra == "dev"
+Requires-Dist: nilearn>=0.10; extra == "dev"
+Requires-Dist: cython>=3.0; extra == "dev"
+Dynamic: license-file
+
+# tfce
+
+**Exact threshold-free cluster enhancement, and the permutation inference around it.**
+
+[![PyPI](https://img.shields.io/pypi/v/tfce.svg)](https://pypi.org/project/tfce/)
+[![Python](https://img.shields.io/pypi/pyversions/tfce.svg)](https://pypi.org/project/tfce/)
+[![License](https://img.shields.io/pypi/l/tfce.svg)](https://github.com/ChristianGaser/tfce/blob/master/python/LICENSE)
+
+TFCE combines focal effects of large height with broad effects of large extent, and needs **no
+cluster-forming threshold** - the arbitrary choice that cluster-based inference forces on you, and
+that the result can depend on heavily.
+
+```bash
+pip install tfce
+```
+
+Wheels for Linux, macOS and Windows. No compiler needed.
+
+---
+
+## Exact, not stepped
+
+The TFCE of an element is an integral:
+
+```text
+TFCE(v) = ∫ e_v(h)^E · h^H dh
+```
+
+over the extent `e_v(h)` of the cluster containing `v` at height `h`. Implementations normally
+approximate it by stepping `h` over a grid and summing. That costs a step size `dh`, a discretisation
+error that depends on it, and an accuracy parameter you have to guess.
+
+This one doesn't. It builds the **max-tree** (the component tree) with union-find, and because
+`e_v(h)` is piecewise constant, integrates each piece in closed form. The answer is the integral, not
+a sample of it. **There is nothing to tune.**
+
+The difference is not academic. Against a stepped implementation on a 60×72×60 volume:
+
+| steps | error vs exact |
+| --- | --- |
+| 50 | 3.4% |
+| 100 | **1.7%** |
+| 200 | 0.8% |
+| 400 | 0.4% |
+
+The error halves every time the steps double - first order, exactly as a step-size approximation must
+behave. The exact transform has no such term.
+
+## Quick start
+
+```python
+import numpy as np
+import tfce
+
+# a volume: (nx, ny, nz)
+t = tfce.tfce(stat_map, E=0.5, H=2.0)
+
+# a surface: faces are 1-based, as GIFTI stores them
+adj = tfce.adjacency_from_faces(faces, n_vertices)
+t = tfce.tfce(surf_map, adjacency=adj, E=1.0, H=2.0)
+
+# a block of permutations, one per thread
+#   (nx, ny, nz, n_perm) -> (nx, ny, nz, n_perm)
+t = tfce.tfce(perms, E=0.5, H=2.0, n_jobs=-1)
+```
+
+Volumes take `connectivity=6 | 18 | 26` (26 is the default, and what fslmaths and the MATLAB toolbox
+use). Surfaces take the mesh, so the neighbourhood is whatever the mesh says it is.
+
+Everything is arrays in, arrays out. No image objects, no file I/O, no design parsing - those belong
+in a layer above, so the core can be dropped anywhere.
+
+## Speed
+
+Permutations are independent, so they are TFCE'd a block at a time, one per thread, with the GIL
+released. On the same 60×72×60 volume:
+
+| | one map | 16 permutations |
+| --- | --- | --- |
+| stepped (100 steps) | 0.38 s | 9.1 s - 569 ms/perm |
+| **tfce** | **0.03 s** (14×) | **0.13 s** - 8 ms/perm (**72×**) |
+
+## Using it with nilearn
+
+nilearn has `permuted_ols(..., tfce=True)`, and its TFCE is a stepped approximation. `tfce` ships a
+drop-in with the same signature:
+
+```python
+from nilearn.mass_univariate import _utils
+import tfce.nilearn_compat as tc
+
+_utils.calculate_tfce = tc.calculate_tfce   # now exact, and much faster
+```
+
+It reads the neighbourhood out of the `bin_struct` it is handed, so it reproduces whichever
+connectivity the caller meant.
+
+## Fewer permutations
+
+Counting exceedances cannot report a p-value below `1/n_perm`. That floor - not the statistic - is
+what forces a permutation test to run many thousands of permutations, and it caps FDR too, since FDR
+is computed from the uncorrected p-values. `tfce.tails` removes it:
+
+- **Gamma** fit to the null of the *maximum*, for FWE-corrected p-values.
+- **Generalised Pareto** fit to each element's own tail, for the uncorrected ones - with the *shape*
+  pooled across elements, since they all carry the same statistic under the same design and so differ
+  in scale, not in shape.
+
+From 1000 permutations this recovers `p ≈ 1e-4` with the median right, where plain counting returns
+zero for 91% of elements and tells you nothing at all.
+
+## What's in the box
+
+| | |
+| --- | --- |
+| `tfce.core` | the exact transform - arrays in, arrays out |
+| `tfce.tails` | Gamma and Generalised Pareto tail approximations |
+| `tfce.glm` | the permuted GLM, which never forms the permuted data |
+| `tfce.nilearn_compat` | drop-in for nilearn's `calculate_tfce` |
+
+Dependencies are deliberately thin: **numpy and scipy**, nothing else. `nibabel` is an optional extra,
+wanted only by I/O.
+
+## Trust
+
+This is not a reimplementation. It is the same C core that the
+[MATLAB TFCE toolbox](https://github.com/ChristianGaser/tfce) has been running for years, with a
+Cython binding instead of a MEX one - so the two give **bit-identical** results, and the test suite
+holds them to it. It ships a validation suite of its own: the exactness of the max-tree is established
+against an *independent* stepped implementation, which must converge onto it at first order.
+
+## Citing
+
+If you use this, please cite the method:
+
+> Smith SM, Nichols TE (2009). *Threshold-free cluster enhancement: addressing problems of smoothing,
+> threshold dependence and localisation in cluster inference.* NeuroImage 44:83–98.
+> [doi:10.1016/j.neuroimage.2008.03.061](https://doi.org/10.1016/j.neuroimage.2008.03.061)
+
+The tail approximations are from:
+
+> Winkler AM, Ridgway GR, Douaud G, Nichols TE, Smith SM (2016). *Faster permutation inference in
+> brain imaging.* NeuroImage 141:502–516.
+> [doi:10.1016/j.neuroimage.2016.05.068](https://doi.org/10.1016/j.neuroimage.2016.05.068)
+
+## Status
+
+Early, but the parts that are here are tested and are the parts that matter. The transform, the tail
+approximations and the permuted GLM are done. Not yet done: the **design layer** - turning a
+[BIDS Stats Model](https://bids-standard.github.io/stats-models/) into a design matrix, contrasts and,
+crucially, an *exchangeability* structure. That last one is the real work, because BIDS-SM specifies
+`X`, `Formula`, `Contrasts` and `GroupBy` but has **no** concept of exchangeability blocks, so what may
+be permuted with what has to be defined on top of it rather than read out of it.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [Installation](https://github.com/ChristianGaser/tfce/blob/master/python/docs/installation.md) | Wheels, building from source, extras |
+| [Usage](https://github.com/ChristianGaser/tfce/blob/master/python/docs/usage.md) | Volumes, surfaces, batches, connectivity, `E` and `H` |
+| [A permutation test, end to end](https://github.com/ChristianGaser/tfce/blob/master/python/docs/permutation.md) | The whole thing, as a worked example you can run |
+| [Theory](https://github.com/ChristianGaser/tfce/blob/master/python/docs/theory.md) | Why the integral is exact, and why you need fewer permutations |
+| [Using it with nilearn](https://github.com/ChristianGaser/tfce/blob/master/python/docs/nilearn.md) | The drop-in - and a bug in nilearn's stepped TFCE |
+| [API reference](https://github.com/ChristianGaser/tfce/blob/master/python/docs/api.md) | Every public function |
+| [Benchmarks](https://github.com/ChristianGaser/tfce/blob/master/python/docs/benchmarks.md) | Accuracy and speed, with scripts to reproduce |
+| [Validation](https://github.com/ChristianGaser/tfce/blob/master/python/docs/validation.md) | What the test suite establishes, and how |
+
+## Links
+
+- **Source, issues, MATLAB toolbox:** <https://github.com/ChristianGaser/tfce>
+- **Licence:** BSD-3-Clause. Permissive on purpose: `nilearn` is BSD-3 and
+  `nipreps` is Apache-2.0, and neither can take on a GPL dependency. Nothing here
+  is derived from SPM, so nothing here has to be GPL. (The MATLAB/SPM toolbox in
+  the same repository *is* GPL, because it genuinely is derived from SPM - see
+  [LICENSE.md](https://github.com/ChristianGaser/tfce/blob/master/LICENSE.md).)
+
+Developed by Christian Gaser, Structural Brain Mapping Group, Jena University Hospital.

tfce-0.1.0/README.md

@@ -0,0 +1,177 @@
+# tfce
+
+**Exact threshold-free cluster enhancement, and the permutation inference around it.**
+
+[![PyPI](https://img.shields.io/pypi/v/tfce.svg)](https://pypi.org/project/tfce/)
+[![Python](https://img.shields.io/pypi/pyversions/tfce.svg)](https://pypi.org/project/tfce/)
+[![License](https://img.shields.io/pypi/l/tfce.svg)](https://github.com/ChristianGaser/tfce/blob/master/python/LICENSE)
+
+TFCE combines focal effects of large height with broad effects of large extent, and needs **no
+cluster-forming threshold** - the arbitrary choice that cluster-based inference forces on you, and
+that the result can depend on heavily.
+
+```bash
+pip install tfce
+```
+
+Wheels for Linux, macOS and Windows. No compiler needed.
+
+---
+
+## Exact, not stepped
+
+The TFCE of an element is an integral:
+
+```text
+TFCE(v) = ∫ e_v(h)^E · h^H dh
+```
+
+over the extent `e_v(h)` of the cluster containing `v` at height `h`. Implementations normally
+approximate it by stepping `h` over a grid and summing. That costs a step size `dh`, a discretisation
+error that depends on it, and an accuracy parameter you have to guess.
+
+This one doesn't. It builds the **max-tree** (the component tree) with union-find, and because
+`e_v(h)` is piecewise constant, integrates each piece in closed form. The answer is the integral, not
+a sample of it. **There is nothing to tune.**
+
+The difference is not academic. Against a stepped implementation on a 60×72×60 volume:
+
+| steps | error vs exact |
+| --- | --- |
+| 50 | 3.4% |
+| 100 | **1.7%** |
+| 200 | 0.8% |
+| 400 | 0.4% |
+
+The error halves every time the steps double - first order, exactly as a step-size approximation must
+behave. The exact transform has no such term.
+
+## Quick start
+
+```python
+import numpy as np
+import tfce
+
+# a volume: (nx, ny, nz)
+t = tfce.tfce(stat_map, E=0.5, H=2.0)
+
+# a surface: faces are 1-based, as GIFTI stores them
+adj = tfce.adjacency_from_faces(faces, n_vertices)
+t = tfce.tfce(surf_map, adjacency=adj, E=1.0, H=2.0)
+
+# a block of permutations, one per thread
+#   (nx, ny, nz, n_perm) -> (nx, ny, nz, n_perm)
+t = tfce.tfce(perms, E=0.5, H=2.0, n_jobs=-1)
+```
+
+Volumes take `connectivity=6 | 18 | 26` (26 is the default, and what fslmaths and the MATLAB toolbox
+use). Surfaces take the mesh, so the neighbourhood is whatever the mesh says it is.
+
+Everything is arrays in, arrays out. No image objects, no file I/O, no design parsing - those belong
+in a layer above, so the core can be dropped anywhere.
+
+## Speed
+
+Permutations are independent, so they are TFCE'd a block at a time, one per thread, with the GIL
+released. On the same 60×72×60 volume:
+
+| | one map | 16 permutations |
+| --- | --- | --- |
+| stepped (100 steps) | 0.38 s | 9.1 s - 569 ms/perm |
+| **tfce** | **0.03 s** (14×) | **0.13 s** - 8 ms/perm (**72×**) |
+
+## Using it with nilearn
+
+nilearn has `permuted_ols(..., tfce=True)`, and its TFCE is a stepped approximation. `tfce` ships a
+drop-in with the same signature:
+
+```python
+from nilearn.mass_univariate import _utils
+import tfce.nilearn_compat as tc
+
+_utils.calculate_tfce = tc.calculate_tfce   # now exact, and much faster
+```
+
+It reads the neighbourhood out of the `bin_struct` it is handed, so it reproduces whichever
+connectivity the caller meant.
+
+## Fewer permutations
+
+Counting exceedances cannot report a p-value below `1/n_perm`. That floor - not the statistic - is
+what forces a permutation test to run many thousands of permutations, and it caps FDR too, since FDR
+is computed from the uncorrected p-values. `tfce.tails` removes it:
+
+- **Gamma** fit to the null of the *maximum*, for FWE-corrected p-values.
+- **Generalised Pareto** fit to each element's own tail, for the uncorrected ones - with the *shape*
+  pooled across elements, since they all carry the same statistic under the same design and so differ
+  in scale, not in shape.
+
+From 1000 permutations this recovers `p ≈ 1e-4` with the median right, where plain counting returns
+zero for 91% of elements and tells you nothing at all.
+
+## What's in the box
+
+| | |
+| --- | --- |
+| `tfce.core` | the exact transform - arrays in, arrays out |
+| `tfce.tails` | Gamma and Generalised Pareto tail approximations |
+| `tfce.glm` | the permuted GLM, which never forms the permuted data |
+| `tfce.nilearn_compat` | drop-in for nilearn's `calculate_tfce` |
+
+Dependencies are deliberately thin: **numpy and scipy**, nothing else. `nibabel` is an optional extra,
+wanted only by I/O.
+
+## Trust
+
+This is not a reimplementation. It is the same C core that the
+[MATLAB TFCE toolbox](https://github.com/ChristianGaser/tfce) has been running for years, with a
+Cython binding instead of a MEX one - so the two give **bit-identical** results, and the test suite
+holds them to it. It ships a validation suite of its own: the exactness of the max-tree is established
+against an *independent* stepped implementation, which must converge onto it at first order.
+
+## Citing
+
+If you use this, please cite the method:
+
+> Smith SM, Nichols TE (2009). *Threshold-free cluster enhancement: addressing problems of smoothing,
+> threshold dependence and localisation in cluster inference.* NeuroImage 44:83–98.
+> [doi:10.1016/j.neuroimage.2008.03.061](https://doi.org/10.1016/j.neuroimage.2008.03.061)
+
+The tail approximations are from:
+
+> Winkler AM, Ridgway GR, Douaud G, Nichols TE, Smith SM (2016). *Faster permutation inference in
+> brain imaging.* NeuroImage 141:502–516.
+> [doi:10.1016/j.neuroimage.2016.05.068](https://doi.org/10.1016/j.neuroimage.2016.05.068)
+
+## Status
+
+Early, but the parts that are here are tested and are the parts that matter. The transform, the tail
+approximations and the permuted GLM are done. Not yet done: the **design layer** - turning a
+[BIDS Stats Model](https://bids-standard.github.io/stats-models/) into a design matrix, contrasts and,
+crucially, an *exchangeability* structure. That last one is the real work, because BIDS-SM specifies
+`X`, `Formula`, `Contrasts` and `GroupBy` but has **no** concept of exchangeability blocks, so what may
+be permuted with what has to be defined on top of it rather than read out of it.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [Installation](https://github.com/ChristianGaser/tfce/blob/master/python/docs/installation.md) | Wheels, building from source, extras |
+| [Usage](https://github.com/ChristianGaser/tfce/blob/master/python/docs/usage.md) | Volumes, surfaces, batches, connectivity, `E` and `H` |
+| [A permutation test, end to end](https://github.com/ChristianGaser/tfce/blob/master/python/docs/permutation.md) | The whole thing, as a worked example you can run |
+| [Theory](https://github.com/ChristianGaser/tfce/blob/master/python/docs/theory.md) | Why the integral is exact, and why you need fewer permutations |
+| [Using it with nilearn](https://github.com/ChristianGaser/tfce/blob/master/python/docs/nilearn.md) | The drop-in - and a bug in nilearn's stepped TFCE |
+| [API reference](https://github.com/ChristianGaser/tfce/blob/master/python/docs/api.md) | Every public function |
+| [Benchmarks](https://github.com/ChristianGaser/tfce/blob/master/python/docs/benchmarks.md) | Accuracy and speed, with scripts to reproduce |
+| [Validation](https://github.com/ChristianGaser/tfce/blob/master/python/docs/validation.md) | What the test suite establishes, and how |
+
+## Links
+
+- **Source, issues, MATLAB toolbox:** <https://github.com/ChristianGaser/tfce>
+- **Licence:** BSD-3-Clause. Permissive on purpose: `nilearn` is BSD-3 and
+  `nipreps` is Apache-2.0, and neither can take on a GPL dependency. Nothing here
+  is derived from SPM, so nothing here has to be GPL. (The MATLAB/SPM toolbox in
+  the same repository *is* GPL, because it genuinely is derived from SPM - see
+  [LICENSE.md](https://github.com/ChristianGaser/tfce/blob/master/LICENSE.md).)
+
+Developed by Christian Gaser, Structural Brain Mapping Group, Jena University Hospital.

tfce-0.1.0/docs/README.md

@@ -0,0 +1,35 @@
+# tfce - documentation
+
+Exact threshold-free cluster enhancement, and the permutation inference around it.
+
+The [package README](../README.md) is the two-minute version. These pages are the rest.
+
+## Start here
+
+| | |
+| --- | --- |
+| **[Installation](installation.md)** | `pip install tfce`, wheels, building from source, optional extras. |
+| **[Usage](usage.md)** | Volumes, surfaces, batches of permutations, connectivity, `E` and `H`. |
+| **[A permutation test, end to end](permutation.md)** | The whole thing: GLM → TFCE → FWE and uncorrected p-values. A worked example you can run. |
+
+## Going deeper
+
+| | |
+| --- | --- |
+| **[Theory](theory.md)** | Why the integral is exact, what a max-tree is, and why the tail approximations mean you can run far fewer permutations. |
+| **[Using it with nilearn](nilearn.md)** | The drop-in, the connectivity mismatch, and a bug in nilearn's stepped TFCE worth knowing about. |
+| **[API reference](api.md)** | Every public function, with its arguments and what they do. |
+| **[Benchmarks](benchmarks.md)** | Accuracy and speed, with the scripts to reproduce them. |
+| **[Validation](validation.md)** | What the test suite establishes, and how it establishes it. |
+
+## The one-paragraph summary
+
+The TFCE of an element is an integral over the extent of the cluster containing it, taken across all
+heights. Implementations normally approximate that integral by stepping the height over a grid and
+summing, which costs a step size, a discretisation error that depends on it, and an accuracy
+parameter the caller has to guess. This one builds the **max-tree** (the component tree) with
+union-find and integrates each piece of the extent function in closed form, because that function is
+piecewise constant. The result is the integral, not a sample of it, and there is nothing to tune.
+
+It is the same C the [MATLAB TFCE toolbox](https://github.com/ChristianGaser/tfce) runs - not a
+reimplementation - so the two are bit-identical, and the test suite holds them to it.

tfce-0.1.0/docs/api.md

@@ -0,0 +1,168 @@
+# API reference
+
+Everything public, with what it takes and what it gives back.
+
+```python
+import tfce
+from tfce.glm import PermutedGLM, partition_design
+from tfce.tails import gamma_pvalue, pareto_pvalue, gpd_fit_pwm, gpd_sf
+from tfce.nilearn_compat import calculate_tfce, connectivity_from_bin_struct
+```
+
+---
+
+## `tfce`
+
+### `tfce(data, *, adjacency=None, connectivity=26, E=0.5, H=2.0, two_sided=True, n_jobs=1)`
+
+Threshold-free cluster enhancement of one map or of many.
+
+| argument | | |
+| --- | --- | --- |
+| `data` | ndarray | `(nx, ny, nz)` or `(nx, ny, nz, B)` for volumes; `(n_vertices,)` or `(n_vertices, B)` for surfaces. Any dtype - used as `float32`. |
+| `adjacency` | sparse or `(indptr, indices)` | The mesh, for surface data. Omit for volumes. |
+| `connectivity` | `6`, `18`, `26` | Volume neighbourhood. Ignored for surfaces. |
+| `E`, `H` | float | Extent and height weights. `0.5, 2` for volumes; `1, 2` for surfaces and TBSS. |
+| `two_sided` | bool | Also enhance the negative part, giving it a negative TFCE value. |
+| `n_jobs` | int | Threads across the `B` maps. `-1` = one per map. Releases the GIL. |
+
+**Returns** `float32` array in the shape the data came in.
+
+**Raises** `ValueError` on a bad shape or connectivity; `TfceError` if the C core refuses the call.
+
+### `adjacency_from_faces(faces, n_vertices)`
+
+CSR adjacency of a triangulated surface.
+
+| argument | | |
+| --- | --- | --- |
+| `faces` | `(n_faces, 3)` int | **1-based** vertex indices, as GIFTI stores them. |
+| `n_vertices` | int | |
+
+**Returns** `(indptr, indices)`, both `int32` and 0-based - ready for `scipy.sparse.csr_matrix`, or to
+pass straight back to `tfce()` as `adjacency`.
+
+**Raises** `TfceError` if any index names a vertex that does not exist. This is a real check, not a
+formality: an out-of-range index used to be written past the end of the adjacency arrays.
+
+### `TfceError`
+
+Raised when the C core refuses a call. Subclasses `RuntimeError`.
+
+---
+
+## `tfce.tails`
+
+### `gamma_pvalue(stat, null_max, floor=None)`
+
+FWE-corrected p-values, from a Gamma fitted to the distribution of the **maximum**.
+
+| argument | | |
+| --- | --- | --- |
+| `stat` | ndarray | Observed statistic, one value per element. |
+| `null_max` | `(n_perm,)` | The maximum of the statistic over the image, one per permutation. |
+| `floor` | float | Smallest p-value to report. Defaults to `1/n_perm`. |
+
+**Returns** p-values, same shape as `stat`.
+
+The Gamma is fitted by matching the first three moments, which inverts in closed form. If the sample
+skewness comes out non-positive there is nothing for a Gamma to hold on to, and the empirical count is
+returned instead.
+
+### `pareto_pvalue(stat, tail, cnt, n_perm, *, n_exc_min=25, n_shape=20000, ad_max=5.0)`
+
+Uncorrected p-values, resolved **below** the `1/n_perm` floor of counting.
+
+| argument | | |
+| --- | --- | --- |
+| `stat` | `(n_elements,)` | Observed statistic, **already an upper tail** - flip the sign of the negative elements first. |
+| `tail` | `(K, n_elements)` | The largest `K` permuted values of each element. `K ≈ 100` is plenty. |
+| `cnt` | `(n_elements,)` | How often the permutations reached or exceeded `stat`, counted over **all** `n_perm` - not just the ones in `tail`. |
+| `n_perm` | int | How many permutations were drawn. |
+| `n_exc_min` | int | Elements exceeded at least this often keep their count; the fit has nothing to add. |
+| `n_shape` | int | How many elements the shape is pooled over. |
+| `ad_max` | float | A tail no candidate fit describes this well is counted, not extrapolated. |
+
+**Returns** p-values, `(n_elements,)`.
+
+> **Why `cnt` and `n_perm` are arguments.** Storing the whole `n_perm × n_elements` null is impossible
+> at any real size, so only the tail is kept - but a truncated tail cannot say *how often* an element
+> was exceeded, and that count is what the p-value is made of. Accumulate it in your permutation loop:
+> it costs one comparison per element. See [permutation.md](permutation.md).
+
+### `gpd_fit_pwm(y)`
+
+Generalised Pareto parameters by probability-weighted moments (Hosking & Wallis).
+
+`y` is `(m, n)` - exceedances above a threshold, **ascending** down each column, one column per
+element. Returns `(k, sigma)`, each `(n,)`, parameterised as `F(y) = 1 − (1 − k·y/σ)^(1/k)`.
+
+### `gpd_sf(z, k, sigma)`
+
+Survival function of that distribution. Handles the `k → 0` limit (exponential) and clamps to zero
+beyond the upper endpoint of a `k > 0` fit.
+
+---
+
+## `tfce.glm`
+
+### `PermutedGLM(Y, design, contrast)`
+
+Fit `Y = X·B`, and re-fit it under permutations **without ever forming the permuted data**.
+
+| argument | | |
+| --- | --- | --- |
+| `Y` | `(n_elements, n_samples)` | One **row** per element, one column per observation. Note the orientation: elements are the long axis and this keeps them contiguous. |
+| `design` | `(n_samples, n_regressors)` | |
+| `contrast` | `(n_regressors,)` or `(n_regressors, q)` | A vector gives a t-contrast, a matrix an F-contrast. |
+
+**Attributes**: `df`, `rank`, `pinvX`, `XtX`, `ssy`, `is_t`.
+
+**Raises** `ValueError` if the design leaves no residual degrees of freedom, or if `Y` and the design
+disagree about the number of observations.
+
+#### `.fit(perm=None)`
+
+Statistic under one permutation. `perm` is read the way numpy reads a fancy index: the permuted data
+is `Y[:, perm]`. `None` is the identity - the unpermuted fit.
+
+**Returns** `(n_elements,)`.
+
+#### `.fit_signs(signs)`
+
+Statistic under one sign-flip, for a one-sample design. `signs` is `(n_samples,)` of ±1.
+
+A one-sample design is not permuted by shuffling - there is nothing to shuffle it with. It is permuted
+by flipping signs, which is exchangeable under the null of "mean zero".
+
+### `partition_design(design, contrast)`
+
+Guttman partition: which columns the contrast tests, and which are nuisance.
+
+**Returns** `(idx_interest, idx_nuisance)`.
+
+---
+
+## `tfce.nilearn_compat`
+
+### `calculate_tfce(arr4d, bin_struct, E=0.5, H=2, dh="auto", two_sided_test=True)`
+
+Drop-in for `nilearn.mass_univariate._utils.calculate_tfce`, with the same signature and an exact
+transform. See [nilearn.md](nilearn.md).
+
+`dh` is **accepted and ignored** - there is no step size. Passing one is not an error; it simply has
+nothing to change.
+
+### `connectivity_from_bin_struct(bin_struct)`
+
+Read `6`, `18` or `26` out of a `scipy.ndimage.generate_binary_structure` array, by counting the
+neighbours it actually marks.
+
+---
+
+## Module-level
+
+| | |
+| --- | --- |
+| `tfce.__version__` | the installed version |
+| `tfce.core.VALID_CONNECTIVITY` | `(6, 18, 26)` |