From 18e20571d4e77d25733d0c7c361e148ac5e9895a Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Tue, 9 Nov 2021 19:18:14 +0100
Subject: [PATCH] [ENH] add `hemi` entity to schema (#917)

* add hemi entity to schema

* lint yml

* Update src/schema/objects/entities.yaml

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

* add link to hemi in appendix

* fix entity order in example derivatives iEEG

* fix hemi entity name and link to appendix

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 .../04-intracranial-electroencephalography.md    |  2 +-
 src/05-derivatives/03-imaging.md                 |  2 +-
 src/schema/objects/entities.yaml                 | 16 ++++++++++++++--
 src/schema/rules/entities.yaml                   |  1 +
 4 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
index e2184b79d5..3d9429d012 100644
--- a/src/04-modality-specific-files/04-intracranial-electroencephalography.md
+++ b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
@@ -390,7 +390,7 @@ General fields:
          "For example, **T1**: `'sub-<label>/ses-<label>/anat/"
          "sub-01_T1w.nii.gz'`  "
          "**Surface**: `'/derivatives/surfaces/sub-<label>/ses-<label>/anat/"
-         "sub-01_desc-T1w_hemi-R_pial.surf.gii'` "
+         "sub-01_hemi-R_desc-T1w_pial.surf.gii'` "
          "**Operative photo**: `'/sub-<label>/ses-<label>/ieeg/"
          "sub-0001_ses-01_acq-photo1_photo.jpg'` "
          "**Talairach**: `'/derivatives/surfaces/sub-Talairach/ses-01/anat/"
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 66d18bf730..2a757fc9e2 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -348,7 +348,7 @@ Template:
             <source_entities>[_hemi-{L|R}][_space-<space>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
 ```
 
-The `hemi` tag is REQUIRED for GIFTI files storing information about
+The [`hemi-<label>`](../99-appendices/09-entities.md#hemi) entity is REQUIRED for GIFTI files storing information about
 a structure that is restricted to a hemibrain.
 For example:
 
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index b5d4339d68..75ae5d9488 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -91,6 +91,18 @@ flip:
     value which needs to be stored in the field `FlipAngle` of the separate JSON file.
   type: string
   format: index
+hemisphere:
+  name: Hemisphere
+  entity: hemi
+  description: |
+    The `hemi-<label>` entity indicates which hemibrain is described by the file.
+    Allowed label values for this entity are `L` and `R`, for the left and right
+    hemibrains, respectively.
+  type: string
+  format: label
+  enum:
+  - "L"
+  - "R"
 inversion:
   name: Inversion Time
   entity: inv
@@ -135,8 +147,8 @@ mtransfer:
     respectively.
   type: string
   enum:
-  - 'on'
-  - 'off'
+  - "on"
+  - "off"
 part:
   name: Part
   entity: part
diff --git a/src/schema/rules/entities.yaml b/src/schema/rules/entities.yaml
index c36b591b72..648f99cfd9 100644
--- a/src/schema/rules/entities.yaml
+++ b/src/schema/rules/entities.yaml
@@ -19,6 +19,7 @@
 - part
 - recording
 - processing
+- hemisphere
 - space
 - split
 - resolution