Start drafting user guide

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
 `````````````````````````````````````````````````````
 

docs/conf.py

@@ -174,7 +174,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),
 }

docs/guide/annotation.rst

@@ -0,0 +1,15 @@
+Annotating Meta-Analytic Data
+==============================
+
+Downloading abstracts for papers
+--------------------------------
+
+Extracting features from text
+-----------------------------
+
+Annotating Datasets
+-------------------
+
+References
+----------
+.. footbibliography::

docs/guide/cbma.rst

@@ -0,0 +1,107 @@
+Coordinate-Based Meta-Analysis
+==============================
+
+Coordinate-based meta-analysis (CBMA) is a popular tool for measuring consistency across neuroimaging studies.
+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.
+
+.. 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_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_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.
+
+    .. 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 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 :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.
+
+3. Large-scale analyses on a database.
+
+    1. Download Neurosynth or NeuroQuery.
+    2. ...
+    3. Plot significant results.
+
+Selecting studies for a meta-analysis
+-------------------------------------
+
+Organizing the dataset in NiMARE
+--------------------------------
+NiMARE contains several functions for converting common formats to Dataset objects.
+
+Performing the meta-analysis
+----------------------------
+
+.. 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_08_plot_cbma_subtraction_conjunction_001.png
+    :target: ../auto_examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.html
+    :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_08_plot_cbma_subtraction_conjunction_002.png
+    :target: ../auto_examples/02_meta-analyses/08_plot_cbma_subtraction_conjunction.html
+    :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::

docs/guide/data.rst

@@ -0,0 +1,24 @@
+Working with Meta-Analytic Data
+===============================
+
+The Neuroimaging Meta-Analysis Data Standard (NIMADS)
+-----------------------------------------------------
+
+Downloading large databases
+---------------------------
+
+Converting datasets from BrainMap
+---------------------------------
+
+The Dataset object
+------------------
+
+: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
+    :end-before: os.remove("pain_dset.pkl")  # cleanup
+
+References
+----------
+.. footbibliography::

docs/guide/decoding.rst

@@ -0,0 +1,18 @@
+Meta-Analytic Functional Decoding
+=================================
+
+Decoding ROIs
+-------------
+
+Decoding VOIs
+-------------
+
+Decoding based on arbitrary subsets of the Dataset
+--------------------------------------------------
+
+Decoding statistical maps
+-------------------------
+
+References
+----------
+.. footbibliography::

docs/guide/ibma.rst

@@ -0,0 +1,31 @@
+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
+-------------------------------------
+
+Organizing the dataset in NiMARE
+--------------------------------
+
+Performing the meta-analysis
+----------------------------
+
+Multiple comparisons correction
+-------------------------------
+
+Saving the results
+------------------
+
+Performing additional followup analyses
+---------------------------------------
+
+References
+----------
+.. footbibliography::

docs/guide/introduction.rst

@@ -0,0 +1,23 @@
+.. include:: ../links.rst
+
+Introduction to NiMARE
+=====================================
+
+Meta-Analysis and Analyses Using Meta-Analytic Data
+---------------------------------------------------
+
+Getting Help
+------------
+
+If you have usage-related questions, please create a new topic on `NeuroStars <https://neurostars.org>`_
+with the `"nimare" tag <https://neurostars.org/tag/nimare>`_.
+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 <https://github.com/neurostuff/NiMARE/issues/new/choose>`_ on GitHub.
+Please look through `open issues <https://github.com/neurostuff/NiMARE/issues>`_ before opening a new one,
+to ensure that you are not duplicating an existing issue.
+
+References
+----------
+.. footbibliography::

docs/guide/toc.rst

@@ -0,0 +1,12 @@
+User Guide
+==========
+
+.. toctree::
+   :numbered:
+
+   introduction.rst
+   data.rst
+   cbma.rst
+   ibma.rst
+   annotation.rst
+   decoding.rst

docs/index.rst

@@ -122,15 +122,16 @@ Then, to cite NiMARE in your manuscript, we recommend something like the followi
 
    about
    installation
+   guide/toc
    api
    auto_examples/index
-   contributing
-   dev_guide
    cli
    outputs
    methods
    changelog
    glossary
+   contributing
+   dev_guide
 
 Indices and tables
 ------------------

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},