Merge branch 'main' into cluster-mass

CONTRIBUTING.md

@@ -90,6 +90,9 @@ Submit a [pull request][link_pullrequest].
 
 A member of the development team will review your changes to confirm that they can be merged into the main codebase.
 
+Please use a sentence-case title for the pull request, and do not include any prefixes (e.g., ``[ENH]``), as we now use labels to distinguish pull request types.
+The title should summarize the changes proposed in the pull request, with an emphasis on readability, as pull request titles are used directly in our release notes.
+
 ## Recognizing contributions
 
 We welcome and recognize all contributions from documentation to testing to code development.

docs/api.rst

@@ -24,6 +24,8 @@ API
 :mod:`nimare.meta`: Meta-analytic algorithms
 --------------------------------------------------
 
+For more information about the components of coordinate-based meta-analysis in NiMARE, see :doc:`cbma`.
+
 .. automodule:: nimare.meta
    :no-members:
    :no-inherited-members:
@@ -121,7 +123,7 @@ API
 
 :mod:`nimare.decode`: Functional characterization analysis
 -----------------------------------------------------------
-For more information about functional characterization analysis, see :ref:`decoding methods`.
+For more information about functional characterization analysis, see :doc:`decoding`.
 
 .. automodule:: nimare.decode
    :no-members:

docs/cbma.rst

@@ -20,10 +20,10 @@ All of the CBMA algorithms currently implemented in NiMARE are `kernel-based` me
 In kernel-based CBMA, coordinates are convolved with some kind of kernel to produce a "modeled activation" map for each experiment in the dataset.
 The modeled activation map acts as a substitute for the original, unthresholded statistical map from which the coordinates were derived.
 The kernel used to create the modeled activation map varies across approaches, but the most common are
-the :class:`ALEKernel<nimare.meta.kernel.ALEKernel>`, which convolves coordinates with a 3D Gaussian distribution,
-and the :class:`MKDAKernel<nimare.meta.kernel.MKDAKernel>`, which creates a binary sphere around each coordinate.
+the :class:`~nimare.meta.kernel.ALEKernel`, which convolves coordinates with a 3D Gaussian distribution,
+and the :class:`~nimare.meta.kernel.MKDAKernel`, which creates a binary sphere around each coordinate.
 
-.. warning::
+.. important::
     While the modeled activation map is an estimate of the original statistical map,
     that doesn't mean that modeled activation maps can actually be used as statistical maps.
     We still need meta-analytic algorithms that are designed for coordinates, rather than images.
@@ -57,15 +57,15 @@ and then comparing the summary statistics from the real Dataset to these "null"
 This method may take a long time, and is only slightly more accurate than the approximate method,
 as long as there are enough iterations.
 
-In general, we would recommend using the approximate method.
+**In general, we recommend using the approximate method.**
 
 Multiple comparisons correction
 -------------------------------
 
 The initial Estimator fit (with the null method of choice) will produce a MetaResult with unthresholded, uncorrected statistical maps.
 These statistical maps shouldn't be thresholded and interpreted on their own, as they don't account for the multiple comparisons issue.
 To correct for multiple comparisons, we have Corrector classes
-(:class:`FWECorrector<nimare.correct.FWECorrector>` and :class:`FDRCorrector<nimare.correct.FDRCorrector>`).
+(:class:`~nimare.correct.FWECorrector` and :class:`~nimare.correct.FDRCorrector`).
 
 These classes ingest MetaResults with uncorrected maps,
 then use the Estimator and Dataset that the MetaResult references to perform multiple comparisons correction.
@@ -79,7 +79,7 @@ These methods can be broadly separated into two groups: generic methods and Esti
 Generic methods rely on tools like ``statsmodels`` to correct the results as an array,
 without accounting for any of the idiosyncrasies of neuroimaging data (e.g., autocorrelation).
 One example of a generic method is the "bonferroni" method for the FWECorrector.
-**We do not recommend using these methods.**
+**We do not recommend using the generic methods.**
 
 Estimator-specific methods are approaches that are implemented within the Estimator as class methods
 that are then called by the Corrector.
@@ -89,7 +89,7 @@ One such method is the Monte Carlo method (``method="montecarlo"``).
 
 The Monte Carlo multiple comparisons correction method
 ``````````````````````````````````````````````````````
-:class:`nimare.correct.FWECorrector`, :meth:`nimare.meta.cbma.base.CBMAEstimator.correct_fwe_montecarlo`
+:class:`~nimare.correct.FWECorrector`, :meth:`~nimare.meta.cbma.base.CBMAEstimator.correct_fwe_montecarlo`
 
 For our CBMA algorithms, we strongly recommend using the "montecarlo" method with the FWECorrector.
 This is the primary Estimator-specific method, which operates by creating simulated versions of the Dataset,

docs/decoding.rst

