Incorporate Estimator and Corrector descriptions into MetaResult objects

docs/conf.py

@@ -209,7 +209,7 @@
 # -----------------------------------------------------------------------------
 # sphinxcontrib-bibtex
 # -----------------------------------------------------------------------------
-bibtex_bibfiles = ["./references.bib"]
+bibtex_bibfiles = ["../nimare/resources/references.bib"]
 bibtex_style = "unsrt"
 bibtex_reference_style = "author_year"
 bibtex_footbibliography_header = ""

examples/02_meta-analyses/04_plot_estimators.py

@@ -32,6 +32,8 @@
 ###############################################################################
 # The Estimator
 # -----------------------------------------------------------------------------
+from pprint import pprint
+
 from nimare.meta.cbma.ale import ALE
 
 # First, the Estimator should be initialized with any parameters.
@@ -40,6 +42,12 @@
 # Then, the ``fit`` method takes in the Dataset and produces a MetaResult.
 results = meta.fit(dset)
 
+# You can also look at the description of the Estimator.
+print("Description:")
+pprint(results.description)
+print("References:")
+pprint(results.bibtex)
+
 ###############################################################################
 # Coordinate-based Estimators allow you to provide a specific KernelTransformer
 # -----------------------------------------------------------------------------
@@ -111,8 +119,6 @@
 ###############################################################################
 # The null distributions are stored within the Estimators
 # `````````````````````````````````````````````````````````````````````````````
-from pprint import pprint
-
 pprint(meta.null_distributions_)
 
 ###############################################################################

examples/02_meta-analyses/05_plot_correctors.py

@@ -8,6 +8,7 @@
 
 Here we take a look at multiple comparisons correction in meta-analyses.
 """
+from pprint import pprint
 
 import matplotlib.pyplot as plt
 import seaborn as sns
@@ -87,6 +88,13 @@
 
 fig.tight_layout()
 
+###############################################################################
+# You can also look at the description of the Corrector.
+print("Description:")
+pprint(cres.description)
+print("References:")
+pprint(cres.bibtex)
+
 ###############################################################################
 # Show corrected results
 # =============================================================================

nimare/base.py

@@ -45,7 +45,7 @@ def __repr__(self):
             if v.default is not inspect.Parameter.empty
         }
 
-        # Eliminate any sub-parameters (e.g., parameters for a MetaEstimator's KernelTransformer),
+        # Eliminate any sub-parameters (e.g., parameters for a Estimator's KernelTransformer),
         # as well as default values
         params = self.get_params()
         params = {k: v for k, v in params.items() if "__" not in k}
@@ -278,6 +278,11 @@ def _collect_inputs(self, dataset, drop_invalid=True):
                     )
                 self.inputs_[k] = v
 
+    @abstractmethod
+    def _generate_description(self):
+        """Generate a text description of the Estimator."""
+        pass
+
     @abstractmethod
     def _preprocess_input(self, dataset):
         """Perform any additional preprocessing steps on data in self.inputs_.
@@ -328,11 +333,11 @@ def fit(self, dataset, drop_invalid=True):
         """
         self._collect_inputs(dataset, drop_invalid=drop_invalid)
         self._preprocess_input(dataset)
-        maps, tables = self._fit(dataset)
+        maps, tables, description = self._fit(dataset)
 
         if hasattr(self, "masker") and self.masker is not None:
             masker = self.masker
         else:
             masker = dataset.masker
 
-        return MetaResult(self, mask=masker, maps=maps, tables=tables)
+        return MetaResult(self, mask=masker, maps=maps, tables=tables, description=description)

nimare/correct.py

@@ -153,7 +153,7 @@ def transform(self, result):
         Returns
         -------
         result : :obj:`~nimare.results.MetaResult`
-            MetaResult with new corrected maps and tables added.
+            MetaResult with new corrected maps, tables, and description added.
         """
         correction_method = f"correct_{self._correction_method}_{self.method}"
 
@@ -163,7 +163,7 @@ def transform(self, result):
         # Also operate on a copy of the estimator
         est = result.estimator
 
-        # If a correction method with the same name exists in the current MetaEstimator, use it.
+        # If a correction method with the same name exists in the current Estimator, use it.
         # Otherwise fall back on _transform, and the Corrector methods.
         # In case a method is present in both the Estimator and the Corrector, the Estimator's
         # implementation takes precedence.
@@ -172,14 +172,17 @@ def transform(self, result):
                 "Using correction method implemented in Estimator: "
                 f"{est.__class__.__module__}.{est.__class__.__name__}.{correction_method}."
             )
-            corr_maps, corr_tables = getattr(est, correction_method)(result, **self.parameters)
+            corr_maps, corr_tables, description = getattr(est, correction_method)(
+                result, **self.parameters
+            )
         else:
             self._collect_inputs(result)
