[ENH] New diagnostics module, with post-meta-analysis Jackknife method

.circleci/config.yml

@@ -296,6 +296,36 @@ jobs:
 workflows:
   version: 2.1
   run_tests:
+    jobs:
+      - make_py36_env
+      - test_py36_minimum
+      - test_py36:
+          requires:
+            - make_py36_env
+      - test_py37
+      - test_py38
+      - test_py39
+      - test_performance_smoke:
+          requires:
+            - make_py36_env
+      - build_docs:
+          requires:
+            - make_py36_env
+      - style_check:
+          requires:
+            - make_py36_env
+      - merge_coverage:
+          requires:
+            - test_py36
+            - test_performance_smoke
+  nightly:
+    triggers:
+      - schedule:
+          cron: "0 0 * * *"
+          filters:
+            branches:
+              only:
+                - main
     jobs:
       - make_py36_env
       - test_py36_minimum

docs/Makefile

@@ -15,6 +15,11 @@ help:
 clean:
 	rm -r _build generated auto_examples
 
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/_static/nimare.css

@@ -1,6 +1,40 @@
 /*Alterations to the theme defaults*/
-/*Just changes to bar colors*/
+
 /* Sidebar header (and topbar for mobile) */
 .wy-side-nav-search, .wy-nav-top {
-  background: #9370DB;
+  background: #a589df;
+}
+
+/* Sphinx gallery example titles */
+/* Taken from scikit-learn */
+#examples {
+  font-family: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";
+}
+
+#examples .caption-text {
+  font-style: normal;
+  font-size: 0.9rem;
+  text-align: center;
+}
+
+#examples h1 {
+  border-radius: 0.3rem;
+  background-color: #b8a6db;
+  text-align: center;
+  font-size: 2rem;
+  font-weight: 500;
+  margin-bottom: 1rem;
+  padding: 0.5rem;
+  font-family: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";
+}
+
+#examples h2 {
+  border-radius: 0.3rem;
+  background-color: #d589d8;
+  text-align: center;
+  font-size: 1.5rem;
+  font-weight: 500;
+  margin-bottom: 1rem;
+  padding: 0.5rem;
+  font-family: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";
 }

docs/api.rst

@@ -77,6 +77,24 @@ API
    correct.FDRCorrector
 
 
+.. _api_diagnostics_ref:
+
+:mod:`nimare.diagnostics`: Diagnostics
+------------------------------------------------------
+
+.. automodule:: nimare.diagnostics
+   :no-members:
+   :no-inherited-members:
+
+.. currentmodule:: nimare
+
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+   diagnostics.Jackknife
+
+
 .. _api_annotate_ref:
 
 :mod:`nimare.annotate`: Automated annotation

docs/conf.py

@@ -23,6 +23,7 @@
 
 import sphinx
 from m2r import MdInclude
+from sphinx_gallery.sorting import FileNameSortKey
 
 sys.path.insert(0, os.path.abspath(os.path.pardir))
 sys.path.insert(0, os.path.abspath("sphinxext"))
@@ -179,17 +180,19 @@
 sphinx_gallery_conf = {
     # path to your examples scripts
     "examples_dirs": "../examples",
+    "filename_pattern": "/[0-9]+_plot_",
     # path where to save gallery generated examples
     "gallery_dirs": "auto_examples",
     "backreferences_dir": "generated",
-    # Modules for which function level galleries are created.  In
-    # this case sphinx_gallery and numpy in a tuple of strings.
+    # Modules for which function level galleries are created.
+    # In this case sphinx_gallery and numpy in a tuple of strings.
     "doc_module": ("nimare"),
     "ignore_pattern": r"utils/.",
     "reference_url": {
         # The module you locally document uses None
         "nimare": None
     },
+    "within_subsection_order": FileNameSortKey,
 }
 
 # Generate the plots for the gallery

examples/01_datasets/plot_dataset_io.py → examples/01_datasets/01_plot_dataset_io.py

@@ -4,10 +4,11 @@
 
 .. _datasets1:
 
-========================================================
- Load and work with a Dataset
-========================================================
+=========================
+The NiMARE Dataset object
+=========================
 
+This is a brief walkthrough of the :class:`nimare.dataset.Dataset` class and its methods.
 """
 ###############################################################################
 # Start with the necessary imports

examples/01_datasets/download_neurosynth.py → examples/01_datasets/02_download_neurosynth.py

@@ -4,9 +4,9 @@
 
 .. _datasets2:
 
-================================================
- Download the Neurosynth or NeuroQuery databases
-================================================
+=========================
+Neurosynth and NeuroQuery
+=========================
 
 Download and convert the Neurosynth database (with abstracts) for analysis with NiMARE.
 
@@ -26,7 +26,6 @@
 
 For information about where these files will be downloaded to on your machine,
 see :ref:`fetching tools`.
-
 """
 ###############################################################################
 # Start with the necessary imports

examples/01_datasets/plot_neurovault_io.py → examples/01_datasets/03_plot_neurovault_io.py

@@ -2,10 +2,11 @@
 
 .. _datasets3:
 
-===========================================
-Using Neurovault Statistical Maps in NiMARE
-===========================================
+=========================================
+Use NeuroVault statistical maps in NiMARE
+=========================================
 