@@ -1,7 +1,5 @@
 .. include:: links.rst
 
-.. _decoding methods:
-
 Meta-analytic functional decoding
 =================================
 
@@ -60,7 +58,7 @@ should be preferred over the correlation distribution-based decoding.
 
 Correlation-based decoding
 ``````````````````````````````
-:class:`nimare.decode.continuous.CorrelationDecoder`
+:class:`~nimare.decode.continuous.CorrelationDecoder`
 
 The correlation-based decoding is implemented in NiMARE’s `CorrelationDecoder` class object.
 
@@ -79,15 +77,15 @@ The correlation-based decoding is implemented in NiMARE’s `CorrelationDecoder`
 
 Correlation distribution-based decoding
 ``````````````````````````````````````````
-:class:`nimare.decode.continuous.CorrelationDistributionDecoder`
+:class:`~nimare.decode.continuous.CorrelationDistributionDecoder`
 
 The distribution-based decoding is implemented in NiMARE’s ``CorrelationDistributionDecoder``
 class object.
 
 
 The GCLDA approach
 `````````````````````
-:func:`nimare.decode.continuous.gclda_decode_map`
+:func:`~nimare.decode.continuous.gclda_decode_map`
 
 Recently, it was introduced a new decoding framework based on Generalized Correspondence LDA
 (GC-LDA, (`Rubin et al., 2017`_)), an extension to the LDA model. This method, in addition to the
@@ -148,7 +146,7 @@ which are evaluated in terms of both statistical significance and effect size.
 
 The BrainMap approach
 `````````````````````
-:class:`nimare.decode.discrete.BrainMapDecoder`, :func:`nimare.decode.discrete.brainmap_decode`
+:class:`~nimare.decode.discrete.BrainMapDecoder`, :func:`~nimare.decode.discrete.brainmap_decode`
 
 The BrainMap discrete decoding method compares the distributions of studies with each label within
 the sample against those in a larger database while accounting for the number of foci from each
@@ -254,7 +252,7 @@ Example: :ref:`brain-map-decoder-example`
 
 The Neurosynth approach
 ```````````````````````
-:class:`nimare.decode.discrete.NeurosynthDecoder`, :func:`nimare.decode.discrete.neurosynth_decode`
+:class:`~nimare.decode.discrete.NeurosynthDecoder`, :func:`~nimare.decode.discrete.neurosynth_decode`
 
 The implementation of the MKDA Chi-squared meta-analysis method used by Neurosynth is quite
 similar to BrainMap’s method for decoding, if applied to annotations instead of modeled activation
@@ -358,7 +356,7 @@ Example: :ref:`neurosynth-chi2-decoder-example`
 
 The Neurosynth ROI association approach
 ```````````````````````````````````````
-:class:`nimare.decode.discrete.ROIAssociationDecoder`
+:class:`~nimare.decode.discrete.ROIAssociationDecoder`
 
 Neurosynth's ROI association approach is quite simple, but it has been used in at least one
 publication, `Margulies et al. (2016)`_.
