Add reports module (#802)

* Add reports module * Add template * Add config file * Add generate_figues script * Add test * Update test_reports.py * Update setup.cfg * Fix lint error * Add yaml to setup file * Update setup.cfg * Update default.yml * Update setup.cfg * Add report to example gallery * check online path * Plot coordinates * Update 10_plot_cbma_workflow.py * Update 10_plot_cbma_workflow.py * Update figures.py * Update 10_plot_cbma_workflow.py * [skip ci] update figures * [skip ci] add static plot * [skip ci] update path to report * [skip ci] update path * [skip ci] explore rtd directory tree * [skip ci] high res images * [skip ci] update path to report * [skip ci] close fig after saving * [skip ci] update path * [skip ci] try another path the report.html * [skip ci] change the path again............. * [skip ci] update path * [skip ci] update path * [skip ci] add cluster table * [skip ci] add title, caption, and description * [skip ci] update example * [skip ci] increase size of heatmap * [skip ci] add ids of studies excluded to summary * [skip ci] update table style * [skip ci] add dynamic coordinates plot * [skip ci] add legend * [skip ci] embed heatmaps wit iframe * [skip ci] change names to fit new bids-like format * [skip ci] pin pandas version * [skip ci] add summary diagnostics * [skip ci] work on copy of diagnostics * [skip ci] get threshold from diagnostics * [skip ci] add all possible combinations of results * [skip ci] add message when tables and map are empty * [skip ci] add alpha to dictionary * [skip ci] add label maps * [skip ci] add tail label * [skip ci] add mask * add documentation * fix typo * add tables naming convention to output * only plot coordinates for CBMAEstimator * fix typo * improve coverage * reduce report and yml file
neurostuff · May 31, 2023 · 01e28ed · 01e28ed
1 parent fccf509
commit 01e28ed
Show file tree

Hide file tree

Showing 14 changed files with 1,212 additions and 44 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -336,6 +336,20 @@ For more information about fetching data from the internet, see :ref:`fetching t
    workflows.macm_workflow
    workflows.cbma_workflow
 
+:mod:`nimare.reports`: NiMARE report
+--------------------------------------------------
+
+.. automodule:: nimare.reports
+   :no-members:
+   :no-inherited-members:
+
+.. currentmodule:: nimare
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   reports.run_reports
 
 .. _api_base_ref:
 

diff --git a/docs/outputs.rst b/docs/outputs.rst
@@ -11,11 +11,13 @@ File names
 
 NiMARE-generated files, especially ones made by meta-analyses, follow a naming convention somewhat based on BIDS.
 
-Here is the basic naming convention for statistical maps:
+Here is the basic naming convention for statistical maps and tables:
 
 .. code-block:: Text
 
-   <value>[_desc-<label>][_level-<cluster|voxel>][_corr-<FWE|FDR>][_method-<label>][_diag-<Jackknife|FocusCounter>].nii.gz
+   <value>[_desc-<label>][_level-<cluster|voxel>][_corr-<FWE|FDR>][_method-<label>][_diag-<Jackknife|FocusCounter>][_tail-<positive|negative>].nii.gz
+
+   <value>[_desc-<label>][_level-<cluster|voxel>][_corr-<FWE|FDR>][_method-<label>]_tab-<clust|counts>.tsv
 
 
 First, the ``value`` represents type of data in the map (e.g., z-statistic, t-statistic).

diff --git a/examples/02_meta-analyses/10_plot_cbma_workflow.py b/examples/02_meta-analyses/10_plot_cbma_workflow.py
@@ -12,12 +12,13 @@
 the fundamental steps of a CBMA meta-analysis.
 """
 import os
-from pprint import pprint
+from pathlib import Path
 
 import matplotlib.pyplot as plt
 from nilearn.plotting import plot_stat_map
 
 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
 
@@ -75,15 +76,19 @@
 result.tables["z_corr-FDR_method-indep_diag-Jackknife_tab-counts"]
 
 ###############################################################################
-# Methods
+# Report
 # -----------------------------------------------------------------------------
-# The MetaResult object also provides boilerplate text automatically generated by NiMARE,
-# which is released under the `CC0 <https://creativecommons.org/publicdomain/zero/1.0/>`_ license.
-print("Description:")
-pprint(result.description_)
+# 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"
+html_dir.mkdir(parents=True, exist_ok=True)
 
-###############################################################################
-# References
-# ``````````````````````````````````````````````````````````````````````````````
-print("References:")
-pprint(result.bibtex_)
+run_reports(result, html_dir)
+
+####################################
+# .. raw:: html
+#
+#     <iframe src="./report.html" style="border:none;" seamless="seamless" width="100%"\
+#        height="1000px"></iframe>
diff --git a/nimare/__init__.py b/nimare/__init__.py
@@ -16,6 +16,7 @@
         decode,
         io,
         meta,
+        reports,
         resources,
         stats,
         utils,
@@ -35,6 +36,7 @@
         "io",
         "stats",
         "utils",
+        "reports",
         "workflows",
         "__version__",
     ]