+Download statistical maps from NeuroVault, then use them in a meta-analysis, with NiMARE.
 """
 ###############################################################################
 # Neurovault + NiMARE: Load freely shared statistical maps for Meta-Analysis

examples/01_datasets/transform_images_to_coordinates.py → examples/01_datasets/04_transform_images_to_coordinates.py

@@ -4,12 +4,12 @@
 
 .. _datasets4:
 
-=============================================
- Transform images into coordinates
-=============================================
+=================================
+Transform images into coordinates
+=================================
+
+Create a dataset with coordinates derived from peak statistic identification in images.
 
-Create a dataset with coordinates derived from peak statistic
-identification in images.
 Why would you want to do this?
 
 * Compare CBMA and IBMA

examples/02_meta-analyses/plot_generate_ma_maps.py → examples/02_meta-analyses/01_plot_generate_ma_maps.py

@@ -4,16 +4,16 @@
 
 .. _metas1:
 
-========================================================
- Generate modeled activation maps
-========================================================
+================================
+Generate modeled activation maps
+================================
 
 For coordinate-based data, individual studies' statistical maps are mimicked
 by generating "modeled activation" (MA) maps.
 These MA maps are used in the CBMA algorithms, although the specific method
 used to generate the MA maps differs by algorithm.
-
 """
+# sphinx_gallery_thumbnail_number = 2
 ###############################################################################
 # Start with the necessary imports
 # --------------------------------
@@ -49,10 +49,20 @@
 
 fig, axes = plt.subplots(nrows=2, ncols=2, figsize=(20, 10))
 plot_stat_map(
-    mkda_r02[2], cut_coords=[-2, -10, -4], title="r=2mm", vmax=2, axes=axes[0, 0], draw_cross=False
+    mkda_r02[2],
+    cut_coords=[-2, -10, -4],
+    title="r=2mm",
+    vmax=2,
+    axes=axes[0, 0],
+    draw_cross=False,
 )
 plot_stat_map(
-    mkda_r06[2], cut_coords=[-2, -10, -4], title="r=6mm", vmax=2, axes=axes[0, 1], draw_cross=False
+    mkda_r06[2],
+    cut_coords=[-2, -10, -4],
+    title="r=6mm",
+    vmax=2,
+    axes=axes[0, 1],
+    draw_cross=False,
 )
 plot_stat_map(
     mkda_r10[2],
@@ -90,6 +100,32 @@
 kernel = nimare.meta.kernel.ALEKernel(sample_size=20)
 ale_res = kernel.transform(dset, return_type="image")
 max_conv = np.max(kda_res[2].get_fdata())
-plot_stat_map(mkda_res[2], cut_coords=[-2, -10, -4], title="MKDA", vmax=max_conv)
-plot_stat_map(kda_res[2], cut_coords=[-2, -10, -4], title="KDA", vmax=max_conv)
-plot_stat_map(ale_res[2], cut_coords=[-2, -10, -4], title="ALE")
+
+fig, axes = plt.subplots(figsize=(12, 12), nrows=3)
+plot_stat_map(
+    mkda_res[2],
+    cut_coords=[-2, -10, -4],
+    title="MKDA",
+    vmax=max_conv,
+    draw_cross=False,
+    axes=axes[0],
+    figure=fig,
+)
+plot_stat_map(
+    kda_res[2],
+    cut_coords=[-2, -10, -4],
+    title="KDA",
+    vmax=max_conv,
+    draw_cross=False,
+    axes=axes[1],
+    figure=fig,
+)
+plot_stat_map(
+    ale_res[2],
+    cut_coords=[-2, -10, -4],
+    title="ALE",
+    draw_cross=False,
+    axes=axes[2],
+    figure=fig,
+)
+fig.show()

examples/02_meta-analyses/plot_cbma.py → examples/02_meta-analyses/02_plot_cbma.py

@@ -4,9 +4,11 @@
 
 .. _metas2:
 
-======================================================
- Run coordinate-based meta-analyses on 21 pain studies
-======================================================
+==============================
+Coordinate-based meta-analysis
+==============================
+
+Perform CBMAs on a toy dataset.
 
 Collection of NIDM-Results packs downloaded from Neurovault collection 1425,
 uploaded by Dr. Camille Maumet.

examples/02_meta-analyses/macm.py → examples/02_meta-analyses/03_macm.py

@@ -4,9 +4,9 @@
 
 .. _metas3:
 
-===================================================
- Run a meta-analytic coactivation modeling analysis
-===================================================
+============================================
+Meta-analytic coactivation modeling analysis
+============================================
 
 Meta-analytic coactivation modeling (MACM) is a common coordinate-based
 analysis in which task-independent "connectivity" is assessed by selecting

examples/02_meta-analyses/plot_cbma_combine_estimators_and_kernels.py → examples/02_meta-analyses/04_plot_cbma_combine_estimators_and_kernels.py

@@ -4,9 +4,9 @@
 
 .. _metas4:
 
-================================================================================
- Test combinations of kernels and estimators for coordinate-based meta-analyses.
-================================================================================
+===================================
+Combine CBMA kernels and estimators
+===================================
 
 Collection of NIDM-Results packs downloaded from Neurovault collection 1425,
 uploaded by Dr. Camille Maumet.