@@ -389,7 +387,7 @@ Example: :ref:`neurosynth-roi-decoder-example`
 
 The GC-LDA approach
 ```````````````````
-:func:`nimare.decode.discrete.gclda_decode_roi`
+:func:`~nimare.decode.discrete.gclda_decode_roi`
 
 
 The GC-LDA approach sums :math:`P(topic|voxel)` weights within the region of interest to produce
@@ -399,3 +397,5 @@ Example: :ref:`gclda-decode-roi-example`
 
 Encoding
 --------
+
+TBD

docs/fetching.rst

@@ -4,7 +4,7 @@
 
 Fetching resources from the internet
 ====================================
-:mod:`nimare.extract`
+:mod:`~nimare.extract`
 
 NiMARE's ``extract`` module contains a number of functions for downloading resources
 (e.g., ontologies, images, and datasets) from the internet.
@@ -24,4 +24,4 @@ NiMARE's ``extract`` module contains a number of functions for downloading resou
     to distinguish a global dataset repository that may be read-only at the user-level.
     Note that you can copy that folder to another user's computers to avoid the initial dataset download on the first fetching call.
 
-    You can check in which directory NiMARE will store the data with the function :func:`nimare.extract.utils.get_data_dirs`.
+    You can check in which directory NiMARE will store the data with the function :func:`~nimare.extract.utils.get_data_dirs`.

examples/01_datasets/01_plot_dataset_io.py

@@ -8,7 +8,7 @@
 The NiMARE Dataset object
 =========================
 
-This is a brief walkthrough of the :class:`nimare.dataset.Dataset` class and its methods.
+This is a brief walkthrough of the :class:`~nimare.dataset.Dataset` class and its methods.
 """
 ###############################################################################
 # Start with the necessary imports
@@ -107,7 +107,7 @@
 # Instead, relative paths to image files are retained in the Dataset.images
 # attribute.
 # When loading a Dataset, you will likely need to specify the path to the images.
-# To do this, you can use :func:`nimare.dataset.Dataset.update_path`.
+# To do this, you can use :func:`~nimare.dataset.Dataset.update_path`.
 dset.update_path(dset_dir)
 columns_to_show = ["id", "study_id", "contrast_id", "beta", "beta__relative"]
 dset.images[columns_to_show].head()
@@ -121,8 +121,8 @@
 # For example, ``varcope = t / beta``, so if you have t-statistic images and
 # beta images, you can also calculate varcope (variance) images.
 #
-# We use :mod:`nimare.transforms` to perform these transformations
-# (especially :class:`nimare.transforms.ImageTransformer`)
+# We use the :mod:`~nimare.transforms` module to perform these transformations
+# (especially :class:`~nimare.transforms.ImageTransformer`)
 varcope_transformer = ImageTransformer(target="varcope")
 dset = varcope_transformer.transform(dset)
 dset.images[["id", "varcope"]].head()
@@ -168,6 +168,6 @@
 # to image files, most elements are not.
 # NiMARE Estimators operate on Datasets and return *new*, updated Datasets.
 # If you want to reduce a Dataset based on a subset of the studies in the
-# Dataset, you need to use :func:`nimare.dataset.Dataset.slice`.
+# Dataset, you need to use :meth:`~nimare.dataset.Dataset.slice`.
 sub_dset = dset.slice(ids=sel_studies)
 print("\n".join(sub_dset.ids))

examples/01_datasets/02_download_neurosynth.py

@@ -30,7 +30,7 @@
         )
 
 For information about where these files will be downloaded to on your machine,
-see :ref:`fetching tools`.
+see :doc:`../../fetching`.
 """
 ###############################################################################
 # Start with the necessary imports

examples/01_datasets/03_plot_neurovault_io.py

@@ -89,7 +89,10 @@
 # and plot our results
 from nimare.meta.ibma import Fishers
 
-meta = Fishers()
+# The default template has a slightly different, but completely compatible,
+# affine than the NeuroVault images, so we allow the Estimator to resample
+# images during the fitting process.
+meta = Fishers(resample=True)
 
 meta_res = meta.fit(dset)
 

examples/01_datasets/README.txt

@@ -3,7 +3,7 @@
 Working with datasets
 ---------------------
 
-NiMARE stores meta-analytic data in its :class:`nimare.dataset.Dataset` class.
+NiMARE stores meta-analytic data in its :class:`~nimare.dataset.Dataset` class.
 Dataset objects may contain a range of elements, including coordinates (for coordinate-based meta-analysis),
 links to statistical maps (for image-based meta-analysis), article text, label weights, and other metadata.
 

examples/02_meta-analyses/06_plot_generate_ma_maps.py

@@ -36,7 +36,7 @@
 ###############################################################################
 # Each kernel can taken certain parameters that control behavior
 # --------------------------------------------------------------
-# For example, :class:`nimare.meta.kernel.MKDAKernel` kernel accepts an `r`
+# For example, :class:`~nimare.meta.kernel.MKDAKernel` kernel accepts an `r`
 # argument to control the radius of the kernel.
 
 kernel = MKDAKernel(r=2)
@@ -86,13 +86,13 @@
 ###############################################################################
 # There are several kernels available
 # --------------------------------------------------
-# :class:`nimare.meta.kernel.MKDAKernel` convolves coordinates with a
+# :class:`~nimare.meta.kernel.MKDAKernel` convolves coordinates with a
 # sphere and takes the union across voxels.
 #
-# :class:`nimare.meta.kernel.KDAKernel` convolves coordinates with a
+# :class:`~nimare.meta.kernel.KDAKernel` convolves coordinates with a
 # sphere as well, but takes the *sum* across voxels.
 #
-# :class:`nimare.meta.kernel.ALEKernel` convolves coordinates with a 3D
+# :class:`~nimare.meta.kernel.ALEKernel` convolves coordinates with a 3D
 # Gaussian, for which the FWHM is determined by the sample size of each study.
 kernel = MKDAKernel(r=10)
 mkda_res = kernel.transform(dset, return_type="image")

examples/02_meta-analyses/README.txt

@@ -3,5 +3,8 @@
 Performing meta-analyses
 ------------------------
 
-NiMARE implements a number of coordinate- and image-based meta-analysis algorithms in its :mod:`nimare.meta` module.
+NiMARE implements a number of coordinate- and image-based meta-analysis algorithms in its :mod:`~nimare.meta` module.
 In the examples below, we exhibit a range of meta-analyses that can be done with coordinates and/or images in NiMARE.
+
+For more information about the components that go into coordinate-based meta-analyses in NiMARE, see :doc:`../cbma`,
+as well as :doc:`../outputs`.

examples/03_annotation/README.txt

@@ -3,5 +3,5 @@
 Automated annotation
 --------------------
 
-Annotation tools within NiMARE (:mod:`nimare.annotate`) refer to methods which
+Annotation tools within NiMARE (:mod:`~nimare.annotate`) refer to methods which
 assign labels to studies in a Dataset, generally based on study text.

examples/04_decoding/README.txt

@@ -5,4 +5,4 @@ Functional characterization analysis
 
 Functional characterization analysis refers to methods which use meta-analytic databases to characterize, or "decode",
 brain regions or statistical maps in terms of tasks and/or mental processes.
-For more information about functional characterization analysis, see :ref:`decoding methods`.
+For more information about functional characterization analysis, see :doc:`../decoding`.

nimare/base.py

@@ -286,15 +286,15 @@ def fit(self, dataset, drop_invalid=True):
 
         Parameters
         ----------
-        dataset : :obj:`nimare.dataset.Dataset`
+        dataset : :obj:`~nimare.dataset.Dataset`
             Dataset object to analyze.
         drop_invalid : :obj:`bool`, optional
             Whether to automatically ignore any studies without the required data or not.
             Default is False.
 
         Returns
         -------
-        :obj:`nimare.results.MetaResult`
+        :obj:`~nimare.results.MetaResult`
             Results of Estimator fitting.
 
         Attributes
@@ -332,7 +332,7 @@ def _fit(self, dataset):
 
 
 class MetaEstimator(Estimator):
-    """Base class for meta-analysis methods in :mod:`nimare.meta`.
+    """Base class for meta-analysis methods in :mod:`~nimare.meta`.
 
     .. versionchanged:: 0.0.8
 
@@ -464,7 +464,7 @@ def transform(self, dataset):
 
 
 class Decoder(NiMAREBase):
-    """Base class for decoders in :mod:`nimare.decode`.
+    """Base class for decoders in :mod:`~nimare.decode`.
 
     .. versionadded:: 0.0.3
 
@@ -538,7 +538,7 @@ def fit(self, dataset, drop_invalid=True):
 
         Parameters
         ----------
-        dataset : :obj:`nimare.dataset.Dataset`
+        dataset : :obj:`~nimare.dataset.Dataset`
             Dataset object to analyze.
         drop_invalid : :obj:`bool`, optional
             Whether to automatically ignore any studies without the required data or not.
@@ -547,7 +547,7 @@ def fit(self, dataset, drop_invalid=True):
 
         Returns
         -------
-        :obj:`nimare.results.MetaResult`
+        :obj:`~nimare.results.MetaResult`
             Results of Decoder fitting.
 
         Notes

nimare/correct.py

@@ -13,7 +13,7 @@
 
 
 class Corrector(metaclass=ABCMeta):
-    """Base class for multiple comparison correction methods in :mod:`nimare.correct`.
+    """Base class for multiple comparison correction methods in :mod:`~nimare.correct`.
 
     .. versionadded:: 0.0.3
 
@@ -81,7 +81,7 @@ def inspect(cls, result):
 
         Parameters
         ----------
-        result : :obj:`nimare.results.MetaResult`
+        result : :obj:`~nimare.results.MetaResult`
             Object for which valid correction methods (i.e., 'method' values) will be identified.
 
         Returns
@@ -106,13 +106,13 @@ def transform(self, result):
 
         Parameters
         ----------
-        result : :obj:`nimare.results.MetaResult`
+        result : :obj:`~nimare.results.MetaResult`
             MetaResult generated by an Estimator to be corrected for multiple
             comparisons.
 
         Returns
         -------
-        result : :obj:`nimare.results.MetaResult`
+        result : :obj:`~nimare.results.MetaResult`
             MetaResult with new corrected maps added.
         """
         est = result.estimator
@@ -165,7 +165,7 @@ class FWECorrector(Corrector):
     To determine what methods are available for the Estimator you're using,
     check the Estimator's documentation. Estimators have special methods
     following the naming convention correct_[correction-type]_[method]
-    (e.g., :func:`nimare.meta.cbma.ale.ALE.correct_fwe_montecarlo`).
+    (e.g., :func:`~nimare.meta.cbma.ale.ALE.correct_fwe_montecarlo`).
     """
 
     _correction_method = "fwe"
@@ -206,7 +206,7 @@ class FDRCorrector(Corrector):
     To determine what methods are available for the Estimator you're using,
     check the Estimator's documentation. Estimators have special methods
     following the naming convention correct_[correction-type]_[method]
-    (e.g., :class:`nimare.meta.mkda.MKDAChi2.correct_fdr_bh`).
+    (e.g., :class:`~nimare.meta.mkda.MKDAChi2.correct_fdr_bh`).
     """
 
     _correction_method = "fdr"