-            corr_maps, corr_tables = self._transform(result, method=correction_method)
+            corr_maps, corr_tables, description = self._transform(result, method=correction_method)
 
         # Update corrected map names and add them to maps dict
         corr_maps = {(k + self._name_suffix): v for k, v in corr_maps.items()}
         result.maps.update(corr_maps)
+        result.description += " " + description
 
         corr_tables = {(k + self._name_suffix): v for k, v in corr_tables.items()}
         result.tables.update(corr_tables)
@@ -214,6 +217,8 @@ def _transform(self, result, method):
         corr_tables : :obj:`dict`
             An empty dictionary meant to contain any tables (pandas DataFrames) produced by the
             correction procedure.
+        description : :obj:`str`
+            A description of the correction procedure.
         """
         p = result.maps["p"]
 
@@ -223,15 +228,15 @@ def _transform(self, result, method):
         p_no_nans = p[nonnan_mask]
 
         # Call the correction method
-        p_corr_no_nans, tables = getattr(self, method)(p_no_nans)
+        p_corr_no_nans, tables, description = getattr(self, method)(p_no_nans)
 
         # Unmask the corrected p values based on the NaN mask
         p_corr[nonnan_mask] = p_corr_no_nans
 
         # Create a dictionary of the corrected results
         corr_maps = {"p": p_corr}
         self._generate_secondary_maps(result, corr_maps)
-        return corr_maps, tables
+        return corr_maps, tables, description
 
 
 class FWECorrector(Corrector):
@@ -284,8 +289,13 @@ def correct_fwe_bonferroni(self, p):
 
         Returns
         -------
-        :obj:`numpy.ndarray`
+        p_corr : :obj:`numpy.ndarray`
             A 1D array of adjusted p values.
+        tables : :obj:`dict`
+            A dictionary of DataFrames with summary information from the correction.
+            This correction method does not produce any tables, so it will be an empty dict.
+        description : :obj:`str`
+            A description of the correction procedure.
 
         References
         ----------
@@ -295,7 +305,11 @@ def correct_fwe_bonferroni(self, p):
         --------
         nimare.stats.bonferroni
         """
-        return bonferroni(p), {}
+        description = (
+            "Family-wise error rate correction was performed with the Bonferroni correction "
+            "procedure \\citep{bonferroni1936teoria,shaffer1995multiple}."
+        )
+        return bonferroni(p), {}, description
 
 
 class FDRCorrector(Corrector):
@@ -352,8 +366,13 @@ def correct_fdr_indep(self, p):
 
         Returns
         -------
-        :obj:`numpy.ndarray`
+        p_corr : :obj:`numpy.ndarray`
             A 1D array of adjusted p values.
+        tables : :obj:`dict`
+            A dictionary of DataFrames with summary information from the correction.
+            This correction method does not produce any tables, so it will be an empty dict.
+        description : :obj:`str`
+            A description of the correction procedure.
 
         References
         ----------
@@ -363,7 +382,11 @@ def correct_fdr_indep(self, p):
         --------
         pymare.stats.fdr
         """
-        return fdr(p, q=self.alpha, method="bh"), {}
+        description = (
+            "False discovery rate correction was performed with the Benjamini-Hochberg procedure "
+            "\\citep{benjamini1995controlling}."
+        )
+        return fdr(p, q=self.alpha, method="bh"), {}, description
 
     def correct_fdr_negcorr(self, p):
         """Perform Benjamini-Yekutieli FDR correction.
@@ -384,8 +407,13 @@ def correct_fdr_negcorr(self, p):
 
         Returns
         -------
-        :obj:`numpy.ndarray`
+        p_corr : :obj:`numpy.ndarray`
             A 1D array of adjusted p values.
+        tables : :obj:`dict`
+            A dictionary of DataFrames with summary information from the correction.
+            This correction method does not produce any tables, so it will be an empty dict.
+        description : :obj:`str`
+            A description of the correction procedure.
 
         Notes
         -----
@@ -403,4 +431,8 @@ def correct_fdr_negcorr(self, p):
         --------
         pymare.stats.fdr
         """
-        return fdr(p, q=self.alpha, method="by"), {}
+        description = (
+            "False discovery rate correction was performed with the Benjamini-Yekutieli procedure "
+            "\\citep{benjamini2001control}."
+        )
+        return fdr(p, q=self.alpha, method="by"), {}, description

nimare/dataset.py

@@ -134,7 +134,7 @@ def __repr__(self):
             if v.default is not inspect.Parameter.empty
         }
 
-        # Eliminate any sub-parameters (e.g., parameters for a MetaEstimator's KernelTransformer),
+        # Eliminate any sub-parameters (e.g., parameters for a Estimator's KernelTransformer),
         # as well as default values
         params = self.get_params()
         params = {k: v for k, v in params.items() if "__" not in k}