From 2ea1079a82f30d568c8e9a0a6291379e520e22bd Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Sat, 16 Jul 2022 09:26:54 -0400 Subject: [PATCH 01/16] Start drafting user guide. --- docs/about.rst | 4 ++++ docs/guide/annotation.rst | 2 ++ docs/guide/cbma.rst | 7 +++++++ docs/guide/data.rst | 8 ++++++++ docs/guide/decoding.rst | 2 ++ docs/guide/ibma.rst | 2 ++ docs/guide/introduction.rst | 8 ++++++++ docs/index.rst | 5 +++-- docs/user_guide.rst | 12 ++++++++++++ 9 files changed, 48 insertions(+), 2 deletions(-) create mode 100644 docs/guide/annotation.rst create mode 100644 docs/guide/cbma.rst create mode 100644 docs/guide/data.rst create mode 100644 docs/guide/decoding.rst create mode 100644 docs/guide/ibma.rst create mode 100644 docs/guide/introduction.rst create mode 100644 docs/user_guide.rst diff --git a/docs/about.rst b/docs/about.rst index 713b8db99..b90b49647 100644 --- a/docs/about.rst +++ b/docs/about.rst @@ -43,11 +43,13 @@ or are never even translated from the original papers into useable tools. NiMARE operates on NIMADS-format datasets, which users will be able to compile by searching the NeuroStore database with the pyNIMADS library. A number of other services in the ecosystem will then use NiMARE functions to perform meta-analyses, including Neurosynth 2.0 and `NeuroVault`_. + Other Meta-Analytic Tools ------------------------- Outside of the shared ecosystem detailed above, there are a number of tools. + Coordinate-based meta-analysis tools ```````````````````````````````````` @@ -60,11 +62,13 @@ The `SDM`_ Toolbox: This toolbox contains the hybrid coordinate/image-based seed `NeuRoi Toolbox`_: This toolbox contains an implementation of the `Analysis of Brain Coordinates`_ (ABC) CBMA algorithm. + Image-based meta-analysis tools ``````````````````````````````` `IBMA SPM extension`_: This SPM extension implements a number of image-based meta-analysis algorithms. + Meta-analysis tools for other neuroimaging modalities ````````````````````````````````````````````````````` diff --git a/docs/guide/annotation.rst b/docs/guide/annotation.rst new file mode 100644 index 000000000..762749586 --- /dev/null +++ b/docs/guide/annotation.rst @@ -0,0 +1,2 @@ +Annotating Meta-Analytic Data +============================== diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst new file mode 100644 index 000000000..7173696b5 --- /dev/null +++ b/docs/guide/cbma.rst @@ -0,0 +1,7 @@ +Coordinate-Based Meta-Analysis +============================== + +.. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_01_plot_cbma_001.png + :target: ../auto_examples/02_meta-analyses/01_plot_cbma.ipynb + :align: center + :scale: 40 diff --git a/docs/guide/data.rst b/docs/guide/data.rst new file mode 100644 index 000000000..8a7d1f658 --- /dev/null +++ b/docs/guide/data.rst @@ -0,0 +1,8 @@ +Working with Meta-Analytic Data +=============================== + +:ref:`sphx_glr_auto_examples_01_plot_dataset_io.py` + +.. literalinclude:: ../../examples/01_datasets/01_plot_dataset_io.py + :start-after: # Now we can load and save the Dataset object + :end-before: os.remove("pain_dset.pkl") # cleanup diff --git a/docs/guide/decoding.rst b/docs/guide/decoding.rst new file mode 100644 index 000000000..f9c94de99 --- /dev/null +++ b/docs/guide/decoding.rst @@ -0,0 +1,2 @@ +Meta-Analytic Functional Decoding +================================= diff --git a/docs/guide/ibma.rst b/docs/guide/ibma.rst new file mode 100644 index 000000000..8d10c9342 --- /dev/null +++ b/docs/guide/ibma.rst @@ -0,0 +1,2 @@ +Image-Based Meta-Analysis +============================== diff --git a/docs/guide/introduction.rst b/docs/guide/introduction.rst new file mode 100644 index 000000000..b3d45ac16 --- /dev/null +++ b/docs/guide/introduction.rst @@ -0,0 +1,8 @@ +Introduction to NiMARE +===================================== + +Meta-Analysis and Analyses Using Meta-Analytic Data + +Installing NiMARE + +Getting Help diff --git a/docs/index.rst b/docs/index.rst index 71caa82de..2237911a2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -122,15 +122,16 @@ Then, to cite NiMARE in your manuscript, we recommend something like the followi about installation + user_guide api auto_examples/index - contributing - dev_guide cli outputs methods changelog glossary + contributing + dev_guide Indices and tables ------------------ diff --git a/docs/user_guide.rst b/docs/user_guide.rst new file mode 100644 index 000000000..5e7939e58 --- /dev/null +++ b/docs/user_guide.rst @@ -0,0 +1,12 @@ +User guide: table of contents +============================== + +.. toctree:: + :numbered: + + guide/introduction.rst + guide/data.rst + guide/cbma.rst + guide/ibma.rst + guide/annotation.rst + guide/decoding.rst From 048b20585090e95ce6a3fa945ae3aabe0978ba48 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Sat, 16 Jul 2022 09:48:14 -0400 Subject: [PATCH 02/16] Fix things up. --- docs/guide/data.rst | 4 +++- docs/user_guide.rst | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/guide/data.rst b/docs/guide/data.rst index 8a7d1f658..d6f54c31c 100644 --- a/docs/guide/data.rst +++ b/docs/guide/data.rst @@ -1,7 +1,9 @@ Working with Meta-Analytic Data =============================== -:ref:`sphx_glr_auto_examples_01_plot_dataset_io.py` +:ref:`_sphx_glr_auto_examples_01_datasets_01_plot_dataset_io.py` + +:ref:`sphx_glr_auto_examples_01_datasets_01_plot_dataset_io.py` .. literalinclude:: ../../examples/01_datasets/01_plot_dataset_io.py :start-after: # Now we can load and save the Dataset object diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 5e7939e58..8a9f05435 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -1,5 +1,5 @@ -User guide: table of contents -============================== +User Guide +========== .. toctree:: :numbered: From 330448715c8d87f169fde9c1f9eba8985dd22038 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Sat, 16 Jul 2022 09:56:37 -0400 Subject: [PATCH 03/16] More refs. --- docs/guide/cbma.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst index 7173696b5..b34e2db4f 100644 --- a/docs/guide/cbma.rst +++ b/docs/guide/cbma.rst @@ -1,7 +1,15 @@ Coordinate-Based Meta-Analysis ============================== +.. note:: + This page walks through coordinate-based meta-analysis (CBMA) in NiMARE from a practical perspective. + The focus is on performing basic CBMAs. + For a more detailed description of the classes and functions used for CBMA, see + :ref:`sphx_glr_auto_examples_02_meta-analyses_01_plot_kernel_transformers.py`, + :ref:`sphx_glr_auto_examples_02_meta-analyses_01_plot_cbma.py`, and + :ref:`sphx_glr_auto_examples_02_meta-analyses_01_plot_correctors.py`. + .. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_01_plot_cbma_001.png :target: ../auto_examples/02_meta-analyses/01_plot_cbma.ipynb :align: center - :scale: 40 + :scale: 100 From 4eac1f9c73ac0c9f901ea2f6b61d761c70c8f726 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Sat, 16 Jul 2022 10:50:18 -0400 Subject: [PATCH 04/16] [skip ci] More updates. --- docs/conf.py | 2 +- docs/guide/cbma.rst | 6 ++++-- docs/guide/data.rst | 2 +- docs/guide/introduction.rst | 15 +++++++++++++-- 4 files changed, 19 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b278fe173..bc546df8b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -173,7 +173,7 @@ "matplotlib": ("https://matplotlib.org/", (None, "https://matplotlib.org/objects.inv")), "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), "nibabel": ("https://nipy.org/nibabel/", None), - "nilearn": ("http://nilearn.github.io/", None), + "nilearn": ("http://nilearn.github.io/stable/", None), "pymare": ("https://pymare.readthedocs.io/en/latest/", None), "skimage": ("https://scikit-image.org/docs/stable/", None), } diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst index b34e2db4f..f2a4ddc0b 100644 --- a/docs/guide/cbma.rst +++ b/docs/guide/cbma.rst @@ -1,13 +1,15 @@ Coordinate-Based Meta-Analysis ============================== +Coordinate-based meta-analysis (CBMA) + .. note:: This page walks through coordinate-based meta-analysis (CBMA) in NiMARE from a practical perspective. The focus is on performing basic CBMAs. For a more detailed description of the classes and functions used for CBMA, see - :ref:`sphx_glr_auto_examples_02_meta-analyses_01_plot_kernel_transformers.py`, + :ref:`sphx_glr_auto_examples_02_meta-analyses_03_plot_kernel_transformers.py`, :ref:`sphx_glr_auto_examples_02_meta-analyses_01_plot_cbma.py`, and - :ref:`sphx_glr_auto_examples_02_meta-analyses_01_plot_correctors.py`. + :ref:`sphx_glr_auto_examples_02_meta-analyses_05_plot_correctors.py`. .. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_01_plot_cbma_001.png :target: ../auto_examples/02_meta-analyses/01_plot_cbma.ipynb diff --git a/docs/guide/data.rst b/docs/guide/data.rst index d6f54c31c..77c853046 100644 --- a/docs/guide/data.rst +++ b/docs/guide/data.rst @@ -1,7 +1,7 @@ Working with Meta-Analytic Data =============================== -:ref:`_sphx_glr_auto_examples_01_datasets_01_plot_dataset_io.py` + :ref:`sphx_glr_auto_examples_01_datasets_01_plot_dataset_io.py` diff --git a/docs/guide/introduction.rst b/docs/guide/introduction.rst index b3d45ac16..8e11fef13 100644 --- a/docs/guide/introduction.rst +++ b/docs/guide/introduction.rst @@ -1,8 +1,19 @@ +.. include:: ../links.rst + Introduction to NiMARE ===================================== Meta-Analysis and Analyses Using Meta-Analytic Data - -Installing NiMARE +--------------------------------------------------- Getting Help +------------ + +If you have usage-related questions, please create a new topic on `NeuroStars `_ +with the `"nimare" tag `_. +The ``NiMARE`` developers follow NeuroStars, and will be able to answer your question there. + +If you have identified a bug in NiMARE, or would like to request a new feature or change, +you can `open an issue `_ on GitHub. +Please look through `open issues `_ before opening a new one, +to ensure that you are not duplicating an existing issue. From 3b11042baba35a06270568d3d4f3b4b9f9906fe9 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Sat, 16 Jul 2022 11:01:15 -0400 Subject: [PATCH 05/16] [skip ci] More stuff. --- docs/guide/cbma.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst index f2a4ddc0b..58ff94f8a 100644 --- a/docs/guide/cbma.rst +++ b/docs/guide/cbma.rst @@ -1,7 +1,10 @@ Coordinate-Based Meta-Analysis ============================== -Coordinate-based meta-analysis (CBMA) +Coordinate-based meta-analysis (CBMA) is a popular tool for measuring consistency across neuroimaging studies. +While :ref:`ibma.rst` leverage more information than CBMA, and is thus superior, +CBMA is much more popular because the majority of fMRI papers report peaks from significant clusters in tables, +rather than uploading unthresholded statistical maps to a database, like NeuroVault. .. note:: This page walks through coordinate-based meta-analysis (CBMA) in NiMARE from a practical perspective. From 288dcc25bb1c824a17e2ac78add1b60a2785b936 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Sat, 16 Jul 2022 13:10:35 -0400 Subject: [PATCH 06/16] [skip ci] Draft outlines. --- docs/guide/annotation.rst | 9 +++++++++ docs/guide/cbma.rst | 18 ++++++++++++++++++ docs/guide/data.rst | 7 +++++++ docs/guide/decoding.rst | 8 ++++++++ docs/guide/ibma.rst | 18 ++++++++++++++++++ 5 files changed, 60 insertions(+) diff --git a/docs/guide/annotation.rst b/docs/guide/annotation.rst index 762749586..56c3b2ab9 100644 --- a/docs/guide/annotation.rst +++ b/docs/guide/annotation.rst @@ -1,2 +1,11 @@ Annotating Meta-Analytic Data ============================== + +Downloading abstracts for papers +-------------------------------- + +Extracting features from text +----------------------------- + +Annotating Datasets +------------------- diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst index 58ff94f8a..0cd9ad734 100644 --- a/docs/guide/cbma.rst +++ b/docs/guide/cbma.rst @@ -14,7 +14,25 @@ rather than uploading unthresholded statistical maps to a database, like NeuroVa :ref:`sphx_glr_auto_examples_02_meta-analyses_01_plot_cbma.py`, and :ref:`sphx_glr_auto_examples_02_meta-analyses_05_plot_correctors.py`. +Selecting studies for a meta-analysis +------------------------------------- + +Organizing the dataset in NiMARE +-------------------------------- + +Performing the meta-analysis +---------------------------- + .. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_01_plot_cbma_001.png :target: ../auto_examples/02_meta-analyses/01_plot_cbma.ipynb :align: center :scale: 100 + +Multiple comparisons correction +------------------------------- + +Saving the results +------------------ + +Performing additional followup analyses +--------------------------------------- diff --git a/docs/guide/data.rst b/docs/guide/data.rst index 77c853046..591c715e6 100644 --- a/docs/guide/data.rst +++ b/docs/guide/data.rst @@ -1,7 +1,14 @@ Working with Meta-Analytic Data =============================== +Downloading large databases +--------------------------- +Converting datasets from BrainMap +--------------------------------- + +The Dataset object +------------------ :ref:`sphx_glr_auto_examples_01_datasets_01_plot_dataset_io.py` diff --git a/docs/guide/decoding.rst b/docs/guide/decoding.rst index f9c94de99..a87263f58 100644 --- a/docs/guide/decoding.rst +++ b/docs/guide/decoding.rst @@ -1,2 +1,10 @@ Meta-Analytic Functional Decoding ================================= + +Decoding ROIs + +Decoding VOIs + +Decoding based on arbitrary subsets of the Dataset + +Decoding statistical maps diff --git a/docs/guide/ibma.rst b/docs/guide/ibma.rst index 8d10c9342..dddb4667b 100644 --- a/docs/guide/ibma.rst +++ b/docs/guide/ibma.rst @@ -1,2 +1,20 @@ Image-Based Meta-Analysis ============================== + +Selecting studies for a meta-analysis +------------------------------------- + +Organizing the dataset in NiMARE +-------------------------------- + +Performing the meta-analysis +---------------------------- + +Multiple comparisons correction +------------------------------- + +Saving the results +------------------ + +Performing additional followup analyses +--------------------------------------- From 6f7428c3e4df204b3cb3b4a5cf11997a05ae72b9 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 18 Jul 2022 08:53:19 -0400 Subject: [PATCH 07/16] Reorganize guide. --- docs/guide/toc.rst | 12 ++++++++++++ docs/index.rst | 2 +- docs/user_guide.rst | 12 ------------ 3 files changed, 13 insertions(+), 13 deletions(-) create mode 100644 docs/guide/toc.rst delete mode 100644 docs/user_guide.rst diff --git a/docs/guide/toc.rst b/docs/guide/toc.rst new file mode 100644 index 000000000..3ad151bfd --- /dev/null +++ b/docs/guide/toc.rst @@ -0,0 +1,12 @@ +User Guide +========== + +.. toctree:: + :numbered: + + introduction.rst + data.rst + cbma.rst + ibma.rst + annotation.rst + decoding.rst diff --git a/docs/index.rst b/docs/index.rst index 2237911a2..6fbd3c81d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -122,7 +122,7 @@ Then, to cite NiMARE in your manuscript, we recommend something like the followi about installation - user_guide + guide/toc api auto_examples/index cli diff --git a/docs/user_guide.rst b/docs/user_guide.rst deleted file mode 100644 index 8a9f05435..000000000 --- a/docs/user_guide.rst +++ /dev/null @@ -1,12 +0,0 @@ -User Guide -========== - -.. toctree:: - :numbered: - - guide/introduction.rst - guide/data.rst - guide/cbma.rst - guide/ibma.rst - guide/annotation.rst - guide/decoding.rst From 42a4afb7cde9d5dc606a35fbf067f84adc8c76c4 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 18 Jul 2022 11:31:41 -0400 Subject: [PATCH 08/16] [skip ci] update again. --- docs/guide/annotation.rst | 4 ++++ docs/guide/cbma.rst | 34 ++++++++++++++++++++++++++++++++++ docs/guide/data.rst | 4 ++++ docs/guide/decoding.rst | 8 ++++++++ docs/guide/ibma.rst | 11 +++++++++++ docs/guide/introduction.rst | 4 ++++ 6 files changed, 65 insertions(+) diff --git a/docs/guide/annotation.rst b/docs/guide/annotation.rst index 56c3b2ab9..9a212f6ab 100644 --- a/docs/guide/annotation.rst +++ b/docs/guide/annotation.rst @@ -9,3 +9,7 @@ Extracting features from text Annotating Datasets ------------------- + +References +---------- +.. footbibliography:: diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst index 0cd9ad734..155bcd260 100644 --- a/docs/guide/cbma.rst +++ b/docs/guide/cbma.rst @@ -14,6 +14,36 @@ rather than uploading unthresholded statistical maps to a database, like NeuroVa :ref:`sphx_glr_auto_examples_02_meta-analyses_01_plot_cbma.py`, and :ref:`sphx_glr_auto_examples_02_meta-analyses_05_plot_correctors.py`. +Types of CBMA studies +--------------------- +1. One large dataset, with multiple subsets. + + 1. Create a single, large Dataset with annotations indicating the subsets. + 2. Perform a meta-analysis on the full Dataset. + + - This omnibus analysis is typically interpreted as evaluating convergent results across the subsets. + + 3. Slice the Dataset into different subsets. + 4. Perform a meta-analysis on each subset. + 5. Perform a subtraction analysis between each subset and the rest of the subsets (combined in one Dataset). + 6. Perform functional decoding comparing something and something. + 7. Plot significant results. + +2. A direct comparison between two datasets. + + 1. Create two Dataset objects. + 2. Perform a meta-analysis on each Dataset. + 3. Perform a subtraction analysis comparing the two Datasets. + 4. Perform a conjunction analysis assessing convergence between the two meta-analyses. + 5. Run FociCounter on all meta-analysis results. + 6. Plot significant results. + +3. Large-scale analyses on a database. + + 1. Download Neurosynth or NeuroQuery. + 2. ... + 3. Plot significant results. + Selecting studies for a meta-analysis ------------------------------------- @@ -36,3 +66,7 @@ Saving the results Performing additional followup analyses --------------------------------------- + +References +---------- +.. footbibliography:: diff --git a/docs/guide/data.rst b/docs/guide/data.rst index 591c715e6..a6093f135 100644 --- a/docs/guide/data.rst +++ b/docs/guide/data.rst @@ -15,3 +15,7 @@ The Dataset object .. literalinclude:: ../../examples/01_datasets/01_plot_dataset_io.py :start-after: # Now we can load and save the Dataset object :end-before: os.remove("pain_dset.pkl") # cleanup + +References +---------- +.. footbibliography:: diff --git a/docs/guide/decoding.rst b/docs/guide/decoding.rst index a87263f58..76d22a528 100644 --- a/docs/guide/decoding.rst +++ b/docs/guide/decoding.rst @@ -2,9 +2,17 @@ Meta-Analytic Functional Decoding ================================= Decoding ROIs +------------- Decoding VOIs +------------- Decoding based on arbitrary subsets of the Dataset +-------------------------------------------------- Decoding statistical maps +------------------------- + +References +---------- +.. footbibliography:: diff --git a/docs/guide/ibma.rst b/docs/guide/ibma.rst index dddb4667b..9a27cbe38 100644 --- a/docs/guide/ibma.rst +++ b/docs/guide/ibma.rst @@ -1,6 +1,13 @@ Image-Based Meta-Analysis ============================== +Types of IBMA studies +--------------------- +1. A manually-curated set of statistical maps. + 1. Perform image-based meta-analysis. The choice of algorithm depends on the data available. + 2. Plot significant results. + 3. Characterize results in a table. + Selecting studies for a meta-analysis ------------------------------------- @@ -18,3 +25,7 @@ Saving the results Performing additional followup analyses --------------------------------------- + +References +---------- +.. footbibliography:: diff --git a/docs/guide/introduction.rst b/docs/guide/introduction.rst index 8e11fef13..71dbf449c 100644 --- a/docs/guide/introduction.rst +++ b/docs/guide/introduction.rst @@ -17,3 +17,7 @@ If you have identified a bug in NiMARE, or would like to request a new feature o you can `open an issue `_ on GitHub. Please look through `open issues `_ before opening a new one, to ensure that you are not duplicating an existing issue. + +References +---------- +.. footbibliography:: From be5a469dc533e8e1f4f253a374e4079ec35be864 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 18 Jul 2022 16:15:13 -0400 Subject: [PATCH 09/16] [skip ci] Add objects dataset. --- docs/guide/cbma.rst | 10 + docs/references.bib | 25 +++ .../08_plot_cbma_subtraction_conjunction.py | 125 +++++++----- ...ge_children.txt => Enge2021_knowledge.txt} | 0 nimare/resources/Enge2021_objects_mni.txt | 85 +++++++++ .../resources/Enge2021_objects_talairach.txt | 179 ++++++++++++++++++ ..._children.txt => Enge2021_relatedness.txt} | 0 7 files changed, 381 insertions(+), 43 deletions(-) rename nimare/resources/{semantic_knowledge_children.txt => Enge2021_knowledge.txt} (100%) create mode 100644 nimare/resources/Enge2021_objects_mni.txt create mode 100644 nimare/resources/Enge2021_objects_talairach.txt rename nimare/resources/{semantic_relatedness_children.txt => Enge2021_relatedness.txt} (100%) diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst index 155bcd260..4ccf9eab1 100644 --- a/docs/guide/cbma.rst +++ b/docs/guide/cbma.rst @@ -30,6 +30,15 @@ Types of CBMA studies 7. Plot significant results. 2. A direct comparison between two datasets. + .. note:: + One conundrum meta-analysts often face is that papers may report a mixture of + within-group analyses and between-group analyses. + For example, if you are planning to perform a meta-analysis of the n-back task with the + comparison between 3-back and 1-back conditions, + you will likely find many papers that report both 3-back > control and 1-back > control results, + as well as many papers that only report 3-back > 1-back results. + + In the case of the 1. Create two Dataset objects. 2. Perform a meta-analysis on each Dataset. @@ -49,6 +58,7 @@ Selecting studies for a meta-analysis Organizing the dataset in NiMARE -------------------------------- +NiMARE contains several functions for Performing the meta-analysis ---------------------------- diff --git a/docs/references.bib b/docs/references.bib index c7f681f96..80a255a92 100644 --- a/docs/references.bib +++ b/docs/references.bib @@ -221,6 +221,18 @@ @article{langner2014meta doi={10.1016/j.neuroimage.2014.06.007} } +@article{muller2018ten, + title={Ten simple rules for neuroimaging meta-analysis}, + author={M{\"u}ller, Veronika I and Cieslik, Edna C and Laird, Angela R and Fox, Peter T and Radua, Joaquim and Mataix-Cols, David and Tench, Christopher R and Yarkoni, Tal and Nichols, Thomas E and Turkeltaub, Peter E and others}, + journal={Neuroscience \& Biobehavioral Reviews}, + volume={84}, + pages={151--161}, + year={2018}, + publisher={Elsevier}, + doi={10.1016/j.neubiorev.2017.11.012}, + url={https://doi.org/10.1016/j.neubiorev.2017.11.012} +} + @article{newman2009distributed, title={Distributed algorithms for topic models.}, author={Newman, David and Asuncion, Arthur and Smyth, Padhraic and Welling, Max}, @@ -292,6 +304,19 @@ @article{Salo2022 journal = {NeuroLibre} } +@article{samartsidis2017coordinate, + title={The coordinate-based meta-analysis of neuroimaging data}, + author={Samartsidis, Pantelis and Montagna, Silvia and Nichols, Thomas E and Johnson, Timothy D}, + journal={Statistical science: a review journal of the Institute of Mathematical Statistics}, + volume={32}, + number={4}, + pages={580}, + year={2017}, + publisher={NIH Public Access}, + doi={10.1214/17-STS624}, + url={https://doi.org/10.1214/17-STS624} +} + @article{shaffer1995multiple, title={Multiple hypothesis testing}, author={Shaffer, Juliet Popper}, diff --git a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py index 483f7652e..bcf58a866 100644 --- a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py +++ b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py @@ -19,10 +19,6 @@ 5. Compare the two samples with a subtraction analysis. 6. Compare the two within-sample meta-analyses with a conjunction analysis. """ -import os - -import matplotlib.pyplot as plt -from nilearn.plotting import plot_stat_map ############################################################################### # Load Sleuth text files into Datasets @@ -33,33 +29,53 @@ # (e.g., correctly naming an object after hearing its auditory description) # while a second group of studies asked children to decide if two (or more) # words were semantically related to one another or not. +import os + from nimare.io import convert_sleuth_to_dataset from nimare.utils import get_resource_path -knowledge_file = os.path.join(get_resource_path(), "semantic_knowledge_children.txt") -related_file = os.path.join(get_resource_path(), "semantic_relatedness_children.txt") +knowledge_file = os.path.join(get_resource_path(), "Enge2021_knowledge.txt") +related_file = os.path.join(get_resource_path(), "Enge2021_relatedness.txt") +# Some papers reported MNI coordinates +objects_file_mni = os.path.join(get_resource_path(), "Enge2021_objects_mni.txt") +# Other papers reported Talairach coordinates +objects_file_talairach = os.path.join(get_resource_path(), "Enge2021_objects_talairach.txt") knowledge_dset = convert_sleuth_to_dataset(knowledge_file) related_dset = convert_sleuth_to_dataset(related_file) +objects_dset = convert_sleuth_to_dataset( + [ + objects_file_mni, + objects_file_talairach, # NiMARE will automatically convert the Talairach foci to MNI + ] +) ############################################################################### -# Individual group ALEs +# View the contents of one of the Sleuth files +with open(knowledge_file, "r") as fo: + sleuth_file_contents = fo.readlines() + +sleuth_file_contents = sleuth_file_contents[:20] +print("\n".join(sleuth_file_contents)) + +############################################################################### +# Meta-analysis of semantic knowledge experiments # ----------------------------------------------------------------------------- -# Computing separate ALE analyses for each group is not strictly necessary for -# performing the subtraction analysis but will help the experimenter to appreciate the -# similarities and differences between the groups. from nimare.correct import FWECorrector from nimare.meta.cbma import ALE ale = ALE(null_method="approximate") knowledge_results = ale.fit(knowledge_dset) -related_results = ale.fit(related_dset) +# Perform Monte Carlo-based multiple comparisons correction corr = FWECorrector(method="montecarlo", voxel_thresh=0.001, n_iters=100, n_cores=2) knowledge_corrected_results = corr.transform(knowledge_results) -related_corrected_results = corr.transform(related_results) -fig, axes = plt.subplots(figsize=(12, 10), nrows=2) +############################################################################### +# Plot the resulting statistical map +# ````````````````````````````````````````````````````````````````````````````` +from nilearn.plotting import plot_stat_map + knowledge_img = knowledge_corrected_results.get_map( "z_desc-size_level-cluster_corr-FWE_method-montecarlo" ) @@ -71,10 +87,37 @@ threshold=2.326, # cluster-level p < .01, one-tailed cmap="RdBu_r", vmax=4, - axes=axes[0], - figure=fig, ) +############################################################################### +# Characterize the relative contributions of experiments in the results +# ````````````````````````````````````````````````````````````````````````````` +# NiMARE contains two methods for this: :class:`~nimare.diagnostics.Jackknife` +# and :class:`~nimare.diagnostics.FocusCounter`. +# We will show both below, but for the sake of speed we will only apply one to +# each subgroup meta-analysis. +from nimare.diagnostics import Jackknife + +jackknife = Jackknife( + target_image="z_desc-size_level-cluster_corr-FWE_method-montecarlo", + voxel_thresh=None, +) +knowledge_jackknife_table, _ = jackknife.transform(knowledge_corrected_results) +knowledge_jackknife_table + +############################################################################### +# Meta-analysis of semantic relatedness experiments +# ----------------------------------------------------------------------------- +ale = ALE(null_method="approximate") +related_results = ale.fit(related_dset) + +# Perform Monte Carlo-based multiple comparisons correction +corr = FWECorrector(method="montecarlo", voxel_thresh=0.001, n_iters=100, n_cores=2) +related_corrected_results = corr.transform(related_results) + +############################################################################### +# Plot the resulting statistical map +# ````````````````````````````````````````````````````````````````````````````` related_img = related_corrected_results.get_map( "z_desc-size_level-cluster_corr-FWE_method-montecarlo" ) @@ -86,59 +129,55 @@ threshold=2.326, # cluster-level p < .01, one-tailed cmap="RdBu_r", vmax=4, - axes=axes[1], - figure=fig, -) -fig.show() - -############################################################################### -# Characterize the relative contributions of experiments in the ALE results -# ----------------------------------------------------------------------------- -# NiMARE contains two methods for this: :class:`~nimare.diagnostics.Jackknife` -# and :class:`~nimare.diagnostics.FocusCounter`. -# We will show both below, but for the sake of speed we will only apply one to -# each subgroup meta-analysis. -from nimare.diagnostics import FocusCounter - -counter = FocusCounter( - target_image="z_desc-size_level-cluster_corr-FWE_method-montecarlo", - voxel_thresh=None, ) -knowledge_count_table, _ = counter.transform(knowledge_corrected_results) -knowledge_count_table.head(10) ############################################################################### -from nimare.diagnostics import Jackknife - +# Characterize the relative contributions of experiments in the results +# ````````````````````````````````````````````````````````````````````````````` jackknife = Jackknife( target_image="z_desc-size_level-cluster_corr-FWE_method-montecarlo", voxel_thresh=None, ) related_jackknife_table, _ = jackknife.transform(related_corrected_results) -related_jackknife_table.head(10) +related_jackknife_table ############################################################################### -# Subtraction analysis +# Compare semantic knowledge to the other conditions with subtraction analysis # ----------------------------------------------------------------------------- -# Typically, one would use at least 10000 iterations for a subtraction analysis. -# However, we have reduced this to 100 iterations for this example. +# The semantic knowledge experiments can be compared to the experiments from +# the other two conditions by first merging the other two sets of experiments +# into a single Dataset, and then performing a subtraction analysis between the +# semantic knowledge Dataset and the new semantic relatedness/objects Dataset. +# +# In :footcite:t:`enge2021meta`, additional subtraction analyses were performed +# for semantic relatedness vs. (knowledge + objects) and semantic objects vs. +# (knowledge + relatedness). +# However, for the sake of executing this example online, we only perform the +# first of these analyses. +# +# .. important:: +# Typically, one would use at least 10000 iterations for a subtraction analysis. +# However, we have reduced this to 100 iterations for this example. from nimare.meta.cbma import ALESubtraction +# First, we combine the relatedness and objects Datasets +related_and_objects_dset = related_dset.merge(objects_dset) + sub = ALESubtraction(n_iters=100, n_cores=1) -res_sub = sub.fit(knowledge_dset, related_dset) +res_sub = sub.fit(knowledge_dset, related_and_objects_dset) img_sub = res_sub.get_map("z_desc-group1MinusGroup2") plot_stat_map( img_sub, cut_coords=4, display_mode="z", - title="Subtraction", + title="Knowledge > Other", cmap="RdBu_r", vmax=4, ) ############################################################################### -# Conjunction analysis +# Evaluate convergence across datasets with a conjunction analysis # ----------------------------------------------------------------------------- # To determine the overlap of the meta-analytic results, a conjunction image # can be computed by (a) identifying voxels that were statistically significant diff --git a/nimare/resources/semantic_knowledge_children.txt b/nimare/resources/Enge2021_knowledge.txt similarity index 100% rename from nimare/resources/semantic_knowledge_children.txt rename to nimare/resources/Enge2021_knowledge.txt diff --git a/nimare/resources/Enge2021_objects_mni.txt b/nimare/resources/Enge2021_objects_mni.txt new file mode 100644 index 000000000..93ffcbb04 --- /dev/null +++ b/nimare/resources/Enge2021_objects_mni.txt @@ -0,0 +1,85 @@ +// Reference=MNI +// dekker2014pw: 9-10 year olds +// Subjects=10 +-28 -82 14 +50 -60 -8 +24 -68 56 +-48 -64 -12 +-38 26 18 +-26 -52 -14 +-44 6 28 +18 -94 8 +46 -76 -2 +-20 -88 10 + +// dekker2014pw: 7-8 year olds +// Subjects=11 +-36 -52 52 +30 -78 16 +-48 -64 -8 +52 -60 -18 +-50 6 26 +-24 -12 50 +18 -94 6 + +// liebig2017nd +// Subjects=41 +26 -96 -4 +38 -92 -6 +-27 -98 -8 +-33 -90 -8 +-42 -52 -18 +-51 -38 6 +-30 -62 42 +-39 6 30 +-51 30 18 +-51 22 28 +-4 20 52 +33 22 -4 +36 32 -6 +9 -82 -26 +-8 -81 -27 + +// monsalvo2012cn +// Subjects=23 +30 -45 -9 +30 -63 -6 +33 -81 9 +-27 -48 -9 +-27 -90 9 +-24 -84 -9 +39 -51 -15 +42 -81 -9 +-39 -60 -15 +-39 -84 -3 + +// okamoto2017ad +// Subjects=12 +-50 -68 0 +54 -74 0 +-48 -24 36 +32 -48 58 +42 52 -18 +4 -56 28 +42 20 -32 +-22 -8 -14 +18 -6 -12 +40 -72 38 + +// passarotti2003td +// Subjects=12 +38 −40 −17 +−40 −40 −17 +58 −40 −9 +−58 40 −9 +50 −53 −17 +−52 −56 −17 +−58 −7 5 +−40 −20 −4 +−1 −25 24 +29 −35 42 +−24 −33 51 +−4 39 53 +−39 3 55 +5 19 −19 +60 21 20 diff --git a/nimare/resources/Enge2021_objects_talairach.txt b/nimare/resources/Enge2021_objects_talairach.txt new file mode 100644 index 000000000..01a77b37a --- /dev/null +++ b/nimare/resources/Enge2021_objects_talairach.txt @@ -0,0 +1,179 @@ +// Reference=Talairach +// aylward2005ba +// Subjects=11 +43 -44 -10 +-40 -66 -9 +39 -59 -8 +36 -68 9 +-49 -20 3 +7 13 46 + +// corbett2008af +// Subjects=15 +36 -56 19 +19 -8 -5 +-30 -78 -20 +23 -86 -20 + +// kersey2016do +// Subjects=29 +20 -70 -33 +-20 49 26 +-6 60 17 +-21 -21 58 +17 55 30 +6 61 16 +60 2 7 +53 31 5 +2 58 33 +-46 -8 -22 +-52 -11 -27 +-28 -28 -18 +-31 -15 -19 +31 -14 -25 +-20 -88 23 +16 -85 13 +-47 -69 -4 +32 -49 -6 +-43 -41 60 +23 -48 55 +-55 -23 28 +34 -4 1 +-43 -20 12 +-39 6 -27 +-40 -22 9 +-46 -2 -13 +-46 10 -24 +61 -11 12 +59 11 -4 +65 -14 -3 + +// libertus2008dc +// Subjects=15 +41 -53 -21 +15 -101 -7 +23 -98 -14 +-26 -86 -14 +-19 -90 -14 +-19 -98 -7 +4 41 -7 +4 19 -7 +-4 45 0 +-45 -53 -28 +-41 -49 -21 +8 -56 21 + + +// scherf2007vc: Adolscents +// Subjects=10 +39 -47 -22 +45 -74 1 +60 -49 9 +55 -4 -16 +10 -59 28 +-39 -70 18 +-47 17 -8 +39 25 -9 +5 54 44 +-6 -4 57 +-5 46 -12 +42 -9 50 +21 -2 54 +26 -66 46 +-11 -67 50 +28 -79 8 +-27 -85 19 +45 -55 -8 +-45 -60 -5 +18 -87 -6 +-13 -89 -5 +26 -40 -4 +-25 -48 -1 +-22 -73 53 +32 -52 51 +-14 -95 12 +-54 -34 33 +40 -60 -7 +-41 -57 -3 +11 -81 -3 +22 -73 -18 +-27 -73 -14 +33 -88 2 +-34 -5 32 + +// scherf2007vc: Children +// Subjects=10 +42 -68 -19 +-15 56 5 +14 -80 38 +-14 -76 51 +6 -41 25 +29 -75 31 +-22 -79 13 +21 -85 -5 +-22 -85 -3 +13 -86 -6 +-19 -94 -5 +19 -30 -18 +-28 -53 -6 +29 -53 49 +-21 -59 43 +-23 -82 37 +31 -70 20 +18 -94 -5 +-23 -86 28 +-9 -97 -15 +41 -72 -12 +-40 -60 -17 +22 -39 -14 +-21 -79 -24 + +// scherf2010ll (46) +// Subjects=10 +40 -41 -23 +-39 -51 -19 +50 -61 9 +55 -50 12 +49 -58 12 +-63 -30 -7 +-41 21 -31 +-39 -60 38 +-1 57 28 +-6 42 -4 +8 43 53 +21 20 49 +5 53 46 +0 35 53 +31 58 9 +-16 28 55 +-18 35 43 +-2 63 8 +33 3 34 +-45 6 51 +-48 28 -5 +-34 -73 -41 +26 -42 -8 +-24 -45 -8 +16 -84 -7 +-5 -87 -3 +30 -76 21 +-22 -82 18 +20 -67 58 +-9 -68 56 +62 -15 25 +58 6 25 +-31 13 12 +-39 31 15 +41 -61 -11 +-41 -66 -7 +23 -62 -12 +-24 -63 -12 +7 -81 0 +31 -80 7 +-22 -85 7 +34 -48 55 +-30 -54 53 +-55 -30 37 +59 -18 27 +-45 -31 21 +-44 30 17 diff --git a/nimare/resources/semantic_relatedness_children.txt b/nimare/resources/Enge2021_relatedness.txt similarity index 100% rename from nimare/resources/semantic_relatedness_children.txt rename to nimare/resources/Enge2021_relatedness.txt From 18754565c2ef6b6b0a709d84018b2e45c0b2eacd Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 18 Jul 2022 16:22:50 -0400 Subject: [PATCH 10/16] [skip ci] Test objects too. --- .../08_plot_cbma_subtraction_conjunction.py | 44 ++++++++++++++++++- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py index bcf58a866..03a8aa970 100644 --- a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py +++ b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py @@ -141,6 +141,42 @@ related_jackknife_table, _ = jackknife.transform(related_corrected_results) related_jackknife_table +############################################################################### +# Meta-analysis of semantic object experiments +# ----------------------------------------------------------------------------- +ale = ALE(null_method="approximate") +objects_results = ale.fit(objects_dset) + +# Perform Monte Carlo-based multiple comparisons correction +corr = FWECorrector(method="montecarlo", voxel_thresh=0.001, n_iters=100, n_cores=2) +objects_corrected_results = corr.transform(objects_results) + +############################################################################### +# Plot the resulting statistical map +# ````````````````````````````````````````````````````````````````````````````` +objects_img = objects_corrected_results.get_map( + "z_desc-size_level-cluster_corr-FWE_method-montecarlo" +) +plot_stat_map( + objects_img, + cut_coords=4, + display_mode="z", + title="Semantic relatedness", + threshold=2.326, # cluster-level p < .01, one-tailed + cmap="RdBu_r", + vmax=4, +) + +############################################################################### +# Characterize the relative contributions of experiments in the results +# ````````````````````````````````````````````````````````````````````````````` +jackknife = Jackknife( + target_image="z_desc-size_level-cluster_corr-FWE_method-montecarlo", + voxel_thresh=None, +) +objects_jackknife_table, _ = jackknife.transform(objects_corrected_results) +objects_jackknife_table + ############################################################################### # Compare semantic knowledge to the other conditions with subtraction analysis # ----------------------------------------------------------------------------- @@ -188,8 +224,12 @@ # :func:`nilearn.image.math_img`. from nilearn.image import math_img -formula = "np.where(img1 * img2 > 0, np.minimum(img1, img2), 0)" -img_conj = math_img(formula, img1=knowledge_img, img2=related_img) +img_conj = math_img( + "np.where((img1 * img2 * img3) > 0, np.minimum(img1, np.minimum(img2, img3)), 0)", + img1=knowledge_img, + img2=related_img, + img3=objects_img, +) plot_stat_map( img_conj, From 16ad3e56cda38fa2c56e205d74397c67e3b80bc5 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 18 Jul 2022 16:36:58 -0400 Subject: [PATCH 11/16] [skip ci] Fix dataset. --- nimare/resources/Enge2021_objects_mni.txt | 30 +++++++++++------------ 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/nimare/resources/Enge2021_objects_mni.txt b/nimare/resources/Enge2021_objects_mni.txt index 93ffcbb04..51e09ac26 100644 --- a/nimare/resources/Enge2021_objects_mni.txt +++ b/nimare/resources/Enge2021_objects_mni.txt @@ -68,18 +68,18 @@ // passarotti2003td // Subjects=12 -38 −40 −17 -−40 −40 −17 -58 −40 −9 -−58 40 −9 -50 −53 −17 -−52 −56 −17 -−58 −7 5 -−40 −20 −4 -−1 −25 24 -29 −35 42 -−24 −33 51 -−4 39 53 -−39 3 55 -5 19 −19 -60 21 20 +38 -40 -17 +-40 -40 -17 +58 -40 -9 +-58 40 -9 +50 -53 -17 +-52 -56 -17 +-58 -7 5 +-40 -20 -4 +-1 -25 24 +29 -35 42 +-24 -33 51 +-4 39 53 +-39 3 55 +5 19 -19 +60 21 20 From 73abc94292976cae8cd1013eb2870401fe86300c Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Tue, 19 Jul 2022 10:11:27 -0400 Subject: [PATCH 12/16] [skip ci] more stuff --- docs/guide/cbma.rst | 36 +++++++++++++++---- .../08_plot_cbma_subtraction_conjunction.py | 15 ++++++-- 2 files changed, 43 insertions(+), 8 deletions(-) diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst index 4ccf9eab1..becbcfaaa 100644 --- a/docs/guide/cbma.rst +++ b/docs/guide/cbma.rst @@ -38,14 +38,17 @@ Types of CBMA studies you will likely find many papers that report both 3-back > control and 1-back > control results, as well as many papers that only report 3-back > 1-back results. - In the case of the + In the case of the former, the standard approach is to perform a subtraction analysis. + In the latter case, you would perform a single univariate meta-analysis. + Unfortunately, you cannot combine the two sets of results. 1. Create two Dataset objects. 2. Perform a meta-analysis on each Dataset. 3. Perform a subtraction analysis comparing the two Datasets. 4. Perform a conjunction analysis assessing convergence between the two meta-analyses. - 5. Run FociCounter on all meta-analysis results. - 6. Plot significant results. + 5. Run :class:`~nimare.diagnostics.FociCounter` or :class:`~nimare.diagnostics.Jackknife` on all meta-analysis results. + 6. Run :func:`~nilearn.reporting.get_clusters_table` on all meta-analysis results. + 7. Plot significant results. 3. Large-scale analyses on a database. @@ -58,25 +61,46 @@ Selecting studies for a meta-analysis Organizing the dataset in NiMARE -------------------------------- -NiMARE contains several functions for +NiMARE contains several functions for converting common formats to Dataset objects. Performing the meta-analysis ---------------------------- -.. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_01_plot_cbma_001.png - :target: ../auto_examples/02_meta-analyses/01_plot_cbma.ipynb +.. literalinclude:: ../../examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py + :start-at: from nimare.meta.cbma import ALE + :end-at: knowledge_results = ale.fit(knowledge_dset) + +.. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_06_plot_compare_ibma_and_cbma_001.png + :target: ../auto_examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.ipynb :align: center :scale: 100 Multiple comparisons correction ------------------------------- +.. literalinclude:: ../../examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py + :start-at: from nimare.correct import FWECorrector + :end-at: knowledge_corrected_results = corr.transform(knowledge_results) + +.. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_06_plot_compare_ibma_and_cbma_002.png + :target: ../auto_examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.ipynb + :align: center + :scale: 100 + Saving the results ------------------ +.. literalinclude:: ../../examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py + :start-at: knowledge_corrected_results.save_maps( + :end-at: ) + Performing additional followup analyses --------------------------------------- +.. literalinclude:: ../../examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py + :start-at: from nimare.diagnostics import Jackknife + :end-at: knowledge_jackknife_table + References ---------- .. footbibliography:: diff --git a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py index 03a8aa970..585c4347c 100644 --- a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py +++ b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py @@ -61,13 +61,16 @@ ############################################################################### # Meta-analysis of semantic knowledge experiments # ----------------------------------------------------------------------------- -from nimare.correct import FWECorrector from nimare.meta.cbma import ALE ale = ALE(null_method="approximate") knowledge_results = ale.fit(knowledge_dset) -# Perform Monte Carlo-based multiple comparisons correction +############################################################################### +# Multiple comparisons correction with a Monte Carlo procedure +# ----------------------------------------------------------------------------- +from nimare.correct import FWECorrector + corr = FWECorrector(method="montecarlo", voxel_thresh=0.001, n_iters=100, n_cores=2) knowledge_corrected_results = corr.transform(knowledge_results) @@ -89,6 +92,14 @@ vmax=4, ) +############################################################################### +# Save the results to disk +# ````````````````````````````````````````````````````````````````````````````` +knowledge_corrected_results.save_maps( + out_dir=".", + prefix="Enge2021_knowledge", +) + ############################################################################### # Characterize the relative contributions of experiments in the results # ````````````````````````````````````````````````````````````````````````````` From eee61766f87befbec6fe7674bc5382a699a4b71f Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Tue, 19 Jul 2022 10:21:34 -0400 Subject: [PATCH 13/16] [skip ci] Fix. --- .../02_meta-analyses/08_plot_cbma_subtraction_conjunction.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py index 585c4347c..b0a031248 100644 --- a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py +++ b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py @@ -96,7 +96,7 @@ # Save the results to disk # ````````````````````````````````````````````````````````````````````````````` knowledge_corrected_results.save_maps( - out_dir=".", + output_dir=".", prefix="Enge2021_knowledge", ) From 86361572ffb503dd930f2b01df282a158f8fc7fc Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Tue, 19 Jul 2022 12:01:52 -0400 Subject: [PATCH 14/16] [skip ci] more improvements --- docs/guide/cbma.rst | 10 +++--- .../08_plot_cbma_subtraction_conjunction.py | 32 ++++++++++++++++--- 2 files changed, 32 insertions(+), 10 deletions(-) diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst index becbcfaaa..090dc3242 100644 --- a/docs/guide/cbma.rst +++ b/docs/guide/cbma.rst @@ -46,7 +46,7 @@ Types of CBMA studies 2. Perform a meta-analysis on each Dataset. 3. Perform a subtraction analysis comparing the two Datasets. 4. Perform a conjunction analysis assessing convergence between the two meta-analyses. - 5. Run :class:`~nimare.diagnostics.FociCounter` or :class:`~nimare.diagnostics.Jackknife` on all meta-analysis results. + 5. Run :class:`~nimare.diagnostics.FocusCounter` or :class:`~nimare.diagnostics.Jackknife` on all meta-analysis results. 6. Run :func:`~nilearn.reporting.get_clusters_table` on all meta-analysis results. 7. Plot significant results. @@ -70,8 +70,8 @@ Performing the meta-analysis :start-at: from nimare.meta.cbma import ALE :end-at: knowledge_results = ale.fit(knowledge_dset) -.. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_06_plot_compare_ibma_and_cbma_001.png - :target: ../auto_examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.ipynb +.. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_08_plot_cbma_subtraction_conjunction_001.png + :target: ../auto_examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.html :align: center :scale: 100 @@ -82,8 +82,8 @@ Multiple comparisons correction :start-at: from nimare.correct import FWECorrector :end-at: knowledge_corrected_results = corr.transform(knowledge_results) -.. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_06_plot_compare_ibma_and_cbma_002.png - :target: ../auto_examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.ipynb +.. figure:: ../auto_examples/02_meta-analyses/images/sphx_glr_08_plot_cbma_subtraction_conjunction_002.png + :target: ../auto_examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.html :align: center :scale: 100 diff --git a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py index b0a031248..e1581d17c 100644 --- a/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py +++ b/examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.py @@ -56,7 +56,7 @@ sleuth_file_contents = fo.readlines() sleuth_file_contents = sleuth_file_contents[:20] -print("\n".join(sleuth_file_contents)) +print("".join(sleuth_file_contents)) ############################################################################### # Meta-analysis of semantic knowledge experiments @@ -67,18 +67,40 @@ knowledge_results = ale.fit(knowledge_dset) ############################################################################### +# Plot the uncorrected statistical map +# ````````````````````````````````````````````````````````````````````````````` +from nilearn.plotting import plot_stat_map + +plot_stat_map( + knowledge_results.get_map("z"), + cut_coords=4, + display_mode="z", + title="Semantic knowledge", + threshold=2.326, # cluster-level p < .01, one-tailed + cmap="RdBu_r", + vmax=4, +) + +############################################################################### +# This z-statistic map is not corrected for multiple comparisons. +# In order to account for the many voxel-wise tests that are performed in +# parallel, we must apply some type of multiple comparisons correction. +# To that end, we will use an :class:`~nimare.correct.FWECorrector` with the +# Monte Carlo method. +# # Multiple comparisons correction with a Monte Carlo procedure # ----------------------------------------------------------------------------- +# We will use the cluster-level corrected map, using a cluster-defining +# threshold of p < 0.001 and 100 iterations. +# In the actual paper, :footcite:`enge2021meta` used 10000 iterations instead. from nimare.correct import FWECorrector corr = FWECorrector(method="montecarlo", voxel_thresh=0.001, n_iters=100, n_cores=2) knowledge_corrected_results = corr.transform(knowledge_results) ############################################################################### -# Plot the resulting statistical map +# Plot the corrected statistical map # ````````````````````````````````````````````````````````````````````````````` -from nilearn.plotting import plot_stat_map - knowledge_img = knowledge_corrected_results.get_map( "z_desc-size_level-cluster_corr-FWE_method-montecarlo" ) @@ -172,7 +194,7 @@ objects_img, cut_coords=4, display_mode="z", - title="Semantic relatedness", + title="Semantic objects", threshold=2.326, # cluster-level p < .01, one-tailed cmap="RdBu_r", vmax=4, From d63537cde1097d6492b9e5febb2d6a8d4d0c82b2 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Tue, 19 Jul 2022 13:26:54 -0400 Subject: [PATCH 15/16] [skip ci] update --- docs/guide/cbma.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guide/cbma.rst b/docs/guide/cbma.rst index 090dc3242..fd82d9a9e 100644 --- a/docs/guide/cbma.rst +++ b/docs/guide/cbma.rst @@ -2,7 +2,7 @@ Coordinate-Based Meta-Analysis ============================== Coordinate-based meta-analysis (CBMA) is a popular tool for measuring consistency across neuroimaging studies. -While :ref:`ibma.rst` leverage more information than CBMA, and is thus superior, +While :ref:`ibma` techniques leverage more information than CBMA, and are thus superior, CBMA is much more popular because the majority of fMRI papers report peaks from significant clusters in tables, rather than uploading unthresholded statistical maps to a database, like NeuroVault. @@ -30,6 +30,7 @@ Types of CBMA studies 7. Plot significant results. 2. A direct comparison between two datasets. + .. note:: One conundrum meta-analysts often face is that papers may report a mixture of within-group analyses and between-group analyses. From 67c82c9d568bf1c713bcf6af59939ba4cc208559 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Thu, 4 Aug 2022 10:10:18 -0400 Subject: [PATCH 16/16] Update data.rst --- docs/guide/data.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/guide/data.rst b/docs/guide/data.rst index a6093f135..4ee5de441 100644 --- a/docs/guide/data.rst +++ b/docs/guide/data.rst @@ -1,6 +1,9 @@ Working with Meta-Analytic Data =============================== +The Neuroimaging Meta-Analysis Data Standard (NIMADS) +----------------------------------------------------- + Downloading large databases ---------------------------