From f41499908d4179e3754f01578b28b028c0bcb973 Mon Sep 17 00:00:00 2001 From: Alejandro de la Vega Date: Fri, 19 Jan 2024 17:52:56 -0600 Subject: [PATCH] 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 --- nimare/annotate/gclda.py | 2 +- nimare/correct.py | 32 +++++++++++++++++++------------- nimare/meta/cbma/ale.py | 6 +++--- nimare/meta/cbma/base.py | 2 +- nimare/meta/cbma/mkda.py | 6 ++++-- nimare/meta/ibma.py | 2 +- 6 files changed, 29 insertions(+), 21 deletions(-) diff --git a/nimare/annotate/gclda.py b/nimare/annotate/gclda.py index 4668f8b6b..51b1cec6e 100755 --- a/nimare/annotate/gclda.py +++ b/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 diff --git a/nimare/correct.py b/nimare/correct.py index d5b74d4e4..3c11e3f03 100644 --- a/nimare/correct.py +++ b/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 diff --git a/nimare/meta/cbma/ale.py b/nimare/meta/cbma/ale.py index b57c260bc..288cf9886 100755 --- a/nimare/meta/cbma/ale.py +++ b/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), diff --git a/nimare/meta/cbma/base.py b/nimare/meta/cbma/base.py index a6bd13913..d9d196664 100644 --- a/nimare/meta/cbma/base.py +++ b/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, ): diff --git a/nimare/meta/cbma/mkda.py b/nimare/meta/cbma/mkda.py index e3d6b42bd..459600843 100644 --- a/nimare/meta/cbma/mkda.py +++ b/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 diff --git a/nimare/meta/ibma.py b/nimare/meta/ibma.py index c58a88640..bab35da1b 100755 --- a/nimare/meta/ibma.py +++ b/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