From b1d2de6c4bc66ff9d810a7061bcd01f2704d485f Mon Sep 17 00:00:00 2001
From: JulioAPeraza <julio.peraza@outlook.com>
Date: Sat, 21 Dec 2024 18:10:13 -0800
Subject: [PATCH 1/3] Add example describing the structure of the JSON/dict
input format for Dataset object
---
examples/01_datasets/01_plot_dataset_io.py | 3 +-
examples/01_datasets/06_plot_dataset_json.py | 164 +++++++++++++++++++
2 files changed, 166 insertions(+), 1 deletion(-)
create mode 100644 examples/01_datasets/06_plot_dataset_json.py
diff --git a/examples/01_datasets/01_plot_dataset_io.py b/examples/01_datasets/01_plot_dataset_io.py
index f83a214d2..8829cfe6c 100644
--- a/examples/01_datasets/01_plot_dataset_io.py
+++ b/examples/01_datasets/01_plot_dataset_io.py
@@ -23,7 +23,8 @@
# 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.
+# to, and loaded from, pkl[.gz] files. Find more information on the JSON file format
+# here :ref:`datasets_json` 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
diff --git a/examples/01_datasets/06_plot_dataset_json.py b/examples/01_datasets/06_plot_dataset_json.py
new file mode 100644
index 000000000..1b5aa80de
--- /dev/null
+++ b/examples/01_datasets/06_plot_dataset_json.py
@@ -0,0 +1,164 @@
+"""
+
+.. _datasets_json:
+
+===============================================
+Create a NiMARE Dataset object from a JSON file
+===============================================
+
+Here, we present the structure of the JSON/dict input format to create a
+:class:`~nimare.dataset.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 Level
+# -----------------------------------------------------------------------------
+# - Every study is assigned a unique identifier (study_id), which is defined by
+# the user (e.g., "pain_01.nidm").
+# - Every study contains a ``contrasts`` dictionary 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").
+#
+# .. code-block:: python
+#
+# {
+# "<study_id>": {
+# "contrasts": {
+# "<contrast_id>": {
+# "annotations": {...},
+# "coords": {...},
+# "images": {...},
+# "metadata": {...},
+# "text": {...},
+# }
+# }
+# }
+# }
+
+###############################################################################
+# Contrast Level
+# -----------------------------------------------------------------------------
+# Each contrast contains five main dictionaries:
+
+###############################################################################
+# 1. **Annotations Dictionary** (`annotations`)
+# `````````````````````````````````````````````````````````````````````````````
+# - Contains labels and annotations.
+# - Optional for studies.
+#
+# .. code-block:: python
+#
+# "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.
+#
+# .. code-block:: python
+#
+# "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".
+#
+# .. code-block:: python
+#
+# "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.
+#
+# .. code-block:: python
+#
+# "metadata": {
+# "sample_sizes": List[int]
+# }
+
+###############################################################################
+# 5. **Text Dictionary** (`text`)
+# `````````````````````````````````````````````````````````````````````````````
+# - Contains study/contrast text information.
+# - Contains keys associated with the linked publication.
+#
+# .. code-block:: python
+#
+# "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])
+
+###############################################################################
+# 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)
+
+###############################################################################
+# Example of accessing metadata
+study_metadata = data["pain_01.nidm"]["contrasts"]["1"]["metadata"]
+sample_size = study_metadata["sample_sizes"][0]
+print(sample_size)
+
+###############################################################################
+# .. note::
+# Find more information about the Dataset class that can be created from this JSON file
+# in :ref:`datasets_object`.
+
+###############################################################################
+# Example JSON Structure
+# -----------------------------------------------------------------------------
+print(json.dumps(data, indent=4))
From a4511494f4990174559d7699088ba84eabedd239 Mon Sep 17 00:00:00 2001
From: "Julio A. Peraza" <52050407+JulioAPeraza@users.noreply.github.com>
Date: Wed, 15 Jan 2025 09:47:52 -0800
Subject: [PATCH 2/3] Update examples/01_datasets/06_plot_dataset_json.py
Co-authored-by: James Kent <jamesdkent21@gmail.com>
---
examples/01_datasets/06_plot_dataset_json.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/examples/01_datasets/06_plot_dataset_json.py b/examples/01_datasets/06_plot_dataset_json.py
index 1b5aa80de..30381a57a 100644
--- a/examples/01_datasets/06_plot_dataset_json.py
+++ b/examples/01_datasets/06_plot_dataset_json.py
@@ -19,7 +19,7 @@
# be mapped to five core DataFrames: annotations, coordinates, images, metadata, and texts.
###############################################################################
-# Study Level
+# Study Dictionary
# -----------------------------------------------------------------------------
# - Every study is assigned a unique identifier (study_id), which is defined by
# the user (e.g., "pain_01.nidm").
From 3e192e7316ebf4df3978dc5a71f73c025331c7aa Mon Sep 17 00:00:00 2001
From: "Julio A. Peraza" <52050407+JulioAPeraza@users.noreply.github.com>
Date: Wed, 15 Jan 2025 09:48:02 -0800
Subject: [PATCH 3/3] Update examples/01_datasets/06_plot_dataset_json.py
Co-authored-by: James Kent <jamesdkent21@gmail.com>
---
examples/01_datasets/06_plot_dataset_json.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/examples/01_datasets/06_plot_dataset_json.py b/examples/01_datasets/06_plot_dataset_json.py
index 30381a57a..834b1a728 100644
--- a/examples/01_datasets/06_plot_dataset_json.py
+++ b/examples/01_datasets/06_plot_dataset_json.py
@@ -44,7 +44,7 @@
# }
###############################################################################
-# Contrast Level
+# Contrast Dictionary
# -----------------------------------------------------------------------------
# Each contrast contains five main dictionaries: