Add DatasetSearcher class with search methods from Dataset

docs/api.rst

@@ -17,6 +17,7 @@ API
    :template: class.rst
 
    dataset.Dataset
+   dataset.DatasetSearcher
 
 
 .. _api_meta_ref:

examples/01_datasets/01_plot_dataset_io.py

@@ -14,7 +14,7 @@
 # -----------------------------------------------------------------------------
 import os
 
-from nimare.dataset import Dataset
+from nimare.dataset import Dataset, DatasetSearcher
 from nimare.extract import download_nidm_pain
 from nimare.transforms import ImageTransformer
 from nimare.utils import get_resource_path
@@ -127,8 +127,11 @@
 dset.images[["id", "varcope"]].head()
 
 ###############################################################################
-# Datasets support many search methods
+# The DatasetSearcher class can search Datasets
 # -----------------------------------------------------------------------------
+searcher = DatasetSearcher()
+
+###############################################################################
 # There are ``get_[X]`` and ``get_studies_by_[X]`` methods for a range of
 # possible search criteria.
 # The ``get_[X]`` methods allow you to search for specific metadata, while the
@@ -139,7 +142,7 @@
 # by default, and for every requested study if the ``ids`` argument is provided.
 # If a study does not have the data requested, the returned list will have
 # ``None`` for that study.
-z_images = dset.get_images(imtype="z")
+z_images = searcher.get_images(dset, imtype="z")
 z_images = [str(z) for z in z_images]
 print("\n".join(z_images))
 
@@ -148,16 +151,16 @@
 # `````````````````````````````````````````````````````````````````````````````
 z_transformer = ImageTransformer(target="z")
 dset = z_transformer.transform(dset)
-z_images = dset.get_images(imtype="z")
+z_images = searcher.get_images(dset, imtype="z")
 z_images = [str(z) for z in z_images]
 print("\n".join(z_images))
 
 ###############################################################################
-# Datasets can also search for studies matching criteria
+# DatasetSearchers can also search for studies matching criteria
 # -----------------------------------------------------------------------------
 # ``get_studies_by_[X]`` methods return a list of study identifiers matching
 # the criteria, such as reporting a peak coordinate near a search coordinate.
-sel_studies = dset.get_studies_by_coordinate(xyz=[[0, 0, 0]], r=20)
+sel_studies = searcher.get_studies_by_coordinate(dset, xyz=[[0, 0, 0]], r=20)
 print("\n".join(sel_studies))
 
 ###############################################################################

examples/02_meta-analyses/07_macm.py

@@ -17,7 +17,7 @@
 from nilearn import datasets, image, plotting
 
 from nimare.correct import FWECorrector
-from nimare.dataset import Dataset
+from nimare.dataset import Dataset, DatasetSearcher
 from nimare.meta.cbma.ale import SCALE
 from nimare.meta.cbma.mkda import MKDAChi2
 
@@ -44,7 +44,8 @@
 ###############################################################################
 # Select studies with a reported coordinate in the ROI
 # -----------------------------------------------------------------------------
-roi_ids = dset.get_studies_by_mask(roi_img)
+searcher = DatasetSearcher()
+roi_ids = searcher.get_studies_by_mask(dset, roi_img)
 dset_sel = dset.slice(roi_ids)
 print(f"{len(roi_ids)}/{len(dset.ids)} studies report at least one coordinate in the ROI")
 

examples/04_decoding/01_plot_discrete_decoders.py

@@ -17,7 +17,7 @@
 import numpy as np
 from nilearn.plotting import plot_roi
 
-from nimare.dataset import Dataset
+from nimare.dataset import Dataset, DatasetSearcher
 from nimare.decode import discrete
 from nimare.utils import get_resource_path
 
@@ -40,7 +40,8 @@
 plot_roi(mask_img, draw_cross=False)
 
 # Get studies with voxels in the mask
-ids = dset.get_studies_by_mask(mask_img)
+searcher = DatasetSearcher()
+ids = searcher.get_studies_by_mask(dset, mask_img)
 
 ###############################################################################
 #

nimare/annotate/cogat.py

@@ -9,7 +9,7 @@
 from nimare.annotate import utils
 from nimare.due import due
 from nimare.extract import download_cognitive_atlas
-from nimare.utils import _uk_to_us
+from nimare.extract.utils import _uk_to_us
 
 LGR = logging.getLogger(__name__)
 

nimare/base.py

@@ -260,7 +260,10 @@ def _collect_inputs(self, dataset, drop_invalid=True):
             )
 
         if self._required_inputs:
-            data = dataset.get(self._required_inputs, drop_invalid=drop_invalid)
+            from nimare.dataset import DatasetSearcher
+
+            searcher = DatasetSearcher()
+            data = searcher.get(dataset, self._required_inputs, drop_invalid=drop_invalid)
             # Do not overwrite existing inputs_ attribute.
             # This is necessary for PairwiseCBMAEstimator, which validates two sets of coordinates
             # in the same object.