From f6bcb0a147effefc7bdc72622d885fbd53ee6310 Mon Sep 17 00:00:00 2001
From: Jan Valosek <39456460+valosekj@users.noreply.github.com>
Date: Mon, 25 Sep 2023 16:07:12 +0200
Subject: [PATCH] [ENH] Add "chunk" entity to MRI images (#1586)

* Add 'chunk' entity to MRI datatype

* Update wording of chunk entitty

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

* Remove MRI paragraph from ChunkTransformationMatrix description

* Add chunk entity for fieldmaps

* Add chunk entity for multiecho

---------

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
Co-authored-by: Remi Gau <remi_gau@hotmail.com>
---
 src/schema/objects/entities.yaml     | 9 ++++++---
 src/schema/rules/files/raw/anat.yaml | 9 +++++++++
 src/schema/rules/files/raw/dwi.yaml  | 2 ++
 src/schema/rules/files/raw/fmap.yaml | 7 +++++++
 src/schema/rules/files/raw/func.yaml | 2 ++
 5 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index bc0af52289..6facc34c0d 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -41,9 +41,12 @@ chunk:
   name: chunk
   display_name: Chunk
   description: |
-    The `chunk-<index>` key/value pair is used to distinguish between different regions,
-    2D images or 3D volumes files,
-    of the same physical sample with different fields of view acquired in the same imaging experiment.
+    The `chunk-<index>` key/value pair is used to distinguish between images of
+    the same physical sample with different fields of view acquired in the same
+    imaging experiment.
+    This entity applies to collections of 2D images, 3D volumes or 4D volume series
+    (for example, diffusion weighted images), and may be used to indicate different
+    anatomical structures or regions of the same structure.
   type: string
   format: index
 density:
diff --git a/src/schema/rules/files/raw/anat.yaml b/src/schema/rules/files/raw/anat.yaml
index 3e026107f4..7a8a3234e6 100644
--- a/src/schema/rules/files/raw/anat.yaml
+++ b/src/schema/rules/files/raw/anat.yaml
@@ -29,6 +29,7 @@ nonparametric:
     run: optional
     echo: optional
     part: optional
+    chunk: optional
 
 parametric:
   suffixes:
@@ -62,6 +63,7 @@ parametric:
     ceagent: optional
     reconstruction: optional
     run: optional
+    chunk: optional
 
 defacemask:
   suffixes:
@@ -81,6 +83,7 @@ defacemask:
     reconstruction: optional
     run: optional
     modality: optional
+    chunk: optional
 
 multiecho:
   suffixes:
@@ -102,6 +105,7 @@ multiecho:
     run: optional
     echo: required
     part: optional
+    chunk: optional
 
 multiflip:
   suffixes:
@@ -123,6 +127,7 @@ multiflip:
     echo: optional
     flip: required
     part: optional
+    chunk: optional
 
 multiinversion:
   suffixes:
@@ -143,6 +148,7 @@ multiinversion:
     run: optional
     inversion: required
     part: optional
+    chunk: optional
 
 mp2rage:
   suffixes:
@@ -165,6 +171,7 @@ mp2rage:
     flip: optional
     inversion: required
     part: optional
+    chunk: optional
 
 vfamt:
   suffixes:
@@ -188,6 +195,7 @@ vfamt:
     flip: required
     mtransfer: required
     part: optional
+    chunk: optional
 
 mtr:
   suffixes:
@@ -208,3 +216,4 @@ mtr:
     run: optional
     mtransfer: required
     part: optional
+    chunk: optional
diff --git a/src/schema/rules/files/raw/dwi.yaml b/src/schema/rules/files/raw/dwi.yaml
index 98840ef6a1..22b224b023 100644
--- a/src/schema/rules/files/raw/dwi.yaml
+++ b/src/schema/rules/files/raw/dwi.yaml
@@ -18,6 +18,7 @@ dwi:
     direction: optional
     run: optional
     part: optional
+    chunk: optional
 
 sbref:
   suffixes:
@@ -36,3 +37,4 @@ sbref:
     direction: optional
     run: optional
     part: optional
+    chunk: optional
diff --git a/src/schema/rules/files/raw/fmap.yaml b/src/schema/rules/files/raw/fmap.yaml
index 8f5e66a508..94b03f7f6f 100644
--- a/src/schema/rules/files/raw/fmap.yaml
+++ b/src/schema/rules/files/raw/fmap.yaml
@@ -19,6 +19,7 @@ fieldmaps:
     session: optional
     acquisition: optional
     run: optional
+    chunk: optional
 
 pepolar:
   suffixes:
@@ -37,6 +38,7 @@ pepolar:
     ceagent: optional
     direction: required
     run: optional
+    chunk: optional
 
 TB1DAM:
   suffixes:
@@ -57,6 +59,7 @@ TB1DAM:
     flip: required
     inversion: optional
     part: optional
+    chunk: optional
 
 TB1EPI:
   suffixes:
@@ -78,6 +81,7 @@ TB1EPI:
     flip: required
     inversion: optional
     part: optional
+    chunk: optional
 
 RFFieldMaps:
   suffixes:
@@ -102,6 +106,7 @@ RFFieldMaps:
     flip: optional
     inversion: optional
     part: optional
+    chunk: optional
 
 TB1SRGE:
   suffixes:
@@ -123,6 +128,7 @@ TB1SRGE:
     flip: required
     inversion: required
     part: optional
+    chunk: optional
 
 parametric:
   suffixes:
@@ -141,3 +147,4 @@ parametric:
     ceagent: optional
     reconstruction: optional
     run: optional
+    chunk: optional
diff --git a/src/schema/rules/files/raw/func.yaml b/src/schema/rules/files/raw/func.yaml
index 589d187444..5e2c42b813 100644
--- a/src/schema/rules/files/raw/func.yaml
+++ b/src/schema/rules/files/raw/func.yaml
@@ -21,6 +21,7 @@ func:
     run: optional
     echo: optional
     part: optional
+    chunk: optional
 
 phase:
   suffixes:
@@ -41,3 +42,4 @@ phase:
     direction: optional
     run: optional
     echo: optional
+    chunk: optional