Add Workflow and CBMAWorkflow classes. Support pairwise CBMA workflows

docs/api.rst

@@ -334,7 +334,8 @@ For more information about fetching data from the internet, see :ref:`fetching t
 
    workflows.ale_sleuth_workflow
    workflows.macm_workflow
-   workflows.cbma_workflow
+   workflows.cbma.CBMAWorkflow
+   workflows.cbma.PairwiseCBMAWorkflow
 
 :mod:`nimare.reports`: NiMARE report
 --------------------------------------------------

examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py

@@ -20,6 +20,7 @@
 6. Compare the two within-sample meta-analyses with a conjunction analysis.
 """
 import os
+from pathlib import Path
 
 import matplotlib.pyplot as plt
 from nilearn.plotting import plot_stat_map
@@ -104,19 +105,20 @@
     target_image="z_desc-size_level-cluster_corr-FWE_method-montecarlo",
     voxel_thresh=None,
 )
-knowledge_corrected_results = counter.transform(knowledge_corrected_results)
+knowledge_diagnostic_results = counter.transform(knowledge_corrected_results)
 
 ###############################################################################
 # Clusters table.
-knowledge_clusters_table = knowledge_corrected_results.tables[
+knowledge_clusters_table = knowledge_diagnostic_results.tables[
     "z_desc-size_level-cluster_corr-FWE_method-montecarlo_tab-clust"
 ]
 knowledge_clusters_table.head(10)
 
 ###############################################################################
 # Contribution table. Here ``PostiveTail`` refers to clusters with positive statistics.
-knowledge_count_table = knowledge_corrected_results.tables[
-    "z_desc-size_level-cluster_corr-FWE_method-montecarlo_diag-FocusCounter_tab-counts"
+knowledge_count_table = knowledge_diagnostic_results.tables[
+    "z_desc-size_level-cluster_corr-FWE_method-montecarlo_diag-FocusCounter"
+    "_tab-counts_tail-positive"
 ]
 knowledge_count_table.head(10)
 
@@ -127,9 +129,9 @@
     target_image="z_desc-size_level-cluster_corr-FWE_method-montecarlo",
     voxel_thresh=None,
 )
-related_corrected_results = jackknife.transform(related_corrected_results)
-related_jackknife_table = related_corrected_results.tables[
-    "z_desc-size_level-cluster_corr-FWE_method-montecarlo_diag-Jackknife_tab-counts"
+related_diagnostic_results = jackknife.transform(related_corrected_results)
+related_jackknife_table = related_diagnostic_results.tables[
+    "z_desc-size_level-cluster_corr-FWE_method-montecarlo_diag-Jackknife_tab-counts_tail-positive"
 ]
 related_jackknife_table.head(10)
 
@@ -138,20 +140,36 @@
 # -----------------------------------------------------------------------------
 # Typically, one would use at least 10000 iterations for a subtraction analysis.
 # However, we have reduced this to 100 iterations for this example.
+# Similarly here we use a voxel-level z-threshold of 0.01, but in practice one would
+# use a more stringent threshold (e.g., 1.65).
 from nimare.meta.cbma import ALESubtraction
+from nimare.reports.base import run_reports
+from nimare.workflows import PairwiseCBMAWorkflow
 
-sub = ALESubtraction(n_iters=100, n_cores=1)
-res_sub = sub.fit(knowledge_dset, related_dset)
-img_sub = res_sub.get_map("z_desc-group1MinusGroup2")
-
-plot_stat_map(
-    img_sub,
-    cut_coords=4,
-    display_mode="z",
-    title="Subtraction",
-    cmap="RdBu_r",
-    vmax=4,
+workflow = PairwiseCBMAWorkflow(
+    estimator=ALESubtraction(n_iters=10, n_cores=1),
+    corrector="fdr",
+    diagnostics=FocusCounter(voxel_thresh=0.01, display_second_group=True),
 )
+res_sub = workflow.fit(knowledge_dset, related_dset)
+
+###############################################################################
+# Report
+# -----------------------------------------------------------------------------
+# Finally, a NiMARE report is generated from the MetaResult.
+# root_dir = Path(os.getcwd()).parents[1] / "docs" / "_build"
+# Use the previous root to run the documentation locally.
+root_dir = Path(os.getcwd()).parents[1] / "_readthedocs"
+html_dir = root_dir / "html" / "auto_examples" / "02_meta-analyses" / "08_subtraction"
+html_dir.mkdir(parents=True, exist_ok=True)
+
+run_reports(res_sub, html_dir)
+
+####################################
+# .. raw:: html
+#
+#     <iframe src="./08_subtraction/report.html" style="border:none;" seamless="seamless" \
+#        width="100%" height="1000px"></iframe>
 
 ###############################################################################
 # Conjunction analysis

examples/02_meta-analyses/10_plot_cbma_workflow.py

@@ -20,7 +20,7 @@
 from nimare.dataset import Dataset
 from nimare.reports.base import run_reports
 from nimare.utils import get_resource_path
-from nimare.workflows import cbma_workflow
+from nimare.workflows.cbma import CBMAWorkflow
 
 ###############################################################################
 # Load Dataset
@@ -32,25 +32,26 @@
 ###############################################################################
 # Run CBMA Workflow
 # -----------------------------------------------------------------------------
-# The CBMA workflow function runs the following steps:
+# The fit method of a CBMA workflow class runs the following steps:
 #
 # 1. Runs a meta-analysis using the specified method (default: ALE)
 # 2. Applies a corrector to the meta-analysis results (default: FWECorrector, montecarlo)
 # 3. Generates cluster tables and runs diagnostics on the corrected results (default: Jackknife)
 #
-# All in one function call!
+# All in one call!
 #
-# result = cbma_workflow(dset)
+# result = CBMAWorkflow().fit(dset)
 #
 # For this example, we use an FDR correction because the default corrector (FWE correction with
 # Monte Carlo simulation) takes a long time to run due to the high number of iterations that
 # are required
-result = cbma_workflow(dset, corrector="fdr")
+workflow = CBMAWorkflow(corrector="fdr")
+result = workflow.fit(dset)
 
 ###############################################################################
 # Plot Results
 # -----------------------------------------------------------------------------
-# The CBMA workflow function returns a :class:`~nimare.results.MetaResult` object,
+# The fit method of the CBMA workflow class returns a :class:`~nimare.results.MetaResult` object,
 # where you can access the corrected results of the meta-analysis and diagnostics tables.
 #
 # Corrected map:
@@ -73,22 +74,22 @@
 ###############################################################################
 # Contribution table
 # ``````````````````````````````````````````````````````````````````````````````
-result.tables["z_corr-FDR_method-indep_diag-Jackknife_tab-counts"]
+result.tables["z_corr-FDR_method-indep_diag-Jackknife_tab-counts_tail-positive"]
 
 ###############################################################################
 # Report
 # -----------------------------------------------------------------------------
 # Finally, a NiMARE report is generated from the MetaResult.
-root_dir = Path(os.getcwd()).parents[1]
-# Use the following path to run the documentation locally:
-# html_dir = root_dir / "docs" / "_build" / "html" / "auto_examples" / "02_meta-analyses"
-html_dir = root_dir / "_readthedocs" / "html" / "auto_examples" / "02_meta-analyses"
+# root_dir = Path(os.getcwd()).parents[1] / "docs" / "_build"
+# Use the previous root to run the documentation locally.
+root_dir = Path(os.getcwd()).parents[1] / "_readthedocs"
+html_dir = root_dir / "html" / "auto_examples" / "02_meta-analyses" / "10_plot_cbma_workflow"
 html_dir.mkdir(parents=True, exist_ok=True)
 
 run_reports(result, html_dir)
 
 ####################################
 # .. raw:: html
 #
-#     <iframe src="./report.html" style="border:none;" seamless="seamless" width="100%"\
-#        height="1000px"></iframe>
+#     <iframe src="./10_plot_cbma_workflow/report.html" style="border:none;" seamless="seamless"\
+#        width="100%" height="1000px"></iframe>