Note
Go to the end to download the full example code.
Create a legacy 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.
Warning
This JSON structure is the legacy Dataset input format.
New projects should generally use Studyset instead.
For the preferred workflow, see The NiMARE Studyset object.
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, load_json
dset_file = os.path.join(get_resource_path(), "nidm_pain_dset.json")
data = load_json(dset_file)
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 legacy Dataset class that can be created from this JSON file in The legacy 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.017 seconds)