Support TFCE thresholding in CBMA algorithms

docs/api.rst

@@ -41,6 +41,7 @@ For more information about the components of coordinate-based meta-analysis in N
    meta.cbma.mkda
    meta.cbma.base
    meta.kernel
+   meta.utils
 
 .. _api_results_ref:
 

docs/cbma.rst

@@ -138,3 +138,9 @@ The Monte Carlo FWE correction approach implemented in NiMARE produces three new
     the voxel's summary statistic value lands on this null distribution.
     **Voxel-level correction is generally more conservative than cluster-level correction,
     so it is only recommended for very large meta-analyses (i.e., hundreds of studies).**
+-   ``<z|logp>_desc-tfce_level-voxel_corr-FWE_method-montecarlo``:
+    Voxel-level FWE-corrected map based on threshold-free cluster enhancement values.
+    `Threshold-free cluster enhancement <TFCE>`_ is a generalization of the cluster mass measure that
+    eliminates the need for a cluster-defining threshold, by essentially calculating cluster mass
+    across a range of thresholds, for each voxel, and then summing those masses across thresholds.
+    **These maps are only produced if ``tfce`` is enabled in the ``FWECorrector``.**

docs/links.rst

@@ -79,3 +79,5 @@
 .. _Sleuth: http://www.brainmap.org/software.html#Sleuth
 
 .. _SPM: https://www.fil.ion.ucl.ac.uk/spm/
+
+.. _TFCE: https://pubmed.ncbi.nlm.nih.gov/18501637/

examples/02_meta-analyses/05_plot_correctors.py

@@ -61,26 +61,28 @@
 #
 # The "montecarlo" method is a special one that is implemented within the
 # Estimator, rather than in the Corrector.
-corr = FWECorrector(method="montecarlo", n_iters=50, n_cores=2)
+corr = FWECorrector(method="montecarlo", n_iters=25, n_cores=2, tfce=True)
 cres = corr.transform(results)
 
 DISTS_TO_PLOT = [
     "values_desc-size_level-cluster_corr-fwe_method-montecarlo",
     "values_desc-mass_level-cluster_corr-fwe_method-montecarlo",
     "values_level-voxel_corr-fwe_method-montecarlo",
+    "values_desc-tfce_level-voxel_corr-fwe_method-montecarlo",
 ]
 XLABELS = [
     "Maximum Cluster Size (Voxels)",
     "Maximum Cluster Mass",
     "Maximum Summary Statistic (ALE Value)",
+    "Maximum TFCE Value",
 ]
 
-fig, axes = plt.subplots(figsize=(8, 8), nrows=3)
+fig, axes = plt.subplots(figsize=(8, 8), nrows=len(DISTS_TO_PLOT))
 null_dists = cres.estimator.null_distributions_
 
 for i_ax, dist_name in enumerate(DISTS_TO_PLOT):
     xlabel = XLABELS[i_ax]
-    sns.histplot(x=null_dists[dist_name], bins=40, ax=axes[i_ax])
+    sns.histplot(x=null_dists[dist_name], bins=20, ax=axes[i_ax])
     axes[i_ax].set_title(dist_name)
     axes[i_ax].set_xlabel(xlabel)
     axes[i_ax].set_xlim(0, None)
@@ -95,15 +97,17 @@
     "z_desc-size_level-cluster_corr-FWE_method-montecarlo",
     "z_desc-mass_level-cluster_corr-FWE_method-montecarlo",
     "z_level-voxel_corr-FWE_method-montecarlo",
+    "z_desc-tfce_level-voxel_corr-FWE_method-montecarlo",
 ]
 TITLES = [
     "Uncorrected z-statistics",
     "Cluster-size FWE-corrected z-statistics",
     "Cluster-mass FWE-corrected z-statistics",
     "Voxel-level FWE-corrected z-statistics",
+    "TFCE FWE-corrected z-statistics",
 ]
 
-fig, axes = plt.subplots(figsize=(8, 10), nrows=4)
+fig, axes = plt.subplots(figsize=(8, 12), nrows=len(MAPS_TO_PLOT))
 
 for i_ax, map_name in enumerate(MAPS_TO_PLOT):
     title = TITLES[i_ax]
@@ -115,6 +119,7 @@
         cut_coords=[0, 0, -8],
         figure=fig,
         axes=axes[i_ax],
+        annotate=False,
     )
     axes[i_ax].set_title(title)
 

nimare/meta/cbma/ale.py

@@ -110,6 +110,8 @@ class ALE(CBMAEstimator):
                 size from each Monte Carlo iteration. An array of shape (n_iters,).
             -   ``values_desc-mass_level-cluster_corr-fwe_method-montecarlo``: The maximum cluster
                 mass from each Monte Carlo iteration. An array of shape (n_iters,).
+            -   ``values_desc-tfce_level-level_corr-fwe_method-montecarlo``: The maximum TFCE
+                value from each Monte Carlo iteration. An array of shape (n_iters,).
 
     Notes
     -----