Note
Go to the end to download the full example code.
Create a NiMARE Dataset object from a JSON file
Here, we present the structure of the JSON/dict input format to create a
Dataset class from scratch.
Data Structure
A JSON file is organized as a nested dictionary structure containing neuroimaging study data. Each study may contain one or multiple contrasts. Each contrast could have coordinates, associated images, metadata, and text information. The data will be mapped to five core DataFrames: annotations, coordinates, images, metadata, and texts.
Study Dictionary
Every study is assigned a unique identifier (study_id), which is defined by the user (e.g., “pain_01.nidm”).
Every study contains a
contrastsdictionary holding all the contrasts for that study. Each contrast is assigned a unique identifier (contrast_id), which is also defined by the user (e.g., “1”).
{
"<study_id>": {
"contrasts": {
"<contrast_id>": {
"annotations": {...},
"coords": {...},
"images": {...},
"metadata": {...},
"text": {...},
}
}
}
}
Contrast Dictionary
Each contrast contains five main dictionaries:
1. Annotations Dictionary (annotations)
Contains labels and annotations.
Optional for studies.
"annotations": {
"label": str, # Label for the contrast
"description": str # Description of the contrast
}
2. Coordinates Dictionary (coords)
Includes space information and x, y, and z coordinates.
"coords": {
"space": str, # e.g., "MNI"
"x": List[float], # x-coordinates
"y": List[float], # y-coordinates
"z": List[float] # z-coordinates
}
3. Images Dictionary (images)
Contains paths to statistical maps. Possible keys are “beta”, “se”, “t”, and “z”.
"images": {
"beta": str, # Path to contrast image
"se": str, # Path to standard error image
"t": str, # Path to t-statistic image
"z": str # Path to z-statistic image
}
4. Metadata Dictionary (metadata)
Contains study-specific metadata.
Flexible schema for user-defined metadata.
"metadata": {
"sample_sizes": List[int]
}
5. Text Dictionary (text)
Contains study/contrast text information.
Contains keys associated with the linked publication.
"text": {
"title": str, # Study title
"keywords": str, # Study keywords
"abstract": str, # Study abstract
"body": str # Main study text/content
}
Example JSON
Load the example dataset JSON file
import json
import os
from nimare.utils import get_resource_path
dset_file = os.path.join(get_resource_path(), "nidm_pain_dset.json")
with open(dset_file, "r") as f_obj:
data = json.load(f_obj)
Example of accessing coordinates for a study
study_coords = data["pain_01.nidm"]["contrasts"]["1"]["coords"]
x_coords = study_coords["x"]
y_coords = study_coords["y"]
z_coords = study_coords["z"]
print(x_coords[:5], y_coords[:5], z_coords[:5])
[48.0, 54.0, 60.0, 60.0, 38.0] [-38.0, -46.0, -30.0, -58.0, 46.0] [-24.0, -26.0, -28.0, -10.0, 6.0]
Example of accessing image paths
study_images = data["pain_01.nidm"]["contrasts"]["1"]["images"]
beta_image_path = study_images["beta"]
t_stat_path = study_images["t"]
print(beta_image_path, t_stat_path)
pain_01.nidm/Contrast.nii.gz pain_01.nidm/TStatistic.nii.gz
Example of accessing metadata
study_metadata = data["pain_01.nidm"]["contrasts"]["1"]["metadata"]
sample_size = study_metadata["sample_sizes"][0]
print(sample_size)
25
Note
Find more information about the Dataset class that can be created from this JSON file in The NiMARE Dataset object.
Example JSON Structure
print(json.dumps(data, indent=4))
{
"pain_01.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
48.0,
54.0,
60.0,
60.0,
38.0,
44.0,
52.0,
36.0,
-36.0,
26.0,
12.0,
-2.0,
-60.0,
-56.0,
-50.0,
-56.0
],
"y": [
-38.0,
-46.0,
-30.0,
-58.0,
46.0,
-6.0,
-4.0,
-12.0,
-68.0,
-80.0,
-106.0,
-104.0,
-52.0,
-62.0,
-42.0,
-66.0
],
"z": [
-24.0,
-26.0,
-28.0,
-10.0,
6.0,
4.0,
6.0,
-12.0,
-40.0,
-48.0,
2.0,
-2.0,
-10.0,
-6.0,
-24.0,
-12.0
]
},
"images": {
"beta": "pain_01.nidm/Contrast.nii.gz",
"se": "pain_01.nidm/ContrastStandardError.nii.gz",
"t": "pain_01.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
25
]
}
}
}
},
"pain_02.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
-36.0,
36.0,
52.0,
36.0,
10.0,
-6.0,
-8.0,
4.0
],
"y": [
2.0,
38.0,
-22.0,
-18.0,
-62.0,
-94.0,
-88.0,
-90.0
],
"z": [
-16.0,
30.0,
22.0,
10.0,
-10.0,
-6.0,
-16.0,
2.0
]
},
"images": {
"beta": "pain_02.nidm/Contrast.nii.gz",
"se": "pain_02.nidm/ContrastStandardError.nii.gz",
"t": "pain_02.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
25
]
}
}
}
},
"pain_03.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
-58.0,
52.0,
60.0,
12.0,
18.0,
22.0,
32.0,
46.0,
-24.0,
-26.0,
-32.0,
-28.0,
8.0,
4.0,
-2.0,
0.0
],
"y": [
10.0,
6.0,
0.0,
10.0,
-102.0,
-92.0,
-92.0,
-82.0,
-68.0,
-66.0,
-90.0,
-74.0,
2.0,
-2.0,
20.0,
-4.0
],
"z": [
8.0,
0.0,
0.0,
0.0,
-4.0,
-6.0,
-12.0,
-8.0,
-28.0,
-40.0,
-10.0,
-32.0,
60.0,
52.0,
40.0,
60.0
]
},
"images": {
"beta": "pain_03.nidm/Contrast.nii.gz",
"se": "pain_03.nidm/ContrastStandardError.nii.gz",
"t": "pain_03.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
20
]
}
}
}
},
"pain_04.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
54.0,
34.0,
54.0,
34.0,
52.0,
56.0,
36.0,
52.0,
32.0,
20.0,
20.0,
14.0,
8.0,
4.0,
2.0,
-8.0,
-36.0,
-24.0,
-34.0,
-28.0,
-40.0,
-32.0,
-30.0,
-38.0
],
"y": [
-28.0,
-20.0,
-22.0,
-18.0,
4.0,
10.0,
2.0,
-8.0,
-98.0,
-92.0,
-100.0,
-104.0,
4.0,
-6.0,
10.0,
-8.0,
-90.0,
-68.0,
-88.0,
-98.0,
4.0,
18.0,
16.0,
16.0
],
"z": [
18.0,
14.0,
16.0,
-10.0,
-2.0,
8.0,
-2.0,
-2.0,
-14.0,
-14.0,
-2.0,
-6.0,
58.0,
66.0,
50.0,
62.0,
-14.0,
-36.0,
-20.0,
-20.0,
-14.0,
-20.0,
2.0,
10.0
]
},
"images": {
"beta": "pain_04.nidm/Contrast.nii.gz",
"se": "pain_04.nidm/ContrastStandardError.nii.gz",
"t": "pain_04.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
20
]
}
}
}
},
"pain_05.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
40.0,
-34.0,
42.0,
38.0,
-20.0,
-32.0,
42.0,
-32.0,
-6.0,
-8.0,
6.0,
-4.0
],
"y": [
10.0,
12.0,
6.0,
22.0,
-58.0,
-60.0,
-64.0,
-32.0,
20.0,
-26.0,
18.0,
10.0
],
"z": [
-8.0,
-10.0,
-6.0,
4.0,
-44.0,
-34.0,
-32.0,
-44.0,
40.0,
28.0,
42.0,
46.0
]
},
"images": {
"beta": "pain_05.nidm/Contrast.nii.gz",
"se": "pain_05.nidm/ContrastStandardError.nii.gz",
"t": "pain_05.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
9
]
}
}
}
},
"pain_06.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
-10.0,
-2.0,
-34.0,
26.0
],
"y": [
-28.0,
6.0,
-4.0,
44.0
],
"z": [
2.0,
56.0,
-8.0,
36.0
]
},
"images": {
"beta": "pain_06.nidm/Contrast.nii.gz",
"se": "pain_06.nidm/ContrastStandardError.nii.gz",
"t": "pain_06.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
9
]
}
}
}
},
"pain_07.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
-10.0,
22.0,
-34.0,
-40.0,
8.0,
2.0,
-4.0,
0.0
],
"y": [
-92.0,
-62.0,
-74.0,
-44.0,
-30.0,
-34.0,
-44.0,
-38.0
],
"z": [
2.0,
-4.0,
-42.0,
-12.0,
82.0,
78.0,
74.0,
84.0
]
},
"images": {
"beta": "pain_07.nidm/Contrast.nii.gz",
"se": "pain_07.nidm/ContrastStandardError.nii.gz",
"t": "pain_07.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
9
]
}
}
}
},
"pain_08.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
64.0,
54.0,
72.0,
60.0,
4.0,
0.0,
-24.0,
4.0,
36.0,
38.0,
38.0,
20.0,
-4.0,
12.0,
0.0,
2.0,
-46.0,
-36.0,
-42.0
],
"y": [
-38.0,
-30.0,
-38.0,
-54.0,
-26.0,
14.0,
-8.0,
-36.0,
44.0,
56.0,
38.0,
-44.0,
-70.0,
-68.0,
-46.0,
-86.0,
-56.0,
-60.0,
-44.0
],
"z": [
22.0,
20.0,
28.0,
2.0,
24.0,
30.0,
6.0,
-16.0,
24.0,
20.0,
12.0,
62.0,
50.0,
46.0,
56.0,
-40.0,
-54.0,
-40.0,
-56.0
]
},
"images": {
"beta": "pain_08.nidm/Contrast.nii.gz",
"se": "pain_08.nidm/ContrastStandardError.nii.gz",
"t": "pain_08.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
12
]
}
}
}
},
"pain_09.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
60.0,
68.0,
66.0,
54.0,
8.0,
2.0,
46.0,
-8.0,
36.0,
30.0,
24.0,
52.0,
14.0,
38.0,
30.0,
36.0,
-28.0,
-20.0,
-46.0,
-50.0
],
"y": [
-60.0,
-48.0,
-44.0,
-50.0,
-26.0,
-52.0,
-50.0,
-34.0,
44.0,
26.0,
36.0,
48.0,
-76.0,
-58.0,
-62.0,
-50.0,
-56.0,
-74.0,
-58.0,
-54.0
],
"z": [
-16.0,
-14.0,
-4.0,
-14.0,
18.0,
50.0,
54.0,
20.0,
34.0,
12.0,
16.0,
24.0,
-42.0,
-44.0,
-38.0,
-40.0,
-46.0,
-40.0,
-54.0,
-44.0
]
},
"images": {
"beta": "pain_09.nidm/Contrast.nii.gz",
"se": "pain_09.nidm/ContrastStandardError.nii.gz",
"t": "pain_09.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
12
]
}
}
}
},
"pain_10.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
68.0,
52.0,
60.0,
52.0,
46.0,
40.0,
44.0,
36.0,
-38.0,
-30.0,
40.0,
26.0,
-4.0,
2.0,
-12.0,
-64.0,
22.0,
-10.0,
-2.0,
-6.0
],
"y": [
-36.0,
-30.0,
-38.0,
-40.0,
-2.0,
8.0,
4.0,
16.0,
-54.0,
-60.0,
-36.0,
-32.0,
-18.0,
18.0,
-24.0,
-24.0,
-40.0,
-66.0,
-38.0,
-68.0
],
"z": [
36.0,
20.0,
32.0,
42.0,
-10.0,
2.0,
12.0,
8.0,
-40.0,
-46.0,
-44.0,
-38.0,
0.0,
28.0,
-14.0,
30.0,
38.0,
50.0,
84.0,
52.0
]
},
"images": {
"beta": "pain_10.nidm/Contrast.nii.gz",
"se": "pain_10.nidm/ContrastStandardError.nii.gz",
"t": "pain_10.nidm/TStatistic.nii.gz",
"z": null
},
"metadata": {
"sample_sizes": [
12
]
}
}
}
},
"pain_11.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
8.0,
-36.0,
-6.0,
10.0
],
"y": [
-22.0,
-20.0,
-48.0,
-12.0
],
"z": [
8.0,
12.0,
54.0,
8.0
]
},
"images": {
"beta": "pain_11.nidm/Contrast_T001.nii.gz",
"se": "pain_11.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_11.nidm/TStatistic_T001.nii.gz",
"z": "pain_11.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
12
]
}
}
}
},
"pain_12.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
-36.0,
38.0,
38.0,
56.0,
4.0,
12.0,
2.0,
10.0,
-34.0,
-28.0,
-30.0,
-30.0
],
"y": [
14.0,
2.0,
4.0,
-24.0,
-70.0,
-68.0,
-74.0,
-72.0,
46.0,
38.0,
40.0,
42.0
],
"z": [
2.0,
2.0,
-16.0,
24.0,
34.0,
34.0,
48.0,
52.0,
30.0,
26.0,
16.0,
38.0
]
},
"images": {
"beta": "pain_12.nidm/Contrast_T001.nii.gz",
"se": "pain_12.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_12.nidm/TStatistic_T001.nii.gz",
"z": "pain_12.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
13
]
}
}
}
},
"pain_13.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
38.0,
36.0,
38.0,
-38.0,
-64.0,
-66.0,
-58.0,
-64.0
],
"y": [
16.0,
2.0,
-10.0,
16.0,
-20.0,
-20.0,
-30.0,
-26.0
],
"z": [
-6.0,
4.0,
-4.0,
-2.0,
20.0,
28.0,
34.0,
40.0
]
},
"images": {
"beta": "pain_13.nidm/Contrast_T001.nii.gz",
"se": "pain_13.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_13.nidm/TStatistic_T001.nii.gz",
"z": "pain_13.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
32
]
}
}
}
},
"pain_14.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
32.0,
22.0,
38.0,
-34.0,
28.0,
26.0,
16.0,
16.0
],
"y": [
22.0,
-102.0,
18.0,
-58.0,
-56.0,
-46.0,
-72.0,
-62.0
],
"z": [
-2.0,
-10.0,
-8.0,
-34.0,
-66.0,
-62.0,
-62.0,
-64.0
]
},
"images": {
"beta": "pain_14.nidm/Contrast_T001.nii.gz",
"se": "pain_14.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_14.nidm/TStatistic_T001.nii.gz",
"z": "pain_14.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
24
]
}
}
}
},
"pain_15.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
-62.0,
0.0,
38.0,
-46.0
],
"y": [
-22.0,
6.0,
-8.0,
4.0
],
"z": [
18.0,
44.0,
-6.0,
28.0
]
},
"images": {
"beta": "pain_15.nidm/Contrast_T001.nii.gz",
"se": "pain_15.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_15.nidm/TStatistic_T001.nii.gz",
"z": "pain_15.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
14
]
}
}
}
},
"pain_16.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
34.0,
32.0,
58.0,
50.0,
30.0,
50.0,
28.0,
46.0,
-32.0,
-6.0,
-54.0,
-48.0,
-2.0,
-8.0,
-20.0,
8.0,
-60.0,
-54.0,
-46.0,
-42.0
],
"y": [
18.0,
22.0,
-46.0,
-24.0,
-54.0,
-50.0,
-48.0,
-54.0,
14.0,
10.0,
-28.0,
-34.0,
-54.0,
-46.0,
-46.0,
-68.0,
-62.0,
-48.0,
-56.0,
-48.0
],
"z": [
-12.0,
-2.0,
14.0,
14.0,
-42.0,
-44.0,
-58.0,
-40.0,
-2.0,
44.0,
14.0,
20.0,
56.0,
52.0,
66.0,
36.0,
4.0,
8.0,
4.0,
-26.0
]
},
"images": {
"beta": "pain_16.nidm/Contrast_T001.nii.gz",
"se": "pain_16.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_16.nidm/TStatistic_T001.nii.gz",
"z": "pain_16.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
14
]
}
}
}
},
"pain_17.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
-60.0,
-36.0,
-52.0,
-54.0,
-2.0,
0.0,
0.0,
0.0,
-42.0,
-10.0,
-50.0,
-32.0,
-48.0,
-52.0,
-44.0,
-58.0
],
"y": [
-28.0,
-18.0,
-28.0,
-10.0,
-58.0,
-54.0,
-84.0,
-64.0,
-60.0,
-66.0,
-56.0,
-60.0,
-70.0,
-64.0,
-62.0,
-56.0
],
"z": [
20.0,
4.0,
22.0,
4.0,
-18.0,
-10.0,
6.0,
-8.0,
-36.0,
-28.0,
-20.0,
-26.0,
-4.0,
4.0,
4.0,
8.0
]
},
"images": {
"beta": "pain_17.nidm/Contrast_T001.nii.gz",
"se": "pain_17.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_17.nidm/TStatistic_T001.nii.gz",
"z": "pain_17.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
12
]
}
}
}
},
"pain_18.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
58.0,
38.0,
36.0,
52.0,
-56.0,
-56.0,
-36.0,
-36.0
],
"y": [
-30.0,
2.0,
16.0,
-44.0,
-32.0,
-22.0,
-2.0,
-24.0
],
"z": [
18.0,
2.0,
0.0,
8.0,
20.0,
24.0,
6.0,
10.0
]
},
"images": {
"beta": "pain_18.nidm/Contrast_T001.nii.gz",
"se": "pain_18.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_18.nidm/TStatistic_T001.nii.gz",
"z": "pain_18.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
12
]
}
}
}
},
"pain_19.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
40.0,
42.0,
-52.0,
34.0,
40.0,
30.0,
20.0,
38.0,
-24.0,
-28.0,
-14.0,
20.0,
-2.0,
-6.0,
4.0,
-8.0,
-42.0,
-38.0,
-42.0,
-50.0
],
"y": [
12.0,
2.0,
-8.0,
22.0,
68.0,
70.0,
72.0,
70.0,
-84.0,
-60.0,
-90.0,
-80.0,
0.0,
10.0,
2.0,
14.0,
58.0,
64.0,
54.0,
54.0
],
"z": [
-6.0,
-4.0,
6.0,
2.0,
-6.0,
-10.0,
18.0,
6.0,
-26.0,
-34.0,
-28.0,
-28.0,
48.0,
38.0,
50.0,
34.0,
0.0,
-6.0,
12.0,
-10.0
]
},
"images": {
"beta": "pain_19.nidm/Contrast_T001.nii.gz",
"se": "pain_19.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_19.nidm/TStatistic_T001.nii.gz",
"z": "pain_19.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
16
]
}
}
}
},
"pain_20.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
40.0,
-54.0,
36.0,
-36.0,
2.0,
4.0,
6.0,
10.0
],
"y": [
6.0,
-68.0,
8.0,
-78.0,
-4.0,
8.0,
8.0,
-24.0
],
"z": [
-8.0,
0.0,
2.0,
-20.0,
64.0,
52.0,
34.0,
40.0
]
},
"images": {
"beta": "pain_20.nidm/Contrast_T001.nii.gz",
"se": "pain_20.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_20.nidm/TStatistic_T001.nii.gz",
"z": "pain_20.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
16
]
}
}
}
},
"pain_21.nidm": {
"contrasts": {
"1": {
"coords": {
"space": "MNI",
"x": [
40.0,
34.0,
30.0,
-26.0,
4.0,
-8.0,
0.0,
-8.0,
-34.0,
-56.0,
-34.0,
-58.0
],
"y": [
-72.0,
10.0,
-78.0,
-86.0,
12.0,
14.0,
2.0,
6.0,
14.0,
-34.0,
8.0,
-44.0
],
"z": [
-20.0,
0.0,
-22.0,
-16.0,
36.0,
34.0,
54.0,
40.0,
2.0,
24.0,
-16.0,
20.0
]
},
"images": {
"beta": "pain_21.nidm/Contrast_T001.nii.gz",
"se": "pain_21.nidm/ContrastStandardError_T001.nii.gz",
"t": "pain_21.nidm/TStatistic_T001.nii.gz",
"z": "pain_21.nidm/ZStatistic_T001.nii.gz"
},
"metadata": {
"sample_sizes": [
16
]
}
}
}
}
}
Total running time of the script: (0 minutes 0.016 seconds)