The NiMARE Studyset object

This example demonstrates the key functionality of the NeuroImaging Meta-Analysis Data Structure (NIMADS) with NiMARE, including working with Studysets, annotations, coordinates, metadata, and native Studyset-backed meta-analysis.

from pprint import pprint

from nimare.io import fetch_neurostore_studyset
from nimare.meta.cbma import ALE

Download Data from NeuroStore

studyset = fetch_neurostore_studyset("Cv2LLUqG76W9", annotation_id="76PyNqoTNEsE")

# Display basic information about the studyset
print("\nStudyset Information:")
print("-" * 50)
print(f"ID: {studyset.id}")
print(f"Name: {studyset.name}")
print(f"Number of studies: {len(studyset.studies)}")
print(f"Number of annotations: {len(studyset.annotations)}")

Studyset Information:
--------------------------------------------------
ID: Cv2LLUqG76W9
Name: Replication of Functional neuroimaging correlates of finger tapping task variations
Number of studies: 38
Number of annotations: 1

Explore Studies and Analyses

Look at the first study and its analyses in detail

first_study = studyset.studies[0]
print("\nFirst Study Details:")
print("-" * 50)
print(f"Study ID: {first_study.id}")
print(f"Title: {first_study.name}")
print(f"Authors: {first_study.authors}")
print(f"Publication: {first_study.publication}")
print(f"Number of analyses: {len(first_study.analyses)}")

# Show details of the first analysis
first_analysis = first_study.analyses[0]
print("\nFirst Analysis Details:")
print("-" * 50)
print(f"Analysis ID: {first_analysis.id}")
print(f"Analysis Name: {first_analysis.name}")
print(f"Number of coordinates: {len(first_analysis.points)}")
print(f"Number of conditions: {len(first_analysis.conditions)}")

First Study Details:
--------------------------------------------------
Study ID: 359AbepuGmEy
Title: The effect of tapping finger and mode differences on cortical and subcortical activities: a PET study.
Authors: Aoki T, Tsuda H, Takasawa M, Osaki Y, Oku N, Hatazawa J, Kinoshita H.
Publication: Exp. Brain Res.
Number of analyses: 3

First Analysis Details:
--------------------------------------------------
Analysis ID: 85HbHMBb8TUq
Analysis Name: Double Fingers versus Rest
Number of coordinates: 12
Number of conditions: 1

Working with Coordinates

Demonstrate coordinate-based queries

# Example coordinate in MNI space
example_coord = [-42, -58, -15]  # MNI coordinates
print("\nCoordinate Search Results:")
print("-" * 50)
print(f"Searching near coordinate: {example_coord}")

# Find analyses with coordinates within 10mm
nearby_analyses = studyset.get_analyses_by_coordinate(example_coord, r=10)
print(f"\nFound {len(nearby_analyses)} analyses within 10mm")

# Find 5 closest analyses
closest_analyses = studyset.get_analyses_by_coordinate(example_coord, n=5)
print(f"\nClosest 5 analyses: {closest_analyses}")

Coordinate Search Results:
--------------------------------------------------
Searching near coordinate: [-42, -58, -15]

Found 0 analyses within 10mm

Closest 5 analyses: [np.str_('mgFSfjvGWoL3'), np.str_('8BhxrSGkD8kb'), np.str_('85HbHMBb8TUq'), np.str_('7L6jX4HmCS5j'), np.str_('5493w2AV4rNf')]

Working with Annotations

Demonstrate how to work with study annotations

print("\nAnnotation Information:")
print("-" * 50)
for annotation in studyset.annotations:
    print(f"\nAnnotation ID: {annotation.id}")
    print(f"Annotation Name: {annotation.name}")
    print(f"Number of notes: {len(annotation.notes)}")

Annotation Information:
--------------------------------------------------

Annotation ID: 76PyNqoTNEsE
Annotation Name: replication_annotations
Number of notes: 27

Query Metadata

Show how to query analyses based on metadata

# Get all analyses that have a specific metadata field
metadata_results = studyset.get_analyses_by_metadata("contrast_type")
print("\nAnalyses with contrast_type metadata:")
print("-" * 50)
pprint(metadata_results)

Analyses with contrast_type metadata:
--------------------------------------------------
{}

Run a meta-analysis directly on the Studyset

Studysets are now accepted directly by NiMARE estimators and workflows.

results = ALE(null_method="approximate").fit(studyset)
print("\nMeta-analysis output maps:")
print("-" * 50)
print(sorted(results.maps))

Meta-analysis output maps:
--------------------------------------------------
['p', 'stat', 'z']

Interoperate with the legacy Dataset class when needed

Some older utilities still operate on Dataset tables. When you need that older interface, you can still convert explicitly.

nimare_dset = studyset.to_dataset()
print("\nLegacy Dataset coordinates preview:")
print("-" * 50)
print(nimare_dset.coordinates.head())

Legacy Dataset coordinates preview:
--------------------------------------------------
                           id      study_id  ...     z       space
13  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...  54.0  mni152_2mm
14  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...  24.0  mni152_2mm
15  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...  10.0  mni152_2mm
16  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...   4.0  mni152_2mm
17  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...   0.0  mni152_2mm

[5 rows x 7 columns]