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: 3pbFDWdMbe23
Analysis Name: Right Ring finger vs. Rest
Number of coordinates: 7
Number of conditions: 0

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_('85HbHMBb8TUq'), np.str_('mgFSfjvGWoL3'), np.str_('7L6jX4HmCS5j'), np.str_('5493w2AV4rNf'), np.str_('8BhxrSGkD8kb')]

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}")
    # An annotation is a set of label columns over the analyses rather than a
    # list of per-analysis notes, so its size is a label count.
    print(f"Number of labels: {len(annotation.columns.keys())}")

# Every annotation merged into one frame, one row per analysis.
print(f"\nMerged annotation frame: {studyset.annotations_df.shape}")

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

Annotation ID: 76PyNqoTNEsE
Annotation Name: replication_annotations
Number of labels: 1

Merged annotation frame: (27, 4)

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:
--------------------------------------------------
['logp', '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())

/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/stable/examples/01_datasets/05_plot_nimads.py:124: FutureWarning: nimare.dataset.Dataset is deprecated and will be removed in NiMARE 1.0.0. Use nimare.nimads.Studyset instead: build one with Studyset(source), Studyset.from_dataset(dataset), or one of the nimare.io.convert_*_to_studyset functions.
  nimare_dset = studyset.to_dataset()

Legacy Dataset coordinates preview:
--------------------------------------------------
                          id      study_id  ...     z       space
0  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...  54.0  mni152_2mm
1  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...  24.0  mni152_2mm
2  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...  10.0  mni152_2mm
3  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...   4.0  mni152_2mm
4  359AbepuGmEy-3pbFDWdMbe23  359AbepuGmEy  ...   0.0  mni152_2mm

[5 rows x 7 columns]