The legacy NiMARE Dataset object

This is a brief walkthrough of the legacy Dataset class and its methods.

Warning

Dataset is deprecated in favor of Studyset. New workflows should start with the The NiMARE Studyset object example instead. This page is retained for migration and for APIs that still operate on legacy Dataset tables.

Start with the necessary imports

import os

from nimare.dataset import Dataset
from nimare.extract import download_nidm_pain
from nimare.transforms import ImageTransformer
from nimare.utils import get_resource_path

Datasets are stored as json or pkl[.gz] files

Json files are used to create Datasets, while generated Datasets are saved to, and loaded from, pkl[.gz] files. Find more information on the JSON file format here Create a legacy NiMARE Dataset object from a JSON file section. We use jsons because they are easy to edit, and thus build by hand, if necessary. We then store the generated Datasets as pkl.gz files because an initialized Dataset is no longer a dictionary.

# Let's start by downloading a dataset
dset_dir = download_nidm_pain()

# Now we can load and save the Dataset object
dset_file = os.path.join(get_resource_path(), "nidm_pain_dset.json")
dset = Dataset(dset_file, target="mni152_2mm", mask=None)
dset.save("pain_dset.pkl")
dset = Dataset.load("pain_dset.pkl")
os.remove("pain_dset.pkl")  # cleanup

Much of the data in Datasets is stored as DataFrames

The five DataFrames in Dataset are “coordinates” (reported peaks), “images” (statistical maps), “metadata”, “texts”, and “annotations” (labels).

Dataset.annotations contains labels describing studies

Columns include the standard identifiers and any labels. The labels may be grouped together based on label source, in which case they should be prefixed with some string followed by two underscores.

dset.annotations.head()

	id	study_id	contrast_id
0	pain_01.nidm-1	pain_01.nidm	1
1	pain_02.nidm-1	pain_02.nidm	1
2	pain_03.nidm-1	pain_03.nidm	1
3	pain_04.nidm-1	pain_04.nidm	1
4	pain_05.nidm-1	pain_05.nidm	1

Dataset.coordinates contains reported peaks

Columns include the standard identifiers, as well as mm coordinates (x, y, z) and voxel indices (i, j, k) specific to the Dataset’s masker’s space.

dset.coordinates.head()

	id	study_id	contrast_id	x	y	z	space
0	pain_01.nidm-1	pain_01.nidm	1	48.0	-38.0	-24.0	mni152_2mm
1	pain_01.nidm-1	pain_01.nidm	1	54.0	-46.0	-26.0	mni152_2mm
2	pain_01.nidm-1	pain_01.nidm	1	60.0	-30.0	-28.0	mni152_2mm
3	pain_01.nidm-1	pain_01.nidm	1	60.0	-58.0	-10.0	mni152_2mm
4	pain_01.nidm-1	pain_01.nidm	1	38.0	46.0	6.0	mni152_2mm

Dataset.images contains images from studies

Columns include the standard identifiers, as well as paths to images grouped by image type (e.g., z, beta, t).

# Here we'll only show a subset of these image types to fit in the window.
columns_to_show = ["id", "study_id", "contrast_id", "beta__relative", "z__relative"]
dset.images[columns_to_show].head()

	id	study_id	contrast_id	beta__relative	z__relative
0	pain_01.nidm-1	pain_01.nidm	1	pain_01.nidm/Contrast.nii.gz	None
1	pain_02.nidm-1	pain_02.nidm	1	pain_02.nidm/Contrast.nii.gz	None
2	pain_03.nidm-1	pain_03.nidm	1	pain_03.nidm/Contrast.nii.gz	None
3	pain_04.nidm-1	pain_04.nidm	1	pain_04.nidm/Contrast.nii.gz	None
4	pain_05.nidm-1	pain_05.nidm	1	pain_05.nidm/Contrast.nii.gz	None

Dataset.metadata contains metadata describing studies

Columns include the standard identifiers, as well as one column for each metadata field.

dset.metadata.head()

	id	study_id	contrast_id	sample_sizes
0	pain_01.nidm-1	pain_01.nidm	1	[25]
1	pain_02.nidm-1	pain_02.nidm	1	[25]
2	pain_03.nidm-1	pain_03.nidm	1	[20]
3	pain_04.nidm-1	pain_04.nidm	1	[20]
4	pain_05.nidm-1	pain_05.nidm	1	[9]

Dataset.texts contains texts associated with studies

Columns include the standard identifiers, as well as one for each text type.

dset.texts.head()

	id	study_id	contrast_id
0	pain_01.nidm-1	pain_01.nidm	1
1	pain_02.nidm-1	pain_02.nidm	1
2	pain_03.nidm-1	pain_03.nidm	1
3	pain_04.nidm-1	pain_04.nidm	1
4	pain_05.nidm-1	pain_05.nidm	1

There are a handful of other important Dataset attributes

Dataset.ids contains study identifiers

dset.ids

array(['pain_01.nidm-1', 'pain_02.nidm-1', 'pain_03.nidm-1',
       'pain_04.nidm-1', 'pain_05.nidm-1', 'pain_06.nidm-1',
       'pain_07.nidm-1', 'pain_08.nidm-1', 'pain_09.nidm-1',
       'pain_10.nidm-1', 'pain_11.nidm-1', 'pain_12.nidm-1',
       'pain_13.nidm-1', 'pain_14.nidm-1', 'pain_15.nidm-1',
       'pain_16.nidm-1', 'pain_17.nidm-1', 'pain_18.nidm-1',
       'pain_19.nidm-1', 'pain_20.nidm-1', 'pain_21.nidm-1'], dtype=object)

Dataset.masker is a nilearn Masker object

dset.masker

NiftiMasker(dtype=<class 'numpy.float32'>,
            mask_img=<nibabel.nifti1.Nifti1Image object at 0x70492668ee70>,
            memory=Memory(location=None))

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.