[ENH] ale subtraction scale improvements (#1002)

* Optimize SCALE and ALESubtraction Monte Carlo workflows

Use empirical voxelwise SCALE nulls and add voxel-level Monte Carlo FWE support.

Stream ALESubtraction voxelwise null updates to reduce storage overhead, speed shared cluster and null-distribution helpers, and deduplicate shared permutation summarystat generation in the CBMA base path.

* Document SCALE Monte Carlo FWE usage in examples

Update the MACM and CBMA example snippets to show voxel-level Monte Carlo FWE correction for SCALE and clarify that cluster-level correction is not supported.

* clear up documentation and minor refactor

* name the variables more clearly

Author: jdkent

examples/02_meta-analyses/01_plot_cbma.py

@@ -192,6 +192,7 @@ def subset_studies(studyset, start=None, stop=None):
 #
 #   import numpy as np
 #
+#   from nimare.correct import FWECorrector
 #   from nimare.meta.cbma.ale import SCALE
 #   from nimare.utils import vox2mm
 #
@@ -202,6 +203,8 @@ def subset_studies(studyset, start=None, stop=None):
 #
 #   meta = SCALE(xyz=xyz, n_iters=10)
 #   results = meta.fit(dset)
+#   corr = FWECorrector(method="montecarlo", n_iters=10, n_cores=1)
+#   cres = corr.transform(results)
 
 ###############################################################################
 # ALE-Based Subtraction Analysis

examples/02_meta-analyses/07_macm.py

@@ -83,12 +83,20 @@
 # SCALE
 # -----------------------------------------------------------------------------
 # Another good option for a MACM analysis is the SCALE algorithm, which was
-# designed specifically for MACM. Unfortunately, SCALE does not support
-# multiple-comparisons correction.
+# designed specifically for MACM.
+# NiMARE supports voxel-level Monte Carlo FWE correction for SCALE, but not
+# cluster-level correction.
 
 # First, we must define our null model of reported coordinates in the literature.
 # We will use the coordinates in Neurosynth
 xyz = studyset.coordinates[["x", "y", "z"]].values
 scale = SCALE(xyz=xyz, n_iters=10000, n_cores=1, kernel__n=20)
 results = scale.fit(studyset_sel)
-plotting.plot_stat_map(results.get_map("z"), draw_cross=False, cmap="RdBu_r", symmetric_cbar=True)
+corr = FWECorrector(method="montecarlo", n_iters=10000, n_cores=1)
+cres = corr.transform(results)
+plotting.plot_stat_map(
+    cres.get_map("z_level-voxel_corr-FWE_method-montecarlo"),
+    draw_cross=False,
+    cmap="RdBu_r",
+    symmetric_cbar=True,
+)