Clarify FWECorrector arguments (#865)

* Set default n_iters to 1,000, and add args to FWECorrector

* Set variable n_iters based on estimator

* Change more n_iters to 5000

* Run black

* Remove voxel thresh from defaults

* Set n_cores to 1

Author: adelavega

nimare/annotate/gclda.py

@@ -353,7 +353,7 @@ def __init__(
             self.topics["total_n_word_tokens_by_topic"][0, topic] += 1
             self.topics["n_word_tokens_doc_by_topic"][doc, topic] += 1
 
-    def fit(self, n_iters=10000, loglikely_freq=10):
+    def fit(self, n_iters=5000, loglikely_freq=10):
         """Run multiple iterations.
 
         .. versionchanged:: 0.0.8

nimare/correct.py

@@ -261,25 +261,31 @@ class FWECorrector(Corrector):
 
     Parameters
     ----------
-    method : :obj:`str`
-        The FWE correction to use. Available internal methods are 'bonferroni'.
-        Additional methods may be implemented within the provided Estimator.
+    method : {'bonferoni', 'montecarlo'}
+        The FWE correction to use. Note that the 'montecarlo' method is only available for
+        a subset of Estimators. To determine what methods are available for the Estimator you're
+        using, use :meth:`inspect`.
+    voxel_thresh : :obj:`float`, optional
+        Only used if ``method='montecarlo'``. The uncorrected voxel-level threshold to use.
+    n_iters : :obj:`int`, optional
+        Number of iterations to use for Monte Carlo correction.
+        Default varies by Estimator.
+        For publication-quality results, 5000 or more iterations are recommended.
+    n_cores : :obj:`int`, optional
+        Number of cores to use for Monte Carlo correction. Default is 1.
     **kwargs
         Keyword arguments to be used by the FWE correction implementation.
-
-    Notes
-    -----
-    This corrector supports a small number of internal FWE correction methods, but can also use
-    special methods implemented within individual Estimators.
-    To determine what methods are available for the Estimator you're using, use :meth:`inspect`.
-    Estimators have special methods following the naming convention
-    ``correct_[correction-type]_[method]``
-    (e.g., :func:`~nimare.meta.cbma.ale.ALE.correct_fwe_montecarlo`).
     """
 
     _correction_method = "fwe"
 
-    def __init__(self, method="bonferroni", **kwargs):
+    def __init__(self, method="bonferroni", n_iters=None, n_cores=1, **kwargs):
+        if method not in ("bonferroni", "montecarlo"):
+            raise ValueError(f"Unsupported FWE correction method '{method}'")
+
+        if method == "montecarlo":
+            kwargs.update({"n_iters": n_iters, "n_cores": n_cores})
+
         self.method = method
         self.parameters = kwargs
 

nimare/meta/cbma/ale.py

@@ -156,7 +156,7 @@ def __init__(
             **kwargs,
         )
         self.null_method = null_method
-        self.n_iters = None if null_method == "approximate" else n_iters or 10000
+        self.n_iters = None if null_method == "approximate" else n_iters or 5000
         self.n_cores = _check_ncores(n_cores)
         self.dataset = None
 
@@ -403,7 +403,7 @@ class ALESubtraction(PairwiseCBMAEstimator):
     def __init__(
         self,
         kernel_transformer=ALEKernel,
-        n_iters=10000,
+        n_iters=5000,
         memory=Memory(location=None, verbose=0),
         memory_level=0,
         n_cores=1,
@@ -698,7 +698,7 @@ class SCALE(CBMAEstimator):
     def __init__(
         self,
         xyz,
-        n_iters=10000,
+        n_iters=5000,
         n_cores=1,
         kernel_transformer=ALEKernel,
         memory=Memory(location=None, verbose=0),

nimare/meta/cbma/base.py

@@ -590,7 +590,7 @@ def correct_fwe_montecarlo(
         self,
         result,
         voxel_thresh=0.001,
-        n_iters=10000,
+        n_iters=5000,
         n_cores=1,
         vfwe_only=False,
     ):

nimare/meta/cbma/mkda.py

@@ -715,7 +715,7 @@ def _apply_correction(self, stat_values, voxel_thresh, vfwe_null, csfwe_null, cm
 
         return p_vfwe_values, p_csfwe_values, p_cmfwe_values
 
-    def correct_fwe_montecarlo(self, result, voxel_thresh=0.001, n_iters=5000, n_cores=1):
+    def correct_fwe_montecarlo(self, result, voxel_thresh=0.001, n_iters=1000, n_cores=1):
         """Perform FWE correction using the max-value permutation method.
 
         Only call this method from within a Corrector.
@@ -732,6 +732,8 @@ def correct_fwe_montecarlo(self, result, voxel_thresh=0.001, n_iters=5000, n_cor
         ----------
         result : :obj:`~nimare.results.MetaResult`
             Result object from a KDA meta-analysis.
+        voxel_thresh : :obj:`float`, optional
+            Voxel-level threshold. Default is 0.001.
         n_iters : :obj:`int`, optional
             Number of iterations to build the vFWE null distribution.
             Default is 5000.
@@ -1164,7 +1166,7 @@ def __init__(
             **kwargs,
         )
         self.null_method = null_method
-        self.n_iters = None if null_method == "approximate" else n_iters or 10000
+        self.n_iters = None if null_method == "approximate" else n_iters or 5000
         self.n_cores = _check_ncores(n_cores)
         self.dataset = None
 

nimare/meta/ibma.py

@@ -1321,7 +1321,7 @@ def _fit(self, dataset):
 
         return maps, {}, description
 
-    def correct_fwe_montecarlo(self, result, n_iters=10000, n_cores=1):
+    def correct_fwe_montecarlo(self, result, n_iters=1000, n_cores=1):
         """Perform FWE correction using the max-value permutation method.
 
         .. versionchanged:: 0.0.8