diff --git a/nimare/diagnostics.py b/nimare/diagnostics.py
@@ -75,30 +75,39 @@ def transform(self, result):
 
         Returns
         -------
-        contribution_table : :obj:`pandas.DataFrame` or None
-            A DataFrame with information about relative contributions of each experiment to each
-            cluster in the thresholded map.
-            There is one row for each experiment.
-            There is one column for each cluster, with column names being
-            ``PostiveTail``/``NegativeTail`` indicating the sign (+/-) of the cluster's
-            statistical values, plus an integer indicating the cluster's associated value
-            in the ``label_maps[0]``/``label_maps[1]`` output.
-            If no clusters are found or a pairwise Estimator was used, ``None`` is returned.
-        clusters_table : :obj:`pandas.DataFrame`
-            A DataFrame with information about each cluster.
-            There is one row for each cluster.
-            The columns in this table include: ``Cluster ID`` (the cluster id, plus a letter
-            for subpeaks only), ``X``/``Y``/``Z`` (coordinate for the center of mass),
-            ``Max Stat`` (statistical value of the peak), and ``Cluster Size (mm3)``
-            (the size of the cluster, in cubic millimeters).
-            If no clusters are found, this table will be empty.
-        label_maps : :obj:`list`
-            List of :obj:`nibabel.nifti1.Nifti1Image` objects of cluster label maps.
-            Each cluster in the map has a single value, which corresponds to the cluster number
-            of the column name in ``contribution_table``.
-            If target_image has negative values after thresholding, first and second maps
-            correspond to positive and negative tails.
-            If no clusters are found, this list will be empty.
+        :obj:`~nimare.results.MetaResult`
+            Results of Diagnostics fitting.
+
+        Notes
+        -----
+        This method adds two new keys to ``maps`` and ``tables`` attributes of the
+        MetaResult object.
+
+            -   ``<target_image>_diag-<Jackknife|FocusCounter>_tab-counts`` :
+                :obj:`pandas.DataFrame` or None.
+                A DataFrame with information about relative contributions of each experiment
+                to each cluster in the thresholded map.
+                There is one row for each experiment.
+                There is one column for each cluster, with column names being
+                ``PostiveTail``/``NegativeTail`` indicating the sign (+/-) of the cluster's
+                statistical values, plus an integer indicating the cluster's associated value
+                in the ``label_maps[0]``/``label_maps[1]`` output.
+                If no clusters are found or a pairwise Estimator was used, ``None`` is returned.
+            -   ``<target_image>_tab-clust`` : :obj:`pandas.DataFrame`
+                A DataFrame with information about each cluster.
+                There is one row for each cluster.
+                The columns in this table include: ``Cluster ID`` (the cluster id, plus a letter
+                for subpeaks only), ``X``/``Y``/``Z`` (coordinate for the center of mass),
+                ``Max Stat`` (statistical value of the peak), and ``Cluster Size (mm3)``
+                (the size of the cluster, in cubic millimeters).
+                If no clusters are found, this table will be empty.
+            -   ``label_<target_image>_tail-<positive|negative>`` : :obj:`numpy.ndarray`
+                Label maps.
+                Each cluster in the map has a single value, which corresponds to the cluster number
+                of the column name in ``contribution_table``.
+                If target_image has negative values after thresholding, first and second maps
+                correspond to positive and negative tails.
+                If no clusters are found, this list will be empty.
         """
         masker = result.estimator.masker
         diag_name = self.__class__.__name__

diff --git a/nimare/reports/__init__.py b/nimare/reports/__init__.py
@@ -0,0 +1,24 @@
+"""Reports module."""
+
+from .base import Report, run_reports
+from .figures import (
+    gen_table,
+    plot_clusters,
+    plot_coordinates,
+    plot_heatmap,
+    plot_interactive_brain,
+    plot_mask,
+    plot_static_brain,
+)
+
+__all__ = [
+    "Report",
+    "run_reports",
+    "gen_table",
+    "plot_clusters",
+    "plot_coordinates",
+    "plot_heatmap",
+    "plot_interactive_brain",
+    "plot_mask",
+    "plot_static_brain",
+]