make it easier to download/work with neurostore studyset (#1078)

Author: jdkent

docs/api.rst

@@ -146,6 +146,7 @@ For more information about functional characterization analysis, see :doc:`decod
    io.convert_neurosynth_to_dict
    io.convert_neurosynth_to_json
    io.convert_neurosynth_to_dataset
+   io.fetch_neurostore_studyset
    io.convert_nimads_to_dataset
    io.convert_nimads_to_sleuth
    io.convert_dataset_to_nimads_dict

examples/01_datasets/05_plot_nimads.py

@@ -12,34 +12,15 @@
 """
 
 from pprint import pprint
-from requests import request
 
+from nimare.io import fetch_neurostore_studyset
 from nimare.meta.cbma import ALE
-from nimare.nimads import Studyset
-
 
 ###############################################################################
 # Download Data from NeuroStore
 # -----------------------------------------------------------------------------
 
-
-def download_file(url):
-    """Download a file from NeuroStore."""
-    response = request("GET", url)
-    return response.json()
-
-
-# Download a studyset and its annotation
-nimads_studyset = download_file("https://neurostore.org/api/studysets/Cv2LLUqG76W9?nested=true")
-nimads_annotation = download_file("https://neurostore.org/api/annotations/76PyNqoTNEsE")
-
-
-###############################################################################
-# Create and Explore Studyset
-# -----------------------------------------------------------------------------
-# Load the data into a NiMADS Studyset object and explore its contents
-
-studyset = Studyset(nimads_studyset, annotations=nimads_annotation)
+studyset = fetch_neurostore_studyset("Cv2LLUqG76W9", annotation_id="76PyNqoTNEsE")
 
 # Display basic information about the studyset
 print("\nStudyset Information:")

nimare/io.py

@@ -185,6 +185,56 @@ def _extract_coordinate_row_metadata(metadata, n_points):
     return coordinate_rows, coordinate_keys
 
 
+def fetch_neurostore_studyset(studyset_id, annotation_id=None, target="mni152_2mm"):
+    """Download a Neurostore studyset and optional annotation as a NiMARE Studyset.
+
+    Parameters
+    ----------
+    studyset_id : :obj:`str`
+        Neurostore studyset ID to download. The studyset is requested as a nested
+        payload.
+    annotation_id : :obj:`str`, optional
+        Neurostore annotation ID to download and attach to the studyset. The regular
+        annotation payload is requested.
+    target : :obj:`str` or None, optional
+        Target template space for coordinates. Default is ``"mni152_2mm"``, matching
+        :class:`~nimare.nimads.Studyset`.
+
+    Returns
+    -------
+    studyset : :obj:`nimare.nimads.Studyset`
+        Downloaded studyset with the optional annotation attached.
+    """
+    from neurostore_sdk import ApiClient, ApiException, StoreApi
+
+    from nimare.nimads import Studyset
+
+    store_api = StoreApi()
+    api_client = ApiClient()
+
+    try:
+        studyset_response = store_api.studysets_id_get(studyset_id, nested=True)
+    except ApiException as exc:
+        raise ValueError(f"Failed to download Neurostore studyset '{studyset_id}'.") from exc
+
+    studyset_payload = api_client.sanitize_for_serialization(studyset_response)
+
+    annotation_payload = None
+    if annotation_id is not None:
+        try:
+            annotation_response = store_api.annotations_id_get(annotation_id)
+        except ApiException as exc:
+            raise ValueError(
+                f"Failed to download Neurostore annotation '{annotation_id}'."
+            ) from exc
+
+        annotation_payload = api_client.sanitize_for_serialization(annotation_response)
+
+    if annotation_payload is None:
+        return Studyset(studyset_payload, target=target)
+    return Studyset(studyset_payload, annotations=annotation_payload, target=target)
+
+
 def convert_nimads_to_dataset(studyset, annotation=None):
     """Convert nimads studyset to a dataset.
 

nimare/tests/cassettes/test_io/test_fetch_neurostore_studyset.yaml

@@ -13,6 +13,85 @@
 from nimare.tests.utils import get_test_data_path
 from nimare.utils import get_template
 
+NEUROSTORE_STUDYSET_ID = "qm2PZBqNsaZK"
+NEUROSTORE_ANNOTATION_ID = "hbTQJVL2kAb8"
+
+
+@pytest.fixture(scope="module")
+def vcr_cassette_dir():
+    """Store test_io cassettes in a stable directory."""
+    return os.path.join(os.path.dirname(__file__), "cassettes", "test_io")
+
+
+@pytest.fixture(scope="module")
+def vcr_config():
+    """Keep Neurostore cassettes stable and free of credentials."""
+    return {
+        "filter_headers": ["authorization"],
+        "decode_compressed_response": True,
+    }
+
+
+@pytest.mark.vcr
+def test_fetch_neurostore_studyset():
+    """Download a nested Neurostore studyset into a NiMARE Studyset."""
+    studyset = io.fetch_neurostore_studyset(NEUROSTORE_STUDYSET_ID, target="ale_2mm")
+
+    assert isinstance(studyset, Studyset)
+    assert studyset.id == NEUROSTORE_STUDYSET_ID
+    assert studyset.space == "ale_2mm"
+    assert len(studyset.studies) > 0
+
+
+@pytest.mark.vcr
+def test_fetch_neurostore_studyset_with_annotation():
+    """Download a nested Neurostore studyset and attach a regular annotation."""
+    studyset = io.fetch_neurostore_studyset(
+        NEUROSTORE_STUDYSET_ID,
+        annotation_id=NEUROSTORE_ANNOTATION_ID,
+    )
+
+    assert isinstance(studyset, Studyset)
+    assert studyset.id == NEUROSTORE_STUDYSET_ID
+    assert len(studyset.annotations) == 1
+    assert studyset.annotations[0].id == NEUROSTORE_ANNOTATION_ID
+    assert "included" in studyset.annotations_df.columns
+    assert studyset.annotations_df["included"].any()
+
+
+def test_fetch_neurostore_studyset_wraps_api_errors(monkeypatch):
+    """Neurostore request failures should report the resource that failed."""
+    import neurostore_sdk
+
+    class FailingStoreApi:
+        def studysets_id_get(self, id, nested=True):
+            raise neurostore_sdk.ApiException(status=404, reason="Not Found")
+
+    monkeypatch.setattr(neurostore_sdk, "StoreApi", FailingStoreApi)
+
+    with pytest.raises(ValueError, match="Failed to download Neurostore studyset 'bad-id'"):
+        io.fetch_neurostore_studyset("bad-id")
+
+
+def test_fetch_neurostore_studyset_wraps_annotation_api_errors(monkeypatch):
+    """Neurostore annotation request failures should report the annotation ID."""
+    import neurostore_sdk
+
+    class FailingAnnotationStoreApi:
+        def studysets_id_get(self, id, nested=True):
+            return {"id": "ok-id", "studies": []}
+
+        def annotations_id_get(self, id):
+            raise neurostore_sdk.ApiException(status=404, reason="Not Found")
+
+    monkeypatch.setattr(neurostore_sdk, "StoreApi", FailingAnnotationStoreApi)
+
+    with pytest.raises(
+        ValueError,
+        match="Failed to download Neurostore annotation 'bad-annotation'",
+    ):
+        io.fetch_neurostore_studyset("ok-id", annotation_id="bad-annotation")
+
 
 def test_convert_nimads_to_dataset(example_nimads_studyset, example_nimads_annotation):
     """Conversion of nimads JSON to nimare dataset."""

nimare/tests/cassettes/test_io/test_fetch_neurostore_studyset_with_annotation.yaml

@@ -32,6 +32,7 @@ install_requires =
     matplotlib>=3.6.0  # this is for nilearn, which doesn't include it in its reqs
     nibabel>=5.2.0  # I/O of niftis
     nilearn>=0.12.0,<0.14
+    neurostore-sdk>=1.1  # nimare.io Neurostore fetching
     numba>=0.57.0 # used by sparse
     numpy>=1.22.4 # numba needs NumPy 1.22 or greater
     pandas>=2.1.4
@@ -79,6 +80,7 @@ tests =
     flake8-isort
     pytest
     pytest-cov
+    pytest-vcr
 minimum =
     matplotlib==3.6.0; python_version < "3.11"
     nibabel==5.2.0; python_version < "3.11"